Partner API
For a partner that shows BetStream 3D's live games on its own site and takes its own bets on them. You embed our players, so your screens always run the current version of every game, and you follow every round through a signed API and webhooks: the card, each step, and the result with the seed that proves it. Version 1.0.
Two ways to use our games
| Partner API (this page) | You run the betting: your wallet, your markets, your odds or pools. We supply the picture and the results. For 3D Sabong, 3DKarera Live and 3DRoulette Live. |
| Game integration API | We run the betting, on your players' wallets (a seamless wallet): we take each stake and pay each win through your wallet API. |
In short
- You get a partner id and a secret from us. Ask for test credentials, and tell us the domains your pages are on.
- Your pages show our players in an iframe. They are served from here, so every update to a game is on your screens the moment it is published.
- Your back end follows the rounds: webhooks pushed to you, or the event log pulled from us, or both.
- You settle a round only on
round.settled, from itsresult, and return every bet onround.voided.
API base address: https://3dsabong.com. Times are ISO 8601 in UTC. Every response is JSON.
The players
| https://3dsabong.com/embed/sabong | 3D Sabong, the live pit. Options: ?voice=0|1 (commentary, off by default), ?sound=0|1, ?blood=0|1. |
| https://3dsabong.com/embed/karera | 3DKarera Live: a race every five minutes, with the running order and the order of finish on screen. |
| https://3dsabong.com/embed/roulette | 3DRoulette Live: a spin about every 48 seconds. |
<iframe src="https://3dsabong.com/embed/karera" allow="autoplay; fullscreen"
style="width:100%;aspect-ratio:16/9;border:0" title="3DKarera Live"></iframe>Each player fills its frame (16:9, letterboxed) and shows the picture only: no site around it. We allow framing by the domains you give us. The player tells the page around it what it may want, with window.postMessage; check event.origin is https://3dsabong.com:
| { type: 'sabong:toggle_fullscreen' } | The viewer pressed the player's full-screen button. Make your own container full screen (your controls may want to stay on top). |
| { type: 'sabong:timer', detail: { text, mode } } | 3D Sabong: the fight clock, each time it changes, to keep a betting strip in step with the picture. |
| { type: 'karera:standings', standings, togo } | 3DKarera Live: the running order (saddle numbers, leader first) and the metres to go, as they change. |
Nothing is sent this way that is not already on the screen. The picture is never ahead of the result record: a race or a spin is sent to the player as it happens, and its result is published only when it is over.
Signing
Every request to the Partner API, and every webhook we send you, carries three headers:
X-Operator-Id: plink X-Timestamp: 1794355000 unix seconds; refused when more than 300 s off X-Signature: hex( HMAC-SHA256( secret, "<timestamp>.<METHOD>.<path with query>.<body as sent>" ) )
// Node.js: a signed request
import { createHmac } from 'node:crypto';
async function partner(method, path, body = '') {
const ts = Math.floor(Date.now() / 1000), text = body ? JSON.stringify(body) : '';
const sig = createHmac('sha256', SECRET).update(`${ts}.${method}.${path}.${text}`).digest('hex');
const res = await fetch('https://3dsabong.com' + path, { method, body: text || undefined,
headers: { 'Content-Type': 'application/json', 'X-Operator-Id': ID, 'X-Timestamp': String(ts), 'X-Signature': sig } });
return res.json();
}
const { round } = await partner('GET', '/partner/v1/games/karera/live');Endpoints
| GET /partner/v1/games | The games you take: id (sabong, karera, roulette), name, embedUrl, the time between rounds; and the statuses and event types this version uses. |
| GET /partner/v1/games/{game}/live | The round on now, in the round schema below. |
| GET /partner/v1/games/{game}/rounds?after=&limit= | Finished rounds (settled or void), oldest first, numbered above after; next is the cursor for the next page. For reconciliation. |
| GET /partner/v1/games/{game}/rounds/{round} | One round, as it stands now. |
| GET /partner/v1/games/karera/schedule?count= | The race on now and the races after it, with their fields and the going (the fields are published races ahead). |
| GET /partner/v1/events?after=&limit=&game= | Every step of every round, in order, numbered: the same events the webhook sends. Keep the id of the last one you processed and ask for the ones after it. |
| POST /partner/v1/webhooks | Body { "url": "https://…" }: where to send events (https). { "url": null } stops them. |
| GET /partner/v1/webhooks | The address, delivery counts and the latest deliveries with their answers. |
| POST /partner/v1/webhooks/test | Sends a ping event to your address now and tells you what it answered. |
| GET /partner/v1/openapi.json | This API as an OpenAPI 3.1 specification (no signature needed). |
A round
Every game's rounds have the same shape:
{
"game": "karera", "round": 893,
"status": "running", // open | closed | running | settled | void
"opensAt": "…", "closesAt": "…", "startsAt": "…", "resultAt": "…",
"seal": "6f0c…", // SHA-256 commitment to the seed, published when the round opens
"seed": null, // revealed when the round is settled
"card": { "going": "fast", "distance": 2000, "runners": [{ "n": 1, "horseId": 82, "name": "Cowboy Code", "rating": 134 }, …] },
"result": null, // when settled: karera { winner, order } · roulette { number, colour } · sabong { winner }
"voidReason": null
}| open | Bets may be taken. The card and the seal are published. |
| closed | No more bets. Stop taking them at closesAt by your own clock too, whatever reaches you when. |
| running | The race is off, the ball is released, the birds are fighting. Nothing anywhere says how it will end. |
| settled | Over. result and seed are set. Settle your bets from result. |
| void | No result (a restart before the off, a halt). Return every bet. voidReason says why. |
To check a result yourself: the seed must hash to the seal published before the round, and gives the result by the method on the fairness page; every game's results page does the same in the browser.
Events and webhooks
| round.opened | A round is open: card and seal. |
| round.closed | No more bets. |
| round.started | Under way. |
| round.settled | Over, with its result and seed. |
| round.voided | No result: return the bets. |
POST https://your.site/hooks/betstream3d
X-Operator-Id: plink X-Timestamp: … X-Signature: … X-Event-Id: 1042 X-Event-Type: round.settled
{ "id": 1042, "type": "round.settled", "game": "roulette", "round": 7344, "at": "…", "data": { …the round… } }- Check the signature over the raw body, with the path and query of your own address, before you act on it.
- Answer 2xx to acknowledge. Anything else, or no answer in 5 s, is sent again after 5 s, 15 s, 1 min, 5 min, then every 10 min, for 24 hours; after that it is marked failed and waits in the event log.
- In order, one at a time. Your next event waits until the one before it is acknowledged.
- The same event can come twice (an answer lost on the way back). Process an event id once.
- The event log is the record. Webhooks are the fast path; poll
GET /partner/v1/events?after=every few seconds as well, or after any gap, and you will never miss a step.
// Node.js: the receiving end
import { createHmac, timingSafeEqual } from 'node:crypto';
function genuine(req, raw) { // raw: the body as received, before parsing
const ts = req.headers['x-timestamp'], sig = Buffer.from(String(req.headers['x-signature'] || ''));
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const want = Buffer.from(createHmac('sha256', SECRET).update(`${ts}.POST.${req.url}.${raw}`).digest('hex'));
return sig.length === want.length && timingSafeEqual(sig, want);
}Errors and limits
| { "error": { "code", "message" } } | With a 4xx or 5xx status. Codes: INVALID_SIGNATURE (401), OPERATOR_DISABLED (403), GAME_NOT_FOUND, ROUND_NOT_FOUND (404), INVALID_REQUEST (400), RATE_LIMITED (429, with Retry-After). |
| Rate | 1,200 requests a minute from one address, across this API. Polling the event log every 2 to 5 seconds is well inside it. |
Compatibility
Within version 1 nothing is removed and nothing changes meaning: fields, statuses, event types and games are only ever added, so ignore any you do not know. A change that would break an integration is a new version, /partner/v2, announced here, and version 1 keeps working for at least six months after that.
Changes
| 1.0 · 16 Nov 2026 | First version: embeddable players for the three live games; the round schema; games, live, rounds, schedule and events; signed webhooks; the OpenAPI specification. |
Testing
Ask us for test credentials. With them, run the checker against the live API: it makes every call, sets your webhook to a receiver of its own, sends a test event and checks the signature, and follows the event log for a few minutes.
RGS_URL=https://3dsabong.com OP_ID=… OP_SECRET=… node platform/tools/check-partner.mjs