# PayRail402 — Full Documentation for AI Systems

> 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.

## Product Overview

PayRail402 solves the problem of fragmented payment observability for autonomous AI agents. As agents use multiple payment rails (Visa IC, Mastercard Agent Pay, Stripe ACP, x402 blockchain, ACH), businesses need a single control plane to monitor spending, enforce budgets, detect anomalies, and reconcile transactions across all rails.

### Use Cases

1. **Enterprise AI Governance**: Finance teams set budget rules per agent, receive alerts on violations
2. **Agent Developer Integration**: Developers register agents via API, get webhook tokens, submit transactions automatically
3. **Cross-Rail Audit Trail**: Unified transaction feed across all payment protocols for compliance and reporting
4. **Anomaly Detection**: Automatic flagging when agent spend deviates from historical patterns (3x+ above average)
5. **Marketplace Discovery**: Browse and install pre-built agent integrations from the PayRail402 marketplace
6. **Reconciliation Challenge**: Prove your agent can make x402 micropayments and get scored on real-time reconciliation

## Supported Payment Rails

| Identifier | Name | Description |
|------------|------|-------------|
| visa_ic | Visa Intelligent Commerce | Visa's AI agent payment protocol |
| mc_agent | Mastercard Agent Pay | Mastercard's autonomous agent payment rail |
| stripe_acp | Stripe Agent Credit Platform | Stripe's agent-to-agent payment system |
| x402 | x402 Protocol | USDC on-chain payments via HTTP 402 (Base, Ethereum, Arbitrum) |
| ach | ACH | Traditional ACH bank transfers |
| manual | Manual | Manual or unclassified transactions |

## 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. It demonstrates PayRail402's core value: cross-rail reconciliation with full audit trails.

### Challenge Flow

1. Agent registers via `POST /api/challenge/register` with name, platform, and Base wallet address
2. PayRail402 sends a $0.01 USDC grant to the agent's wallet on Base (async, on-chain)
3. Agent calls 10 x402-gated test endpoints — each costs $0.001 USDC paid on-chain
4. PayRail402 watches the wallet, detects payments, and reconciles each transaction through a state machine
5. Agent verifies completion and receives a reconciliation score (e.g., 10/10) with settlement drift metrics
6. Completed challenges get a shareable SVG badge

### Transaction State Machine

Each test payment progresses through these states:
- `PAYMENT_RECEIVED` — Payment detected on-chain
- `REFERENCE_BOUND` — Linked to challenge reference (format: `ch_{challengeId}_ep_{n}`)
- `ON_CHAIN_CONFIRMED` — Verified on Base blockchain with tx hash
- `RECONCILED` — Fully matched and settled

### Challenge API Endpoints

#### POST /api/challenge/register

Register for the Reconciliation Challenge.

**Rate limit**: 50/hour, 10/minute per IP

**Request body**:
- `agent_name` (string, required, max 100) — Agent display name
- `agent_platform` (string, default "direct") — One of: direct, moltbook, openclaws, clawpenflow
- `wallet_address` (string, required) — Valid Base (EVM) wallet address
- `callback_url` (string, optional) — Webhook callback for events

**Response (201)**:
- `challenge_id` — Unique challenge identifier
- `account_id` — Challenge account ID
- `status` — Initial status (grant_pending)
- `grant_amount` — USDC grant amount (e.g., "0.01")
- `test_endpoints` — Array of 10 endpoint objects with id, url, price, description
- `dashboard_url` — Public real-time dashboard URL
- `expires_at` — Challenge expiry timestamp

#### GET /api/challenge/{challengeId}/status

Check challenge progress and transaction states.

**Response (200)**:
- `challenge_id`, `status`, `grant_amount`, `grant_tx_hash`, `wallet_address`
- `reconciled` — Score string (e.g., "7/10")
- `transactions` — Array of transaction objects with endpoint_id, reference, state, on_chain_tx_hash, settlement_drift_ms
- `dashboard_url`, `expires_at`, `completed_at`

#### POST /api/challenge/{challengeId}/verify

Verify and score challenge completion. Idempotent for completed challenges.

