Contract — Request · Response · Rules

This page is the contract for implementing the wallet API correctly: the request/response shapes and the hard rules (atomic · idempotency · retry) that keep the money right

Request envelope

Every endpoint shares the same envelope: player context at the top level + a batch of transactions in txns[] — endpoints differ only in small per-txn extras · example POST {base}/api/bet, a 200 bet:

{
  "request_id": "r1",
  "player_username": "foobar",
  "currency": "THB",
  "product_code": "PGSOFT",
  "timestamp": 1712760660000,
  "txns": [
    { "txn_id": "T-001", "round_id": "R-1", "amount": 200, "game_code": "10300" }
  ]
}

Fields inside txns[]

/api/balance carries the top level only (read-only, no txns[])

Special /settle — single-state round

Some games (e.g. single-state slots) finish both the bet and the result in one call — no /bet comes first. The txn in /settle then carries extra fields:

{ "txn_id": "T-001", "round_id": "R-1", "single_state": true, "bet_amount": 200, "payout_amount": 500, "direction": "CREDIT", "amount": 300, "is_feature": false }

• single_state: true → apply amount (the net = payout − bet, always positive) in the given direction, and always check balance >= bet_amount first (as if the player committed the stake before receiving the payout) — insufficient balance replies 10002
• single_state: false (a normal settle, a /bet came earlier) → credit amount (= payout) directly — no bet_amount/direction

Sportsbook — the same bet arrives twice

A sport bet reaches /api/bet twice in the normal flow: once when the ticket is placed (best-system holds it as WAITING → the txn carries status: "WAITING"), and once more when the vendor confirms the ticket (OPEN) — best-system then relays another /api/bet with the same txn_id, carrying status: "OPEN" + skip_balance_update: true. Your txn_id dedupe must absorb the second call: reply code: 0 with the current balance and never debit twice (use status/skip_balance_update to tell them apart, or just dedupe on txn_id)

Two consecutive /api/bet payloads for the same ticket — new request_id/timestamp, same txn_id:

{
  "request_id": "r10",
  "player_username": "foobar",
  "currency": "THB",
  "product_code": "SBOBET",
  "timestamp": 1712760660000,
  "txns": [
    { "txn_id": "S-88001", "round_id": "SB-1", "amount": 100, "game_code": "SBO-FOOTBALL", "status": "WAITING" }
  ]
}

{
  "request_id": "r11",
  "player_username": "foobar",
  "currency": "THB",
  "product_code": "SBOBET",
  "timestamp": 1712760790000,
  "txns": [
    { "txn_id": "S-88001", "round_id": "SB-1", "amount": 100, "game_code": "SBO-FOOTBALL", "status": "OPEN", "skip_balance_update": true }
  ]
}

Debit 100 on the first call · on the second call reply code: 0 + the current balance with no wallet write — exactly the idempotency rule below, no sport-specific handling needed

Response

Every endpoint replies with the same flat JSON shape — no nested envelope · example reply for /api/bet, a 200 bet (previous balance 1000):

{
  "code": 0,
  "request_id": "r1",
  "username": "foobar",
  "currency": "THB",
  "balance_before": 1000,
  "balance_after": 800,
  "timestamp": 1712760660100
}

/api/balance returns a single balance instead of the before/after pair

Error codes

These codes belong to best-system and are stable — they do not change per game or version.

Full details: Seamless codes

Hard rules

Atomic batch

• Process the whole txns[] batch in one DB transaction — if any txn fails (insufficient balance, unknown ref_txn_id) → roll back the whole batch; a half-applied batch must never exist
• Reply the error with the failing txn's code and balance_before == balance_after
• balance_before/balance_after are the whole batch's balances, not per txn

Idempotency per txn_id

txn_id is the transaction's identity — on a txn_id you have already processed successfully, never re-apply, and reply either code: 0 + the current balance (recommended) or code: 20002

Dedupe on txn_id, not request_id — a re-send of the same transaction may arrive with a new request_id, but the txn_id always stays the same · in practice: a unique index on txn_id, with the conflict handled inside the same transaction as the wallet write

Retry / timeout on best-system's side

• Timeout per call: 10 seconds — a system-wide value (env SEAMLESS_RELAY_TIMEOUT_MS, ops-tuned), not configurable per agent. The relay runs inside the vendor's synchronous callback window, so the budget is bounded by the vendor's SLA, not a per-agent knob.
• Single synchronous attempt — no inline retry. On a network error / timeout best-system returns an error to the upstream vendor immediately; it never queues the transaction to re-send later (no outbox, no asynchronous re-delivery).
• Recovery relies solely on the upstream game vendor retransmitting the transaction — which arrives as a fresh call with the same txn_id (so txn_id dedupe is mandatory).
• Any HTTP response — even a business error — is final (there is nothing to retry). Keep your endpoint highly available and fast.

Re-settle after rollback

A /rollback reopens the round as pending and the new outcome is sent again with the same txn_id — either a /settle with a corrected result or a /refund cancelling it instead. Never reply 20002 in this case, or the round's outcome is lost for good.

We send no field to help you tell them apart, because the game provider sends none to us. You count them yourself, which you can do because you receive every /rollback we receive.

How

1. Keep a rollback counter per bet, starting at 0.
2. On /rollback, increment it. If transaction_type is BY_ROUND, increment it for every bet in that round_id.
3. Use (endpoint, txn_id, current counter) as your idempotency key.
4. A transaction arriving after a rollback lands on a fresh key and is applied; a genuine retransmit still collides with the existing key and is skipped as before.

Checklist — common mistakes

• Verify X-Signature from the raw bytes — not a parsed object stringified back
• Reply business errors as HTTP 200 + code — a 5xx is read as an internal error and is never retried
• Dedupe on txn_id before writing money, always
• amount is always positive — the direction comes from the endpoint type or direction
• Single-state settle: check balance >= bet_amount before applying the net amount
• balance_before/balance_after are the whole batch's balances
• Reply within 10 seconds — defer heavy work until after the commit