Skip to content
Sign in
Menu

Understand an HTTP 402 response

Read a NODRA quote field by field, and decide whether to pay it.

  • Tutorial
On this page

What you'll achieve

You can decode a quote, check it against your rules, and know exactly what you'd be paying.

Prerequisites

  • A gateway URL from the directory.
  • curl, base64 and jq, or any HTTP client.

1. Request without paying

ShellIllustrative values
curl -s -D headers.txt -o body.json 'https://gateway.example.com/v1/weather-forecasts/forecast?city=Lisbon'
cat body.json
# { "error": "payment_required", "quoteId": "q_3f9c…" }

2. Decode the header

Shell
grep -i '^payment-required:' headers.txt | cut -d' ' -f2 | tr -d '\r' | base64 -d | jq
JSONDecodedIllustrative values
{
  "x402Version": 2,
  "resource": {
    "url": "https://gateway.example.com/v1/weather-forecasts/forecast?city=Lisbon",
    "description": "Paid API weather-forecasts",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
      "amount": "13000",
      "asset": "<USDC mint for the network>",
      "payTo": "<the API's vault address>",
      "maxTimeoutSeconds": 60,
      "extra": {
        "feePayer": "<NODRA fee payer address>",
        "memo": "q_3f9c2a7b8e1d4c6a9b0e2f4d6c8a1b3e",
        "successPolicy": { "mode": "non_empty_2xx" },
        "priceBreakdown": { "providerPrice": "10000", "platformFee": "3000" }
      }
    }
  ]
}

3. Read each field

amount
What you'd pay, in base units: 13000 is 0.013 USDC. extra.priceBreakdown splits it into the provider's price and NODRA's fee.
network and asset
The Solana network and the USDC mint. Pay only if they're the ones you hold.
payTo
The API's vault. You pay its USDC token account, not the address itself.
extra.feePayer
NODRA's fee payer, which pays the network fee.
extra.memo
The quote id, which your transaction must carry as its memo.
extra.successPolicy
When you'll be charged. non_empty_2xx means only for a 2xx answer with a body.
maxTimeoutSeconds
60. Pay within that time or ask again.

4. Decide

Pay if the amount is within your limit and the network and asset match. Otherwise walk away: an unpaid quote simply expires.

Expected result

You know the exact cost, destination and billing rule of one call before any money moves.

Common mistakes

MistakeFix
Parsing amount as a floatUse a big integer. Amounts are base units.
Reusing a quote for a second callEach quote pays for one call. Ask again for each call.
Reading only the JSON bodyThe body has the quote id; the details are in the PAYMENT-REQUIRED header.