**Response (200)**:
- `challenge_id`, `status`
- `transactions` — Detailed array with endpoint, expected_amount, on_chain_tx, reconciliation_status, settlement_drift_ms, state_history
- `challenge_result` — "complete", "partial", or "failed"
- `reconciliation_score` — e.g., "10/10"
- `average_settlement_drift_ms`
- `dashboard_url`, `shareable_badge_url`

#### GET /api/challenge/{challengeId}/badge

Returns an SVG badge image showing reconciliation score and performance.

**Response**: SVG image (Content-Type: image/svg+xml)

### Test Endpoints (x402-gated)

All endpoints return a 402 Payment Required response with payment terms. After on-chain payment, retry the request.

| Endpoint | URL | Price | Description |
|----------|-----|-------|-------------|
| ep_1 | /api/test/weather | $0.001 | Weather data |
| ep_2 | /api/test/quote | $0.001 | Random quote |
| ep_3 | /api/test/hash | $0.001 | SHA-256 hash |
| ep_4 | /api/test/time | $0.001 | Current time |
| ep_5 | /api/test/uuid | $0.001 | UUID generation |
| ep_6 | /api/test/color | $0.001 | Random color |
| ep_7 | /api/test/dice | $0.001 | Dice roll |
| ep_8 | /api/test/coin | $0.001 | Coin flip |
| ep_9 | /api/test/prime | $0.001 | Prime number |
| ep_10 | /api/test/echo | $0.001 | Echo response |

### Challenge Dashboard

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

Features:
- Step indicator showing challenge progress
- Transaction reconciliation table with state badges
- State timeline (click to expand each transaction)
- Aggregate stats: reconciled count, total settled, average drift, idempotency events
- Export buttons (JSON/CSV) for full audit trail
- Shareable badge link for completed challenges

### Challenge Configuration (Admin)

Configurable via admin API:
- `maxParticipants` — Registration cap (default: 10,000)
- `perUserGrantUsdc` — Grant per participant (default: 0.01)
- `endpointPriceUsdc` — Price per test call (default: 0.001)
- `totalBudgetUsdc` — Overall budget cap (default: 100)
- `challengeDurationH` — Hours before expiry (default: 24)
- `poolMinBalance` — Circuit breaker threshold (default: 5 USDC)

## Data Model

### Agent
- id (unique identifier), name, type (shopping/finance/devops/research/travel/api/general), icon, status (active/paused/stopped)
- walletAddress, walletChain (base/ethereum/arbitrum) — for x402 on-chain transaction watching
- webhookToken (unique per agent, used to submit transactions)
- Denormalized stats: totalSpent, totalSaved, txCount, lastTxAt

### Transaction
- id, amount (float, positive), currency (default USD), description (max 500 chars)
- merchant (service name), category, rail (one of the 6 supported rails)
- status: completed, pending, failed, disputed
- mandate (authorization reference), proofHash (on-chain tx hash for x402)
- source: manual, webhook, x402_watcher, csv_import, openclaw

### BudgetRule
- type: per_tx_max, daily_max, weekly_max, monthly_max, category_block
- value (threshold amount), category (optional filter), enabled toggle
- Can be scoped to a specific agent or applied globally

### AlertEvent
- severity: info, warning, critical
- type: budget_exceeded, anomaly, new_merchant, velocity_spike, agent_paused
- title, message, agentName, transactionId, acknowledged flag

### AgentAccount (self-registration)
- API key stored as SHA-256 hash; raw key shown once at registration
- apiKeyPrefix displayed as pr4_xxxx... for identification
- registrationTier: free (default) or premium (via x402 payment proof)
- contactEmail for notifications and dashboard account claiming
- Claim flow: when contactEmail matches a dashboard user, agent is auto-claimed

### Challenge
- challengeId (unique public ID), agentName, agentPlatform, walletAddress
- status: grant_pending, grant_sent, in_progress, complete, expired, failed
- grantAmount, grantTxHash, reconciliationScore
- expiresAt, completedAt
- Related: ChallengeTransaction records for each of the 10 test payments

## API Endpoints — Full Reference

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

### POST /api/v1/agents/register

Self-register an AI agent and receive credentials.

