API 参考 › 余额

会员逐资产余额（八桶）

GET /v1/balances scope: balances:read

代会员调用 · 必带 x-on-behalf-of

一个资产一行，八个桶各自独立。它们不是「总额的几种切法」，

而是八个互不重叠的余额，会员的该资产总量 = 八个之和。

available 可用。唯一能直接花的那一桶。所有下单类端点扣的都是它。
pending 在途。已检测到但尚未确认到账的入金。

在 merchant_hosted 下它恒为 0 —— 到账判定发生在商户那一侧，

商户调 POST /v1/deposits 时已经是确认过的钱。

frozen 冻结。运营/风控按会员按资产冻住的部分，

解冻只能由我方后台操作，商户没有解冻入口。

isolated 隔离。争议、司法协助、反洗钱调查期间单独隔出来的部分。

与 frozen 分开是因为处置流程不同，不要合并展示。

locked 业务锁定。汇款等异步且可能失败的订单在下单那一刻

把钱从 available 挪进来的桶，订单终局时要么结算掉要么退回 available。

card 卡内资金。已经充进发卡上游的钱，物理上不在我方，

只能由发卡线的接口动它 —— 不要把它算进「用户还能花多少」。

earn 理财。已申购进活期/定期的本金。
withdrawing 提现在途。POST /v1/withdrawals 从 available

扣进来的那一桶，只能走 confirm（清零）或 fail（退回 available）。

运营碰不到它，商户也没有第三条路径。

⚠ 返回的是「这个会员已经有账户行的资产」，不是资产目录。

一个还没收到过任何一笔钱的会员返回的是空数组，而不是一串 0。

要展示全部可选资产请另取 GET /v1/assets，两者做外连接。

⚠ 响应信封已于 2026-08-13 统一成 { data, next_cursor, has_more }。

它不分页，也不会分页 —— next_cursor 恒为 null、has_more 恒为

false，那是一句明确的「就这些了」，而不是一个缺失的字段。于是

你的通用翻页器在这个端点上不用再单独分支。

balances 仍然返回，且与 data 指向同一份数组，但它是

过渡期兼容字段：只为让改动之前已经接完的调用方不断线。

新接入请一律读 data；已经读 balances 的请择期改过来 ——

它会在变更日志里预告之后移除，届时不再有第二次兼容。

前置条件

该会员属于这把 Key 的商户（否则一律 member_not_found，与「不存在」同一响应）

字段	类型	必填	说明
`x-on-behalf-of`	string	必填	查谁的余额。两种标识都收 —— 商户自己的 `external_member_id`，或我方在会员出参里发的 `mem_<uuid>`。

响应

200OK

{
  "data": [
    {
      "asset": "USDT",
      "available": "1250.000000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "300.000000",
      "card": "0.000000",
      "earn": "5000.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    },
    {
      "asset": "USD",
      "available": "48.750000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "0.000000",
      "card": "120.000000",
      "earn": "0.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "balances": [
    {
      "asset": "USDT",
      "available": "1250.000000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "300.000000",
      "card": "0.000000",
      "earn": "5000.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    },
    {
      "asset": "USD",
      "available": "48.750000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "0.000000",
      "card": "120.000000",
      "earn": "0.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    }
  ]
}

400member_context_required 没带 x-on-behalf-of

404member_not_found 会员不存在 / 属于别的商户 / 已停用 —— 三种同一响应，不要据它判断会员是否存在

请求

curl -X GET 'https://api.zise.com/v1/balances' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID'

const res = await fetch("https://api.zise.com/v1/balances", {
  method: "GET",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
  },
});
// 金额按字符串读，别让它变成 number
const data = await res.json();

import requests

res = requests.get(
    "https://api.zise.com/v1/balances",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
    },
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()

req, _ := http.NewRequest("GET", "https://api.zise.com/v1/balances",
    nil)
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zise.com/v1/balances"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
// 金额字段用 String / BigDecimal，不要 double

$ch = curl_init('https://api.zise.com/v1/balances');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
  ],
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval

200

{
  "data": [
    {
      "asset": "USDT",
      "available": "1250.000000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "300.000000",
      "card": "0.000000",
      "earn": "5000.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    },
    {
      "asset": "USD",
      "available": "48.750000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "0.000000",
      "card": "120.000000",
      "earn": "0.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "balances": [
    {
      "asset": "USDT",
      "available": "1250.000000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "300.000000",
      "card": "0.000000",
      "earn": "5000.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    },
    {
      "asset": "USD",
      "available": "48.750000",
      "pending": "0.000000",
      "frozen": "0.000000",
      "isolated": "0.000000",
      "locked": "0.000000",
      "card": "120.000000",
      "earn": "0.000000",
      "withdrawing": "0.000000",
      "ledger_scale": 6,
      "display_scale": 2
    }
  ]
}

会员逐资产余额（八桶）

前置条件

请求头

响应