Integrate with AI agents

Give this guide to your coding agent together with access to your repository and the names of secrets in your vault. It defines the integration boundaries, implementation sequence and evidence required for delivery.

For the agent: read this guide and the linked contracts before editing the operator application. The currently hosted deployment is staging. A customer environment named production does not establish commercial production readiness.

• Download this guide as Markdown
• Agent index — llms.txt
• Machine-readable integration manifest
• Wallet OpenAPI contract
• Aggregator OpenAPI contract

1. Understand the boundary

OrbiSportbook provides an iframe sportsbook: odds, markets, betslip, betting, settlement and cash-out. The casino owns registration, login, KYC, eligibility, deposits, withdrawals and player balances. Do not build a second player account or cashier inside the iframe.

Authenticated casino player
  → casino backend creates an OrbiSportbook session
  → browser receives only a launchToken
  → embed SDK opens the iframe
  → OrbiSportbook calls the casino wallet over HTTPS + HMAC
  → casino applies each transaction once and returns the balance

Wallet playerId is the stable externalPlayerId supplied when creating a session, isolated by tenant. Do not send national IDs, identity documents or player passwords. A session response with kycStatus: verified records delegation to the operator; it is not identity verification performed by OrbiSportbook.

2. Obtain the required inputs

For credentials, request a vault reference, not secret values pasted into prompts, tickets or logs.

Input	Purpose
Authorized target: local, hosted sandbox or approved production	Defines permitted testing and publication. Confirm the deployment environment too.
SPORTSBOOK_URL	Confirmed origin; hosted staging is https://api.orbisportbook.com.
TENANT_ID and currency	Separate values for each environment.
INTEGRATION_API_KEY	Backend-only credential sent as X-API-Key.
WALLET_SECRET	HMAC signing secret for this tenant/environment; different from the integration key.
WALLET_BASE_URL	Public HTTPS base for the four callbacks, configured in OrbiSportbook.
Casino frontend origins	Exact allowed embedding origins, including scheme and port when applicable.
Existing authentication and player ID	Casino session middleware and stable externalPlayerId mapping.
Wallet ledger and database	Where balance changes and idempotency results commit atomically.
Test players and fictitious balances	Authorized local/sandbox acceptance fixtures.
Optional AGGREGATOR_API_KEY	Only for backend provisioning by an already authorized aggregator.

List missing credentials, authorizations and financial identity decisions explicitly. Continue independent work, but do not invent values, use local development keys against hosted services or silently replace a real wallet with a mock.

3. Read the contracts in order

Order	Reference	What it defines
1	Player sessions	Authentication, payload, launch tokens, renewal and errors.
2	Wallet API and OpenAPI	Callbacks, HMAC, idempotency, rollback and reconciliation.
3	Embed SDK	Mounting, sizing, login, logout and UI callbacks.
4	postMessage protocol	Events and commands when implementing without the SDK.
5	Testing and certification	Acceptance evidence and financial edge cases.
6	Security and go-live	Secrets, origins, operation and release requirements.
Optional	Aggregator API	Automatic casino provisioning and isolated environments.

Use schemas and detailed references as the contract. If the environment behaves differently, capture sanitized request/response evidence and confirm its version with the integration team. Do not guess endpoints or fields.

4. Implement the session backend

Create a route in the casino server, protected by existing player authentication. POST /sportsbook/session is one possible casino route name, not an OrbiSportbook endpoint.

1. Derive the player from the authenticated casino session. Do not trust a browser-supplied arbitrary player ID.
2. Check eligibility and restrictions in the casino.
3. Call POST {SPORTSBOOK_URL}/api/v1/integration/sessions with X-Tenant-ID, X-API-Key and Content-Type: application/json.
4. Send the stable player ID, display name and optional supported currency, path and locale.
5. Check HTTP status and the error envelope. Return only necessary launch data to the page with Cache-Control: no-store.

{"externalPlayerId":"player-42","displayName":"Maria","path":"/live","locale":"en"}

The response includes launchToken, launchExpiresAt and launchUrl. Launch tokens are single-use and valid for 120 seconds. The legacy token field is a longer-lived session: keep it server-side or discard it. Never forward the complete API response to the browser, or log tokens in analytics.

Use your platform’s CSRF protection for cookie-authenticated routes. Resolve the tenant from trusted server configuration, not unrestricted player input. Renewal requires a new launch token, not reuse of the previous one.

5. Implement the wallet without duplicating money

Expose these endpoints under each environment’s wallet base URL:

Endpoint	Operation
POST /balance	Read the player’s balance; no movement.
POST /debit	Bet or correction debit; validate funds and apply the full amount.
POST /credit	Settlement, refund, cash-out or correction; accept zero as well.
POST /rollback	Reverse the debit identified by ref, including rollback arriving before debit.

Verify X-Signature against the original bytes before parsing JSON:

hex(HMAC-SHA256(WALLET_SECRET, X-Timestamp + "." + rawBody))

Use constant-time comparison and reject timestamps outside ±300 seconds. The offline test vector verifies your implementation without real secrets. Its fixed timestamp is not valid for a live request.

Mandatory behavior:

• Amounts and balances are integers in minor units, never floating point; validate currency.
• Authenticate every request and bind URL/secret to the correct wallet. Callbacks do not provide an X-Tenant-ID that replaces environment isolation.
• Commit movement, complete transaction identity and original result in one database transaction. Concurrent retries return that result without moving funds twice.
• A known txId with a different player, endpoint, amount, currency, kind, bet or reference returns 409 duplicate_tx.
• Financial success must echo the exact txId, an explicit integer balance and matching currency. /balance need not echo txId.
• A rollback received before its debit records a durable ref tombstone; reject a late debit as rolled_back.
• Definitive rejection uses 4xx with error.code; temporary failures use 5xx or timeout. Do not turn an unknown outcome into success or definitive rejection.
• Do not partially debit or create a negative balance for an underfunded correction. Preserve the rejection and escalate for reconciliation.

