Documentation Index
Fetch the complete documentation index at: https://docs.swiftpay.finance/llms.txt
Use this file to discover all available pages before exploring further.
What is x402?
x402 is an open protocol that brings native payment to the HTTP layer. Instead of a checkout flow, your server returns anHTTP 402 Payment Required response when a caller has not yet paid. The
caller signs a USDC transfer authorisation and retries — your server verifies and settles through
SwiftPay, then serves the resource.
This is the right choice when you are charging per request rather than per invoice:
- API monetisation — charge per call without subscription management
- Metered access — pay-as-you-go data, AI, or compute endpoints
- Machine-to-machine payments — autonomous agents paying for on-chain services in real time
x402 is currently supported on EVM chains only (Base, Ethereum, Polygon). USDC is the accepted
token.
How it works
x402 uses a two-round HTTP flow between the caller, your server, and SwiftPay:Round 1 — No payment header
The client makes a normal HTTP request. Your middleware detects the missing
X-PAYMENT header,
calls SwiftPay to fetch PaymentRequirements for that route, and returns HTTP 402 with the
requirements JSON body.Client signs the payment
The client wallet signs an EIP-3009
TransferWithAuthorization — a pre-authorised USDC transfer
valid for 5 minutes. No transaction is broadcast at this point. The signed payload is
base64-encoded and placed in the X-PAYMENT request header.Round 2 — Retry with X-PAYMENT header
The client re-sends the same request with the
X-PAYMENT header attached.Middleware settles, then serves
Your middleware extracts the
X-PAYMENT header and calls POST /v1/x402/settle. SwiftPay
verifies the EIP-712 signature, atomically claims the nonce (replay protection), and executes the
on-chain USDC transfer. On success, your server sets the X-PAYMENT-RESPONSE header and serves
the resource.
Setup
1. Register a forwarder
Go to Dashboard → x402 → Forwarders and click New Forwarder. SwiftPay derives a CREATE2 address — no on-chain transaction yet. The forwarder is deployed automatically the first time you register an endpoint. The forwarder is the per-merchant smart contract that receives incoming USDC and splits it between your treasury wallet and the SwiftPay protocol fee.2. Register an endpoint
For each route you want to protect, register an endpoint via the API:payment_requirements object — the exact payload your middleware returns
inside the 402 body for this route.
Business server integration
Your server needs a middleware that implements the two-round gate. The middleware calls SwiftPay on every request — either to get requirements (round 1) or to settle (round 2).Idempotent payment check
If a client retries a request after a network timeout it may send the sameX-PAYMENT header
again. Before calling settle, check whether that nonce was already processed:
status values: not_found | pending | settled | failed.
If settled, serve the resource immediately without calling settle again. If pending, the
settlement is in progress — wait and retry. If failed, treat it as an unpaid request.
Webhook events
SwiftPay fires the following events after each x402 settlement attempt:| Event | Trigger |
|---|---|
x402.payment.settled | On-chain USDC transfer confirmed |
x402.payment.failed | On-chain transaction reverted or timed out |
API reference
Facilitator endpoints
supported, verify, settle, payment status
Endpoint management
register, list, deactivate, get requirements
