API reference

x402 headers

When a gateway-protected route is hit without a valid payment, the response is HTTP 402 with the following headers attached:

HTTP/1.1 402 Payment Required
X-USDC-Amount: 0.0042
X-USDC-Chain: base
X-USDC-PayTo: 0xA1f3...7C2d
X-USDC-Nonce: 01HD5K8...
X-USDC-Expires: 2026-05-25T19:14:21Z
X-USDC-Receipt-URL: https://gateway.example.com/.well-known/openusdc/receipt

To complete the request, the client retries with a signed payment header:

POST /v1/score HTTP/1.1
X-USDC-Payment: eyJjaGFpbiI6ImJhc2UiLCJhbW91bnQiOiIwLjAwNDIi...
X-USDC-Signer: 0x9A3f...c821
Content-Type: application/json

{"input": "..."}

On success, the gateway adds X-USDC-Receipt to the forwarded request so your handler can persist it alongside business state. The receipt is a compact JWT-style envelope signed with the gateway's payment key.

Gateway endpoints

POST /v1/payments

Issue a payment directly. Useful for agent-to-agent transfers without an HTTP target.

POST https://api.openusdc.ai/v1/payments
{
  "to": "agent://maple.ai/quote",
  "amount": "0.25 USDC",
  "chain": "solana",
  "metadata": { "reason": "fx-quote", "task": "task_94f1" }
}

GET /v1/payments

List payments. Filters: chain, route, since, counterparty, status.

GET /v1/payments?chain=base&since=24h&status=settled
→ 200
{
  "data": [
    {
      "id": "ousdc_3f9a8a",
      "amount": "0.0042 USDC",
      "chain": "base",
      "status": "settled",
      "counterparty": "openrouter.ai",
      "trace_id": "01HD5...",
      "settled_at": "2026-05-25T18:14:21Z"
    }
  ],
  "next_cursor": "01HD5L1..."
}

POST /v1/refunds

Issue a refund against a prior settlement. Operator scope required.

Wallet policies

A policy is a JSON document attached to a wallet at provisioning time. Policies are evaluated at sign time and cannot be bypassed from agent code.

{
  "version": 1,
  "caps": {
    "perCall":  "0.05 USDC",
    "perHour":  "5.00 USDC",
    "perDay":  "50.00 USDC"
  },
  "allow": ["*.openusdc.ai", "api.tavily.com"],
  "deny": ["*.gambling.example", "agent://known-bad/*"],
  "chains": ["base", "solana"],
  "revokeAt": "2026-12-31T00:00:00Z",
  "approvers": ["finance-ops@acme.co"]
}

Webhooks

OpenUSDC Cloud delivers events with at-least-once semantics and exponential back-off.

• payment.settled — every successful settlement
• payment.failed — payments that failed validation or did not finalize on-chain
• payment.refunded — operator-issued refunds
• payment.disputed — disputes opened against a settlement
• policy.violated — agent attempted a payment outside policy
• sweep.completed — treasury sweep landed in destination

Every payload is signed with an Ed25519 key you fetch from the dashboard:

POST /your-webhook
X-OpenUSDC-Signature: ed25519=...
X-OpenUSDC-Timestamp: 2026-05-25T18:14:21Z

{
  "event": "payment.settled",
  "data": { "id": "ousdc_3f9a8a", "amount": "0.0042 USDC", ... }
}

Error codes

402  payment_required            // route is priced; pay and retry
402  payment_quote_expired       // nonce expired; fetch a new quote
402  payment_amount_insufficient // sent less than the quoted price
403  policy_violation            // wallet policy rejected the payment
409  payment_nonce_replay        // nonce already settled (idempotent return)
424  settlement_failed           // chain rejected the on-chain settlement
429  rate_limited                // workspace or wallet rate cap hit
500  internal_error              // contact support with the receipt URL

Rate limits

The Cloud API allows 100 requests per second per workspace by default. Self-hosted gateways are limited only by the host. There is no rate limit on the agent SDK; backpressure happens at the chain layer (block inclusion).