{"txId":"bet:example-id","balance":49500,"currency":"USD"}

The published transport has four endpoints; do not assume OrbiSportbook will call a transaction-status endpoint you invent. Network delivery may repeat after failures, requiring durable idempotency. A displayed bet result or HTTP 200 from a bet action does not prove that the wallet confirmed payment.

6. Connect the frontend

Load https://api.orbisportbook.com/embed/v1.js and call OrbiSportbook.mount. Functions below are casino-side functions you must implement, not supplied backend APIs.

const sb = OrbiSportbook.mount('#sportsbook', {
  url: 'https://api.orbisportbook.com',
  tenant: tenantId,
  launchToken: await requestLaunchTokenFromYourBackend(),
  locale: 'en',
  height: 'fill',
  onLoginRequired: async () => {
    if (await openYourLogin()) {
      sb.setLaunchToken(await requestLaunchTokenFromYourBackend());
    }
  },
  onDepositRequested: () => openYourCashier(),
  onSessionExpired: () => requestLaunchTokenFromYourBackend(),
  onBalanceChanged: ({ balance, currency }) => updateBalanceDisplay(balance, currency),
});
// Casino logout: sb.logout(). Screen unmount: sb.destroy().

Size the container for fill; see the SDK guide for responsive modes. Anonymous visitors may browse without launchToken. Return null from renewal when the casino session has ended. After a confirmed cashier deposit, call sb.refreshBalance().

Browser events drive UI, not ledger credits. Never treat balance_changed or bet_settled as financial authorization. Direct postMessage integrations must validate origin, source window and protocol envelope; do not use * as the target for session data.

7. Provision through an aggregator when applicable

For authorized aggregators, follow the complete provisioning contract:

1. POST /api/v1/aggregator/clients creates a client and suspended environments; save IDs and secrets in separate vault entries.
2. Install each secret in its wallet and create validation players in the operator systems.
3. POST /api/v1/aggregator/clients/{id}/activate verifies balance, currency and rejection of invalid signatures in both wallets. When policy allows, it activates automatically and returns separate integration keys.
4. Store each key in its environment backend and complete session/iframe acceptance tests.

Use aggregator Authorization: Bearer, without X-Tenant-ID. Every POST requires a durable Idempotency-Key. Preserve body, idempotency key and API credential when retrying. Original response retrieval lasts 24 hours; afterward inspect client state and your vault rather than creating another client to bypass conflict. Activation performs no debit or credit and does not replace financial certification or licensing.

8. Test and retain evidence

Run financial tests only in local/sandbox with fictitious balances and authorized accounts. Production requires explicit authorization and go-live completion.

Group	Minimum evidence
Sessions	Correct authenticated player; arbitrary browser IDs cannot impersonate; no secrets in bundles, responses or logs.
Tokens	Reused, expired and wrong-tenant launch tokens fail; renewal and logout work.
Iframe	Allowed origin works, unapproved origin fails; desktop/mobile layout and scrolling work.
Signatures	Valid request passes; changed body, wrong secret and stale timestamp fail.
Idempotency	Concurrent identical txId applies once; mismatched payload is rejected.
Financial lifecycle	Win, loss with zero credit, void, cash-out, rollback before/after debit and underfunded correction.
Recovery	Timeout after commit, retry and downtime do not duplicate funds; pending obligations remain observable.
Isolation	Sandbox/production tenant, keys, URLs, players and balances stay separate.
Reconciliation	Match ledger, txId, bet and wallet confirmation, not just the displayed bet status.

Record environment, revision, executed scenarios, expected/observed results and sanitized transaction IDs. Distinguish implemented, tested locally, certified in sandbox and approved for production. A build, loaded iframe or isolated balance check does not establish complete readiness.

9. Copy-ready agent prompt

Integrate OrbiSportbook into this casino using the official guide:
https://api.orbisportbook.com/docs/ai-integration/
Tool index: https://api.orbisportbook.com/docs/llms.txt

Read the guide, session contract, wallet OpenAPI and embed SDK first.
Map our authentication, stable player ID, ledger and repository conventions.
Identify missing inputs and authorizations before depending on them.

Implement an authenticated server-side session route, the four wallet
callbacks with raw-body HMAC and transactional idempotency, and an iframe
with login, cashier, renewal, logout and responsive sizing.
Use documented provisioning only if an authorized aggregator key exists.
Do not invent endpoints, credentials, approvals or financial rules.
Keep API keys and session tokens out of the frontend, prompts and logs.

Run acceptance scenarios locally/in sandbox with fictitious funds.
Keep environments isolated; do not move real money without authorization.
Deliver changed files, configuration variable names, test results,
operation instructions and concrete go-live blockers.
Do not claim production readiness for unverified dependencies.

Quick diagnosis

Symptom	Check
Session 401	Correct key, tenant and environment; aggregator keys are not integration keys.
launch_token_used / launch_token_expired	Issue a fresh token immediately before mounting or renewing.
Blocked iframe	Exact registered origin, CSP and embedding configuration.
Invalid signature	Raw bytes, environment secret, Unix seconds and HMAC comparison.
Pending money	Valid response with txId/currency/balance, transaction logs and financial queue.
Provisioning 409	Existing state, idempotency, quota or changed configuration; do not blindly create another ID.

Branch on error.code and details.reason, never translated message text. Escalate with environment, timestamp, endpoint and relevant IDs, removing sensitive headers and body fields.