开发文档

1. 接入概述

Hash Play 是游戏内容供应商，向商户提供游戏产品（Crash、Dice 等 Hash Play 游戏）。双方采用**余额托管（Hosted Wallet）**合作模式：

• 玩家游戏资金由 Hash Play 托管。 每个玩家在平台内拥有一个独立的托管钱包账户，以 (operator_id, user_id) 寻址，与商户平台的玩家一一对应；
• 商户在玩家进入游戏前后，通过钱包接口向该托管账户存入（deposit）资金；玩家游戏内的投注、派奖、局次撤销等全部资金变动均由 Hash Play 在托管账户内实时本地结算，不回调商户；
• 商户可随时**查询（balance）**托管余额、**对账（transactions）资金流水、核查投注订单（orders），并在玩家需要回收资金时提走（withdraw）**余额（支持部分提现）；
• 上述过程对玩家透明，玩家在游戏内看到的是托管钱包余额的实时变动。

整个接入只涉及一个方向的交互——全部接口均由商户主动调用 Hash Play：

整体交互流程

点击放大

说明：蓝色区域为启动阶段，玩家每次进入游戏时执行一次；绿色区域为游戏与资金管理阶段——玩家进入游戏后直接与 Hash Play交互完成投注与结算（托管钱包内实时动账，不经过商户）；仅当玩家需要充值或提现时，才经由商户平台中转（商户调用 /wallet/deposit、/wallet/withdraw）。余额查询与流水对账由商户按需随时发起。

2. 双方职责划分

Hash Play 负责：

