钱包（转账）

转账钱包：转入、转出、查询转账结果与余额。转账以 txnId 幂等。

TIP

示例使用〈认证与签名〉的示例密钥与时间戳计算签名，可直接用〈签名调试器〉验算。

转入（加点）

POST /api/tenant/v1/wallet/deposit

把金额转入玩家的游戏钱包。单阶段、幂等：同一个 txnId 重送不会重复入账，而是返回第一次的结果（同一个 balance），duplicate 为 true。同一个 txnId 但金额或方向不同，或最近两个月内已用在另一位玩家，回 TXN_CONFLICT。

玩家不存在时会以请求的 currency 自动创建。
currency 必须等于玩家的币种，否则回 CURRENCY_MISMATCH。
balance 是这笔转账完成当下的余额。
响应成功的转账一定查得到：GET /wallet/transfer?txnId=…&username=…。
超时或收到 5xx 时，以相同 txnId 与相同内容重送，或先以 GET /wallet/transfer 查询；不要换一个新的 txnId。

请求体（application/json）

字段	类型	必填	说明
`username`	string	是	玩家账号，1–32 个字符（字母或数字与 `_ . @ -`）；不分大小写（`Alice` 与 `alice` 是同一位玩家）。格式：`^[A-Za-z0-9_.@-]{1,32}$`
`txnId`	string	是	你的转账单号，1–64 个字符（字母或数字与 `_ . : -`），作为幂等键。请在你的整个租户内保持唯一（不要在不同玩家之间重复使用）。格式：`^[A-Za-z0-9_.:-]{1,64}$`
`amount`	string	是	大于 0 的金额，十进制字符串，最多 4 位小数，例如 `"1000"`、`"99.5"`。请用字符串，不要用浮点数。格式：`^\d{1,15}(\.\d{1,4})?$`
`currency`	string	是	必须等于玩家的币种。格式：`^[A-Za-z]{3,5}$`

请求示例

http

POST /api/tenant/v1/wallet/deposit HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: exc3b9fb78a452ce2fc90cff
X-Signature: a43ebc031d05839610a3d5e52eb10ffa82fd8c83f87e8476d57c3cde3b80917a
Content-Type: application/json

{"username":"alice","txnId":"dep-20260924-000123","amount":"1000","currency":"TWD"}

响应的 data

字段	类型	说明
`txnId`	string	请求的 `txnId`。
`status`	string	一律为 `done`（单阶段，没有处理中状态）。
`balance`	string	这笔转账完成当下的余额；重送同一个 `txnId` 时返回第一次的值。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`duplicate`	boolean	`true` 表示这个 `txnId` 先前已处理过：这次没有再动到余额，响应是第一次的结果。

响应示例

第一次处理

json

{
  "ok": true,
  "data": {
    "txnId": "dep-20260924-000123",
    "status": "done",
    "balance": "2500.5",
    "duplicate": false
  }
}

重送同一个 txnId（返回第一次的结果）

json

{
  "ok": true,
  "data": {
    "txnId": "dep-20260924-000123",
    "status": "done",
    "balance": "2500.5",
    "duplicate": true
  }
}

错误码

错误码	HTTP	意义
`INVALID_PARAMETER`	400	缺少必要字段，或字段格式、值不正确；`message` 会指出是哪个字段。
`INVALID_AMOUNT`	400	金额不是大于 0、最多 4 位小数的十进制字符串。
`INVALID_USERNAME`	400	玩家账号不符合规则（1–32 个字符，字母或数字与 `_ . @ -`），或查询时没有带 `username`。
`INVALID_CURRENCY`	400	创建新玩家时指定的币种代码不合法（需要 3–5 个英文字母）。
`CURRENCY_NOT_ENABLED`	400	创建新玩家时指定的币种，租户还没打开（多币种：Console「限红方案 → 币种」）。已存在的玩家不受影响。
`CURRENCY_MISMATCH`	400	转账的 `currency` 与玩家的币种不同。玩家的币种在创建时决定，之后不能变更。
`PLAYER_LIMIT`	403	玩家账号数已达方案上限（免费展示方案默认 50、沙箱 500）。
`TXN_CONFLICT`	409	这个 `txnId` 已经用在另一笔金额或方向不同的转账，或最近两个月内已用在另一位玩家。

