U本位合约 API 开发指南：从签名到交易的完整调用手册

关键词：U本位合约、HmacMD5 签名、资金划转、下单、撤单、止盈止损、查询资产、仓位、永续合约 API

1. SDK 与快速上手

Bibox 提供了 JavaScript、Python 与 C# 多语言 SDK，已自动完成 数据签名 与 深度合成 流程。

// js 示意
console.log('U本位合约 javascript 代码示例');

# python 示意
if __name__ == '__main__':
 print('U本位合约 python 代码示例')

// C# 示意
Console.WriteLine("U本位合约 c# 代码示例");

👉 点此查看如何一键部署云量化脚本

2. 构建安全请求：HmacMD5 签名七步曲

步骤	描述
1	获取毫秒时间戳 timestamp
2	序列化业务参数为 JSON 字符串
3	拼接待签名字符串：`timestamp + JSON`
4	用 secret 做 HmacMD5 签名
5	在 HTTP 头增加 `bibox-api-key`、`bibox-api-sign`、`bibox-timestamp`
6	Content-Type 设为 `application/json`，body 传原始 JSON
7	解析响应，state 为 0 即成功

示例代码片段

let strToSign = timestamp + strParam;
let sign = CryptoJS.HmacMD5(strToSign, secret).toString();

FAQ
Q1：收到 401 签名失败怎么办？
检查时间戳偏差是否小于 60 秒，确保 JSON 拼接顺序一致。
Q2：可以重放同一组签名吗？
不建议，时间戳会被平台校验一次有效性。

3. 资金划转：从钱包到合约账户

将 USDT 或其他币种从现货钱包转入合约账户后方可下单。

路径：POST /v3/cbuassets/transfer
核心参数：
- symbol：币种，如 USDT
- amount：划转数量（字符串）
- type：0 转入，1 转出

👉 抢先体验实时划转零延迟通道

FAQ
Q3：提示“可用余额不足”？
先去现货账户确认余额再做划转；划转成功后再调用下单接口。

4. 下单：市价单 & 限价单

路径： POST /v3/cbu/order/open
关键字段：

pair：标的，如 4BTC_USDT
amount：必须满足整张合约面值倍数的整数
price：市价单填 1；限价单填指定价格
order_side：1 开多、2 开空、3 平多、4 平空

进阶：一次下单挂止盈止损
在开仓时追加：

profit_price / loss_price：触发价
plan_type：1 市价、2 限价

body = {
  "pair": "4BTC_USDT",
  "order_side": 1,
  "order_type": 2,
  "price": "25000",
  "amount": "10",
  "profit_price": "26000",
  "loss_price": "24500"
}

FAQ
Q4：为何部分订单报“amount 参数错误”？
数量不是合约面值整数倍，请查阅对应品种的合约面值说明。

5. 撤单：单条、批量、全部

场景	路径
撤销 1 条	`/v3/cbu/order/close`
撤销 N 条	`/v3/cbu/order/closeBatch`
清仓该标的	`/v3/cbu/order/closeAll`

示例（撤某一条）：

{"order_id": "426610511577093"}

6. 止盈止损委托（计划单）

路径：POST /v3/cbu/order/planOpen
核心需求：side=多仓/空仓、plan_type=止盈/止损、trigger_price=触发价

撤回与查询

列表：/v3/cbu/order/planOrderList
单撤：/v3/cbu/order/planClose
全撤：/v3/cbu/order/planCloseAll

FAQ
Q5：“触发价错误”如何解决？
多仓止盈触发价必须 > 当前价，止损则反之，空单反之亦然。

7. 仓位与风险管理

7.1 逐仓调保证金

POST /v3/cbu/changeMargin
调增可将爆仓价推远，调减则可能触发强平。

7.2 调整杠杆和仓位模式

通过 POST /v3/cbu/changeMode 可将同一标的的多、空仓杠杆分开设置。

8. 查询接口速查表

场景	接口	说明
资产	`/v3/cbu/assets`	查看可用与冻结
仓位	`/v3/cbu/position`	查看持仓、已委托止盈止损剩余额度
订单列表	`/v3/cbu/order/list`	历史+在线
在线订单详情	`/v3/cbu/order/detail`	实时状态
仓位变化	`/v3.1/cquery/base_u/dealLog`	仓位流水
成交明细	`/v3.1/cquery/base_u/orderDetail`	逐笔成交

FAQ
Q6：如何防止爆仓？
监控有效杠杆与保证金率，必要时调增保证金或减小仓量。

9. 实战思路与最佳实践

时间同步：本地时间误差 < 3 秒。
重连策略：对 5xx、429 做指数退避。
资金阶梯：先做小额划转与测试单，无误后再批量。
缓存订单 ID：在本地持久化，避免失联后无法撤单。
日志追踪：对每次 sign 参数与返回 state 做持久日志，方便回测排查。