Crypto Balance Inquiry

Overview

The balance inquiry API returns the real-time balance of a merchant's crypto account, including available balance, frozen amount and total amount. You can query a single coin or fetch all enabled coins at once.

Common request headers (including the mandatory Nonce), common body fields and the unified response envelope are described in Crypto Integration Overview.

Request path

Domain: Prefer unified host openapi.toppayment.com (path unchanged); legacy crypto domain (global-digit-openapi.toppayment.com) remains available.

Environment	URL
Sandbox	`https://openapi.toppayment.com/crypto/sandbox/balance/v1`
Production	`https://openapi.toppayment.com/crypto/balance/v1`

Request headers

Field	Required	Type	Description
Content-Type	M	String	Fixed value: application/json
Nonce	M	String(16-64)	Anti-replay random string, unique within 10 minutes, excluded from the signature

Request body

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number In sandbox use the `SD`-prefixed sandbox merchant number
timestamp	M	String(13)	Request timestamp (13-digit milliseconds), within ±5 minutes
sign	M	String	Signature, see Signature
currency	O	String(16)	Coin Provided: returns only that coin Omitted or empty: returns balances for all enabled coins Example: `USDT`
netWork	O	String(100)	Chain network Only echoed back in the response `netWork` field; it does not filter balances Crypto balances are booked per coin, not per chain
tenantCode	O	String(32)	Sub-tenant code, defaults to the default tenant
countryCode	O	String(16)	Country code, not needed for crypto

netWork does not affect the balance

Account balances are booked per coin; holdings of the same coin across different chains are aggregated. The netWork in the request is only echoed back and will not filter or split the balance.

Request example

Content-Type: application/json
Nonce: a91e60c3b7d248f5c0a2

{
    "mchNo": "{{mchNo}}",
    "currency": "USDT",
    "timestamp": "1749102949784",
    "sign": "replace with generated signature"
}

{
    "mchNo": "{{mchNo}}",
    "timestamp": "1749102949784",
    "sign": "replace with generated signature"
}

Response body

Field	Required	Type	Description
success	M	Boolean	Whether the request succeeded
code	M	String	Response code 9999: success; otherwise see Exception Codes
msg	O	String	Response message, `null` on success
timeStamp	M	Number	Server response time (milliseconds)
data	M	Object	Response payload
mchNo	M	String	Merchant number
tenantCode	M	String	Tenant code The merchant's default tenant code when `tenantCode` is omitted
balances	M	Array	Balance details An empty array `[]` when no account is available
tenantCode	M	String	Tenant code
currency	M	String	Coin
netWork	O	String	Chain network Echoes the request `netWork`; `null` when omitted
balance	M	Number	Available balance Quantity currently usable for payouts and fees
freeze	M	Number	Frozen amount Held by in-flight payouts, risk holds, etc.
totalAmount	M	Number	Total amount held in the account

Precision

Balance amounts are returned with 8 decimal places. Parse them with a high-precision type (BigDecimal, Decimal, etc.) and avoid floating point.

Response example

{
    "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": []
    }
}

Sandbox response differences

The sandbox response shape differs from production

The sandbox balance endpoint returns mock data with a different shape: sandbox returns flat single-coin fields whereas production returns a balances array. Parse the response per environment.

The balance is always 2000000 and freeze is always 0.
When currency is omitted, sandbox defaults to USDT.

Field	Type	Description
mchNo	String	Merchant number (sandbox merchant number)
currency	String	Coin, `USDT` when omitted in the request
totalAmount	Number	Total amount, always `2000000`
balance	Number	Available balance, always `2000000`
freeze	Number	Frozen amount, always `0`
waitingSettleAmount	Number	Amount awaiting settlement, always `0`
freezeWaitingSettleAmount	Number	Frozen amount awaiting settlement, always `0`

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

Crypto Balance Inquiry

# Overview

# Request path

# Request headers

# Request body

# Request example

# Response body

# Response example

# Sandbox response differences

# References