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

Result codes结果码

Every result code, the codes allowed per endpoint and strict response validation.全部结果码、各接口允许返回的结果码与响应强制校验。

One code set is used in both directions. Codes are uppercase snake_case strings. Any code other than OK means the request did not change any balance.

两个方向共用一套结果码，都是大写下划线字符串。除 OK 以外的任何码，都表示这次请求没有改变任何余额。

Common codes (both directions)通用码（两个方向）

CodeMeaning含义Caller action调用方怎么办
OKSuccess.成功。Use data.使用 data。
INVALID_SIGNATURESignature wrong or missing; X-Merchant-Code unknown or not 1–64 letters/digits; X-Request-Id not 1–64 printable ASCII characters.签名错误或缺失；X-Merchant-Code 不认识或不是 1–64 位字母数字；X-Request-Id 不是 1–64 个可见 ASCII 字符。Check key and string-to-sign. Do not retry unchanged.检查密钥和待签字符串；不要原样重试。
TIMESTAMP_EXPIREDX-Timestamp outside ±300 s.X-Timestamp 超出 ±300 秒。Sync clock, resend with a new timestamp.对时后用新时间戳重发。
DUPLICATE_REQUESTX-Request-Id already seen within 11 minutes.X-Request-Id 11 分钟内重复。Resend with a new request id.换新的请求编号重发。
IP_NOT_ALLOWEDSource IP not whitelisted.来源 IP 不在白名单。Ask the other side to whitelist the IP.请对方把 IP 加入白名单。
INVALID_PARAMMissing required field, bad format or value. message names the field.缺必填字段、格式或取值不合法，message 会写字段名。Fix the request. Do not retry unchanged.修正请求；不要原样重试。
MAINTENANCEPlanned maintenance.计划维护中。Retry later with backoff.稍后退避重试。
INTERNAL_ERRORUnexpected error; no balance was changed.内部错误；没有改变任何余额。Retry according to the endpoint rules.按各接口的规则重试。

Codes we return (Platform API)平台返回的码（平台接口）

CodeMeaning含义Your action商户怎么办
MERCHANT_DISABLEDYour merchant account (or its parent) is disabled.商户账号（或其上级）已停用。Contact our operations.联系平台运营。
GAME_NOT_FOUNDtableCode / lobbyCode unknown, wrong platform, or removed.tableCode / lobbyCode 不存在、平台不对、或已下架。Refresh the catalog.刷新游戏目录。
GAME_UNAVAILABLEGame exists but cannot be entered now: closed for your account, under maintenance, or no configuration for the player's currency.游戏存在但此刻进不去：对该商户关闭、维护中、或没有该玩家币种的配置。Show "temporarily unavailable"; do not retry immediately.提示「暂不可用」，不要立刻重试。
INVALID_TOKENYour /auth rejected the token.商户的 /auth 拒绝了这个 token。Issue a new token.重新签发 token。
PLAYER_MISMATCH/auth returned an extPlayerId different from the request./auth 返回的 extPlayerId 与请求里的不一致。Fix your token binding.检查 token 与玩家的绑定。
PLAYER_DISABLEDPlayer is frozen or disabled on our side, or your /auth said so.玩家在平台被冻结 / 禁用，或商户 /auth 返回了禁用。Do not retry.不要重试。
CURRENCY_NOT_SUPPORTEDCurrency from /auth is not enabled on our platform./auth 返回的币种平台未开通。Contact us.联系平台。
CURRENCY_MISMATCHThe player is already bound to a different currency.该玩家已绑定了别的币种。Use a separate extPlayerId per currency.每个币种用不同的 extPlayerId。
WALLET_UNAVAILABLEYour /auth timed out, failed at transport level, or answered INTERNAL_ERROR / MAINTENANCE.商户 /auth 超时、网络失败，或返回 INTERNAL_ERROR / MAINTENANCE。Check your wallet; retry later.检查钱包服务，稍后重试。
WALLET_ERRORYour /auth answered something invalid: a code not allowed for /auth, a malformed body, or data failing Strict response validation. message gives the detail.商户 /auth 的返回不合规：码不在 /auth 允许范围内、正文格式错、或数据不满足 响应强制校验。message 写明原因。Fix your wallet implementation.修正钱包实现。
ROUND_NOT_FOUNDrounds/report-url: no such wallet round for your account, or it is not finished yet (rounds whose main bet never succeeded have no report).rounds/report-url：该商户下没有这个钱包局，或这局还没结束（主注没成功的局没有报表）。Check the roundId; for an open round, try again after it closes.核对 roundId；没结束的局等关局后再试。

