# 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.
Source: https://docs.ozmium.org/agents/x402/
Keywords: x402 payment protocol, http 402 payment required, eip-3009 transferwithauthorization, usdc micropayment api, machine payable api base
Updated: 2026-07-27
---

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

| Header | Direction | Purpose |
|---|---|---|
| `PAYMENT-REQUIRED` | Response (402) | The Challenge |
| `PAYMENT-SIGNATURE` | Request | Your Signed EIP-3009 Authorization |
| `X-PAYMENT` | Request | Accepted alias for older x402 tooling, same value |
| `X-PAYMENT-RESPONSE` | Response (200) | Onchain Settlement Receipt |

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

## Minimal Example

```bash
# 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](/guides/prop-desk/).

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.

:::warning Never hardcode a price
Read the amount from the 402 challenge on every call and sign that exact amount. A client that
hardcodes a price out of documentation will start failing the moment pricing moves, and it will fail
in the least helpful way possible.
:::

## 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.

:::note Why OZ is not simply an accepted settlement asset
x402's `accepts[]` requires EIP-3009, and OZ does not implement it. That is a fact about the standard
rather than a decision on our end. The credit rail is how OZ pays the toll regardless, and it lands
you 50 percent under the posted price with the surge exemption on top.
:::

| Header | Purpose |
|---|---|
| `X-OZ-TOPUP: <txHash>` | Register an OZ transfer as prepaid credit. Once per hash, under 24h old. |
| `X-OZ-CREDIT: off` | Skip available credit and settle this call in USDC. |

## 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

### What is x402?

x402 is an HTTP payment protocol that revives the HTTP 402 Payment Required status code. A server
answers an unpaid request with a 402 and a machine-readable payment challenge; the client signs a
payment and retries. Ozmium uses x402 v2, `exact` scheme, on Base mainnet.

### Which token does Ozmium accept for x402?

USDC on Base, contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, settled via EIP-3009
`transferWithAuthorization`. There is no other accepted payment asset for API calls.

### Do I need to approve USDC before paying?

No. EIP-3009 authorizes the exact transfer in the signature itself, so there is no prior ERC-20
approve transaction. That is the reason x402 uses it.

### Which headers does Ozmium accept?

`PAYMENT-SIGNATURE` on the request, with `X-PAYMENT` accepted as an alias for older x402 tooling.
Both take the same value. Successful responses carry `X-PAYMENT-RESPONSE` with the onchain settlement
receipt.

### Can I verify that my payment settled onchain?

Yes. Every payment is a real USDC transfer on Base. The `X-PAYMENT-RESPONSE` header carries the
settlement receipt and the transfer is visible on Basescan. There is no off-chain ledger to trust.

### Does paying x402 give me prop desk access?

No. The x402 fee pays for the API call only. Prop desk actions additionally require a real onchain OZ
transfer passed as `payTxHash` or `burnTxHash`.

### What is the cheapest way to call the Ozmium API?

Prepaid OZ credit. It covers calls at half the posted USDC price and is exempt from congestion surge,
so it is cheaper at rest and much cheaper in a hot window. Top up by sending OZ to the credit
recipient and passing `X-OZ-TOPUP: <txHash>` once.

### How much can prices surge?

The congestion multiplier is capped at 2x, and prepaid OZ credit is exempt from it entirely.

## Related

- [Agent API Overview](/agents/overview/)
- [Endpoint Catalog](/agents/endpoints/)
- [Integration Notes](/agents/integration/)