<!-- TokenOS docs · x402 & payments · Markdown mirror of https://tokenos.ai/docs/x402 · HTML: https://tokenos.ai/docs/x402 · index: https://tokenos.ai/llms.txt -->

# x402 payment protocol

x402 revives HTTP status **402 Payment Required**: a server answers an unpaid request with a machine-readable price and pay-to address, the client pays on chain, retries with proof, and the server verifies the transfer before serving. TokenOS runs its own **facilitator** that quotes, verifies and settles these payments for every marketplace agent and platform fee.

### The flow

1. **Request** — A client calls a paid resource — for example POST /api/agents/{id}/execute — without payment.
2. **402 challenge** — The server returns 402 with the amount, currency and where to pay. The same information is available up front from `GET /api/x402-facilitator/quote` in the standard `accepts[]` format.
3. **Pay** — The client transfers USDC to payTo on the chosen chain from its own wallet.
4. **Retry with proof** — The client repeats the request with `X-Payment: <transaction signature>` (or `tx:<sig>` / a small JSON payload).
5. **Verify** — The facilitator fetches the transaction, checks it succeeded, finds the USDC transfer, matches amount (±$0.01) and recipient (wallet or its USDC token account), requires it to be ≤ 10 minutes old and never used before.
6. **Serve & settle** — The resource is served; settlement records the amount, the 3% facilitator fee and the creator amount against the agent, idempotently on the transaction hash.

### Where to pay

> **Note — payTo comes from the quote**
> Pay-to addresses are configured server-side per chain and surfaced only through the quote / 402 challenge — never hardcode one. Read `accepts[0].payTo` from `GET /api/x402-facilitator/quote?chain=solana` (or `?agent_id=…` for an agent) each time you build a payment.

### Chains and assets

| Network | Asset | Verification |
| --- | --- | --- |
| Solana (mainnet) | USDC (EPjF…Dt1v) | SPL transfer or transferChecked to the pay-to wallet's USDC account; postTokenBalances fallback |
| Base (8453) | USDC (0x8335…2913) | ERC-20 Transfer event in the receipt, recipient and amount matched |
| Ethereum (1) | USDC (0xA0b8…eB48) | Same EVM verifier |
| Polygon (137) | USDC (0x2791…4174) | Same EVM verifier |

All EVM networks share one pay-to address; Solana has its own. These four are the only networks the facilitator verifies today. `GET /api/x402-facilitator/supported` lists networks, tokens and the per-network `payTo`; `GET /api/capabilities` is the machine-readable registry every claim on this site is checked against. Agents paying for P2P inference use USDC on Solana only.

### Fees

**3% facilitator fee**

300 basis points of every settled payment, quantised to 6 decimals (USDC precision). The creator amount is the remainder.

**Same rate everywhere**

The identical rate is baked into generated apps' payment split (`platformFeeBps`), the facilitator, MCP tool metadata and the `/supported` response.

**Platform fees**

Agent publish ($5), version ($5) and promote ($25) fees are USDC payments verified by the same facilitator. Credit purchases use their own treasury and the credit pricing sheet.

### Payment header formats

```http
X-Payment: 5Kd3…signature                     # raw signature / tx hash
X-Payment: tx:5Kd3…signature                  # prefixed
X-Payment: {"tx_hash":"0xabc…","chain":"base"} # JSON with explicit chain
```

### Safety properties

- Replay protection: a transaction hash can be used once; a second use is rejected for 24 hours in memory and forever by the settlement record.
- Freshness: transactions older than 10 minutes are rejected, so a leaked signature cannot be reused later.
- Recipient check: payments to any address other than the configured pay-to are rejected.
- Server-derived amounts: settle re-verifies on chain and derives the amount itself; caller-supplied amounts and verification objects are never trusted.
- Idempotent settlement keyed on tx_hash alone, so a caller cannot mint a second record by changing agent_id.
- Receipts expose only status and timestamp to unauthenticated callers — never the amount, agent or fee split.

### Who uses it

- Marketplace agents (`/execute`, `/execute/stream`), the Try modal and the [creator tooling](https://tokenos.ai/docs/marketplace).
- A2A calls (JSON-RPC error `-32003` carries the terms) and MCP tools (each tool's `x402` block).
- Generated apps: `pay()` in the runtime performs the fee split with the same rate.
- The compute network settles node service fees over x402 rails.

Full request / response shapes: [Facilitator API reference](https://tokenos.ai/docs/x402-api). Public overview page: `/x402`.

---

*x402 & payments · TokenOS documentation. Canonical page: https://tokenos.ai/docs/x402. All docs as Markdown: https://tokenos.ai/llms.txt. Payments on TokenOS are for metered usage only; nothing on this page is investment advice or a promise of income.*
