llms.txt API v1 · 2026-11-02
Core concepts基础约定

Wallet rounds钱包局

The wallet round model, delivery guarantees, retries and transaction sequences.钱包局模型、发送保证、重试规则与交易时序。

Wallet round model钱包局模型

Term名词Meaning含义
roundIdAll money movement of one player in one game round at one table. Different players in the same game round have different roundIds. Generated by us, opaque; see txnId for the format.一个玩家在一张桌一局里的全部资金往来。同一局的不同玩家 roundId 不同。平台生成，按不透明字符串处理；格式见 txnId。
txnIdOne debit, credit or rollback. Generated by us, globally unique, ≤ 32 characters. Your idempotency key. Like roundId it is guaranteed to be ≤ 32 characters of upper-case letters, digits and -, so it stays unique in a case-insensitive column (the MySQL default) — a unique key on it is safe. Today both are 16 characters: T / R followed by 15 of 23456789ABCDEFGHJKLMNPQRSTUVWXYZ (e.g. T7K2M9QXH4ZP8WNA); size your columns for 32.一次扣款、派彩或冲正。平台生成，全局唯一，≤ 32 个字符。商户侧的幂等键。它和 roundId 一样保证 ≤ 32 个字符、只含大写字母、数字与 -，放在大小写不敏感的列里（MySQL 默认）也唯一，可以放心建唯一键。目前两者都是 16 位：T / R 开头，后 15 位取自 23456789ABCDEFGHJKLMNPQRSTUVWXYZ（如 T7K2M9QXH4ZP8WNA）；列宽请按 32 留。
txnSeqOrder of the transaction inside the wallet round, starting at 1. For diagnostics only — not an idempotency key.交易在钱包局里的顺序，从 1 开始。只用于排查，不是幂等键。

A wallet round may contain any number of debits and credits:

一个钱包局可以有任意多笔扣款和派彩：

Game游戏Transactions in one wallet round一个钱包局里的交易
Live baccarat, roulette真人百家乐、轮盘one debit (all bets of the round) → one credit with roundClosed: true (may be 0)一笔 debit（这局所有注的合计）→ 一笔带 roundClosed: true 的 credit（可以是 0）
Single-player blackjack单机 21 点debit main → [debit insurance] → [debit split] → [debit double] … → one credit with roundClosed: truedebit 主注 → [debit 保险] → [debit 分牌] → [debit 加倍] … → 一笔带 roundClosed: true 的 credit
Games with mid-round payout有局中派彩的玩法debit → credit (roundClosed: false) → … → credit (roundClosed: true)
No current game sends a mid-round credit, but your wallet must accept it (conformance case MUL-08).目前的玩法都不发局中派彩，但钱包必须支持（对接测试 MUL-08）。
debit OK (none) ───────────────► open ──── credit (roundClosed=true) ─────► closed │ ▲ │ └── debit · credit (roundClosed=false) · rollback (roundClosed=false) │ └──── rollback (roundClosed=true) ───────► closed (cancelled)
Must必须
  • R1 A wallet round is opened by its first successful debit. A failed debit does not open it.
  • R2 While open, accept any number of debits, credits and rollbacks, each idempotent by txnId. Never deduplicate by round + type.
  • R3 After a transaction with roundClosed: true succeeds, the round is closed: a new txnId for it gets ROUND_CLOSED; a repeated txnId still gets its original result.
  • R4 A credit for a round with no successful debit gets ROUND_NOT_FOUND.
  • R5 A credit of "0.00" is a valid losing settlement: record it, close the round, return OK.
  • R6 Never refuse a credit or rollback because the player is disabled.
  • R1 钱包局由第一笔成功的扣款打开；失败的扣款不打开钱包局。
  • R2 钱包局打开期间，接受任意多笔扣款、派彩、冲正，每笔按 txnId 幂等。绝不按「局 + 类型」去重。
  • R3 带 roundClosed: true 的交易成功后钱包局关闭：之后该局新的 txnId 返回 ROUND_CLOSED；重发的 txnId 仍返回第一次的结果。
  • R4 派彩指向的钱包局没有任何成功扣款时，返回 ROUND_NOT_FOUND。
  • R5 "0.00" 的派彩是合法的输局结算：照样记录、关局、返回 OK。
  • R6 绝不能因为玩家被禁用而拒绝派彩或冲正。

Our sending guarantees平台发送保证

#Guarantee保证
G1Transactions of one wallet round are sent one at a time: the next is sent only after the previous has a definite outcome. Different rounds are sent concurrently.同一个钱包局的交易串行发送：上一笔有确定结果后才发下一笔。不同钱包局之间并发。
G2Every wallet round that was opened eventually receives exactly one transaction with roundClosed: true.每个打开过的钱包局，最终都会收到恰好一笔带 roundClosed: true 的交易。
G3A retry resends the identical body (same txnId, txnSeq, amount, createdAt); only X-Request-Id, X-Timestamp and X-Signature change.重试时正文逐字节相同（txnId、txnSeq、金额、createdAt 都不变），只有 X-Request-Id、X-Timestamp、X-Signature 变。
G4A debit with an unknown result is never retried; we send a rollback for it instead.结果未知的扣款绝不重试，改为发一笔冲正。
G5A rollback always reverses the full amount of exactly one debit.一笔冲正总是全额冲正恰好一笔扣款。
G6The closing credit's amount is the total return (stake included) of all bets not already paid by an earlier mid-round credit.关局派彩的 amount = 尚未在局中派彩过的全部注的返还总额（含本金）。

