x402 payments and Stripe MPP: let your AI agent top up its own balance

x402 and MPP, in one sentence each

Both are open protocols built on the HTTP status 402 Payment Required: the server says what to pay, the client pays and repeats the request. On QuanticData they do one thing only: they add credit to the balance of the API key that made the call. They never buy a single call and never change a price.

• x402 is an open payment protocol, published by Coinbase and maintained by the x402 Foundation: your agent signs a USDC payment from its own wallet, and QuanticData settles it on the Base network.
• MPP, the Machine Payments Protocol, is the open standard Stripe and Tempo published for agent payments over HTTP: QuanticData accepts it with Stripe Shared Payment Tokens, a one-time permission, capped to one amount, to charge your card in Link.

Why you would turn it on

• The agent does not stop at an empty balance. A job that runs overnight keeps going: the top-up and the call happen in the same request, and the call is billed at list price like any other.
• No card form, no dashboard. Nobody opens a checkout page: the payment travels as a header on the API request the agent was already making.
• Pay in USDC if you prefer. x402 takes USDC on Base, with no VAT and no card, and the wallet needs nothing else: QuanticData pays the network fee.
• You keep the limits. A cap per payment in the client, a monthly budget on the account and a key you can revoke, all explained below.
• The free tier comes first. Every account has $2 of free API usage a month; the 402 appears only when that and the balance together cannot cover the next call.

What you need

Give the agent a wallet of its own and keep in it only what you are happy for it to spend. Its private key lives where the agent runs, in an environment variable next to the API key, never in code, logs or chat.

Set up x402 in five steps

1. Get an API key. Create one on the API keys page, or let the agent register itself with your email. The key decides which balance is topped up.
2. Fund a wallet with USDC on Base. Send USDC on the Base network, not on Ethereum mainnet, to the wallet the agent will use, and put its private key in the agent's environment, for example WALLET_PRIVATE_KEY next to QD_API_KEY. No ETH is needed.
3. Give the agent an x402 client with a cap. Install @x402/fetch or the Python x402 package and wrap the HTTP client the agent already uses, as in the code below. Set the cap per payment: both clients refuse anything above $1 by default, and a QuanticData top-up starts at $5, so $20 is a sensible first cap.
4. Let it run. When the balance is short, the call answers 402, the client signs the amount offered, repeats the call and returns the result. To top up ahead of time instead, the agent sends POST /v1/billing/x402-topup with {"amount_usd": 20}.
5. Check the first payment. The credit shows on the balance in the dashboard, the invoice, with no VAT, reaches the account's email, and the response header PAYMENT-RESPONSE carries the Base transaction hash.

Set up MPP in four steps

The simplest way to hold Shared Payment Tokens yourself is Link, Stripe's wallet, through its command-line tool. An agent platform that issues the tokens for you works the same way from step 3.

1. Get an API key. The same as for x402: the payment tops up the balance of the key that made the call.
2. Sign in to Link where the agent runs. Run npx @stripe/link-cli auth login, keep a card in your Link wallet and the Link app on your phone for approvals.
3. Let the agent pay through the Link CLI when the balance is short. npx @stripe/link-cli mpp pay sends the call with the API key, reads the 402, asks Link for a token of the exact amount ($6.10 for $5 of credit with VAT), sends you a request to approve in the Link app, then pays and repeats the call. The command is in the code below.
4. Check the invoice. A numbered invoice with 22% VAT is emailed to the account, and the credit appears on the balance with the Stripe payment reference.

Link asks you to approve each request within 30 minutes, and each token pays once: the next top-up is a new request.

Limits, VAT and invoices

Both ways buy the same thing, credit on the prepaid balance of your account, which does not expire. The call is then billed from it at the published price, and a failed call is not billed.

An account can pay up to 30 MPP top-ups a minute and 2,000 a day. Unit prices for every call are on the pricing page and in llms.txt.

See every top-up, and stop it when you want

• See it. Every top-up is a row in the balance history and an invoice on the invoices page, and the same invoice is emailed to the account. The agent gets the Base transaction hash (x402) or the Stripe payment reference (MPP) in the response.
• Cap each payment. The x402 client refuses any offer above the cap you set in it; Link asks you to approve every MPP payment.
• Cap the month. In Billing, under Spend controls, set a monthly Data API budget with the hard stop on. Once it is reached the API answers 402 BUDGET_REACHED, which carries no payment offer, so the agent cannot top up again until next month or until you raise it.
• Get an alert. The same Spend controls send an email, or a webhook, when the balance falls under the amount you choose.
• Stop everything. Revoke the key on the API keys page: the agent can no longer call, and no payment can be credited without a valid key. For x402 you can also empty the agent's wallet; for MPP, remove the card from Link.