所有端点另外都可能返回共通错误（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

转出（扣点）

POST /api/tenant/v1/wallet/withdraw

从玩家的游戏钱包转出。幂等规则同转入：同一个 txnId 重送会返回第一次的结果。

只能转出可用余额：下注时本金已先扣除，未结算的注不会被转走；不足时回 INSUFFICIENT_BALANCE。
玩家必须已存在（PLAYER_NOT_FOUND）。

请求体（application/json）

字段	类型	必填	说明
`username`	string	是	玩家账号，1–32 个字符（字母或数字与 `_ . @ -`）；不分大小写（`Alice` 与 `alice` 是同一位玩家）。格式：`^[A-Za-z0-9_.@-]{1,32}$`
`txnId`	string	是	你的转账单号，1–64 个字符（字母或数字与 `_ . : -`），作为幂等键。请在你的整个租户内保持唯一（不要在不同玩家之间重复使用）。格式：`^[A-Za-z0-9_.:-]{1,64}$`
`amount`	string	是	大于 0 的金额，十进制字符串，最多 4 位小数，例如 `"1000"`、`"99.5"`。请用字符串，不要用浮点数。格式：`^\d{1,15}(\.\d{1,4})?$`
`currency`	string	是	必须等于玩家的币种。格式：`^[A-Za-z]{3,5}$`

请求示例

http

POST /api/tenant/v1/wallet/withdraw HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: exc26f22db83dc51cea1eb7f
X-Signature: 3cdc9cb2100e63618316b3d333d880daab0adae2e861f2a40e1ff8ab4fd971a7
Content-Type: application/json

{"username":"alice","txnId":"wd-20260924-000077","amount":"500.25","currency":"TWD"}

响应的 data

字段	类型	说明
`txnId`	string	请求的 `txnId`。
`status`	string	一律为 `done`（单阶段，没有处理中状态）。
`balance`	string	这笔转账完成当下的余额；重送同一个 `txnId` 时返回第一次的值。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`duplicate`	boolean	`true` 表示这个 `txnId` 先前已处理过：这次没有再动到余额，响应是第一次的结果。

响应示例

json

{
  "ok": true,
  "data": {
    "txnId": "wd-20260924-000077",
    "status": "done",
    "balance": "2000.25",
    "duplicate": false
  }
}

错误码

错误码	HTTP	意义
`INVALID_PARAMETER`	400	缺少必要字段，或字段格式、值不正确；`message` 会指出是哪个字段。
`INVALID_AMOUNT`	400	金额不是大于 0、最多 4 位小数的十进制字符串。
`INVALID_USERNAME`	400	玩家账号不符合规则（1–32 个字符，字母或数字与 `_ . @ -`），或查询时没有带 `username`。
`CURRENCY_MISMATCH`	400	转账的 `currency` 与玩家的币种不同。玩家的币种在创建时决定，之后不能变更。
`PLAYER_NOT_FOUND`	404	这个账号的玩家不存在。
`TXN_CONFLICT`	409	这个 `txnId` 已经用在另一笔金额或方向不同的转账，或最近两个月内已用在另一位玩家。
`INSUFFICIENT_BALANCE`	409	转出金额大于可用余额（未结算注单的本金不可转出）。

所有端点另外都可能返回共通错误（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

查询转账

GET /api/tenant/v1/wallet/transfer

依 txnId 查询转账结果。用在转入、转出超时之后，确认是否已经处理。

