Opening
A platform operator, an iGaming aggregator, a loyalty programme platform, a social gaming company, has an audience and wants to add poker. Their players want poker. The commercial case is clear. The engineering question is not: build or embed?
Most operators who ask this question answer it with "build" and discover 14 months later that the engine is not quite right, the shuffle doesn't pass audit, and the side-pot logic produces disputes at the worst possible moment, during a high-stakes player session.
River's API path exists for operators who want to ask a different question: what if someone else has already solved the engine, and you just need to connect to it?
Why It Matters
The online poker market is growing at 11.2% CAGR. New operators entering the market face a choice between building their own engine, expensive, time-consuming, and correctness-risky, or licensing a white-label platform from a third party, fast, but with limited product control and a generic experience.
The River API model is a third option: the operator's front end calls River's server, which is authoritative over every game decision, shuffle, and chip movement. The operator's brand, UX, and player experience are entirely their own. River's engine, shuffle audit, and chip ledger are entirely River's responsibility. The operator ships a poker product without taking on the poker engine problem.
The Build-vs-Embed Decision
The case for building in-house:
- Full control over every aspect of the game
- No external API dependency in the critical path
- Custom game variants possible
The case for building in-house, honestly assessed:
- Poker engine correctness is harder than it looks, side pots, all-in resolution, tournament math, CSPRNG shuffles all have non-trivial edge cases
- 12-18 months of development before any production evidence
- Correctness problems discovered in production are expensive, they occur in front of players, not in testing
- Ongoing maintenance burden as platform requirements evolve
The case for the River API:
- Production evidence exists: 14,721 hands, zero chip discrepancies, auditable CSPRNG shuffle
- Integration is faster than building: a working integration can be demonstrated in days, not months
- River's correctness is River's responsibility, the operator is buying a guarantee, not a liability
- The operator's engineering resource goes into product differentiation, not engine plumbing
River's API Model
River exposes the production holdem.js / PLO engine, CSPRNG shuffle, side-pot and all-in resolution, and tournament system as an API surface. The operator's front end interacts with River's server using a defined request/response protocol; River's server remains the single source of truth for all game decisions and chip movements.
// Operator creates a table
POST /v1/tables
{
"game": "nlhe",
"stakes": "1/2",
"max_players": 9,
"operator_id": "op_xyz"
}
→ { "table_id": "tbl_8f3a", "join_token": "...", "state": "waiting" }
// Operator's front end connects via WebSocket for real-time state
ws://api.river.gg/v1/tables/tbl_8f3a/stream
// Player actions are sent to River's server
POST /v1/tables/tbl_8f3a/actions
{ "player_id": "p_001", "action": "raise", "amount": 400 }
// River validates, applies rules, broadcasts authoritative state to all clients
The operator controls everything their player sees. River controls everything that determines whether the game is fair.
Integration Architecture
The River API integration has three layers:
Authentication and operator isolation. Each operator has a scoped API namespace, their tables, players, and chip accounts are completely isolated from other operators. API key authentication with request signing prevents cross-operator access.
Game lifecycle management. Table creation, player seating, betting action processing, showdown resolution, and pot award are all server-side operations. The operator's front end receives game state events via WebSocket and renders them, it does not compute any game logic.
Chip ledger integration. River's chip ledger tracks all chip movements within the operator's games. The operator can query chip positions, movement history, and audit trails via read-only API endpoints. This data integrates with the operator's own financial accounting system.
What Comes Next
The River API model is designed to scale with the operator's ambition. An operator who starts with cash games can add tournaments using the same engine integration. An operator who starts in one market can add regulated markets by adding the compliance layer above River's engine, which has already satisfied the game-correctness requirements regulators look for.
The API-first architecture also means River can be updated, shuffled implementations, rule variant additions, performance improvements, without the operator updating their front end. API versioning ensures backward compatibility while allowing the engine to improve continuously.
Key Takeaways
- Building a poker engine is a 12-18 month commitment with significant correctness risk; embedding a proven one via API is a faster path with a different risk profile.
- The River API gives operators full control of their product experience while River owns game correctness, shuffle auditability, and chip accounting.
- Server authority is enforced at the API level, the operator's front end cannot alter game state, only send player intent.
- Integration timeline: a working integration in days; production deployment in weeks.
- The same engine that powers our production deployment is what the operator embeds, not a separate, less-tested API version.
FAQ
Q1. What latency does the API add to game action processing?
River's API processing adds approximately 20-40ms to the round-trip from player action to authoritative state broadcast, depending on geography. For most poker use cases, where action timers are 15-30 seconds, this latency is imperceptible. For high-frequency heads-up formats, server co-location options can reduce latency further.
Q2. Can we customise game rules (e.g., custom hand rankings, side game variants)?
Standard NLHE and PLO variants are supported out of the box. Custom game variants require API extension work on River's side and are scoped per operator agreement. River's architecture supports variant addition without affecting existing game implementations.
Q3. How does the API handle disconnected players?
River's server maintains player connection state. A disconnected player's hands are treated according to configurable rules: sit-out (fold or check at the appropriate action) or time-bank consumption. Reconnecting players receive the current authoritative state immediately, there is no client-side state to reconcile.
Q4. What are the uptime and latency SLAs for the River API?
SLAs are defined in the operator agreement. Standard terms include 99.9% monthly uptime and 50ms P95 API response latency. Enterprise terms with co-location and higher SLAs are available.
Embed real poker without building the engine. Book a technical call to discuss integration requirements and timeline. Book a Technical Call →