API Keys & Authentication

The DEADBOX API is open by default — anyone can hit it without an account. Keys exist to give you a larger daily quota, a stable identity for support, and access to pay-per-use overflow once you grow past the free tier.

Anonymous tier

Requests without an Authorization header get bucketed by IP and capped at 500 calls per UTC day. Plenty for prototyping or low-traffic dashboards. The bucket resets at 00:00 UTC. The server returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds) on every response so you can pace yourself.

Creating a key

POST https://api.deadbox.rip/api/keys with the signed body { ownerAddress, signature, message, label? }. The wallet must hold at least $100 combined in DEAD + uDEAD on Base — a holding gate that prevents trivial spam-minting. The response contains the key.publicId (safe to log) and a one-time secret of the form dbx_<publicId>_<32 hex>. The secret is shown only once — store it like a password. Free-tier keys ship with a 2 000 req/day quota that is SHARED across every key your wallet owns.

Using the key

Send the full secret in the Authorization header on every request: Authorization: Bearer dbx_8f3a1c0d_…. The middleware looks up the key by SHA-256 hash, stamps the tier on the response headers, and counts the call against your daily bucket. Invalid or revoked keys get a 401.

Checking your usage

GET /api/usage returns today's request count, daily quota, remaining calls, any paid overage, and your prepaid balance. Works for both anonymous and keyed callers — when no key is presented it reports the anonymous IP bucket.

End-to-end examples

All snippets below assume the API host is https://api.deadbox.rip. Replace SECRET with the value returned by the mint call. Wallet-signature minting is most easily done in the browser via the API Console — but the curl payload shape is identical to what /dashboard/api sends.

bash
# Mint a key — sign the message with your wallet first (e.g. cast / viem / ethers).
curl -X POST https://api.deadbox.rip/api/keys \
  -H 'Content-Type: application/json' \
  -d '{
    "ownerAddress": "0xyourWallet…",
    "signature": "0x…65byteHex",
    "message": "DEADBOX API — mint API key\nAddress: 0xyourWallet…\nIssued: 2026-05-12T14:30:00Z",
    "label": "my-app"
  }'
# → { "key": { "publicId": "8f3a1c0d", … }, "secret": "dbx_8f3a1c0d_…" }

bash
# Use the key on every subsequent request.
curl https://api.deadbox.rip/api/stats \
  -H 'Authorization: Bearer dbx_8f3a1c0d_…'
# Response headers carry your quota state:
# X-RateLimit-Limit: 2000
# X-RateLimit-Remaining: 1987
# X-RateLimit-Reset: 1747094400
# X-RateLimit-Tier: free

bash
# Check today's usage at any time.
curl https://api.deadbox.rip/api/usage \
  -H 'Authorization: Bearer dbx_8f3a1c0d_…'
# → {
#   "identity": "key:dbx_8f3a1c0d",
#   "tier": "free",
#   "requestCount": 13,
#   "dailyQuota": 2000,
#   "remaining": 1987,
#   "overageCount": 0,
#   "prepaidBalanceUsd": 0.0,
#   "resetUnix": 1747094400
# }