Codes your wallet returns (Wallet API)商户钱包返回的码（钱包接口）

CodeWhen you must return it什么时候必须返回What we do平台怎么处理
INVALID_TOKEN/auth: token unknown, expired or already used./auth：token 不存在、过期或已用过。Launch fails with INVALID_TOKEN.进游戏失败，返回 INVALID_TOKEN。
PLAYER_NOT_FOUNDNo such extPlayerId.没有这个 extPlayerId。Request fails; no money moved.请求失败，没有动钱。
PLAYER_DISABLEDPlayer blocked on your side. Never on /credit or /rollback — money owed to a player must always be paid.玩家在商户侧被禁。/credit、/rollback 绝不能返回它——欠玩家的钱必须付。Debit/launch refused.扣款 / 进游戏被拒。
CURRENCY_MISMATCHRequest currency differs from the player's currency.请求币种与玩家币种不同。Request fails; alert.请求失败，告警。
INSUFFICIENT_BALANCE/debit: balance lower than amount. Include the current balance in data./debit：余额小于 amount。data 里必须带当前 balance。Bet not placed.注不生效。
BET_REJECTED/debit: your limits, responsible-gaming or risk rules refuse the bet./debit：商户的限额、自我限制或风控拒绝这笔下注。Bet not placed.注不生效。
TXN_CONFLICTSame txnId already processed with different content; or a rollback whose amount/player/round does not match the referenced debit.同一 txnId 已处理过但内容不同；或冲正的金额 / 玩家 / 局与被冲正的扣款对不上。/debit: bet not placed, alert. /credit / /rollback: flagged for manual attention and alerted, retries continue until we close the case./debit：注不生效，告警。/credit / /rollback：标「需人工关注」并告警，仍按节奏重试，直到平台人工关闭。
TXN_NOT_FOUND/rollback: the referenced debit was never received, or it failed. Remember the rollback so a late debit with that txnId is refused./rollback：被冲正的扣款从没收到过，或那笔扣款是失败的。必须记下这次冲正，之后同 txnId 的扣款迟到时要拒绝。Rollback treated as complete.视为冲正完成。
TXN_ROLLED_BACK/debit: this txnId was already rolled back before it arrived./debit：这笔扣款到达之前已被冲正。Bet not placed.注不生效。
ROUND_NOT_FOUND/credit: the wallet round has no successful debit on your side./credit：商户侧这个钱包局没有任何成功的扣款。Flagged for manual attention and alerted; retries continue until we close the case.标「需人工关注」并告警；仍按节奏重试，直到平台人工关闭。
ROUND_CLOSEDA new txnId arrives for a closed wallet round.已关闭的钱包局又来了新的 txnId。/debit: bet not placed, alert. /credit / /rollback: flagged for manual attention and alerted, retries continue until we close the case./debit：注不生效，告警。/credit / /rollback：标「需人工关注」并告警，仍按节奏重试，直到平台人工关闭。

Allowed codes per endpoint各接口允许的码

Each endpoint may return only the codes marked here (plus the common codes in Common codes (both directions)). A code outside this list is a protocol violation: we treat the result as unknown (as if INTERNAL_ERROR) and the conformance test fails.

