07 - API-Referenz¶

Dokument: Vollständige API-Endpunkt-Dokumentation Stand: 28.02.2026 Scope: Alle 41 API-Routes in /pages/api/ Status: Audit-ready

Übersicht¶

Kategorie	Endpunkte	Beschreibung
Player	1	Spieler-Initialisierung
Buy Flow	6	Ticket-Kauf-Prozess
Claim	4	Gewinn-Auszahlung
User	7	Benutzerdaten & Profil
Public	4	Öffentliche Statistiken
Admin	4	Administration
KYC	2	Identitätsverifizierung
Push	2	Push-Benachrichtigungen
Telegram	1	Bot-Webhook
Charity	2	Charity-Voting
Sonstige	8	Logging, Maintenance, etc.

1. Player-Initialisierung¶

POST /api/player/init¶

Kombinierter Login-Endpoint: Lädt Spieler-Stats, Pool-Daten und Claim-Status in einem Call.

Request:

{ "address": "0x...", "ref": "0x..." }

Response:

{
  "player": { "todayTickets": 5, "todayTips": 12, "todayWins": 1 },
  "pools": {
    "jackpots": { "0": 150.25, "1": 340.50, ... },
    "jackpotReserves": { ... },
    "noHitStreaks": { "0": 3, ... },
    "charityTotal": 1250.00
  },
  "claims": {
    "winnerCount": 2, "winnerTotal": "5000000",
    "affiliateCount": 1, "affiliateTotal": "250000",
    "totalCount": 3, "totalAmount": "5250000",
    "hasClaims": true,
    "affiliateLocked": false
  },
  "affiliate": "0x..."
}

Affiliate-Binding: Nur beim Erst-Login, verhindert Self-Referral, Default-Rate: 500 BP (5%)

2. Buy-Flow-Endpoints¶

POST /api/buy/intent¶

Erstellt einen Kauf-Intent mit EIP-712 Permit.

Parameter	Typ	Pflicht	Beschreibung
buyer	address	Ja	Wallet-Adresse
chainId	number	Ja	Chain ID
poolId	0-4	Ja	Pool/Tier
tips	number[][]	Ja	Array von 6-Zahlen-Arrays
paidTipCount	number	Nein	Bezahlte Tips
bonusTipCount	number	Nein	Bonus-Tips

Errors: 400 (Input), 403 (Self-excluded/Limit), 409 (TX in progress), 503 (Maintenance)

POST /api/buy/confirm-signature¶

Validiert EIP-712 Signatur, generiert Extra-Bonus-Proof.

Parameter	Typ	Beschreibung
intentId	uuid	Intent-ID
nonce	hex	Permit-Nonce
signature	hex	EIP-712 Signatur

POST /api/buy/submit-tx¶

Relayer sendet buyTicketFor-Transaktion on-chain.

Parameter	Typ	Beschreibung
intentId	uuid	Intent-ID
signature	hex	EIP-712 Signatur

POST /api/buy/confirm-tx¶

Bestätigt TX-Completion, fügt Tickets/Tips in DB ein.

Parameter	Typ	Beschreibung
intentId	uuid	Intent-ID
txHash	hex	TX-Hash (optional)

POST /api/buy/resume-intent¶

Wiederaufnahme unterbrochener Intents.

Parameter	Typ	Beschreibung
intentId	uuid	Intent-ID

POST /api/buy/gas-faucet¶

ETH für Erst-Approval senden.

Parameter	Typ	Beschreibung
intentId	uuid	Intent-ID
wallet	address	Ziel-Wallet

Anti-Abuse: Max 20 unrecouped, 50/Stunde, nur Web3Auth, 1/Wallet

3. Claim-Endpoints¶

GET /api/claim/payload¶

Claims + Merkle Proofs laden (signierte Anfrage).

Headers: | Header | Beschreibung | |---|---| | x-claim-address | Wallet-Adresse | | x-claim-signature | ECDSA-Signatur | | x-claim-timestamp | Unix-Timestamp |

Einschränkungen: Max 20 Claims/Batch, Affiliate nur Sonntags, 5+ Tips/6 Tage

POST /api/claim/execute¶

Claim via Relayer on-chain ausführen.

Request: permit, signature, winnerClaims[], affiliateClaims[] Response: txHash, gasUsed, gasCostUsdt, netPayout

POST /api/claim/optimistic-update¶

DB-Update nach TX-Submission (vor Confirmation).

GET /api/claim/debug¶

Debug-Endpoint ohne Signatur: On-chain vs. DB-Status-Vergleich.

4. User-Endpoints¶

GET /api/user/profile?address=0x...¶

Vollständiges Benutzerprofil.

Response-Felder: walletAddress, firstName, lastName, email, emailVerified, phone, dateOfBirth, nationality, displayName, address (Straße/Stadt/PLZ/Land), kycStatus, kycLevel, dailyLimitUsdt, weeklyLimitUsdt, monthlyLimitUsdt, selfExclusionUntil, loginStreak, maxLoginStreak, monthlyLogins, createdAt, updatedAt

