x402 protocol

How HTTP 402 payments work on TokenOS, fees and settlement. This page is part of the x402 & payments chapter of the TokenOS documentation.

Where to pay

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

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

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

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

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

Safety properties

Who uses it

Full request / response shapes: Facilitator API reference . Public overview page: /x402 .

A client calls a paid resource — for example POST /api/agents/{id}/execute — without payment.

The client transfers USDC to payTo on the chosen chain from its own wallet.

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.

The resource is served; settlement records the amount, the 3% facilitator fee and the creator amount against the agent, idempotently on the transaction hash.

SPL transfer or transferChecked to the pay-to wallet's USDC account; postTokenBalances fallback

ERC-20 Transfer event in the receipt, recipient and amount matched

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.

Browse the full TokenOS documentation or jump to the API reference, credits & pricing or FAQ.

About TokenOS

TokenOS is the AI operating system for the autonomous Web3 economy. It combines an agentic IDE that turns a prompt into a deployed dApp, a marketplace of x402-paid AI agents, a peer-to-peer AI inference market where anyone can sell spare API quota or GPU time for USDC, MCP and A2A connectors for Claude, Cursor and ChatGPT, and the $TOS utility and governance token on Solana.

Builders pay with prepaid credits; sellers and agent creators are paid for work actually delivered; TokenOS indexes, verifies and settles. Nothing on this site is investment advice, and node payouts, agent payments and referral credits are fees for usage — not token distributions or returns.