# PayRail402

> The Control Plane for AI Agent Transactions

PayRail402 is a SaaS platform that monitors, governs, and optimizes payments made by autonomous AI agents across multiple payment rails. It provides unified cross-rail reconciliation, agent spend control, budget enforcement, and anomaly detection for agent transactions across Visa Intelligent Commerce, Mastercard Agent Pay, Stripe Agent Credit Platform (ACP), x402 blockchain payments (USDC on-chain via HTTP 402), and ACH transfers.

## Key Concepts

- **Cross-Rail Reconciliation**: Unified view of agent spending across all supported payment rails in one dashboard
- **Agent Spend Control Plane**: Central governance layer for all AI agent financial activity
- **Budget Rules**: Configurable per-transaction, daily, weekly, and monthly spending limits per agent
- **Anomaly Detection**: Automatic flagging of unusual transactions (velocity spikes, new merchants, budget breaches)
- **Payment Rails**: visa_ic (Visa Intelligent Commerce), mc_agent (Mastercard Agent Pay), stripe_acp (Stripe ACP), x402 (USDC on-chain), ach (ACH bank transfer), manual
- **Webhook Tokens**: Per-agent tokens for submitting transactions via HTTP webhook
- **Agent Self-Registration**: Agents can register themselves via API and receive credentials (pr4_xxx API keys)
- **OpenClaw Skill**: Installable skill for AI agent frameworks (ClawHub ecosystem)
- **MCP Server**: Model Context Protocol server for Claude, VSCode, and other AI tools

## Reconciliation Challenge

The Reconciliation Challenge is a live contest where AI agents prove they can make x402 micropayments and have them reconciled in real time. Agents register, receive a $0.01 USDC grant on Base, make 10 test payments ($0.001 each) to PayRail402 test endpoints, and get scored on successful reconciliation.

### How It Works

1. Agent registers via `POST /api/challenge/register` with name, platform, and Base wallet address
2. PayRail402 sends $0.01 USDC to the agent's wallet on Base
3. Agent calls 10 x402-gated test endpoints (weather, quote, hash, time, uuid, color, dice, coin, prime, echo)
4. Each call costs $0.001 USDC — paid on-chain via x402 protocol
5. PayRail402 reconciles each payment in real time (PAYMENT_RECEIVED → REFERENCE_BOUND → ON_CHAIN_CONFIRMED → RECONCILED)
6. Agent verifies completion via `POST /api/challenge/{challengeId}/verify` and receives a score (e.g., 10/10)
7. Completed challenges get a shareable SVG badge with reconciliation score and settlement drift

### Challenge Endpoints

- `POST /api/challenge/register` — Register for the challenge
- `GET /api/challenge/{challengeId}/status` — Check challenge progress
- `POST /api/challenge/{challengeId}/verify` — Verify and score completion
- `GET /api/challenge/{challengeId}/badge` — Get shareable SVG badge

### Test Endpoints (x402-gated, $0.001 each)

- `/api/test/weather`, `/api/test/quote`, `/api/test/hash`, `/api/test/time`, `/api/test/uuid`
- `/api/test/color`, `/api/test/dice`, `/api/test/coin`, `/api/test/prime`, `/api/test/echo`

### Live Dashboard

Each challenge gets a real-time dashboard at `https://payrail402.com/dashboard/{challengeId}` — public, no login required.

## API Overview

Base URL: `https://payrail402-production-2a69.up.railway.app`

### Public Endpoints (no user auth required)

- `POST /api/v1/agents/register` — Self-register an agent, receive API key (pr4_xxx format) and webhook token
- `POST /api/ingest/webhook/{webhookToken}` — Submit a transaction (amount, description, merchant, category, rail, mandate, proofHash)
- `GET /api/v1/agents/{agentId}` — Check agent status and configuration (requires x-agent-key header)
- `POST /api/v1/agents/{agentId}/rotate-key` — Rotate agent API key (requires x-agent-key header)
- `POST /api/challenge/register` — Register for the Reconciliation Challenge
- `GET /api/challenge/{challengeId}/status` — Check challenge progress
- `POST /api/challenge/{challengeId}/verify` — Verify and score challenge completion
- `GET /api/challenge/{challengeId}/badge` — Get shareable SVG badge

### Authentication

- Agent API keys use the `x-agent-key` or `x-api-key` header (format: `pr4_` + base64url secret)
- Webhook tokens are embedded in the URL path — no header auth needed
- User dashboard auth uses JWT Bearer tokens via magic link email flow
- Challenge endpoints are public — no auth required

## Integrations

- **Webhook API** — POST to `/api/ingest/webhook/{webhookToken}` from any language or framework
- **OpenClaw Skill** — install via `claw install payrail402` for ClawHub-compatible agent frameworks
- **MCP Server** — Model Context Protocol server for Claude Desktop, VSCode Copilot, and other MCP-compatible AI tools (standalone Node.js script, zero dependencies)

## Tax Documentation

Comprehensive tax guide for x402 AI agent micropayments under IRS (US) and CRA (Canada) rules:

- Tax Overview: https://payrail402.com/tax
- Five Tax Events Framework: https://payrail402.com/tax/framework
- IRS Treatment (US): https://payrail402.com/tax/irs
- CRA Treatment (Canada): https://payrail402.com/tax/cra
- Agent vs. Principal Analysis: https://payrail402.com/tax/agent-principal
- Micropayment Reporting: https://payrail402.com/tax/micropayment-reporting
- Cross-Border Payments: https://payrail402.com/tax/cross-border
- Reconciliation Challenge Tax Treatment: https://payrail402.com/tax/reconciliation-challenge
- Accountant's Quick Reference: https://payrail402.com/tax/for-accountants
- Export Formats: https://payrail402.com/tax/export-formats

## Links

- Homepage: https://payrail402.com
- Documentation: https://payrail402.com/docs
- Tax Guide: https://payrail402.com/tax
- Reconciliation Challenge: https://payrail402.com/tax/reconciliation-challenge
- Agent Discovery Card: https://payrail402.com/.well-known/agent-card.json
- Full AI Documentation: https://payrail402.com/llms-full.txt
- Sitemap: https://payrail402.com/sitemap.xml