How do I add x402 payments to my API?

To add x402 payments to your API or web endpoint, you return an HTTP 402 Payment Required response with a payment challenge on protected routes. The client signs the challenge, pays the requested amount (typically in USDC), and submits the payment proof. Your endpoint verifies the proof via a facilitator, then serves the resource with an offline-verifiable receipt. This turns any web endpoint into a chargeable service without requiring upfront credentials or subscriptions.

x402 is the HTTP status code for "Payment Required." It is the standard way to monetize APIs, agentic workflows, and web endpoints without friction. Unlike subscriptions or API keys, x402 lets you charge per request, per byte, or per computation, and it works across any blockchain or payment rail. The flow is simple: your endpoint returns 402, the client pays, and you verify the payment before serving the resource.

The x402 payment flow, step by step

1. Protect your route with HTTP 402

On any route you want to monetize (for example, /api/data, /agent/task), return an HTTP 402 response with a payment challenge in the headers. The challenge includes: - The amount to pay (in USDC or another stablecoin). - A unique payment reference (a nonce or content-addressed identifier). - The facilitator's settlement address (where the client sends the payment). - A signature binding the challenge to your endpoint's identity.

The client must sign this challenge with their private key and include the signature in the payment transaction. This prevents replay attacks and ensures the payment is tied to the specific request.

2. Let the client sign and pay

The client receives the 402 response and constructs a payment transaction. They: - Sign the payment challenge with their private key (using RFC 9421 HTTP Message Signatures). - Send the payment (in USDC) to the facilitator's settlement address, including the signed challenge in the transaction memo or calldata. - Submit the transaction hash and signature back to your endpoint as proof of payment.

The facilitator verifies the payment onchain and issues a signed attestation that the payment was settled. This attestation is your receipt.

3. Verify the payment and serve the resource

Your endpoint receives the payment proof (the transaction hash and signature). It: - Queries the facilitator you run to verify the payment was settled and the challenge was signed correctly. - Checks that the payment amount matches the requested amount. - Serves the resource with an offline-verifiable receipt (a signed attestation from the facilitator).

The receipt is a tamper-evident record that the payment was made and the resource was delivered. It can be verified offline, without trusting your endpoint or the facilitator, using open tools like AlgoVoi's free verifier.

4. Optional: Add compliance and audit trails

For regulated use cases (for example, AI training data, clinical records, or financial APIs), you can: - Screen the client's wallet against sanctions lists (KYB/KYC) before serving the resource. - Bind the payment to a credential (for example, an agent passport or corporate identity) using Key Credential Binding (KCB). - Canonicalize the entire flow (challenge, payment, receipt) into a verifiable corpus for compliance (for example, EU AI Act, MiCA).

This turns x402 from a simple payment mechanism into a verifiable trust chain.

Do it with AlgoVoi

AV-RAILS is AlgoVoi's self-hosted x402 facilitator: the software you run yourself (SQLite-first, air-gap capable). It handles the payment challenge, settlement, and offline-verifiable receipt generation on infrastructure you control, so there is no hosted service to depend on and no per-request fees to a third party.

• Verify any signed request, free and offline: verify.algovoi.co.uk/rfc9421.
• Docs: start with the quickstart guide.
• Get AV-RAILS: available via the Suite Store.

Start with the free verifier, then run AV-RAILS yourself when you are ready to settle.