📖 API Reference
Africa Jackpot operator integration API. Sandbox base URL: https://api.africajackpot.io
Authentication
All requests are authenticated with a bearer token in the Authorization header. Each operator receives a unique key. The demo key demo-sandbox-key-afriqjackpot-2026 works only against sandbox.
Authorization: Bearer YOUR_API_KEYRequired headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer token issued to your operator account. |
| Content-Type | Yes | Always application/json for POST requests. |
| X-Sandbox | Optional | Set to true to route requests to sandbox pools. |
POST /api/contribute
Call this on every jackpot-eligible spin. The server records the contribution, updates pool balances, and rolls for a jackpot win when jpGame is true.
Request body
{
"roundId": "demo-1714000000000-ab12cd", // unique per spin
"playerId": "demo-player-001",
"operatorId": "demo-operator",
"gameId": "buffalo-king-ngn",
"betNgn": 500, // base wager in NGN
"jpBetNgn": 30, // jackpot side-bet in NGN
"jpGame": true, // must be true to be eligible
"timestamp": "2026-05-13T12:00:00.000Z"
}Field reference
| Field | Type | Notes |
|---|---|---|
| roundId | string | Globally unique. Replaying the same roundId with different data returns 409. |
| playerId | string | Stable identifier for the player at your operator. |
| operatorId | string | Your operator code. |
| gameId | string | Game slug, e.g. buffalo-king-ngn. |
| betNgn | number | Total wager in NGN, integer or decimal. |
| jpBetNgn | number | Jackpot contribution portion, must be > 0 when jpGame is true. |
| jpGame | boolean | Must be true. False returns 400. |
| timestamp | ISO 8601 | Client-side time of the spin. |
Response (200)
{
"auditId": "aud_01HXY...",
"jackpotResult": {
"won": true,
"tier": "mid", // "mega" | "mid" | "mini"
"amountNgn": 85640
},
"pools": {
"mega": 2000040.50,
"mid": 85420.10,
"mini": 12480.00
}
}When no jackpot is hit, jackpotResult.won is false and tier / amountNgn are omitted. Always read pools from the response to refresh your ticker.
cURL
curl -X POST https://api.africajackpot.io/api/contribute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Sandbox: true" \
-d '{
"roundId":"demo-'$(date +%s)'",
"playerId":"demo-player-001",
"operatorId":"demo-operator",
"gameId":"buffalo-king-ngn",
"betNgn":500,
"jpBetNgn":30,
"jpGame":true,
"timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"
}'GET /api/pools
Returns current jackpot pool balances. Use for initial load or periodic polling. Not required — every /api/contribute response also includes the latest pool snapshot.
Response (200)
{
"pools": [
{ "tier": "mega", "balance": 2000040.50, "currency": "NGN" },
{ "tier": "mid", "balance": 85420.10, "currency": "NGN" },
{ "tier": "mini", "balance": 12480.00, "currency": "NGN" }
]
}Error codes
| Status | Code | When |
|---|---|---|
| 400 | Bad Request | Missing required field, or jpGame is false. |
| 401 | Unauthorized | Missing or invalid Authorization bearer token. |
| 402 | Payment Required | Operator credit balance is insufficient. |
| 409 | Conflict | roundId already exists with different payload. |
| 429 | Too Many Requests | Rate limit exceeded — back off and retry. |
| 500 | Internal Server Error | Unexpected server error — safe to retry. |
Error responses are JSON of the shape { "error": "...", "message": "..." }. See the live "Error Responses" panel on the demo page to inspect each one.
Sandbox mode
Sandbox uses isolated jackpot pools and a higher win frequency so you can verify your integration end-to-end. Wins issued in sandbox carry no real value and are not paid out. Send X-Sandbox: true with the demo key to opt in.