HostNexFlow › Library › x402 payments explained
x402 — machine-payable HTTP, explained
HTTP has had status code 402 "Payment Required" since 1991, reserved for a future nobody built. x402 finally builds it: a standard where a server can answer a request with a price, a client can pay in stablecoins, and the retried request returns both the resource and a settlement receipt — no accounts, no API keys, no invoices. This is how it works mechanically, and how our own paid lanes use it today.
The problem it solves
Every paid API on the internet requires the same dance: create an account, verify an email, generate a key, attach billing. Fine for humans — impossible for software that needs to buy a resource right now, once, for two cents, without an identity. Agents and scripts can't fill out Stripe onboarding. The missing primitive was a payment that lives inside the HTTP request itself — that's all x402 is. The resource stays a normal URL; the payment rides in headers.
The handshake, step by step
1. Client requests a resource — a plain GET/POST to a normal URL.
2. Server answers 402 with an offer body: a list of accepted payment options (accepts), each naming the scheme (ours uses exact — fixed price), the network, the asset (USDC), maxAmountRequired in atomic units, and the payTo address.
3. Client pays by constructing a payment payload — a signed USDC transfer authorization — and retrying the identical request with it in a header: X-PAYMENT on x402 v1, PAYMENT-SIGNATURE on v2 (both transport the same signed payload; the version split is a header-naming migration).
4. A facilitator verifies and settles: an off-chain service (ours is facilitator.payai.network) checks the signature, submits the transfer on-chain, and confirms settlement.
5. Server returns the resource plus a receipt header — X-PAYMENT-RESPONSE (v1) / PAYMENT-RESPONSE (v2) — a base64 JSON blob with the payer address, the transaction signature, and the network. The receipt is your proof, and it's verifiable on-chain.
The property that makes this honest: charge-on-success. A 402 offer is free — you're never billed for being told the price. Payment only settles when the server actually returns the resource; if settlement fails, the response is withheld and nothing is charged. An API that can't deliver doesn't get paid.
What we actually sell over it
Not a demo — a live price sheet. The full machine-readable list is at /.well-known/x402; representative resources as of this writing:
| Resource | Method | Price |
|---|---|---|
GET /api/v1/x402/token-risk/{chain}/{address} — A+–F token safety verdict | GET | $0.02 |
POST /api/v1/x402/token-risk — free-form query, resolved to top-liquidity match | POST | $0.02 |
GET /api/v1/x402/signals/solana/{mint} — pre-graduation on-chain signals | GET | $0.05 |
POST /api/v1/x402/rpc/{chain} — one JSON-RPC call on the 82-chain relay | POST | $0.002 |
POST /api/v1/x402/keys — a 30-day Agent API key minted inside the paid response | POST | $5 |
Payment settles in USDC on Solana to a published payTo address — you can read it off the manifest yourself. The standard paths (/v1/* with an API key, the keyless free tier) keep working; x402 is a lane alongside them, not a replacement.
Why agents specifically need this
An autonomous agent doing real work hits paid resources constantly — risk checks, RPC reads, datasets. Before x402 the options were all bad: pre-provisioned keys (a funding relationship per provider, and a leaked key leaks budget), pre-paid accounts (capital parked everywhere), or a human in the loop (not autonomous). A payment inside the request fixes the shape: the agent's wallet pays for exactly what it consumes, priced per call, with the receipt proving settlement. It also composes — a paid endpoint can itself call paid endpoints upstream, which is how agent economies actually chain. Our relay's RPC lane and the token-risk verdicts on the API docs are live instances of exactly that.
The honest limits
x402 is new infrastructure and the sharp edges are real: facilitator trust (settlement depends on the facilitator being reachable and honest — pick well-known ones), settlement latency (a paid call takes verify+settle+handler time, so paid endpoints answer slower than cached reads), no refund primitive beyond charge-on-success (if you got a bad-but-successful response, that's a dispute with the provider, not the protocol), and price discovery is per-server manifest, so standardization is still maturing across the ecosystem. It's also worth knowing what it's not: not a wallet-drain risk (the payment payload is a scoped transfer authorization for an exact amount, not an open approval), and not private (payments settle on a public chain like everything else).
Consuming it as a developer
Any standard x402 client handles the dance automatically: request, receive 402, pick an accepts option, sign the payment, retry, read the receipt. Hand-rolling is also reasonable — the payloads are plain JSON and the facilitator endpoints are documented — but the honest advice is to start from a client library, because the version skew between v1 (X-PAYMENT) and v2 (PAYMENT-SIGNATURE) headers is the sort of thing that silently breaks hand-rolled integrations. Our edge speaks both, which is the point of the dual-stack plumbing you'd otherwise never see.
If you're scanning tokens by hand rather than building, the human lane is /check-token — same verdicts, no payment. If you're deciding between a subscription and per-call, the free tier covers a hundred verdicts a day and the paid lanes start at $5 for a 30-day Agent key — the full picture is on /integrate.
Read the live manifest
The whole price sheet, one GET:
curl -s https://nexflowscan.com/.well-known/x402 | jq .
Frequently asked
What is x402 in simple terms?
A standard that lets a web server charge per request without accounts: the server answers HTTP 402 with a price, the client pays in stablecoin and retries the same request with the payment proof attached, and the server returns the resource along with an on-chain settlement receipt. It turns 'Payment Required' — a status code reserved since 1991 — into an actual mechanism, designed for software (agents, bots) that can't create accounts or manage API keys.
How does an x402 payment actually happen?
Five steps: (1) request the resource normally; (2) receive 402 with a list of accepted payment options — scheme, network, USDC amount in atomic units, payTo address; (3) sign a payment authorization and retry the same request with it in the X-PAYMENT header (v1) or PAYMENT-SIGNATURE (v2); (4) a facilitator verifies the signature and settles the transfer on-chain; (5) the server returns the resource plus a receipt header containing the transaction signature. You're only charged when the resource is delivered — a 402 itself never bills you.
What do I need to pay with x402?
A wallet holding USDC on the network the offer accepts (ours settles on Solana) and an x402-aware client that can sign the payment payload — either a library that handles the 402/retry flow automatically or a few lines that construct the exact-scheme payload by hand. There is no signup, no API key, and no account on the seller's side — the payment itself is the credential.
What's the difference between x402 v1 and v2?
Header names, mostly. v1 carries the payment proof in X-PAYMENT and the receipt in X-PAYMENT-RESPONSE; v2 renames the same three to PAYMENT-SIGNATURE and PAYMENT-RESPONSE (with the offer arriving as PAYMENT-REQUIRED). The signed payment payload underneath is the same idea — a scoped exact-amount authorization. Servers running both stacks advertise both; our edge proxies all of them so v1 and v2 clients see their own dialect.
What can I actually buy with x402 on NexFlow?
Per-call token-risk verdicts ($0.02), Solana pre-graduation on-chain signals ($0.05), authority quick-checks ($0.005), batch verdicts and portfolio audits ($0.15), JSON-RPC calls on the 82-chain relay ($0.002), a 30-day Agent API key ($5, minted inside the paid response), and datasets like the weekly safety snapshot ($0.25). The live machine-readable price list is the manifest at /.well-known/x402 — every price on this page is read from it.
Is x402 safe — can a malicious endpoint drain my wallet?
The payment payload is an exact-amount transfer authorization, not an approval: it can only move the stated USDC amount to the stated payTo address, once. That's meaningfully safer than handing a provider a card or an open token approval. The real risks are different: a malicious server can sell you garbage (pay two cents for a bad answer — check the provider's reputation), and settlement depends on the facilitator being honest and reachable. Treat the manifest like a menu: read the prices and the payTo before your client pays.