x402 payments

The payment flow

The API uses the HTTP 402 Payment Required status as a negotiation mechanism:

1. Your client sends the intended request without payment proof.
2. The server returns acceptable payment requirements, including asset, amount, network, and payee.
3. The client checks the requirement against its policy and signs a payment authorization.
4. It retries the same request with the payment payload.
5. The server verifies and settles the payment before returning the resource.

Set a maximum payment

Treat payment requirements as untrusted input. A production client should compare the challenge against /v1/pricing, enforce a hard maximum amount, allow only expected networks and assets, and verify the payee.

Safe retries

Network failures can occur after a payment is accepted but before the response reaches your client. x402labs supports payment identifiers so a compatible retry can replay the cached response instead of charging twice.

Preserve your client's payment identifier across a retry. Do not create a new payment authorization until you know the original attempt cannot be recovered.

Keep keys out of the browser

This documentation site never asks for or stores wallet secrets. Run paid calls from a trusted agent, backend, CLI, or wallet-aware runtime. A browser playground is intentionally not included.

Public metadata

• /v1/pricing exposes current route prices and networks.
• /openapi.json exposes request and response contracts.
• x402 Bazaar metadata lets compatible discovery systems index paid resources.