Modern Sportsbook API Integration — From Zero to Live Betting, Step By Step.
A real integration guide written for engineers, not procurement decks. Authentication, WebSocket setup, market subscriptions, bet placement, settlement, error handling — covered in the order you’ll actually build them. Same API powering the WSGaming sportsbook platform and exposed through our odds feed solution.
Integration is infrastructure, not glue code.
A sportsbook API integration isn’t a weekend project. It’s the foundation everything else — your front-end, your risk engine, your settlement layer — runs on top of. Treat it as infrastructure and budget engineering time accordingly. Two engineers, three weeks, is typical for a clean integration with our API.
This guide walks through the integration in the order you’ll actually do it. Authentication first because nothing else works without it. WebSocket subscriptions second because that’s where live odds live. Bet placement and settlement third because they need the price stream already running. Same path every operator on the WSGaming Asia platform takes when they connect to our sportsbook odds feed.
What follows is the integration shape, not a full reference. The complete API docs ship with sandbox credentials when you talk to our team.
Seven steps from zero to production.
Each step is independently testable. Don’t skip ahead — get authentication solid before adding subscriptions, get subscriptions solid before placing bets.
Authentication & Tokens
API keys for REST, JWT bearer tokens for WebSocket. HMAC signing on every REST call with your secret key. Tokens expire on a fixed schedule — implement refresh before they do, not after.
# Refresh token via REST POST /v1/auth/refresh Authorization: Bearer <refresh_token> → { "token": "eyJh...", "expires_in": 3600 }
WebSocket Connection & Heartbeat
Open a persistent WebSocket connection. Send a ping every 25 seconds; if you don’t get a pong back within 5, reconnect. Build the reconnect logic before you build anything else on top of it — connections drop more often than you’d think.
// Heartbeat pattern setInterval(() => ws.send('{"type":"ping"}'), 25000); ws.on('pong', () => lastPong = Date.now());
Subscribe To Markets
Subscribe to channels by sport, league, or specific match ID. Subscriptions are additive — send another subscribe message to add more without disconnecting. Unsubscribe explicitly when you no longer care; otherwise you’ll get throttled.
{
"type": "subscribe",
"channels": ["odds.football.epl.live"]
}
Handle Odds Updates
Updates arrive as discrete messages. Each carries match ID, market type, current price, and a timestamp. Process them off the WebSocket thread — never block the socket loop with heavy logic. Buffer if your downstream is slow.
{ "type": "odds.update",
"match_id": "epl_4821",
"market": "1X2",
"odds": { home: 1.85, draw: 3.40, away: 4.20 },
"ts": 1715847291842 }
Place Bets With Price Acceptance
POST to /v1/bets/place with the ticket, stake, and the price you saw. The API accepts the bet only if the current price hasn’t moved beyond your acceptance window. Set the window per your product — most operators use 1-3 seconds with “better odds only” logic.
POST /v1/bets/place
{
"match_id": "epl_4821",
"market": "1X2", "selection": "home",
"odds": 1.85, "stake": 100,
"accept_change": "better_only"
}
Listen For Settlement
When a match resolves, settlement messages flow through the same WebSocket. Each carries the bet ID, result, payout, and final timestamp. Your wallet engine credits the player; the API handles the result side. Build this idempotently — duplicate settlement messages must not double-credit.
{ "type": "bet.settled",
"bet_id": "bet_92a1f",
"result": "won",
"payout": 185.00 }
Error Handling & Resilience
Every endpoint can fail. Implement exponential backoff on retries, idempotency keys on bet placement, and a dead-letter queue for messages that fail downstream processing. Test the unhappy paths before going live — they’re where production breaks.
If your integration falls over during a Saturday EPL slate, the problem isn’t the API — it’s that you didn’t load-test reconnection logic. Build for the busiest hour, not the average one.
Common integration questions.
How long does a clean integration take? +
Two engineers, 2-3 weeks for a production-grade integration covering odds streaming, bet placement, and settlement. Add another week if you’re also integrating wallet, KYC, and reporting endpoints. Operators using our full white label sportsbook skip integration entirely.
What languages do you have SDKs for? +
Official sample code in JavaScript/Node, Python, PHP, Java, and Go. The API is plain WebSocket + REST, so any language with HTTP and WS support works. Detailed examples come with sandbox onboarding via our team.
How do I handle rate limits? +
REST endpoints are rate-limited per API key (typical: 600 requests/minute). WebSocket subscriptions don’t count against REST limits but have their own subscription caps per connection. Both are headers in the response — implement back-pressure when you approach them.
Is there a sandbox environment? +
Yes — full sandbox with real-time data, separate credentials, complete sport coverage, no monetary settlement. Most operators run sandbox in parallel with production for staging deploys. Same data backbone as the production real-time odds feed.
Can the API handle pre-match and live in one connection? +
Yes. Subscribe to pre-match and live channels on the same WebSocket. Messages carry a state flag (pre-match / live / suspended / settled) so your client can route them appropriately. Standard pattern on every WSGaming integration.
What happens if my server disconnects mid-event? +
On reconnect, the API ships you a backfill message containing the current state of every subscription you had — current prices, suspension states, recent settlements. No need to query separately. The point is to make resilience cheap.
How do you version the API? +
Major versions in the URL path (/v1/, /v2/). Breaking changes only on major version bumps with 12-month notice. Backward-compatible additions ship without notice but never break existing fields. Standard sane versioning.
How do I get started today? +
One email. Request sandbox credentials and you’ll get them within a business day, along with the full API reference, sample code, and an integration specialist assigned to your project.
Start integrating today.
Sandbox credentials within one business day. Full docs, sample code, and a real human engineer on the other end of every question.