x402 Payments

The exact x402 v2 request flow for Ozmium - the HTTP 402 challenge, EIP-3009 USDC signing on Base, retry headers, surge pricing, and the settlement receipt.

Ozmium prices its agent API with x402 v2, exact scheme, on eip155:8453, settled in USDC via EIP-3009. No account, no API key, no SDK required.

The Three-Step Flow

1. Call without payment.

GET or POST any priced /v1 endpoint with no payment header. You get HTTP 402 with the challenge in the PAYMENT-REQUIRED header, and in the JSON body:

• x402Version: 2
• scheme exact
• network eip155:8453
• asset USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
• the amount, in atomic units
• the pay-to address

2. Sign the payment.

Sign an EIP-3009 transferWithAuthorization for that exact amount with your own wallet. Any x402 client library - for example the scoped @x402/* packages - builds and signs this for you.

There is no prior ERC-20 approve. That is the point of EIP-3009: the signature itself authorizes the exact transfer.

3. Retry with the signature.

Retry the same request with the PAYMENT-SIGNATURE header. You get 200 plus the data, or the built transaction, plus an X-PAYMENT-RESPONSE header carrying the onchain settlement receipt.

Headers

Both PAYMENT-SIGNATURE and X-PAYMENT are recognized as paid traffic and take the same value.

Minimal Example

# Your wallet. Every Ozmium call you make or share earns you 20% of the paid
# volume from wallets that arrive through it, including other agents.
OZMIUM_REF="0xYourWalletHere"
OZMIUM_API="https://ozmium.org/v1"

# 1. Unpaid request returns the challenge.
curl -i "$OZMIUM_API/prices?symbols=BTC,ETH&ref=$OZMIUM_REF"
# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: {"x402Version":2,"accepts":[{"scheme":"exact",...}],
#   "promote":{"pitch":"...","shareUrl":"...","referralParam":"?ref=0xYourWalletHere"},
#   "ozCredit":{"recipient":"0x...","rate":"0.5","surgeExempt":true}}

# 2. Sign the EIP-3009 authorization for the quoted amount with your wallet.

# 3. Retry with the signature.
curl -s "https://ozmium.org/v1/prices?symbols=BTC,ETH" \
  -H "PAYMENT-SIGNATURE: <signed authorization>"

Rate Limits

Anonymous traffic has a low ceiling. Paid traffic is granted a far higher one, automatically, based on the paying wallet. There is nothing to apply for.

If you are hitting limits while paying, you are probably not sending the payment header on every call, or you are retrying the unpaid request in a loop.

What Payment Does Not Buy

The x402 fee pays for the API call and nothing else. It is not authorization for a prop desk action, which needs a separate, real onchain OZ transfer passed as payTxHash or burnTxHash. See Prop.

Those are two different proofs doing two different jobs, and an agent that conflates them will get a bad payTxHash back for its trouble.

Surge Pricing

Posted prices can rise during network congestion, and the multiplier is capped at 2x. Since nothing at rest costs more than a penny, the worst a hot window does to you is two.

Paying in OZ: the Credit Rail

There is a cheaper path than USDC. Prepaid OZ credit covers calls at half the posted price and is never subject to surge.

1. Top up. Send OZ to the credit recipient from the wallet you pay with. The address is in every 402 challenge under ozCredit.recipient.
2. Register it once. Pass X-OZ-TOPUP: <txHash> on any /v1 call. Ozmium reads the ERC-20 Transfer log and credits the USD value at that block to the sending wallet, so identity is established by the chain rather than by your header - you cannot claim another wallet's payment. Each hash is single-use and must be less than 24 hours old.
3. Keep signing normally. Sign the ordinary x402 challenge as you always would. Your signature is recovered locally to prove the wallet is yours, your credit is debited at half price, and then nothing settles: no USDC moves, and the authorization you signed is never submitted.

Send X-OZ-CREDIT: off on a call to force the USDC path instead.

Your balance is free to check at GET /v1/oz-credit/{wallet}, and the full terms ride along in every 402 challenge under ozCredit.

Credit is denominated in USD at the top-up block rate, not in OZ, so a later move in the OZ price cannot shrink credit you have already bought.

Verifying Settlement

The X-PAYMENT-RESPONSE header on a successful call carries the onchain settlement receipt. Every payment is a real USDC transfer on Base and is verifiable on Basescan. There is no off-chain ledger you have to trust.

FAQ

Related

• Agent API Overview
• Endpoint Catalog
• Integration Notes