What does 402 Payment Required mean?
402 Payment Required is an HTTP status code an API uses to ask for payment before supplying a resource. With x402, the response includes a payment offer that the client can read, check and pay. The client signs one exact USDC authorization and sends the same request again with the signed payment attached.
| Item | Current state |
|---|---|
| Status | HTTP 402 Payment Required |
| vAPI payment support | x402 v2 exact, in USDC |
| Offer | PAYMENT-REQUIRED header and response body |
| vAPI Call | Launching. The console does not serve Call yet. |
| Checked on | 2026-10-02 |
Read the offer, not just the status
The status tells the client that payment is required. It does not by itself tell the client how much to pay, which asset to use or who receives it. Those details belong to the payment protocol in the response. A client needs a supported offer before it can sign anything.
An x402 v2 offer identifies the resource and its accepted payment options. Each option names the scheme, network, asset, amount, recipient (payTo) and timeout. The PAYMENT-REQUIRED header carries base64-encoded JSON. The JSON response body carries the offer too, so a client can inspect the fields rather than treating the 402 as an unexplained failure.
The live offer is authoritative. A directory may have recorded an earlier price or recipient. vapi-network reads the endpoint's 402 again before paying, then checks the live offer against the buyer's per-call and daily caps. Discovery helps find the API; it does not authorize the payment.
How x402 turns a 402 into a paid request
- Send the API request without a payment header. The API answers 402 with its current offer.
- Check the offer's scheme, network, USDC asset, amount and recipient against the client's policy and spending limits.
- Sign one EIP-3009 authorization locally. It fixes the amount, recipient, token, chain, nonce and validity window.
- Send the same request again, with the signed payment in the
PAYMENT-SIGNATUREheader. - The API has a facilitator verify and settle the payment onchain, then supplies the response and settlement evidence in
PAYMENT-RESPONSE.
The settling party submits the transaction, so the buyer pays no gas for the signed USDC authorization. vAPI Network never signs for the buyer and holds no buyer balance. The API's price and payout address remain part of its own offer, and the buyer-local client decides whether to accept them.
Inspect a 402 without paying
vapi check reads the unpaid response and checks its x402 conformance without signing a payment. This sample is copied from the x402 guide: vapi-network 0.7.0 checked the paid decoder on staging on 2026-10-02. Its title line is omitted, as in that guide.
$ vapi check https://api-staging.vapinetwork.ai/x402/decode --method POST
pass status HTTP 402 Payment Required.
pass transport The offer is in the PAYMENT-REQUIRED header and the body.
pass version Declares x402 version 2.
pass fields Every field x402 v2 requires is present and well-typed.
pass scheme 1 of 1 accepted option uses the exact scheme.
pass asset Pays canonical USDC on eip155:8453.
pass pay_to Every exact option names a well-formed payTo address.
pass timeout maxTimeoutSeconds 120.
pass extensions Advertises bazaar, builder-code, payment-identifier.
pass discovery Discovery document at https://api-staging.vapinetwork.ai/.well-known/x402 lists 1 resource.
pass openapi https://api-staging.vapinetwork.ai/x402/openapi.json declares x-payment-info for POST /x402/decode.
11 passed, 0 warnings, 0 failed.A passing check means the observed offer met those protocol checks at that time. It does not establish that a later paid request will succeed. The price can change, the endpoint can stop responding, or a settlement can be uncertain. Read the current offer each time you pay.
A 402 is not always payable through vAPI
vAPI pays x402 exact offers in canonical USDC on supported networks. External APIs may advertise upto or auth-capture schemes, which vAPI does not pay. The directory also recognizes MPP (Stripe/Tempo) payment challenges in WWW-Authenticate: Payment, but labels them as not payable here. The status code alone does not make an API compatible.
If the paid response is missing
A missing response is not proof that payment failed. vapi-network keeps a local receipt and can check the authorization's state onchain without signing again. If the API advertises payment-identifier, the same identifier and request fingerprint can retrieve a cached response without a second settlement. Check the receipt before starting another payment.