Do not close a long-open round or refund it yourself: G2 guarantees that we will close it. If a round stays open for more than one hour, contact us with its roundId.

长时间未关的钱包局，不要自己关局或退款：G2 保证平台一定会关。超过 1 小时仍未关的，请带上 roundId 联系平台。

Concurrent rounds并发局A player can bet on several tables at the same time, so transactions for different roundIds of the same player arrive concurrently (G1). Serialize them per player (e.g. a row lock on the player's balance) or use optimistic locking — but never reject a new round because the player already has an open one. Conformance cases CON-03 and CON-04 check this.玩家可以同时在多张桌下注，所以同一玩家不同 roundId 的交易会并发到达（G1）。按玩家串行处理（例如给玩家余额行加行锁）或用乐观锁都可以，但不能因为「玩家已有进行中的局」就拒绝新局。对接测试 CON-03 / CON-04 验的就是这个。

Retries重试

Transaction交易When the result is unknown结果未知时Until直到
/debitnever retried; we send a rollback for it instead绝不重试，改发一笔 rollback 冲正它—
/credit · /rollbackresent with the identical body after 10 s, 30 s, 1 min, 2 min, 5 min, 10 min, 30 min, 1 h, then every hour with no limit (each delay ±20 % jitter)用相同正文在 10 秒、30 秒、1 分、2 分、5 分、10 分、30 分、1 小时后重发，之后每小时一次、不设上限（每次间隔 ±20% 抖动）a definite answer (OK; for a rollback also TXN_NOT_FOUND), or we close the case manually. Never dropped silently.得到明确回复（OK；冲正还包括 TXN_NOT_FOUND），或平台人工关闭。绝不悄悄丢弃。
/auth · /balancenot retried不重试—

The first attempt is sent immediately. Codes that mean the two sides disagree (ROUND_NOT_FOUND, ROUND_CLOSED, TXN_CONFLICT, and on a credit also PLAYER_NOT_FOUND, CURRENCY_MISMATCH) flag the transaction for manual attention and raise an alert, and the retries go on — fix the cause on your side and the next attempt completes it. Retries of one wallet round stay in order (G1); different rounds are retried independently.

第一次立即发送。表示两边状态对不上的码（ROUND_NOT_FOUND、ROUND_CLOSED、TXN_CONFLICT，派彩还有 PLAYER_NOT_FOUND、CURRENCY_MISMATCH）会把这笔标为「需人工关注」并告警，重试照常继续——商户修好自己这边，下一次重试就能完成。同一钱包局的重试保持顺序（G1），不同钱包局互不影响。

Sequences时序

Baccarat, player wins百家乐，玩家赢

debit T1 seq1 amount 100 → OK balance 900 credit T2 seq2 amount 195 roundClosed → OK balance 1095 (round closed)

Single-player blackjack: main → insurance → split → double on one hand单机 21 点：主注 → 保险 → 分牌 → 其中一手加倍

Start balance 1000. Insurance loses, first hand loses, second hand (stake 20) wins and returns 40.起始余额 1000。保险输，第一手输，第二手（注 20）赢，返还 40。

debit T1 seq1 main 10 → OK balance 990 debit T2 seq2 insurance 5 → OK balance 985 debit T3 seq3 split 10 → OK balance 975 debit T4 seq4 double 10 → OK balance 965 credit T5 seq5 amount 40 roundClosed → OK balance 1005 (bets: 4 lines)

Blackjack, double down with insufficient balance点加倍时余额不足

debit T1 seq1 main 10 → OK debit T2 seq2 double 10 → INSUFFICIENT_BALANCE (double does not happen; hand continues) credit T3 seq3 amount 20 roundClosed → OK

Blackjack, double down times out点加倍超时

debit T1 seq1 main 10 → OK debit T2 seq2 double 10 → (no answer in 5 s; double does not happen) rollback T3 seq3 ref T2 10 decision_failed roundClosed=false → OK or TXN_NOT_FOUND credit T4 seq4 amount 20 roundClosed → OK

If T2 had in fact been applied, T3 returns the money. If T2 is still in flight, T3 answers TXN_NOT_FOUND, and when T2 arrives it is refused with TXN_ROLLED_BACK. Either way the balance equals "no double down".如果 T2 其实已经扣成功，T3 把钱退回；如果 T2 还在路上，T3 返回 TXN_NOT_FOUND，T2 迟到时被 TXN_ROLLED_BACK 拒掉。两种情况下余额都等于「没有加倍」。

Main bet times out主注超时

debit T1 seq1 main 100 → (timeout; player sits out) rollback T2 seq2 ref T1 100 debit_uncertain roundClosed=true → TXN_NOT_FOUND (round was never opened on your side)

Round cancelled by the platform before settlement结算前平台取消这局

debit T1 seq1 100 → OK rollback T2 seq2 ref T1 100 round_cancelled roundClosed=true → OK (100 returned, round closed)

With several debits, each is rolled back in turn; only the last rollback has roundClosed: true.有多笔扣款时逐笔冲正，只有最后一笔带 roundClosed: true。

Credit times out派彩超时

credit T2 seq2 195 roundClosed → (timeout) credit T2 seq2 195 roundClosed (same body) → OK (if the first attempt was applied, return its original result; never pay twice)