x402 payments

x402 is an HTTP-native payment protocol for paid APIs and paid content.

A protected endpoint returns 402 Payment Required with payment requirements. The client signs payment data and retries with a PAYMENT-SIGNATURE header. A facilitator verifies and settles the payment on Radius.

Radius is a strong fit for this model because fees are low and predictable.

Start with radius-sdk

Use radius-sdk when it fits your stack. It handles the challenge, signing, the Permit2 approval and its gas sponsoring, settlement through the Radius facilitator, and receipts, with SBC and the Radius network as defaults:

• Accept payments: charge for routes in a Hono app, including Cloudflare Workers.
• Make payments: pay from TypeScript in any runtime with fetch, including browsers. From a terminal or an agent shell, use radius-cli.

Build against the protocol directly only when the SDK does not fit, for example another server framework or another language. radius-sdk speaks standard x402 v2, so any compliant x402 client can pay a radius-sdk endpoint, and radius-sdk can pay any x402 v2 endpoint on Radius. The rest of this page and the facilitator API reference give the values a direct integration needs.

What you can build with x402

• Per-request API billing: charge per call with immediate settlement
• Content access: charge for a single article, feed, or download
• Streaming payments: combine x402 with recurring payment loops for compute and inference workloads

Request lifecycle

1. Client requests a protected resource.
2. Server responds with 402 Payment Required and a PAYMENT-REQUIRED header listing the payments it accepts.
3. Client signs a payment for one offer and retries with a PAYMENT-SIGNATURE header.
4. Server sends the payment to a facilitator, which verifies it and settles it on Radius.
5. Server returns the resource with a PAYMENT-RESPONSE header that carries the transaction hash.

The Radius payment challenge

The PAYMENT-REQUIRED header holds a Base64-encoded JSON PaymentRequired object; the response body carries no protocol data. This is the decoded challenge radius-sdk sends for a 0.1 SBC route on mainnet, with the extension's JSON Schema omitted:

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.example.com/premium/report",
    "description": "Premium report",
    "mimeType": ""
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:723487",
      "amount": "100000",
      "asset": "0x33ad9e4BD16B69B5BFdED37D8B5D9fF9aba014Fb",
      "payTo": "0x{{MERCHANT_ADDRESS}}",
      "maxTimeoutSeconds": 300,
      "extra": {
        "assetTransferMethod": "permit2",
        "name": "Stable Coin",
        "version": "1",
        "paymentFlow": "upfront"
      }
    }
  ],
  "extensions": {
    "eip2612GasSponsoring": {
      "info": { "description": "…", "version": "1" },
      "schema": {}
    }
  }
}

The client answers with a PAYMENT-SIGNATURE header: a Base64-encoded PaymentPayload that echoes the chosen offer in accepted and carries a Permit2 permitWitnessTransferFrom signature. The spender is the canonical x402ExactPermit2Proxy (0x402085c248EeA27D92E8b30b2C58ed07f9E20001), which only transfers to the payTo address. When the payer has not approved Permit2 yet, the payload also carries the EIP-2612 permit under extensions.eip2612GasSponsoring. See the x402 exact EVM scheme spec for every field, and the x402 facilitator API for /verify and /settle.

Choose a facilitator

Radius (recommended)

The Radius facilitator settles each payment in one atomic call through the Permit2 proxy and pays all gas. It exposes /supported, /verify, /settle, and /health; it is the default in radius-sdk. Integrators do not need to know its settlement wallet addresses. Query the endpoint you plan to use before deployment:

curl https://facilitator.radiustech.xyz/supported
curl https://facilitator.testnet.radiustech.xyz/supported

Other facilitators

erc2612 is Stablecoin.xyz's own transfer method, not part of the x402 exact EVM scheme, which defines eip3009 and permit2. radius-sdk, radius-cli, and other standard x402 clients cannot pay it; payers need a client that supports Stablecoin.xyz's format. They are therefore not failover targets for payments made with radius-sdk or radius-cli. See the Stablecoin.xyz x402 documentation to integrate with it.

