注册商户

GET · /api/v1/wallet/balance/address

查询指定地址余额

按 chainCode + address（memo 链需同时传 memo）查询该地址在所有已启用代币上的余额快照。

Memo 链必须同时传 memo

XRP / XLM / EOS 等 memo 链使用共享热地址，memo 才是区分用户的关键。 查询时不传 memo 则返回整个共享地址的余额合计，而非单个用户的余额。
GET/api/v1/wallet/balance/address HMAC

Header 参数

X-Api-Key
string required
应用 apiKey。沙箱前缀 pk_test_，正式 pk_live_。
例： pk_test_4f9d8ab1c0e74...
X-Timestamp
integer (UNIX 毫秒) required
请求发起时刻的 UNIX 毫秒时间戳（13 位整数）。与服务端时差不能超过 ±300000ms（5 分钟）。
例： 1746450000000
X-Nonce
string required
本次请求的随机串，建议 UUID v4 或 16 字节 hex。同一 (apiKey, nonce) 在 10 分钟窗口内不可重复。
例： 8e3a1c2f7b6d4a90
X-Signature
string required
HMAC-SHA256 签名（小写 hex，64 字符）。算法：HMAC(secret, METHOD + "\n" + PATH + "\n" + ts + "\n" + nonce + "\n" + SHA256(body))。详见 鉴权章节。
例： 6e4a8c1f...（64 字符）

Query 参数

chainCode
string required
公链 code，必须是该应用已开通的公链。
例： ETH
address
string required
链上地址。EVM 地址大小写不敏感（系统内部按 EIP-55 规范化）。
例： 0xab12cd34ef56...
memo
string optional
Memo / Tag；XRP / XLM / EOS 等 memo 链用于区分用户，非 memo 链无需传。

请求示例

# 签名算法（stringToSign / 4 个 header）见 /docs/api/auth
API_KEY=pk_live_xxx
SECRET=sk_live_xxx
METHOD=GET
REQ_PATH=/api/v1/wallet/balance/address
QUERY="chainCode=ETH&address=0xab12cd34ef56..."
TS=$(( $(date +%s) * 1000 ))
NONCE=$(uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]')
BODY_SHA=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
# 签名 PATH 不含 query string
SIG=$(printf "%s\n%s\n%s\n%s\n%s" "$METHOD" "$REQ_PATH" "$TS" "$NONCE" "$BODY_SHA" \
  | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')

curl "https://api.pqpa.com$REQ_PATH?$QUERY" \
  -H "X-Api-Key:    $API_KEY" \
  -H "X-Timestamp:  $TS" \
  -H "X-Nonce:      $NONCE" \
  -H "X-Signature:  $SIG"

响应

Response
200OK
{
  "code": 0,
  "data": [
    {
      "addressId": 90123,
      "chainCode": "ETH",
      "chainName": "Ethereum",
      "address": "0xab12cd34ef56...",
      "memo": null,
      "addressType": "USER",
      "externalUserId": "user_1024",
      "status": "ACTIVE",
      "balances": [
        {
          "chainCode": "ETH",
          "chainName": "Ethereum",
          "chainTokenId": 19,
          "tokenSymbol": "USDT",
          "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
          "decimals": 6,
          "balance": "320.500000"
        },
        {
          "chainCode": "ETH",
          "chainName": "Ethereum",
          "chainTokenId": 1,
          "tokenSymbol": "ETH",
          "contractAddress": null,
          "decimals": 18,
          "balance": "0.005000000000000000"
        }
      ]
    }
  ],
  "msg": ""
}

data[] 字段说明

addressId
integer required
地址记录 id（系统内部主键）。
例： 90123
chainCode
string required
公链 code。
例： ETH
chainName
string required
公链名称。
例： Ethereum
address
string required
链上地址。
memo
string | null required
Memo / Tag；非 memo 链恒为 null。
addressType
string required
地址类型，如 USER、COLLECT、HOT。
例： USER
externalUserId
string | null required
商户侧用户标识；非用户地址为 null。
例： user_1024
status
string required
地址状态，如 ACTIVE。
例： ACTIVE
balances
array required
该地址各代币余额列表，见下方 BalanceTokenAmountVO 字段。

balances[] · BalanceTokenAmountVO 字段说明

chainCode
string required
公链 code。
例： ETH
chainName
string required
公链名称。
例： Ethereum
chainTokenId
integer required
链上代币 id。
例： 19
tokenSymbol
string required
代币符号。
例： USDT
contractAddress
string | null required
合约地址；原生币为 null。
decimals
integer required
代币小数位。
例： 6
balance
string required
余额快照（字符串金额）。
例： "320.500000"

下一步