What is x402?
x402 is a protocol that embeds payment into the HTTP request flow, making it useful for pay-per-request APIs, digital content, and AI agent-accessible resources.
Basic idea
x402 is a payment protocol built around the HTTP 402 Payment Required status code. A server can declare an API, file, data feed, or agent tool as a paid resource. If the first request does not include valid payment credentials, the server returns a 402 response that describes the price, network, asset, settlement address, and protected resource scope.
After receiving the 402 challenge, a client or AI agent can sign a standardized on-chain payment authorization and retry the same request. The server verifies the authorization, checks that the amount and resource match, settles the payment, and then returns the protected content. This embeds payment directly into the HTTP request flow without redirecting users to a checkout page.
Why it fits agent payments
- Machine-readable: price, asset, network, and resource scope are returned in the 402 response, so agents can understand the requirement automatically.
- Pay per request: suitable for data APIs, model inference, report generation, file downloads, MCP tool calls, and other small high-frequency resources.
- No prepaid balance required: agents can authorize payment at request time, and merchants settle according to the resource requirement.
- Aligned with HTTP semantics: unpaid requests return 402, paid requests return the original business response, which fits existing API gateways and server routes.
How one x402 request works
- The agent requests a protected resource, such as GET /api/premium-data.
- The server SDK detects that the request has no valid payment credential and returns HTTP 402 with payment requirements.
- The agent signs a USDC authorization and retries the request with the x402 payment payload.
- PolyPay verifies the signature, resource, amount, validity window, and nonce to prevent mismatched or duplicate settlement.
- After verification succeeds, PolyPay submits on-chain settlement and the server returns the original API data.
Core concepts
| Concept | Meaning |
|---|---|
resource | The protected public URL. Payment authorization is bound to this resource so it cannot be reused for another resource. |
method | The HTTP method for the protected resource, such as GET or POST. |
maxAmountRequired | The payment amount in the asset base unit. USDC has 6 decimals, so $0.01 is 10000. |
payTo | The merchant settlement wallet address that receives the payment. |
nonce | A one-time random value used to prevent the same authorization from being settled twice. |
How PolyPay fits in
PolyPay provides the x402 facilitator, merchant resource configuration, SDK middleware, and payment record management. Merchants do not need to implement signature verification, nonce locking, or on-chain settlement directly; they configure resource rules and use the SDK in server-side routes.