To use your own facilitator with radiusPayments, pass facilitator: { url, apiKey } for one that serves the x402 facilitator API, or a FacilitatorClient from @x402/core/server.

SBC and transfer methods

The token determines which x402 transfer methods are available:

Because SBC has no EIP-3009, Radius payments use Permit2. The payer grants Permit2 an allowance once, through a gas-sponsored EIP-2612 permit or an approval transaction. After that, each payment is a separate Permit2 signature capped to its amount, settled in one transaction.

Check settlement and delivery

radius-sdk performs these checks for you. If you verify payments yourself, check the payment against your own requirements before settling:

• scheme, network, asset, and payTo match what you offered
• amount is at least the price, in six-decimal base units
• the signature is valid and the validity window has not expired

After settlement, store the transaction hash with an idempotency key so a retried request does not charge twice. The PAYMENT-RESPONSE header carries the hash; to reconcile a payment on-chain, use getSettlement(radiusTestnet, txHash) (or radiusMainnet) from radius-sdk/client.

With settle-before-handler (the radius-sdk default), a payment can succeed while the resource fails to deliver. Log the transaction hash with the failure so you can serve the resource again or refund.

Recover from failed or uncertain payments

One rule applies to buyers and sellers: before authorizing another payment, find out whether the first one settled. Checking status, delivering a paid resource again, and signing a new payment are different actions.

radiusPayments answers 502 with facilitator_error when the facilitator fails or cannot be reached, at verification or settlement, so a buyer must treat a 502 as uncertain. A definite settlement failure is a 402.

Check status

• With a transaction hash, from the PAYMENT-RESPONSE header or the seller's logs: getSettlement(radiusTestnet, txHash) (or radiusMainnet) from radius-sdk/client. undefined means the node does not know the transaction yet, not that it failed.
• Without one: the seller can check whether the payment's Permit2 nonce has been used, with isPermit2NonceUsed(client, { owner, nonce }) from radius-sdk/client (or the permit2Actions() action). owner and nonce are payload.permit2Authorization.from and .nonce in the base64 JSON of the request's PAYMENT-SIGNATURE header; radiusPayments does not pass them to the handler, so log the header if you need this check. Until the authorization's deadline passes, an unused nonce can still be settled; after it, an unused nonce means the payment did not settle. The buyer can ask the seller.

Retry or pay again

• Submitting the same signed payment again cannot charge twice: each Permit2 nonce can be used once.
• Signing a new payment while the first is uncertain can charge twice. Calling the payFetch from createRadiusFetch or radius-cli wallet x402 again signs a new payment.
• Switch facilitators only to one that supports the same scheme and transfer method (exact with permit2 on Radius). Today that is the Radius facilitator; the other facilitators are not substitutes for radius-sdk payments.

Troubleshooting

"No available wallets in pool"

This error from the facilitator /settle endpoint means the facilitator's internal pool of settlement wallets is temporarily exhausted. This is a facilitator operational issue, not a client-side or payer-wallet problem.

Retry after a brief delay (1-2 seconds). If persistent, contact the facilitator operator.

502 from facilitator

The facilitator failed or could not be reached. During settlement the payment may still have settled, so check before paying again; see recover from failed or uncertain payments.

"Permit expired"

The validBefore or deadline timestamp in the payment authorization has passed. The paying client needs to re-sign with a fresh deadline.

Client refuses to pay

radius-sdk and radius-cli refuse offers before signing when the network, asset, or transfer method does not match, or the price is above the cap. The SDK's RadiusPaymentError.code names the reason, for example network_mismatch, asset_mismatch, unsupported_transfer_method, or price_above_limit.

Related pages

• Accept payments
• Make payments
• radius-sdk reference
• radius-cli
• x402 facilitator API
• Contract addresses
• Agent payments
• Workshop playground
• Network and RPC