API-Keys & Authentifizierung

Die DEADBOX API ist standardmaessig offen — jeder kann sie ohne Account nutzen. Keys gibt es nur, um dir ein groesseres Tageskontingent zu geben, eine stabile Identitaet fuer Support und Zugang zu Pay-per-Use, sobald du ueber das Free-Tier hinauswaechst.

Anonymes Tier

Requests ohne Authorization Header werden pro IP gebuendelt und auf 500 Calls pro UTC-Tag begrenzt. Genug fuer Prototypen oder Dashboards mit wenig Traffic. Der Counter resettet um 00:00 UTC. Der Server liefert X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Unix-Sekunden) in jeder Response, damit du dich selbst drosseln kannst.

Key erstellen

POST https://api.deadbox.rip/api/keys mit dem signierten Body { ownerAddress, signature, message, label? }. Die Wallet muss mindestens $100 in DEAD + uDEAD kombiniert auf Base halten — ein Holding-Gate gegen triviales Spam-Minten. Die Response enthaelt key.publicId (gefahrlos loggbar) und ein einmaliges Secret im Format dbx_<publicId>_<32 hex>. Das Secret wird nur einmal angezeigt — speichere es wie ein Passwort. Free-Tier-Keys starten mit 2 000 Req/Tag, das Kontingent wird GETEILT zwischen allen Keys deiner Wallet.

Key verwenden

Sende das vollstaendige Secret bei jedem Request im Authorization-Header: Authorization: Bearer dbx_8f3a1c0d_…. Die Middleware schlaegt den Key per SHA-256-Hash nach, stempelt das Tier in die Response-Header und zaehlt den Call gegen dein Tageskontingent. Ungueltige oder widerrufene Keys erhalten 401.

Verbrauch pruefen

GET /api/usage gibt die heutige Request-Anzahl, das Tageskontingent, verbleibende Calls, eventuell bezahlte Overage und dein Prepaid-Guthaben zurueck. Funktioniert sowohl fuer anonyme als auch fuer Key-Aufrufer — ohne Key wird das anonyme IP-Bucket gemeldet.

End-to-End-Beispiele

Alle Snippets unten gehen von https://api.deadbox.rip als API-Host aus. Ersetze SECRET durch den Wert aus der Mint-Antwort. Wallet-Signatur-Minting geht am einfachsten ueber die API-Konsole im Browser — der curl-Payload ist exakt das, was /dashboard/api intern sendet.

bash
# Key minten — die Message vorher mit der Wallet signieren (z.B. cast / viem / ethers).
curl -X POST https://api.deadbox.rip/api/keys \
  -H 'Content-Type: application/json' \
  -d '{
    "ownerAddress": "0xdeineWallet…",
    "signature": "0x…65byteHex",
    "message": "DEADBOX API — mint API key\nAddress: 0xdeineWallet…\nIssued: 2026-05-12T14:30:00Z",
    "label": "meine-app"
  }'
# → { "key": { "publicId": "8f3a1c0d", … }, "secret": "dbx_8f3a1c0d_…" }

bash
# Key bei jedem Request mitschicken.
curl https://api.deadbox.rip/api/stats \
  -H 'Authorization: Bearer dbx_8f3a1c0d_…'
# Response-Header zeigen dir den Quota-Status:
# X-RateLimit-Limit: 2000
# X-RateLimit-Remaining: 1987
# X-RateLimit-Reset: 1747094400
# X-RateLimit-Tier: free

bash
# Verbrauch jederzeit pruefen.
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
# }