请一并带 username：这样只要转账已经成功就一定查得到（包含租户流水的副本还在送达途中的时候）。
租户流水的查询范围是当月与前 3 个月（依 UTC 月份）。
回 TXN_NOT_FOUND 表示这笔转账没有执行（或仍在处理中）：请以相同 txnId、相同内容重送，直到得到明确的成功或 4xx 结果；不要改用新的 txnId。
dir 为 adjust 表示这个单号是 Console 的人工上下分。

参数

参数	位置	类型	必填	说明
`txnId`	query	string	是	转账时使用的 `txnId`。格式：`^[A-Za-z0-9_.:-]{1,64}$`
`username`	query	string	否	转账的玩家账号（建议带）。租户流水查不到时，改以这位玩家钱包自己的记录回答。格式：`^[A-Za-z0-9_.@-]{1,32}$`

请求示例

http

GET /api/tenant/v1/wallet/transfer?txnId=dep-20260924-000123&username=alice HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex6926b9a725a67c6cc02f60
X-Signature: 93a44cb15149333af7e00fc57274af52ba62f79f102be9a9269edc1eaede7a67

响应的 data

字段	类型	说明
`txnId`	string	转账单号。
`username`	string	玩家账号。
`dir`	string	`in` 转入、`out` 转出、`adjust` Console 人工上下分。可能的值：`in`、`out`、`adjust`
`amount`	string	金额（正数）。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`status`	string	一律为 `done`。
`balance`	string \| null	这笔转账完成后的余额。
`at`	string (date-time)	UTC 时间，ISO-8601 含毫秒。

响应示例

json

{
  "ok": true,
  "data": {
    "txnId": "dep-20260924-000123",
    "username": "alice",
    "dir": "in",
    "amount": "1000",
    "status": "done",
    "balance": "2500.5",
    "at": "2026-09-24T03:00:01.250Z"
  }
}

错误码

错误码	HTTP	意义
`INVALID_PARAMETER`	400	缺少必要字段，或字段格式、值不正确；`message` 会指出是哪个字段。
`TXN_NOT_FOUND`	404	查不到这个 `txnId` 的转账：查询时有带 `username` 表示这笔转账没有执行（或仍在处理中）；没带时只查租户流水（当月与前 3 个月）。

所有端点另外都可能返回共通错误（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

查询余额

GET /api/tenant/v1/wallet/balance

玩家目前的可用余额（已扣除未结算注单的本金）。

参数

参数	位置	类型	必填	说明
`username`	query	string	是	玩家账号。格式：`^[A-Za-z0-9_.@-]{1,32}$`

请求示例

http

GET /api/tenant/v1/wallet/balance?username=alice HTTP/1.1
Host: elite.ewin888.com
X-Api-Key: ek_s_1a_XXXXXXXXXXXXXXXX
X-Timestamp: 1790218800
X-Nonce: ex176285a304e084623ee6cf
X-Signature: d80f06a9225952f186571488addf4319ae8f87645fb80486d46cf5eac36db51f

响应的 data

字段	类型	说明
`balance`	string	玩家金额，十进制字符串，最多 4 位小数；响应会去掉小数尾端的 0（例如 `"100"`、`"0.95"`、`"1000.5"`）。格式：`^-?\d{1,15}(\.\d{1,4})?$`
`currency`	string	币种。

响应示例

json

{
  "ok": true,
  "data": {
    "balance": "2500.5",
    "currency": "TWD"
  }
}

错误码

错误码	HTTP	意义
`INVALID_USERNAME`	400	玩家账号不符合规则（1–32 个字符，字母或数字与 `_ . @ -`），或查询时没有带 `username`。
`PLAYER_NOT_FOUND`	404	这个账号的玩家不存在。

所有端点另外都可能返回共通错误（UNAUTHORIZED、IP_NOT_ALLOWED、TENANT_SUSPENDED、RATE_LIMITED、INTERNAL_ERROR…）。

钱包（转账） ​

转入（加点） ​

转出（扣点） ​

查询转账 ​

查询余额 ​

钱包（转账）

转入（加点）

转出（扣点）

查询转账

查询余额