POST /api/user/profile?address=0x...¶

Profil erstellen/aktualisieren.

Speziallogik: - Altersverifizierung: 18+ - Self-Exclusion: 24h-365d, nicht verkürzbar - Profil-Bonus: 10 Tips bei Vervollständigung - Login-Streak: 7-Tage-Bonus (5-8 Tips) - USDT-Limits werden in Micro-Units konvertiert

GET /api/user/dashboard?address=0x...¶

Umfassendes Dashboard: Stats, Tickets, Wins, Affiliate.

GET /api/user/tickets?address=0x...&limit=20&offset=0¶

Paginierte Ticket-Liste (max 50 pro Seite).

GET /api/user/prize-history?pool=0&days=10¶

Gewinnhistorie pro Pool mit Klassen-Breakdown.

GET /api/user/claim-details?address=0x...¶

Detaillierte Claim-Aufschlüsselung (Winner + Affiliate).

GET /api/user/bonus-stats?address=0x...¶

Bonus-Tip-Statistiken: earned, used, remaining, winsFromBonus.

5. Öffentliche Endpoints¶

GET /api/global-stats?pool=0&days=3&all=true¶

Plattformweite Statistiken. Cache: s-maxage=30, stale-while-revalidate=60

Response: today, biggestWin7d, metrics7d, jackpots, prizeHistory, winDistribution, hotNumbers, coldNumbers, alltime, recentWins, charityBalance, communityVotes

GET /api/winners/yesterday¶

Gestrige Gewinner. Cache: s-maxage=300

GET /api/leaderboard?period=month|alltime¶

Login-Leaderboard. Cache: 5 Minuten in-memory.

GET /api/maintenance¶

Maintenance-Status. Cache: 10 Sekunden.

6. Admin-Endpoints¶

GET/POST /api/admin/nonce-status¶

Nonce-Manager-Monitoring. POST: reset/refresh.

POST /api/admin/reset-faucet-test¶

Test: Gas-Faucet-Berechtigung zurücksetzen.

POST /api/admin/revoke-allowance¶

TX-Daten für Allowance-Widerruf generieren.

GET /api/admin/revoke-approve¶

HTML-Testseite für Allowance-Widerruf.

7. KYC-Endpoints¶

POST /api/kyc/token¶

Sumsub WebSDK Access Token generieren.

Request: { "wallet": "0x..." } Response: { "token": "...", "userId": "0x..." }

Externer Service: Sumsub API (HMAC-SHA256 signiert)

POST /api/kyc/webhook¶

Sumsub Status-Updates empfangen.

Signatur-Header: x-payload-digest (HMAC-SHA256)

Event	DB-Update
applicantReviewed (GREEN)	kyc_status = "verified"
applicantReviewed (RED)	kyc_status = "rejected"
applicantPending	kyc_status = "pending"

8. Push-Notification-Endpoints¶

POST /api/push/subscribe¶

Push-Subscription registrieren.

Request:

{
  "walletAddress": "0x...",
  "subscription": { "endpoint": "...", "p256dh": "...", "auth": "..." }
}

POST /api/push/unsubscribe¶

Push-Subscription entfernen.

9. Telegram-Endpoint¶

POST /api/telegram/webhook¶

Telegram Bot Webhook für /start-Kommando.

Security: Optional x-telegram-bot-api-secret-token Aktion: Willkommensnachricht mit "Jetzt spielen"-Button (Mini App Link) Affiliate: startapp=refCode Parameter

10. Charity-Endpoints¶

GET /api/charity/active-round?wallet=0x...¶

Aktive Voting-Runde mit Projekten.

Berechtigung: 1+ Ticket in den letzten 7 Tagen Response: round, projects[], voterStatus

POST /api/charity/vote¶

Stimme für Charity-Projekt abgeben.

Request: { "projectId": 1, "wallet": "0x..." } Einschränkung: 1 Stimme pro Spieler pro Runde

11. Sonstige Endpoints¶

POST /api/log-error¶

Frontend-Fehler loggen.

Request: walletAddress, sessionId, errorCode, errorMessage, errorStack, action, context, intentId, txHash Auto-Kategorisierung: Patterns zu Fehlercodes zugeordnet

GET /api/bonus-balance?address=0x...¶

Bonus-Tips-Guthaben und -Historie.

GET /api/player-tickets?address=0x...¶

Legacy-Endpoint (identisch mit /user/tickets).

GET /api/ticket-details?ticketId=123¶

Ticket-Details mit Tips, Treffern, Gewinnen.

GET /api/tx/[hash]¶

On-Chain-TX-Decoder: buyTicket, claim, approve, transfer, multicall.

12. Datenbank-Verbindungen¶

Pool	Datenbank	Max Connections	Verwendung
db (Haupt)	chainbets	10	Alle Standard-Queries
charityDb	chainbets_charity	5	Charity Voting
DATABASE_URL_RO	chainbets (RO)	-	Claim Payload

Weiterführende Dokumente: - 05 - Buy Flow - 06 - Claim Flow - 10 - Sicherheit