每个接口只能返回下表打勾的码（加上 通用码（两个方向） 的通用码）。返回清单以外的码属于违反协议：平台按结果未知处理（等同 INTERNAL_ERROR），对接测试判为不通过。

On the Wallet API every common code other than OK (INVALID_SIGNATURE, TIMESTAMP_EXPIRED, IP_NOT_ALLOWED, DUPLICATE_REQUEST, INVALID_PARAM, MAINTENANCE, INTERNAL_ERROR) is also handled as result unknown: a debit is rolled back, a credit or rollback is retried. They usually mean a configuration problem and are alerted.

钱包接口上，OK 以外的通用码（INVALID_SIGNATURE、TIMESTAMP_EXPIRED、IP_NOT_ALLOWED、DUPLICATE_REQUEST、INVALID_PARAM、MAINTENANCE、INTERNAL_ERROR）同样按结果未知处理：扣款发冲正，派彩 / 冲正继续重试。它们多半是配置问题，平台会告警。

Wallet code钱包结果码authbalancedebitcreditrollback
INVALID_TOKEN✓
PLAYER_NOT_FOUND✓✓✓
PLAYER_DISABLED✓✓✓
CURRENCY_MISMATCH✓✓✓
INSUFFICIENT_BALANCE✓
BET_REJECTED✓
TXN_CONFLICT✓✓✓
TXN_NOT_FOUND✓
TXN_ROLLED_BACK✓
ROUND_NOT_FOUND✓
ROUND_CLOSED✓✓✓
Platform API endpoint平台接口Codes besides the common ones通用码以外可能返回的码
games/listMERCHANT_DISABLED
games/launchMERCHANT_DISABLED GAME_NOT_FOUND GAME_UNAVAILABLE INVALID_TOKEN PLAYER_MISMATCH PLAYER_DISABLED CURRENCY_NOT_SUPPORTED CURRENCY_MISMATCH WALLET_UNAVAILABLE WALLET_ERROR
rounds/report-urlMERCHANT_DISABLED ROUND_NOT_FOUND

Strict response validation响应强制校验

We validate every Wallet API response. A response that fails any rule below is treated as result unknown (same handling as a timeout), is logged as a protocol violation, and fails the conformance test.

平台对每个钱包接口的响应都做校验。任何一条不满足，都按结果未知处理（与超时相同），记为违反协议，对接测试判为不通过。

#Rule规则
V1HTTP status is 200 and the body is a JSON object with a string code, at most 64 KB. Redirects are not followed: a 3xx fails this rule.HTTP 状态是 200，正文是 JSON 对象且有字符串类型的 code，不超过 64 KB。平台不跟随跳转：3xx 不满足本条。
V2code is OK, a common code, or a code allowed for this endpoint (Allowed codes per endpoint).code 是 OK、通用码，或该接口允许的码（各接口允许的码）。
V3On OK, every required data field of the endpoint is present with the right type.OK 时，该接口 data 的必填字段齐全且类型正确。
V4Every amount and balance is a decimal string (Amounts & time) with no more decimals than the currency precision.所有金额、余额都是十进制字符串（金额与时间），小数位不超过币种精度。
V5/auth: extPlayerId matches ^[A-Za-z0-9_-]{1,64}$; currency is non-empty./auth：extPlayerId 匹配 ^[A-Za-z0-9_-]{1,64}$，currency 非空。
V6/debit, /credit, /rollback on OK: merchantTxnId is a non-empty string ≤ 64 characters./debit、/credit、/rollback 返回 OK 时，merchantTxnId 是非空字符串、不超过 64 个字符。
V7INSUFFICIENT_BALANCE carries data.balance.INSUFFICIENT_BALANCE 必须带 data.balance。
V8A repeated request with the same txnId returns the same code and the same merchantTxnId as the first.同一 txnId 重发，返回的 code 与 merchantTxnId 必须和第一次相同。