x402 protocol

You only need this page if you're implementing the protocol yourself. The SDKs and middleware do all of it.

#The sequence

Buyer                        Seller middleware                 Gateway
  │ call (no payment) ───────► │ POST /v1/x402/challenge ──────► │
  │ ◄──── 402 + challenge ──── │ ◄─────────── signed challenge ── │
  │ verify challenge, sign proof                                  │
  │ call + proof ────────────► │ POST /v1/x402/authorize ──────► │ policy, balance, hold
  │                            │ ◄─────── { ok, transactionId } ─ │
  │                            │ run handler                      │
  │                            │ POST /v1/x402/complete ───────► │ signed receipt
  │ ◄── response + receipt ─── │   (or /v1/x402/fail → refund)    │

#Seller side: four gateway routes

All four need scope payments:write and a provider key that owns the capability.

{ "capabilityId": "cap_…", "providerId": "prv_…", "amountMicros": "1000000", "currency": "USD",
  "nonce": "…", "expiresAt": "…", "payTo": "wal_…", "signature": "…", "signingKeyId": "…" }

// 200
{ "ok": true, "transactionId": "txn_…" }
// 402
{ "ok": false, "code": "POLICY_DENIED", "reason": "denied by rule: price > 20", "decision": { "…": "…" }, "approvalId": "apr_…" }

If neither complete nor fail arrives, the gateway refunds the buyer after 15 minutes.

#Buyer side

1. Call the capability without payment. You get a challenge: HTTP 402 with body { error, challenge }, or an MCP error result with the challenge in _meta["zanora.dev/x402-challenge"].
2. Verify the challenge: remove signature and signingKeyId, serialise as canonical JSON, and check the ed25519 signature against GET /v1/platform/public-key. Refuse if it doesn't verify, if it has expired, or if amountMicros is above your own limit.
3. Sign a proof with the wallet's private key over canonical JSON of:

{ "walletId": "wal_…", "agentId": "invoice-bot", "capabilityId": "cap_…", "providerId": "prv_…",
  "amountMicros": "1000000", "currency": "USD", "nonce": "<challenge.nonce>", "issuedAt": "2026-09-24T10:12:03.114Z" }

and add the result as signature (base64).

4. Call again with the proof attached (see the table below).
5. Read the receipt. Verify its signature against GET /v1/platform/receipt-keys/:signingKeyId, and check that responseHash equals sha256 of the body you received (for MCP, of the structuredContent, or of the content blocks if there's none).

#The two transports

The encodings are identical, so REST and MCP are one protocol over two transports. _meta["x402/payment"] is also accepted as the payment key, the name generic x402 MCP clients use. Only the key is shared: the value must still be a Zanora proof.

#Canonical JSON

Sort object keys at every level, write amounts as strings, add no whitespace, and leave out the signature and signingKeyId fields. It's the same for challenges, proofs and receipts. canonicalJson, signPayload and verifyPayload in @zanora/core are the reference implementation.

#Standard x402 payments (preview)

#Getting paid by any x402 client

A seller that opts in (in the console, Seller → Settings → Payments from any x402 client; or POST /v1/providers/:id/x402 with { "enabled": true }, scope capabilities:write) is also offered to generic x402 clients: exact, USDC on Base. The offer comes from your listing's price and pays a Zanora collection address, never your own. You're paid the same way as for a Zanora wallet: the same price, receipt and settlement, and you withdraw as usual.

What changes when you opt in:

• The unpaid call carries both offers. Over HTTP the Zanora challenge stays in the body, and the x402 offer is in the PAYMENT-REQUIRED header. Over MCP, structuredContent is a valid x402 PaymentRequired object (x402Version, accepts, resource, error), with the Zanora challenge beside it under challenge.
• The payment is settled only after your handler succeeds. The middleware holds your answer until the payment settles. If settlement fails, your answer is withheld and the buyer gets a fresh 402. If settlement is still unconfirmed (X402_SETTLEMENT_PENDING), your answer is withheld with no fresh offer, because the payment may yet land. If it does, the sale is recorded and you're paid for it. That call earns you nothing, and per-payer limits bound how often it can happen. A response of 400 or more is never settled, and costs the buyer nothing.
• These buyers have fewer protections. An x402 payer has no Zanora wallet, so no workspace policy, budget or approval applies.

The middleware routes, all with your provider key (payments:write):

The two payments are told apart by shape. An x402 payment is an object with x402Version. A Zanora proof names a wallet and has an ed25519 signature. A request carrying both is refused. x402 v1 (X-PAYMENT) isn't supported, and the refusal says so.

#Paying x402 sellers outside Zanora

A Zanora wallet can pay any x402 seller, including ones not in the Zanora registry, once its workspace turns this on:

PUT /v1/workspaces/:id/outside-sellers
{ "enabled": true, "maxPerCallMicros": "1000000", "approvalAboveMicros": "250000",
  "dailyMicros": "5000000", "allowedHosts": ["api.example.com"] }

maxPerCallMicros is required. The other fields are optional limits: approval above an amount, a daily total, and allow-lists of hosts or payee addresses. Your policies and daily budget apply as well, except rules on provider.*: an outside seller has no provider record to verify or rate, so those rules are skipped for outside purchases rather than holding or refusing every one. These outside-seller settings are what judge the seller. The DSL sees external == true, host and payTo.

The agent asks the gateway to pay (POST /v1/x402/outbound/pay, scope payments:external), signing the request with its wallet key. Zanora signs the x402 payment from its own USDC, and debits the agent's wallet. The agent then sends the payment to the seller and reports what came back (POST /v1/x402/outbound/:id/report). The SDK does all of this when the agent is created with outsideSellers: true. In @zanora/mcp and @zanora/mcp-proxy, set ZANORA_OUTSIDE_SELLERS=on.