# OrbiPoker

> B2B real-money poker for casinos and sportsbooks. The operator embeds the game in an iframe with a single-use launch URL and keeps the money: every chip movement is a signed debit, credit or rollback call to the operator's seamless-wallet webhook. OrbiPoker never takes players directly. All amounts are integers in the currency's minor unit.

All links are relative to the OrbiPoker host that served this file. They are public, need no login and are readable without JavaScript.

## Integration
- [AI agent integration guide](/integration-agent.md): end-to-end workflow for an agent implementing the integration (launch, iframe/SDK, wallet webhook, reconciliation, responsible gaming) with acceptance tests.
- [OpenAPI 3.1](/openapi.json): operator REST API v1 (`Authorization: Bearer orbp_sk_…`) and the `wallet` webhook schema. The source of truth for request and response schemas.
- [Developer docs](/docs): human-readable reference in en, pt-BR and es (launch, embedding, wallet contract, configuration keys, game rules, provably fair, reports, go-live checklist).
- [Iframe SDK v1](/sdk/v1/orbipoker.js): `OrbiPoker.mount({container, launchUrl, onReady, onBalance, onDeposit, onExit, onSessionExpired, onError, onEvent})`.
- [Reference wallet receiver](/wallet-receiver.mjs): Node 24, no dependencies, SQLite. Signature check, idempotency by transactionId, rollback with tombstones.

## Contract summary
- Launch: `POST /api/v1/launch` from the operator backend with `playerId` and `currency` (optional `nickname`, `locale` pt-BR|en|es, `country`, `parentOrigin`, `sessionToken`, `lobby`, `table`, `theme`, `depositUrl`, `exitUrl`, header `Idempotency-Key`). Returns `launchUrl`, single use, valid 120 s. Unknown body fields fail with 400.
- Wallet webhook: POST JSON `{version:1, event: balance|debit|credit|rollback, transactionId, referenceTransactionId, tenantId, playerId, currency, amount, reason, tableId, tournamentId, handId, sessionToken, createdAt}`, header `X-OrbiPoker-Signature: t=<unix s>,v1=<hex HMAC-SHA256(secret, t + "." + rawBody)>`, 300 s tolerance. Answer 2xx with `{"balance": <integer>}`.
- A non-2xx debit means "not charged" and is never retried. A debit that times out (8 s) is followed by a `rollback` with `reason: debit_timeout`. Credits and rollbacks are retried with the same body for 24 h. A rollback for an unknown debit must leave a tombstone so the late debit is refused.
- iframe events: `{source:'orbipoker', version:1, type:'orbipoker:ready'|'orbipoker:resize'|'orbipoker:balance'|'orbipoker:deposit'|'orbipoker:exit'|'orbipoker:session-expired'|'orbipoker:error'|'orbipoker:table-opened'|'orbipoker:hand-complete'}` posted to `parentOrigin` only.

## Try it
- [Live demo](/demo): anonymous demo player on the sandbox operator, practice bots, demo money.
- [Sandbox](/sandbox): acts as an operator backend for the sandbox tenant and shows SDK events and wallet balance.

## Rules for agents
- API keys (`orbp_sk_`) and wallet secrets (`whsec_`) stay on the server, in a secret manager. Never put them in browser code, chats or commits.
- Do not infer endpoints that are not in `/openapi.json`. The `/api/console/*` routes are the internal back office, not a public API.
- Do not mark an integration as production-ready until every acceptance test in the integration guide passes against the operator's staging wallet.