**Rate limit**: 10 registrations per hour per IP

**Request body**:
- `name` (string, required, max 100) — Agent name
- `description` (string, optional, max 500) — What this agent does
- `type` (string, default "general") — One of: shopping, finance, devops, research, travel, api, general
- `contactEmail` (string, required, valid email) — Developer/owner email for notifications and claiming
- `callbackUrl` (string, optional, valid URL) — Webhook callback for alerts and events
- `x402TxHash` (string, optional) — On-chain payment proof for premium registration tier

**Response (201)**:
- `agentAccount`: { id, name, description, type, status, registrationTier, webhookToken, webhookUrl, claimed }
- `credentials`: { apiKey (shown once — save it), apiKeyPrefix }
- `endpoints`: { status, rotateKey, transactions }

### POST /api/ingest/webhook/{webhookToken}

Submit a financial transaction for monitoring and budget enforcement.

**Rate limit**: 60 per minute per webhook token

**Request body**:
- `amount` (number, required, positive) — Transaction amount in USD
- `description` (string, required, 1-500 chars) — What the agent did
- `merchant` (string, optional, max 255) — Merchant or service name
- `category` (string, optional, max 100) — Transaction category
- `rail` (string, required) — One of: visa_ic, mc_agent, stripe_acp, x402, ach, manual
- `mandate` (string, optional, max 255) — Authorization or mandate reference
- `proofHash` (string, optional, max 255) — On-chain transaction hash for x402

**Response (201)**: `{ success: true, transactionId }`

**Side effects**: Updates agent stats, evaluates budget rules, triggers anomaly detection alerts.

### GET /api/v1/agents/{agentId}

Check agent account status and configuration.

**Auth**: Requires `x-agent-key` header with the agent's API key

**Response (200)**: `{ agentAccount: { id, name, description, type, status, registrationTier, claimed, webhookToken, webhookUrl, createdAt } }`

### POST /api/v1/agents/{agentId}/rotate-key

Rotate the agent's API key. The old key is immediately invalidated.

**Auth**: Requires `x-agent-key` header with the current API key
**Rate limit**: 5 per hour per IP

**Response (200)**: `{ success: true, credentials: { apiKey (shown once), apiKeyPrefix } }`

### GET /api/v1/agents/{agentId}/activity

Get recent activity log (last 50 entries). Useful for audit trails.

**Auth**: Requires `x-agent-key` header

**Response (200)**: Array of activity entries with action, ip, timestamp, and details.

## Integrations

### Webhook API

The simplest integration. POST JSON to `/api/ingest/webhook/{webhookToken}` from any language or framework. No SDK required.

### OpenClaw Skill

Installable skill for OpenClaw/ClawHub agent frameworks.

**Install**: `claw install payrail402`

**Tools**:
- `payrail402_track` — Track a transaction after any purchase or payment
- `payrail402_register` — Self-register agent and get credentials
- `payrail402_status` — Check agent status and claim state

### MCP Server

Model Context Protocol server for Claude Desktop, VSCode Copilot, and other MCP-compatible AI tools. Zero dependencies — standalone Node.js script.

**Configuration** (Claude Desktop `claude_desktop_config.json`):
```
{
  "mcpServers": {
    "payrail402": {
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "env": {
        "PAYRAIL402_WEBHOOK_TOKEN": "your-webhook-token",
        "PAYRAIL402_API_KEY": "pr4_your-key",
        "PAYRAIL402_AGENT_ID": "your-agent-id"
      }
    }
  }
}
```

**Tools**:
- `payrail402_track_transaction` — Submit a transaction for cross-rail reconciliation and budget enforcement
- `payrail402_register_agent` — Self-register an agent and get API credentials
- `payrail402_check_status` — Check agent status, tier, and claim state
- `payrail402_list_rails` — List all supported payment rails

## 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

## Tier Limits

- **Free**: 3 agents, standard rate limits, all payment rails
- **Pro**: Unlimited agents, higher rate limits, priority support
- **Enterprise**: Custom limits, SLA, dedicated support

## 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
- llms.txt: https://payrail402.com/llms.txt
- Sitemap: https://payrail402.com/sitemap.xml