数字货币余额查询

概述

余额查询 API 用于获取商户数字货币账户的实时余额，包含可用余额、冻结金额与总额。可查询单一币种，也可一次拉取全部已开通币种。

公共请求头（含必填 Nonce）、公共请求体字段与统一响应结构见数字货币接入总览。

请求路径

域名：推荐使用统一域名 openapi.toppayment.com（路径不变）；原数字货币域名（global-digit-openapi.toppayment.com）仍可用。

环境	地址
沙箱	`https://openapi.toppayment.com/crypto/sandbox/balance/v1`
生产	`https://openapi.toppayment.com/crypto/balance/v1`

请求头参数

字段	必填	类型	描述
Content-Type	M	String	固定值：application/json
Nonce	M	String(16-64)	防重放随机串，10 分钟内不可重复，不参与签名

请求体参数

字段	必填	类型	描述
mchNo	M	String(32)	商户编号沙箱需使用 `SD` 前缀的沙箱商户号
timestamp	M	String(13)	请求时间戳（13 位毫秒级），偏差须在 ±5 分钟内
sign	M	String	签名，见签名规则
currency	O	String(16)	币种传入：仅返回该币种余额不传或传空：返回全部已开通币种余额示例：`USDT`
netWork	O	String(100)	链网络仅用于原样回填响应中的 `netWork` 字段，不参与余额筛选数字货币余额按币种统一记账，不区分链
tenantCode	O	String(32)	子租户编码，不传使用默认租户
countryCode	O	String(16)	国家码，数字货币场景无需传

netWork 不影响余额

账户余额按币种记账，同一币种在不同链上的资产合并计算。请求中的 netWork 只会被原样写回响应，不会过滤或拆分余额。

请求示例

Content-Type: application/json
Nonce: a91e60c3b7d248f5c0a2

{
    "mchNo": "{{mchNo}}",
    "currency": "USDT",
    "timestamp": "1749102949784",
    "sign": "按签名规则生成后替换"
}

{
    "mchNo": "{{mchNo}}",
    "timestamp": "1749102949784",
    "sign": "按签名规则生成后替换"
}

响应体参数

字段	必填	类型	描述
success	M	Boolean	是否成功
code	M	String	响应状态码 9999：成功；其他见异常码
msg	O	String	响应消息，成功时为 `null`
timeStamp	M	Number	服务器响应时间（毫秒级）
data	M	Object	响应数据对象
mchNo	M	String	商户编号
tenantCode	M	String	租户编码请求未传 `tenantCode` 时为商户默认租户编码
balances	M	Array	余额明细列表无可用账户时为空数组 `[]`
tenantCode	M	String	租户编码
currency	M	String	币种
netWork	O	String	链网络原样回填请求中的 `netWork`，未传时为 `null`
balance	M	Number	可用余额当前可用于代付、扣费的数量
freeze	M	Number	冻结金额代付在途、风控冻结等占用的数量
totalAmount	M	Number	总额账户总数量

精度

余额相关金额按 8 位小数返回。请使用高精度类型（如 BigDecimal、Decimal）解析，避免使用浮点数。

响应示例

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "mchNo": "JIMMY001",
        "tenantCode": "JIMMY001",
        "balances": [
            {
                "tenantCode": "JIMMY001",
                "currency": "USDT",
                "netWork": null,
                "balance": 12580.36000000,
                "freeze": 120.00000000,
                "totalAmount": 12700.36000000
            }
        ]
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "mchNo": "JIMMY001",
        "tenantCode": "JIMMY001",
        "balances": [
            {
                "tenantCode": "JIMMY001",
                "currency": "USDT",
                "netWork": null,
                "balance": 12580.36000000,
                "freeze": 120.00000000,
                "totalAmount": 12700.36000000
            },
            {
                "tenantCode": "JIMMY001",
                "currency": "TRX",
                "netWork": null,
                "balance": 8800.00000000,
                "freeze": 0.00000000,
                "totalAmount": 8800.00000000
            }
        ]
    }
}

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "mchNo": "JIMMY001",
        "tenantCode": "JIMMY001",
        "balances": []
    }
}

沙箱响应差异

沙箱与生产响应结构不同

沙箱余额接口返回模拟数据，且结构与生产不一致：沙箱返回单币种平铺字段，生产返回 balances 数组。请在代码中按环境分别解析。

余额固定返回 2000000，freeze 固定为 0。
请求未传 currency 时，沙箱默认按 USDT 返回。

字段	类型	描述
mchNo	String	商户编号（沙箱商户号）
currency	String	币种，请求未传时为 `USDT`
totalAmount	Number	总额，固定 `2000000`
balance	Number	可用余额，固定 `2000000`
freeze	Number	冻结金额，固定 `0`
waitingSettleAmount	Number	待结算金额，固定 `0`
freezeWaitingSettleAmount	Number	冻结待结算金额，固定 `0`

{
    "success": true,
    "code": "9999",
    "msg": null,
    "timeStamp": 1767873172906,
    "data": {
        "mchNo": "SDJIMMY001",
        "currency": "USDT",
        "totalAmount": 2000000,
        "balance": 2000000,
        "freeze": 0,
        "waitingSettleAmount": 0,
        "freezeWaitingSettleAmount": 0
    }
}

数字货币余额查询

# 概述

# 请求路径

# 请求头参数

# 请求体参数

# 请求示例

# 响应体参数

# 响应示例

# 沙箱响应差异

# 参考

概述