Jackpot pools
API · Operator → Boss HubReturns the jackpot pools you are connected to and the current amount of each level; use it to show jackpot tickers in your lobby. The win history comes from GET /v1/jackpots/{pool_id}/wins. Requires the jackpot module, the games.read scope for pools and rounds.read for wins.
Headers
| Header | Description |
|---|---|
| X-Operator-Id | Your operator ID |
| X-Timestamp | Unix seconds. Rejected outside ±30 s |
| X-Signature | hex(HMAC_SHA256(secret, ts + "." + METHOD + "." + path?query + "." + body)) |
| X-Api-Key | Optional. Selects the right secret when you have several keys |
[
{
"id": "pool_mrd_bell",
"type": "private",
"name": "Meridyen Mega Pool",
"currency": "USD",
"levels": [
{ "level": "grand", "amount": 8319.44, "seed": 5846.00, "must_drop_amount": 14615.00 },
{ "level": "major", "amount": 1032.87, "seed": 584.60, "must_drop_amount": null },
{ "level": "minor", "amount": 104.21, "seed": 58.46, "must_drop_amount": null },
{ "level": "mini", "amount": 29.23, "seed": 29.23, "must_drop_amount": null }
]
}
]Pool fields
| Field | Type | Description |
|---|---|---|
| id | string | Pool ID. |
| type | string | private your own pool, shared a network pool. |
| name | string | Pool name. |
| currency | ISO 4217 | Currency of the amounts: currency if given, otherwise the pool currency. |
| levels | object[] | Levels, in the order of the provider schema. |
Level fields
| Field | Type | Description |
|---|---|---|
| level | string | Level code, e.g. grand. Codes come from the provider’s jackpot schema, not a fixed list. |
| amount | decimal(18,2) | Current amount. On a fixed level it is the fixed amount. |
| seed | decimal(18,2) | Seed: after a drop the level starts again from this amount. |
| must_drop_amount | decimal(18,2) | null | Must-drop cap. null when there is no cap, on a fixed level, or when the provider runs the pool. |
Must-drop cap
A level with a cap drops on the first eligible bet whose contribution brings it to must_drop_amount; the drop probability also works before that amount. The payout never exceeds the cap: if simultaneous bets push the level slightly past it, the excess stays for the next cycle. When two bets cross the cap at the same time there is a single winner. Boss Hub sets the cap; you can show "drops before this amount" in your lobby from this field. The win arrives through win with the jackpot field set, like any drop.
Win history
GET /v1/jackpots/{pool_id}/wins returns your 500 newest drops in the pool, newest first; there is no pagination, so narrow the range with from (inclusive) and to (exclusive). In a shared pool other operators’ drops are not shown and cancelled drops are not listed; drops not paid yet are listed too. Query: site_id, from, to. Row: pool_id, level, amount (the paid amount, in the payout currency), currency (payout currency), site_id, player_id, round_id, won_at.
GET /v1/jackpots/pool_mrd_bell/wins?from=2026-11-01T00:00:00Z HTTP/1.1 Host: staging.example.com X-Operator-Id: op_meridyen X-Timestamp: 1762344100 X-Signature: 47d0b2…91ac
Error codes
| Code | HTTP | Meaning |
|---|---|---|
| INVALID_SIGNATURE | 401 | Signature could not be verified |
| TIMESTAMP_SKEW | 401 | X-Timestamp is outside ±30 s |
| IP_NOT_ALLOWED | 403 | IP is not on the allowlist |
| SCOPE_MISSING | 403 | The games.read scope, or rounds.read for wins, is missing |
| SCOPE_DENIED | 403 | site_id is not yours or is outside your key’s scope |
| MODULE_DISABLED | 403 | The jackpot module is disabled |
| NOT_FOUND | 404 | Wins: no such pool or you are not connected to it |
| VALIDATION_ERROR | 422 | Invalid query parameter |
| RATE_LIMITED | 429 | Rate limit exceeded |