For developers: one 402, two offers

Every call made with an API key that answers 402 INSUFFICIENT_FUNDS carries both offers, as long as the shortfall is at most $500. The body is the usual error envelope; the offers travel in two headers, PAYMENT-REQUIRED for x402 and WWW-Authenticate: Payment for MPP.

curl -i https://api.quanticdata.io/v1/serp \
  -H "Authorization: Bearer $QD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"best espresso grinder","engine":"google","country":"us"}'

HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…        # x402 version 2, base64 JSON
www-authenticate: Payment id="…", realm="api.quanticdata.io", method="stripe", intent="charge",
  request="eyJhbW91bnQiOiI2MTAi…", expires="…", description="…", opaque="…"

{"type":"error","message":"Your free tier for this month is used up …",
 "payload":{"code":"INSUFFICIENT_FUNDS","estimated_cost":0.002,"balance":0,"free_remaining":0}}

Decoded, PAYMENT-REQUIRED holds one exact requirement in USDC base units (6 decimals). payTo is QuanticData's own wallet: read it from the offer, never hardcode it.

{
  "x402Version": 2,
  "resource": { "url": "https://api.quanticdata.io/…", "serviceName": "QuanticData Data API", … },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "5000000",
    "payTo": "0x…",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

You can see a real offer now, without a key or a wallet: the top-up endpoint answers 402 with the requirements for the amount you ask. We ran it on 30 October 2026; a payment sent without a key is refused with 401 before anything is charged.

curl -i -X POST https://api.quanticdata.io/v1/billing/x402-topup \
  -H "Content-Type: application/json" -d '{"amount_usd":20}'

HTTP/2 402
payment-required: eyJ4NDAyVmVyc2lvbiI6Mi…        # accepts[0].amount "20000000" = 20 USDC

{"x402Version":1,"error":"Pay $20 in USDC on eip155:8453 and retry this request with the payment
 header and Authorization: Bearer <API key> (the key whose balance is topped up)","accepts":[…]}

MPP: the credential, and a test with Link

The challenge in WWW-Authenticate is paid by repeating the same request with Authorization: Payment <credential> (or Payment-Authorization). The credential is base64url JSON of every challenge parameter, unchanged, plus the token. The challenge is bound to your key and account, so the paid request needs no Bearer header. amount is in cents and already includes VAT: "610" for $5 of credit.

# the paid request: same method, URL and body as the call that got the 402
Authorization: Payment base64url({"challenge":{"id":"…","realm":"api.quanticdata.io","method":"stripe",
  "intent":"charge","request":"…","expires":"…","description":"…","opaque":"…"},"payload":{"spt":"spt_…"}})

→ 200 { …the search… }
  Payment-Receipt: base64url({"status":"success","method":"stripe","reference":"pi_…","timestamp":"…"})
  X-MPP-Credited: 500          # credit added, in cents
  X-MPP-Invoice: <invoice id>

To try it yourself, Stripe's Link CLI does the whole round trip: it calls the URL, reads the challenge, creates a spend request for a Shared Payment Token scoped to QuanticData, waits for your approval in the Link app and repeats the call with the credential.

npx @stripe/link-cli auth login

npx @stripe/link-cli mpp pay https://api.quanticdata.io/v1/serp \
  --header "Authorization: Bearer $QD_API_KEY" \
  --data '{"query":"best espresso grinder","engine":"google","country":"us"}' \
  --context "Top up my QuanticData API balance with 5 USD of credit plus 22% VAT, 6.10 USD in all, so my research agent can keep running searches."

# 1. the network id (QuanticData's Stripe profile) is inside the challenge
npx @stripe/link-cli mpp decode --challenge 'Payment id="…", realm="api.quanticdata.io", method="stripe", …'

# 2. a one-time token for the exact amount, approved in the Link app
npx @stripe/link-cli spend-request create \
  --credential-type shared_payment_token \
  --network-id profile_… \
  --amount 610 --currency usd \
  --context "At least 100 characters on what the payment is for: a QuanticData balance top-up of 5 USD plus VAT." \
  --request-approval

# 3. pay and repeat the call with the approved request
npx @stripe/link-cli mpp pay https://api.quanticdata.io/v1/serp \
  --spend-request-id lsrq_… \
  --header "Authorization: Bearer $QD_API_KEY" \
  --data '{"query":"best espresso grinder","engine":"google","country":"us"}'

Until the free allowance and the balance are used up, the call simply runs and nothing is paid: the Link CLI returns the response as it is.

Answers an agent should handle

The full reference, with every header and problem type, is in the Agents tag of the API documentation.