Skip to main content

账户余额 (Balances)

查询用户的资产余额，包括可用余额和冻结余额。

获取余额​

接口信息​

  • Method: GET
  • Path: /api/v1/account/balances
  • Authentication: 需要 JWT Token

响应示例​

{
  "balances": [
    {
      "token": "USDT",
      "available": "1000.50",
      "frozen": "200.25",
      "total": "1200.75"
    }
  ]
}

响应字段说明​

字段类型描述
tokenstring资产符号（如 USDT）
availablestring可用余额（Decimal 字符串）
frozenstring冻结余额（Decimal 字符串）
totalstring总余额 = available + frozen

余额类型说明​

可用余额 (Available)​

可以自由使用的余额，用于：

  • ✅ 创建新订单：作为保证金开仓
  • ✅ 增加保证金：为现有仓位添加抵押品
  • ✅ 提现：提取到外部钱包

冻结余额 (Frozen)​

被锁定无法使用的余额，包括：

  • 🔒 订单保证金：活动订单（open/partially_filled）占用的保证金
  • 🔒 仓位抵押品：持仓占用的保证金
  • 🔒 待处理提现：pending 状态的提现请求

余额流转示例​

初始状态：
available: 1000 USDT
frozen: 0 USDT

创建订单（需要 100 USDT 保证金）：
available: 900 USDT  (-100)
frozen: 100 USDT     (+100)

订单成交（开仓）：
available: 900 USDT  (不变)
frozen: 100 USDT     (保证金转为仓位抵押品)

平仓：
available: 950 USDT  (+100 保证金 -50 亏损)
frozen: 0 USDT       (-100)

保证金计算​

开仓/加仓保证金​

基础保证金 = (订单数量 × 价格) ÷ 杠杆
手续费缓冲 = 基础保证金 × 0.5%
所需保证金 = 基础保证金 + 手续费缓冲

示例：

  • 买入 0.1 BTC @ 65000，10x 杠杆
  • 基础保证金 = (0.1 × 65000) ÷ 10 = 650 USDT
  • 手续费缓冲 = 650 × 0.005 = 3.25 USDT
  • 所需保证金 = 653.25 USDT

平仓保证金​

得益于智能保证金计算，平仓订单几乎不需要额外保证金：

  • 完全平仓：只需手续费（约 0.5%）
  • 部分平仓：只需净开仓部分的保证金

余额监控​

实时余额查询​

async function getBalances() {
  const response = await fetch('/api/v1/account/balances', {
    headers: {
      'Authorization': `Bearer ${jwtToken}`
    }
  });
  
  const { balances } = await response.json();
  
  // 查找 USDT 余额
  const usdt = balances.find(b => b.token === 'USDT');
  
  return {
    available: parseFloat(usdt.available),
    frozen: parseFloat(usdt.frozen),
    total: parseFloat(usdt.total)
  };
}

余额变化监控​

// 使用 WebSocket 监听余额变化
ws.on('balance_update', (data) => {
  console.log('余额更新:', data);
  // { token: 'USDT', available: '950.00', frozen: '100.00', total: '1050.00' }
  
  updateUI(data);
});

常见问题​

Q: 为什么可用余额减少了？​

A: 可能的原因：

  1. 创建了新订单（保证金被冻结）
  2. 开仓/加仓（余额转为仓位抵押品）
  3. 发起提现请求（资金被冻结）
  4. 支付手续费或资金费率

Q: 冻结余额什么时候会释放？​

A: 冻结余额在以下情况释放：

  • 订单取消 → 保证金立即释放
  • 订单成交 → 保证金转为仓位抵押品
  • 平仓 → 仓位抵押品释放（扣除亏损或加上盈利）
  • 提现取消 → 资金立即释放

Q: 可以使用冻结余额吗？​

A: 不可以。冻结余额已被锁定，必须先释放才能使用。您可以：

  • 取消订单释放保证金
  • 平仓释放仓位抵押品
  • 取消未确认的提现请求

Q: 总余额怎么会变少？​

A: 总余额减少通常是由于：

  • 交易亏损
  • 支付交易手续费
  • 支付资金费率（funding fee）
  • 成功提现

相关文档​