API Pricing & x402 Pay-per-Use

DEADBOX is free to use up to a generous daily quota — only heavy callers ever pay, and they pay only for what they use. There are no monthly subscriptions and no credit-card paywall. Overage flows through x402, the HTTP 402 Payment Required standard built on stablecoin transfers.

Daily-quota tiers

Anonymous (no header): 500 calls/day, free. Free key: 2 000 calls/day, free. Premium (verified uDEAD holder ≥ 0.1% of supply): 50 000 calls/day, free. Pay-per-use: no daily cap — every call after your free quota debits your prepaid USD balance at 0.0001 USD/call (i.e. 10 000 calls per $1). Quotas reset at 00:00 UTC.

Why x402?

x402 is a small spec on top of HTTP 402 that lets servers ask 'pay $X to keep going' and clients pay programmatically via on-chain stablecoin transfers — no API-key dashboards, no credit-card forms, no subscription lock-in. Pay $1 of USDC on Base, get 10 000 extra calls. Pay nothing, get nothing extra. Settles in seconds.

The flow

1) You hit a quota wall and the server returns 402 with a JSON body describing the asset (USDC), network (Base), payTo address, and price per call. 2) Your client sends USDC to that address and POSTs the tx hash + the key publicId to /api/sessions/prepay. 3) A background verifier confirms the on-chain transfer and credits the key's prepaid balance. 4) Subsequent requests succeed and silently debit the balance until it's empty.

Decoding the 402 response

Body shape: { x402Version: 1, error: 'payment_required', errorMessage: '…', accepts: [ { scheme: 'exact', network: 'base', asset: '0x833589fc…', assetSymbol: 'USDC', maxAmountRequired: '0.0001', payTo: '0x…', description: '…', docs: '…' } ] }. The accepts array can list multiple options (different chains or assets) as the protocol expands. Today only USDC on Base is supported.

json
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "error": "payment_required",
  "errorMessage": "Daily quota exhausted. Top up via x402 to continue.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "assetSymbol": "USDC",
      "maxAmountRequired": "0.0001",
      "payTo": "0xd1Df5a16e1b19De2997828eDfD457237F281412F",
      "description": "DEADBOX API — per-call price (USD)",
      "docs": "https://deadbox.rip/en/learn/wiki/developers/api-pricing"
    }
  ]
}

Registering an on-chain prepayment

After the USDC transfer mines, POST the tx hash + your wallet + the amount to /api/sessions/prepay. The verifier confirms it within ~60 seconds and credits the key.

bash
# 1. Send USDC on Base to the payTo address from the 402 body.
#    Any wallet works — Metamask, viem, ethers, cast.
# 2. Register the tx with the API.
curl -X POST https://api.deadbox.rip/api/sessions/prepay \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKeyPublicId": "8f3a1c0d",
    "txHash": "0xabc…",
    "payerAddress": "0xyourWallet…",
    "amountUsd": 1.00
  }'
# → { id, txHash, amountUsd, verified: false, message: "pending_verification" }
# Balance updates on the key within ~60s once the verifier confirms the on-chain transfer.