• 提供游戏内容及游戏内全部逻辑（投注判定、开奖、派奖金额计算）；
• 提供游戏启动接口（/launch）与钱包存取接口（/wallet/*）；
• 维护每个玩家的托管钱包账户与全部资金流水，保证账务一致；
• 提供游戏编码清单、联调环境与技术支持。

商户负责：

• 玩家账户体系：在商户平台维护玩家，并以稳定的 user_id 与 Hash Play 侧托管账户对应；
• 在商户平台提供游戏入口，调用启动接口并向玩家分发游戏链接；
• 根据业务节奏调用钱包接口完成存入、提走、余额查询、流水对账与投注订单核查；
• 妥善保管 API Secret，实现签名调用，确保仅商户服务器可以操作本商户的资金。

商户无需对外提供任何钱包回调接口，也无需实现逐笔投注的扣款/入账/撤销逻辑——这些全部由 Hash Play 在托管账户内完成。

3. 环境信息

商户开发前请向 Hash Play 索取下表信息，所有环境信息集中于此处核对：

环境信息变更（如网关地址、IP 白名单）将由 Hash Play 提前通知；请勿将沙箱凭证用于生产。

关于 Base URL 的组成：Base URL 由「网关域名 + nginx 前缀 prod-api + 网关路由 customer + 应用前缀 app-api + api/v1/game」拼成。文档其余章节用 {base_url} 代指它，具体接口路径在其后拼接：

• 启动游戏 {base_url}/launch
• 游戏列表 {base_url}/list
• 钱包接口 {base_url}/wallet/deposit、/wallet/withdraw、/wallet/balance、/wallet/transactions、/wallet/orders、/wallet/operation/status

联调地址以 Hash Play 提供为准，禁止自行拼装路径。

4. 接入凭证与配置

签约后，Hash Play 为商户分配身份凭证。商户无需向 Hash Play 登记任何回调地址。

4.1 Hash Play 分配的凭证

安全要求：API Secret 等同于资金接口的访问密钥，请仅保存在服务端安全存储中，禁止写入前端代码、客户端安装包、日志或代码仓库。如怀疑泄露，请立即联系 Hash Play 轮换密钥。

4.2 商户需提供的配置

商户无需提供钱包接口地址，配置仅有一项：

IP 白名单是必需项，不是可选项：平台侧查不到该商户的启用白名单记录时，会直接判定 IP 校验不通过并返回 4004。白名单支持精确 IPv4 与 CIDR 网段（如 203.0.113.0/24）。商户出口 IP 发生变化（扩容、迁移机房、NAT 出口调整）时请提前通知 Hash Play 更新，否则全部接口将不可用。

沙箱联调阶段同样需要登记 IP 白名单，请把联调机/联调出口 IP 一并提供给 Hash Play。

5. 安全机制：接口签名

双方之间的每一次通信均需通过同一套签名校验，用于确保：

1. 请求来源可信（未被第三方伪造）；
2. 内容未被篡改（金额等参数在传输途中未被修改）；
3. 请求未被重放（历史请求无法被重复提交以触发存入或提走）。

5.1 通信规则

商户调用 Hash Play 的每个请求均携带 4 个专用请求头：

验签通过后平台才会继续校验商户状态（4005）与出口 IP 白名单（4004），因此签名错误会先于 IP 问题暴露——排查时请按 4002 → 4005 → 4004 的顺序逐项确认。

5.2 签名计算方法（唯一算法，双方一致）

签名算法为业界通用的 HMAC-SHA256，主流编程语言均有标准实现。计算分两步：

第一步：构造规范化签名串（canonical string）。

1. 取请求体（JSON）中的全部顶层字段，剔除值为空的字段；
2. 按字段名字典顺序排序，拼接为 字段名=值&字段名=值&... 的形式；
3. 末尾依次追加时间戳与随机串（以 & 连接）。

例如存入接口的请求体为：

{
  "user_id": "u_10086",
  "request_id": "dep_20260908_0001",
  "amount": "1000.00"
}

按字段名字典序排序拼接并追加时间戳、随机串后，待签名原文为：

amount=1000.00&request_id=dep_20260908_0001&user_id=u_10086&1712345678123&f3a9c2e8d1b4...

无请求体的接口（如 GET /list）：签名串中没有字段部分，退化为 &{timestamp}&{nonce}（即以 & 开头）。这是常见踩坑点——此时不要在开头凭空拼一个 & 之外的字符。

第二步：以 API Secret 为密钥，对原文执行 HMAC-SHA256 运算，结果以十六进制小写表示，即为 X-Signature 的值。

关于"原始报文"的说明（消除歧义）：签名对象永远是上面的规范化签名串，而非 HTTP 报文的原始字节。因此 JSON 的空格、字段顺序、大小写差异均不影响验签结果。推荐实现方式是：解析 JSON → 提取字段 → 重新构造规范化签名串（见第 6 章代码示例）。所谓"不要重新序列化"指的是不要把解析后的对象直接转回 JSON 字符串再拿去 HMAC——那不是本协议的签名对象。

5.3 重要注意事项（对接失败的常见原因）

1. 时间戳单位统一为毫秒：X-Timestamp 使用毫秒（13 位 Unix epoch 毫秒值）。校验窗口为 ±60 秒（60000 毫秒），请确保服务器时间为标准时间（建议开启 NTP 同步）。
2. 禁止使用 JSON 数字类型传递金额：amount、balance、bet_amount、win_amount、mult_value 等字段在请求与响应中均为 JSON 字符串（如 "1000.00"）。禁止写成数字（"amount": 10.00），否则平台按数字文本参与签名时可能变为 10.0，与商户签名串不一致而返回 4002。构造签名串时按请求体原样字符串拼接（"1000.00" → amount=1000.00），禁止数值格式化；前端展示时再 Number() 转换。
3. 空值剔除：值为 null、空字符串的字段不参与签名串构造（平台侧同样跳过）。因此 "amount": null 与不传该字段等价。
4. 字段名大小写敏感：签名串与请求体字段名均使用小写下划线风格（user_id、request_id、game_code…），请勿写成驼峰。

5.4 验签失败的统一响应

Hash Play 校验商户请求验签未通过时，返回：

{
  "code": 4002,
  "message": "签名验证失败"
}

message 为本地化提示文本（可能随语言变化），请始终以 code 作为判定依据。例外：游戏列表接口 /list 在验签失败时固定返回 {"code": 4002, "message": "SIGNATURE_VERIFY_FAILED"}。

5.5 响应结构与两类错误

业务接口的响应统一为扁平 JSON，成功与业务失败均返回 HTTP 200，以 code 区分（code = 0 表示成功）：

{ "code": 0, "message": "success", "...": "各接口自有字段" }

需注意两类错误的字段名不一致，解析时请同时兼容：

分工说明：/launch、/exchange 对请求体做了注解校验，漏传 operator_id/user_id/currency 这类必填项时会走框架级错误（{code:500, msg}），而不是业务错误码；/wallet/* 未做注解校验，字段缺失一般返回业务码（如 4011），只有请求体整体缺失或不是合法 JSON 时才返回 {code:500, msg}。

实现建议：先判 HTTP 状态码，再判 code === 0；取提示文案时用 data.message ?? data.msg。

const crypto = require('crypto');

// 签名生成：body 为请求体对象
function generateSignature(apiSecret, timestampMs, nonce, body) {
    const sorted = {};
    Object.keys(body || {})
        .filter((k) => body[k] !== null && body[k] !== undefined && body[k] !== '')
        .sort()
        .forEach((k) => (sorted[k] = String(body[k])));

    const canonical = Object.entries(sorted)
        .map(([k, v]) => `${k}=${v}`)
        .join('&');
    const signText = `${canonical}&${timestampMs}&${nonce}`;

    return crypto
        .createHmac('sha256', apiSecret)
        .update(signText, 'utf8')
        .digest('hex'); // 十六进制小写
}

// 调用 /launch（钱包 /wallet/* 接口同理，仅换路径与请求体）
const axios = require('axios');

async function launch(apiSecret, apiKey, payload) {
    const timestamp = String(Date.now()); // 毫秒级（13 位）
    const nonce = crypto.randomUUID().replace(/-/g, '');
    const signature = generateSignature(apiSecret, timestamp, nonce, payload);

    const resp = await axios.post(
        'https://api.example.com/prod-api/customer/app-api/api/v1/game/launch',
        payload,
        {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': apiKey,
                'X-Timestamp': timestamp,
                'X-Nonce': nonce,
                'X-Signature': signature,
            },
        }
    );
    return resp.data; // { code: 0, message: 'success', game_url: '...', balance: '0' }
}

// 调用 /wallet/deposit：为玩家托管钱包充值
// request_id 为本次存入的唯一订单号（商户侧生成），平台按 (operator_id, request_id) 幂等防重
async function deposit(apiSecret, apiKey, userId, requestId, amount) {
    // 金额用字符串传入，避免浮点序列化差异导致验签失败
    const payload = { user_id: userId, request_id: requestId, amount: String(amount) };
    const timestamp = String(Date.now());
    const nonce = crypto.randomUUID().replace(/-/g, '');
    const signature = generateSignature(apiSecret, timestamp, nonce, payload);

    const resp = await axios.post(
        'https://api.example.com/prod-api/customer/app-api/api/v1/game/wallet/deposit',
        payload,
        {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': apiKey,
                'X-Timestamp': timestamp,
                'X-Nonce': nonce,
                'X-Signature': signature,
            },
        }
    );
    return resp.data; // { code: 0, message: 'success', currency: 'USDT', amount: '1000.00', balance: '1000.00', txn_id: '...' }
}

// 调用 /wallet/operation/status：按商户订单号核对存取是否成功（超时/未知结果时使用）
async function operationStatus(apiSecret, apiKey, requestId, operationType) {
    const payload = { request_id: requestId, operation_type: operationType }; // 'DEPOSIT' | 'WITHDRAW'
    const timestamp = String(Date.now());
    const nonce = crypto.randomUUID().replace(/-/g, '');
    const signature = generateSignature(apiSecret, timestamp, nonce, payload);

    const resp = await axios.post(
        'https://api.example.com/prod-api/customer/app-api/api/v1/game/wallet/operation/status',
        payload,
        {
            headers: {
                'Content-Type': 'application/json',
                'X-API-Key': apiKey,
                'X-Timestamp': timestamp,
                'X-Nonce': nonce,
                'X-Signature': signature,
            },
        }
    );
    return resp.data; // { code: 0, status: 1, amount: '1000.00', txn_id: '...' }
}

// 调用 GET /list（游戏列表）：无请求体，签名串退化为 '&timestamp&nonce'
async function gameList(apiSecret, apiKey, language = 'zh-CN') {
    const timestamp = String(Date.now());
    const nonce = crypto.randomUUID().replace(/-/g, '');
    const signature = generateSignature(apiSecret, timestamp, nonce, null); // body 传 null

    const resp = await axios.get(
        `https://api.example.com/prod-api/customer/app-api/api/v1/game/list?language=${encodeURIComponent(language)}`,
        {
            headers: {
                'X-API-Key': apiKey,
                'X-Timestamp': timestamp,
                'X-Nonce': nonce,
                'X-Signature': signature,
            },
        }
    );
    return resp.data; // { code: 0, games: [...] }
}

7. 游戏启动

7.1 业务流程

1. 玩家在商户平台点击游戏入口；
2. 商户后端（不得从前端直接调用，否则将暴露 Secret）向 Hash Play 申请游戏入场链接；
3. Hash Play 校验签名与参数后，为该 (operator_id, user_id) 查找或创建平台用户与托管钱包账户，并生成一次性入场链接（内含一次性票据 ticket）返回，同时返回该玩家当前的平台内托管余额；
4. 商户将链接交由玩家浏览器打开（新窗口或内嵌均可），玩家进入游戏。

入场链接每次申请仅有效一次且具有时效（票据 ticket 有效期 5 分钟，兑换一次后立即失效），不得缓存复用，亦不得多玩家共用。玩家每次进入游戏重新申请即可，该接口开销很小。

幂等提示：/launch 按 (operator_id, user_id) 查找或创建平台用户与托管钱包，重复调用不会新建用户，也不会改变余额，可以放心重复调用（但每次都要重新打开返回的 game_url）。

余额来源：返回的 balance 是玩家当前的平台托管余额（字符串）。首次启动通常为 "0"，请随后调用 /wallet/deposit 为玩家充值（见第 8 章）。

7.1.1 game_code 不传时会发生什么

game_code 是可选字段，语义分两种情况：

因此若商户希望在大厅中屏蔽未开通的游戏入口，仍需传入 game_code 走权限校验；而不传 game_code 时，玩家进入大厅后能否开局由平台按游戏权限另行判定。

game_code 与 game_type 字典的标签（dictLabel）做大小写不敏感匹配（crash / CRASH / Crash 等价）；若某个标签自身含空格，则允许只传其第一个单词作为简写。最稳妥的做法始终是：直接用 游戏列表 API 返回的 gameCode 原值，不要自己改写。

7.2 接口定义

商户调用：

POST {base_url}/api/v1/game/launch

请求参数（JSON 格式，字段名为小写下划线风格）：

language 常用取值（完整列表见 SimpleLocalize 语言代码表）：

传入前请与 Hash Play 确认该语言的游戏语言包是否就绪；传入未支持的语言时，游戏将回退至英文界面。

请求示例：

{
  "operator_id": "M001",
  "user_id": "u_10086",
  "game_code": "Crash",
  "currency": "USDT",
  "username": "玩家A",
  "language": "zh-CN",
  "return_url": "https://yourdomain.com/lobby"
}

Hash Play 返回：

{
  "code": 0,
  "message": "success",
  "game_url": "https://game.hashplay.io/hashWeb/#/zh-CN?ticket=8f3e...c21a",
  "balance": "1000.00"
}

失败返回（{code, message, game_url: null}）：

除 500 外，上述失败重试同一请求大概率仍会失败，请按上表定位原因后再重发，避免无脑轮询。玩家侧统一提示为「游戏暂不可用，请稍后再试」即可。

8. 钱包接口

玩家进入游戏后，游戏内的一切资金变动（投注扣减、派奖入账、异常局次退款）均由 Hash Play 在该玩家的托管钱包内实时本地结算，商户无需感知、无需提供回调。商户的职责是按本节规范调用 6 个钱包接口，管理玩家在平台内的托管资金。

8.1 六个钱包接口的语义

六个接口统一位于 {base_url}/api/v1/game/wallet 下。除存取状态外，均按 (operator_id, user_id) 寻址玩家（operator_id 由 X-API-Key 对应的凭证自动确定，请求体中无需传）；存取状态按 (operator_id, request_id, operation_type) 查询；流水/订单查询的 user_id 可不传，缺省查询该商户全部用户（响应 records 中含 user_id 供区分）。鉴权与 /launch 完全一致（四请求头验签 + IP 白名单）。

8.2 存入（Deposit）——为玩家充值

商户调用：

POST {base_url}/wallet/deposit

请求参数：

request_id 是存取接口的幂等键，也是后续用 /wallet/operation/status 核对结果的查询键。请由商户侧生成并落库（与自己的充值订单绑定），长度建议 ≤ 64。

request_id 不是随机串：它必须能唯一标识"这一笔业务"。网络超时后重发时沿用同一个 request_id；而一次全新的充值必须换新号，否则会被 4014 拒绝。

请求示例：

{
  "user_id": "u_10086",
  "request_id": "dep_20260908_0001",
  "amount": "1000.00"
}

Hash Play 返回：

{
  "code": 0,
  "message": "success",
  "currency": "USDT",
  "amount": "1000.00",
  "balance": "1000.00",
  "txn_id": "txn_20260904_0001"
}

amount 为本次存入金额，balance 为存入后的最新托管余额，txn_id 为本笔流水号（由 Hash Play 统一生成，供对账使用）。金额字段均为字符串（见 5.3）。

deposit 可能返回的错误码：

8.3 提走（Withdraw）——回收余额

商户调用：

POST {base_url}/wallet/withdraw

请求参数：

全额提走时不要传 amount（或传空串），不要自己先查余额再传入该数值——两次调用之间可能会发生游戏结算，导致金额不匹配而返回 4001。

请求示例（部分提现）：

{
  "user_id": "u_10086",
  "request_id": "wd_20260908_0001",
  "amount": "500.00"
}

请求示例（全额提走）：

{
  "user_id": "u_10086",
  "request_id": "wd_20260908_0002"
}

Hash Play 返回：

• 提现成功：{ "code": 0, "message": "success", "currency": "USDT", "amount": "500.00", "balance": "515.00", "txn_id": "txn_20260904_0002" }（amount 为本次提现金额，balance 为提现后最新余额；全额提走时 balance 为 "0.00"）
• 余额为零：{ "code": 4003, "message": "WALLET_BALANCE_ZERO", "currency": "USDT", "balance": "0.00" }（无可提资金，按业务场景处理即可）

Withdraw 支持部分提现：传入 amount 提取指定金额；不传 amount 则提走全部余额并清零。提现金额不得超过当前余额，否则平台返回 4001 金额非法。

withdraw 可能返回的错误码：

8.4 余额查询（Balance）

商户调用：

POST {base_url}/wallet/balance

请求参数：

{ "user_id": "u_10086" }

user_id 必填（同 8.3）。余额查询不涉及动账，无需 request_id。

Hash Play 返回：

{
  "code": 0,
  "message": "success",
  "currency": "USDT",
  "balance": "1015.00"
}

balance 为字符串（如 "1015.00"），商户前端展示前请自行 Number() / BigDecimal 转换，勿用 typeof === 'number' 判断"平台未返回"。

可能返回的错误码： 4011 / 4012（user_id 为空 / 无效——通常意味着该玩家尚未通过 /launch 在平台建档）。

8.5 流水查询（Transactions）——对账

商户调用：

POST {base_url}/wallet/transactions

请求参数：

Hash Play 返回：

{
  "code": 0,
  "message": "success",
  "currency": "USDT",
  "page_num": 1,
  "page_size": 10,
  "total": 3,
  "records": [
    {
      "user_id": "u_10086",
      "txn_id": "txn_20260904_0001",
      "txn_type": "DEPOSIT",
      "amount": "1000.00",
      "balance_before": "0.00",
      "balance_after": "1000.00",
      "round_id": null,
      "ref_txn_id": null,
      "remark": "deposit:M001",
      "create_time": 1756948800000
    },
    {
      "user_id": "u_10086",
      "txn_id": "txn_20260904_0003",
      "txn_type": "BET",
      "amount": "10.00",
      "balance_before": "1000.00",
      "balance_after": "990.00",
      "round_id": "r_20260904_0001",
      "ref_txn_id": null,
      "remark": null,
      "create_time": 1756948900000
    },
    {
      "user_id": "u_10086",
      "txn_id": "txn_20260904_0004",
      "txn_type": "WIN",
      "amount": "25.00",
      "balance_before": "990.00",
      "balance_after": "1015.00",
      "round_id": "r_20260904_0001",
      "ref_txn_id": "txn_20260904_0003",
      "remark": null,
      "create_time": 1756948950000
    }
  ]
}

8.6 订单查询（Orders）——投注订单核查

商户调用：

POST {base_url}/wallet/orders

请求参数（与 8.5 流水查询一致）：

Hash Play 返回：

{
  "code": 0,
  "message": "success",
  "currency": "USDT",
  "page_num": 1,
  "page_size": 10,
  "total": 1,
  "records": [
    {
      "user_id": "u_10086",
      "round_id": "r_20260904_0001",
      "game_code": "Crash",
      "currency": "USDT",
      "bet_amount": "10.00",
      "win_amount": "25.00",
      "status": "SETTLED",
      "settle_result": 1,
      "mult_value": "2.5",
      "settle_time": 1756948950000,
      "create_time": 1756948900000,
      "game_detail": "{...}"
    }
  ]
}

流水（8.5）记录的是每一笔资金变动（含存取款），订单（本节）记录的是每一局游戏的投注与结算结果。两者通过 round_id 关联，配合使用可完整还原玩家行为与资金变化。

8.7 存取状态查询（Operation Status）——核对商户订单是否成功

商户调用：

POST {base_url}/wallet/operation/status

请求参数：

请求示例：

{
  "request_id": "dep_20260908_0001",
  "operation_type": "DEPOSIT"
}

本接口不需要传 user_id——request_id 在商户维度内唯一即可定位。

Hash Play 返回：

{
  "code": 0,
  "message": "success",
  "currency": "USDT",
  "request_id": "dep_20260908_0001",
  "operation_type": "DEPOSIT",
  "status": 1,
  "amount": "1000.00",
  "txn_id": "txn_20260904_0001",
  "error_msg": null,
  "create_time": 1756948800000
}

可能返回的错误码： 4016（未找到该 request_id 的记录——包含从未发起、request_id 拼写错误两种情况）/ 4017（operation_type 非 DEPOSIT/WITHDRAW）。

超时或未知结果时，请先调本接口核对：status=1 表示已成功入账/扣款，勿用同一 request_id 重发；status=0 或返回 4016（记录不存在）时，可用原 request_id 重试。

8.8 统一返回码约定

同名不同义：4006、4011、4012、4013 在 /launch 与 /wallet/* 下含义不同（前者报的是票号/游戏权限类问题，后者报的是参数类问题），部分文案还受多语言影响。请按"接口 + code"两部分一起判断，不要只看 code：

code	/launch 下的含义	/wallet/* 下的含义
4006	商户无该游戏权限（见 7.2）	transactions/orders 时间范围非法
4011	ticket 为空（仅 /exchange）	user_id 为空
4012	ticket 无效或已过期	user_id 无效（未建档）
4013	ticket 对应用户不存在	request_id 为空

9. 完整交互示例

以玩家（商户为其首次充值 1000.00 USDT）进行一局 Crash 游戏为例：

点击放大

对账公式（任意时刻均应成立，供商户财务核验）：

所有存入(Deposit) − 所有提走(Withdraw) − 所有投注(Bet) + 所有派奖(Win) + 所有退款(Rollback) = 当前托管余额(Balance)

上图示例：商户 deposit 1000（余额 0 → 1000.00）、玩家游戏内投注 Debit 10（→ 990.00）、派奖 Win 25（→ 1015.00），玩家退出后商户 withdraw 提走全部 1015.00（余额清零）。若局次异常被取消，平台自动追加一笔 Rollback 把投注本金原路退回托管余额，无需商户介入。

10. 商户系统技术要求

以下为余额托管模式的硬性要求，直接关系到玩家体验与双方资金安全：

1. 资金变动以 Hash Play 流水为准：游戏内动账全部发生在平台侧，商户财务请以 /wallet/transactions 流水 + /wallet/balance 余额为对账依据，公式见第 9 章。
2. user_id 稳定唯一：托管钱包以 (operator_id, user_id) 寻址。同一玩家必须始终使用同一 ID，错用其他玩家的 ID 将操作到他人钱包。
3. 充值前置：玩家投注使用托管余额，余额不足时投注将被平台拒绝并向玩家提示。请确保玩家进入游戏前或余额耗尽时及时 deposit。
4. 提现支持部分金额：withdraw 传入 amount 提取指定金额，不传则提走全部余额并清零；如遇 4003 表示余额已为零，属正常业务结果而非故障。
5. 响应性能：deposit/balance 位于玩家进入游戏的关键路径上，请确保商户侧发起调用的链路稳定；Hash Play 侧目标 500 毫秒内响应。
6. 先签验后调用：所有请求必须携带合法签名（规则见第 5 章；失败返回 4002）。
7. IP 白名单必配：商户出口 IP 须在 Hash Play 侧登记，未登记时全部接口返回 4004。支持 IPv4 / CIDR；出口变更须提前通知。
8. 时钟准确：服务器须同步 NTP；时间戳与窗口规则见 5.3。
9. 金额类型：禁止使用 JSON 数字传递金额，规则见 5.3。
10. request_id 与重试：deposit/withdraw 的 request_id 须落库并作为幂等键（规则见 8.2）；超时或未知结果时先调 /wallet/operation/status 核对，禁止未核对就换新号重发。

11. 接入清单

• 准备：从 Hash Play 获取商户编码、API Key、API Secret、网关地址（沙箱/生产，见第 3 章环境信息）
• 准备：向 Hash Play 提供商户服务器出口 IP（必配，支持 IPv4 / CIDR；不登记则全部接口返回 4004）
• 准备：调 /api/v1/game/list 拉取当前已开通的游戏清单，不要写死本地游戏编码表（清单会随平台上下架变动）
• 开发：实现 HMAC-SHA256 签名工具，通过 Hash Play 提供的签名自测用例（重点验证：字段字典序、空值剔除、金额按原样字符串拼接、毫秒级时间戳）
• 开发：实现游戏启动调用（服务端调 /launch、向前端分发 game_url）
• 开发：实现钱包接口调用（/wallet/deposit、/wallet/withdraw、/wallet/balance、/wallet/transactions、/wallet/orders、/wallet/operation/status）
• 开发：request_id 生成规则 + 落库；deposit/withdraw 前必填校验；超时后走 /wallet/operation/status 核对
• 开发：金额字段按 5.3 以字符串全链路处理（展示前再 Number()）
• 自测：正常场景——充值 → 余额查询 → 部分提现 / 全额提走
• 自测：异常场景——验签失败（4002）、IP 未登记（4004）、余额为零提走（4003）、user_id 无效（4012）、金额非法（4001）、request_id 缺失（4013）、request_id 重复（4014）
• 自测：时间戳超出 ±60 秒窗口 → 确认返回 4002 且能通过 NTP 修复
• 联调：与 Hash Play 共同跑通全流程：启动 → 充值 → 投注 → 派奖 → 流水核对 → 提走
• 上线：生产凭证切换、IP 白名单确认、上线首日对账

13. 游戏列表

13.1 游戏列表 API（推荐，实时获取）

游戏清单持续更新，请优先通过本接口实时获取，不要把清单写死在您的系统里——Hash Play 上线新游戏后无需等待文档重发，接口即刻可见：

商户调用：

GET {base_url}/api/v1/game/list?language=zh-CN

签名：与 /launch 完全一致（X-API-Key / X-Timestamp 毫秒级 ±60 秒 / X-Nonce / X-Signature）。GET 请求无请求体，签名串退化为 &时间戳&随机串（见 5.2）。

Hash Play 返回：

{
  "code": 0,
  "message": "success",
  "games": [
    {
      "gameCode": "Crash",
      "gameName": "爆点",
      "status": 1,
      "supportedCurrency": "USDT",
      "thumbnail": "https://resource.hashplay.io/xxx.png",
      "isMultiplayer": 0,
      "sort": 1
    }
  ]
}

本接口返回平台全量上架游戏，status 表示"贵商户是否已开通"。请只对 status=1 的游戏展示入口——传入未开通游戏的 game_code 调 /launch 会返回 4006。

错误码：验签失败、商户停用、IP 未登记时返回 { "code": <4002|4005|4004>, "message": "SIGNATURE_VERIFY_FAILED" 或对应文案, "games": null }。注意本接口的失败文案不跟随语言（验签失败固定为字面量 SIGNATURE_VERIFY_FAILED），请以 code 为准。

建议商户每次玩家进入游戏大厅时调用本接口（或短 TTL 缓存，如 5 分钟），status=1 的游戏才展示入口。

13.2 附录：游戏编码速查表（快照，仅供参考）

本表只是某一时点的快照，不是契约。 game_code 的真实来源是平台 game_type 字典的 dictLabel，运营侧会随游戏上下架、改名而调整（历史上 Coinflip → flipCoin、Xoc Dia → Xocdia、Cock fighting → CockFight 都发生过）。请一律以 13.1 的 /api/v1/game/list 接口为准，本表仅用于理解命名风格与联调时人工核对。

上表"序号"即平台 game_type 字典的 dictValue（内部编号，商户无需传该编号，/launch 只认 game_code 标签）。编号 6、7 已废弃。

匹配规则回顾：大小写不敏感（crash、CRASH、Crash 等价）；若标签自身含空格，允许只传首单词。除此之外的拼写差异（例如把 flipCoin 写成历史名 Coinflip）会匹配失败并返回 4006。