合约交易

本模块所有接口 baseurl：https://openapi.bitbaby.com/futures/open
完整 URL 格式：{baseurl}{requestPath}，例如 https://openapi.bitbaby.com/futures/open/fapi/v1/order。
签名时 requestPath 仅使用 /fapi/v1/... 部分，不要带 /futures/open 前缀。详见基本信息 → 需要签名的接口。

公共

安全类型: NONE

公共下方的接口不需要 API-Key 或者签名就能自由访问。

测试连接

GET /fapi/v1/ping

测试 REST API 的连通性。

200

json

{}

获取服务器时间

GET /fapi/v1/time

200

json

{
    "serverTime": 1607702400000,
    "timezone": "中国标准时间"
}

Response:

名称	类型	描述
serverTime	long	服务器时间戳（毫秒）
timezone	string	服务器时区显示名

合约列表

GET /fapi/v1/contracts

获取所有合约的元信息。可选请求头 brokerId 用于按商户过滤。

200

json

[
    {
        "symbol": "E-BTC-USDT",
        "type": "E",
        "status": 1,
        "side": 1,
        "multiplier": 0.001,
        "multiplierCoin": "BTC",
        "pricePrecision": 2,
        "minOrderVolume": 1,
        "minOrderMoney": 0.001,
        "maxMarketVolume": 100000,
        "maxMarketMoney": 10000000,
        "maxLimitVolume": 1000000,
        "maxLimitMoney": 1000000,
        "maxValidOrder": 20
    }
]

Response:

名称	类型	描述
symbol	string	合约名称，例如 `E-BTC-USDT`
status	number	合约状态（0 不可交易，1 可交易）
type	string	合约类型 (`E` 永续，`S` 模拟，其它为混合)
side	number	合约方向 (`0` 反向，`1` 正向)
multiplier	number	合约面值
multiplierCoin	string	合约面值单位
pricePrecision	number	价格精度
minOrderVolume	number	最小下单量
minOrderMoney	number	最小下单金额
maxMarketVolume	number	市价单最大下单数量
maxMarketMoney	number	市价单最大下单金额
maxLimitVolume	number	限价单最大下单数量
maxValidOrder	number	最大有效委托数量

行情

安全类型: NONE

行情下方的接口不需要 API-Key 或者签名就能自由访问。

订单薄

GET /fapi/v1/depth

Query Parameters

Name	Type	Description
contractName*	string	合约名称，例如 `E-BTC-USDT`
limit	integer	默认 100；最大 100

200

json

{
  "time": 1595563624731,
  "bids": [
    ["3.90000000", "431.00000000"],
    ["4.00000000", "431.00000000"]
  ],
  "asks": [
    ["4.00000200", "12.00000000"],
    ["5.10000000", "28.00000000"]
  ]
}

每档为 [price, size]，按最优价排序。

行情ticker

GET /fapi/v1/ticker

24 小时价格变化数据。

Query Parameters

Name	Type	Description
contractName*	string	合约名称，例如 `E-BTC-USDT`

200

json

{
    "high": "9279.0301",
    "low": "9279.0301",
    "last": "9200",
    "vol": "1302",
    "rose": "0",
    "time": 1595563624731
}

全部合约 ticker

GET /fapi/v1/all_ticker

返回 Map<contractName, ticker> 结构，字段同上。

获取指数 / 标记价格

GET /fapi/v1/index

Query Parameters

Name	Type	Description
contractName*	string	合约名称，例如 `E-BTC-USDT`

200

json

{
    "contractName": "E-ETH-USDT",
    "indexPrice": 646.3933333333333,
    "markPrice": 581.5,
    "lastFundingRate": 0.001,
    "time": 1608273554063
}

全部合约指数价格

GET /fapi/v1/get_all_indexPrice

返回所有合约的指数价格 Map<contractName, BigDecimal>。

全部合约指数 + 标记价格

GET /fapi/v1/public_all_index_tag_price

返回每个合约的 symbol、indexPrice、markPrice。

K 线/蜡烛图数据

GET /fapi/v1/klines

Query Parameters

Name	Type	Description
contractName*	string	合约名称，例如 `E-BTC-USDT`
interval*	string	K 线区间，可选值：`1min`, `5min`, `15min`, `30min`, `1h`, `1day`, `1week`, `1month`
limit	integer	默认 100；最大 300
startTime	long	起始时间（毫秒）
endTime	long	结束时间（毫秒）

200

json

[
    {
        "idx": 1594640340,
        "open": "6228.77",
        "close": "6228.77",
        "high": "6228.77",
        "low": "6228.77",
        "vol": "111"
    }
]

交易

安全类型: TRADE

所有交易接口必须携带以下 Headers，下文 Headers 表格不再重复列出。

Header	Type	Description
X-CH-APIKEY*	string	您的 API-Key
X-CH-TS*	string	时间戳（毫秒）
X-CH-SIGN*	string	签名（hex）
Content-Type*	string	`application/json`

创建订单

POST /fapi/v1/order

创建单个新订单（限价 / 市价）。

Request Body

Name	Type	Description
contractName*	string	合约名称，例如 `E-BTC-USDT`
volume*	number	下单数量（张）；市价开仓时这里单位是金额
side*	string	买卖方向，`BUY` / `SELL`
type*	string	订单类型，`LIMIT` / `MARKET`
open*	string	开平仓方向，`OPEN` / `CLOSE`
positionType*	number	持仓类型，`1` 全仓 / `2` 逐仓
price	number	订单价格，`LIMIT` 必填
clientOrderId	string	客户端下单标识，长度 < 32 的字符串
timeInForce	string	有效方式，`IOC` / `FOK` / `POST_ONLY`

200

json

{
    "orderId": 256609229205684228
}

创建条件单

POST /fapi/v1/conditionOrder

按触发价创建条件单（止损 / 止盈 / 追涨 / 杀跌）。

Request Body

在创建订单的字段基础上额外要求：

Name	Type	Description
triggerType*	number	条件单类型：`3` stop-loss / `4` take-profit
triggerPrice*	number	触发价
trailCallbackRatio	number	移动止盈止损回调比例（追踪止损时使用）

200

json

{
    "orderId": 256609229205684228
}

撤销订单

POST /fapi/v1/cancel

限速规则: 20次/2s

Request Body

Name	Type	Description
contractName*	string	合约名称，例如 `E-BTC-USDT`
orderId*	string	订单 ID

200

json

{
    "orderId": 256609229205684228
}

批量下单

POST /fapi/v1/batchOrders

也可使用别名 POST /fapi/v1/placeBatchOrder，行为一致。

Request Body

Name	Type	Description
contractName*	string	合约名称
orders*	array	订单列表，每条字段同创建订单的 body 字段

200

json

{
    "ids": ["256609229205684228", "256609229205684229"]
}

批量撤单

POST /fapi/v1/batchCancel

Request Body

Name	Type	Description
contractName*	string	合约名称
orderIds*	array	要撤销的订单 ID 数组

200

json

{
    "success": ["256609229205684228"],
    "failed":  ["256609229205684229"]
}

订单详情

GET /fapi/v1/order

Query Parameters

Name	Type	Description
contractName*	string	合约名称
orderId	string	订单 ID（与 `clientOrderId` 二选一）
clientOrderId	string	客户端订单 ID

200

json

{
    "orderId": 259396989397942275,
    "contractName": "E-BTC-USDT",
    "side": "BUY",
    "action": "OPEN",
    "type": "LIMIT",
    "price": 10000,
    "origQty": 1,
    "executedQty": 0,
    "avgPrice": 0,
    "transactTime": "1607702400000",
    "status": "INIT",
    "fills": []
}

Response:

名称	类型	描述
orderId	long	订单 ID
contractName	string	合约名称
side	string	`BUY` / `SELL`
action	string	`OPEN` / `CLOSE`
type	string	`LIMIT` / `MARKET`
price	number	委托价格
origQty	number	委托数量
executedQty	number	成交数量
avgPrice	number	成交均价
transactTime	string	创建时间（毫秒）
status	string	`INIT` / `NEW` / `PARTIALLY_FILLED` / `FILLED` / `CANCELED` / `REJECTED`
fills	array	成交明细

当前委托

GET /fapi/v1/openOrders

获取当前用户的未完结委托。contractName 可选，留空时返回全合约。

Query Parameters

Name	Type	Description
contractName	string	合约名称（可选）

200 返回结构同订单详情的数组。

当前委托数量

POST /fapi/v1/openOrdersCount

适合分页查询当前委托。

Request Body

Name	Type	Description
contractId	integer	合约 ID（可选）
page	integer	页码（从 1 开始）
pageSize	integer	每页大小

200

json

{
    "code": "0",
    "data": {
        "count": 12,
        "orderList": [ /* 同 openOrders */ ]
    }
}

历史委托

POST /fapi/v1/orderHistorical

Request Body

Name	Type	Description
contractName	string	合约名称（可选，留空查询全部合约）
limit	integer	分页条数；默认 100；最大 1000
fromId	long	从该订单 ID 开始检索

200

json

[
    {
        "orderId": 777293886968070157,
        "contractName": "E-BTC-USDT",
        "side": "BUY",
        "openOrClose": "OPEN",
        "positionType": 2,
        "type": 4,
        "price": 41000,
        "volume": 2,
        "dealVolume": 1,
        "dealMoney": 4.1,
        "avgPrice": 41000,
        "leverageLevel": 26,
        "openTakerFeeRate": 0.00065,
        "openMakerFeeRate": 0.00025,
        "closeTakerFeeRate": 0.00065,
        "closeMakerFeeRate": 0.00025,
        "status": 4,
        "ctime": "2021-09-29T16:16:51",
        "ctimeMs": 1632903411000
    }
]

盈亏记录

POST /fapi/v1/profitHistorical

Request Body 同历史委托。

200

json

[
    {
        "id": 8764,
        "contractId": 1,
        "side": "SELL",
        "positionType": 2,
        "leverageLevel": 26,
        "openPrice": 44500,
        "openEndPrice": 44500,
        "volume": 900,
        "tradeFee": -5.23575,
        "capitalFee": 0,
        "shareAmount": 0,
        "closeProfit": -45,
        "settleProfit": 0,
        "realizedAmount": 0,
        "historyRealizedAmount": -50.23575,
        "ctime": 1632882691000,
        "mtime": 1632882739000
    }
]

成交记录

GET /fapi/v1/myTrades

限速规则: 20次/2s

Query Parameters

Name	Type	Description
contractName	string	合约名称，例如 `E-BTC-USDT`
limit	integer	分页条数；默认 100；最大 1000
fromId	long	从该 tradeId 开始检索

200

json

[
  {
    "tradeId": 100211,
    "symbol": "E-BTC-USDT",
    "contractName": "E-BTC-USDT",
    "bidId": 150695552109032492,
    "askId": 150695552109032493,
    "bidUserId": 10024,
    "askUserId": 10025,
    "price": "4.00000100",
    "qty": "12.00000000",
    "amount": "48.00",
    "time": 1499865549590,
    "side": "BUY",
    "isBuyer": true,
    "isMaker": false,
    "fee": "0.001"
  }
]

主动平仓 / 强平 / 自适应减仓记录

GET /fapi/v1/tradesRecord

按合约维度分页拉取自身成交（含开 / 平方向标记）。参数同成交记录。

GET /fapi/v1/adlRecord

ADL（自动减仓）记录。contractName 必填，分页字段同上。

GET /fapi/v1/liquidationList

强平记录。

计划委托相关

方法	路径	说明
POST	`/fapi/v1/profitLossOrder`	创建一组止盈止损单（与持仓绑定）
POST	`/fapi/v1/trigger_order_list`	查询触发条件单列表
POST	`/fapi/v1/cancel_trigger_order`	撤销条件单

profitLossOrder 的请求体核心字段：

Name	Type	Description
contractName	string	合约名称
positionId	integer	仓位 ID
side	string	`BUY` / `SELL`
positionType	integer	`1` 全仓 / `2` 逐仓
orderList	array	子条件单数组

orderList[] 字段：

Name	Type	Description
triggerType	integer	`3` 止损 / `4` 止盈
triggerPrice	number	触发价
price	number	触发后委托价
volume	number	触发后委托数量
type	integer	委托类型
expiredTime	integer	过期时间（毫秒）
tagPriceTrigger	integer	`1` 按标记价触发 / `0` 按最新价触发

账户

安全类型: USER_DATA

账户下方的接口都需要签名和 API-Key 验证。Headers 同交易部分。

账户信息

GET /fapi/v1/account

限速规则: 20次/2s

200

json

{
    "account": [
        {
            "marginCoin": "USDT",
            "accountNormal": 999.5606,
            "accountLock": 23799.5017,
            "partPositionNormal": 9110.7294,
            "totalPositionNormal": 0,
            "achievedAmount": 4156.5072,
            "unrealizedAmount": 650.6385,
            "totalEquity": 99964804.560,
            "partEquity": 13917.8753,
            "totalCost": 0,
            "totalMarginRate": 0,
            "sumMarginRate": 873.4608,
            "positionVos": [
                {
                    "contractId": 1,
                    "contractName": "E-BTC-USDT",
                    "contractSymbol": "BTC-USDT",
                    "positions": [
                        {
                            "id": 13603,
                            "contractId": 1,
                            "positionType": 2,
                            "side": "BUY",
                            "volume": 69642.0,
                            "openPrice": 11840.2394,
                            "avgPrice": 11840.3095,
                            "leverageLevel": 24,
                            "holdAmount": 7014.2111,
                            "marginRate": 0.2097,
                            "reducePrice": 9740.8083,
                            "unRealizedAmount": 2164.5289,
                            "realizedAmount": 8115.9125,
                            "positionBalance": 82458.2839,
                            "indexPrice": 12151.1175,
                            "status": 1
                        }
                    ]
                }
            ]
        }
    ]
}

Response 字段速读：

区域	关键字段	说明
账户	`marginCoin`、`accountNormal`、`accountLock`、`totalEquity`、`partEquity`	保证金币、可用、冻结、全/逐仓权益
账户	`unrealizedAmount`、`achievedAmount`、`sumMarginRate`	未实现盈亏、已实现盈亏、账户保证金率
仓位	`positionVos[].positions[]`	各合约下的仓位明细
单个仓位	`volume`、`avgPrice`、`leverageLevel`、`positionType`、`side`	持仓规模与杠杆
单个仓位	`marginRate`、`reducePrice`、`unRealizedAmount`、`indexPrice`	维持/强减/未实现盈亏，对接风控告警常用

完整字段解释参考下方两张表。

account[] 字段：

名称	类型	描述
marginCoin	string	保证金币种
accountNormal	number	余额账户
accountLock	number	保证金冻结账户
partPositionNormal	number	逐仓保证金余额
totalPositionNormal	number	全仓占用的初始保证金
achievedAmount	number	已实现盈亏
unrealizedAmount	number	未实现盈亏
totalEquity	number	全仓权益
partEquity	number	逐仓权益
totalCost	number	全仓占用成本
totalMarginRate	number	全仓保证金率
sumMarginRate	number	全账户保证金率
positionVos	array	仓位合约记录

positionVos[].positions[] 字段：

名称	类型	描述
id	integer	仓位 ID
positionType	integer	`1` 全仓 / `2` 逐仓
side	string	`BUY` 多 / `SELL` 空
volume	number	持仓数量
openPrice	number	开仓价
avgPrice	number	持仓均价
leverageLevel	number	杠杆倍数
holdAmount	number	持仓保证金
realizedAmount	number	已实现盈亏
historyRealizedAmount	number	历史累计已实现盈亏
unRealizedAmount	number	未实现盈亏
openRealizedAmount	number	开仓未实现盈亏
positionBalance	number	仓位价值
marginRate	number	保证金率
reducePrice	number	强减价
returnRate	number	收益率
indexPrice	number	最新标记价
keepRate	number	阶梯最低维持保证金率
maxFeeRate	number	平仓最大手续费率
tradeFee	number	交易手续费
capitalFee	number	资金费用
shareAmount	number	分摊金额
freezeLock	integer	0 正常 / 1 爆仓冻结 / 2 交割冻结
status	integer	0 无效 / 1 有效

持仓信息

GET /fapi/v1/positions

Query Parameters

Name	Type	Description
contractName	string	合约名称（可选）

200

json

{
    "positions": [
        /* 单个仓位字段同 account.positionVos[].positions[] */
    ]
}

资金流水

GET /fapi/v1/capital

Query Parameters

Name	Type	Description
beginTime	long	起始时间（毫秒）
endTime	long	结束时间（毫秒）
page	integer	页码
limit	integer	每页数量

200

json

{
    "records": [
        {
            "contractName": "E-BTC-USDT",
            "type": "TRADE_FEE",
            "amount": "-0.123",
            "balance": "1000.5",
            "time": 1607702400000
        }
    ]
}

调整杠杆 / 持仓模式

方法	路径	说明
POST	`/fapi/v1/edit_lever`	调整指定合约的杠杆倍数
POST	`/fapi/v1/level_edit`	兼容旧接口，调整杠杆
POST	`/fapi/v1/edit_user_position_model`	切换全仓 / 逐仓
POST	`/fapi/v1/edit_user_margin_model`	切换保证金模式
POST	`/fapi/v1/trigger_time_edit`	修改条件单触发时间

edit_lever 请求示例：

json

{
    "contractName": "E-BTC-USDT",
    "leverageLevel": 20,
    "positionType": 2
}

资金划转（RSA 签名）

与 HMAC 接口不同

以下两个接口使用独立的 RSA 签名机制，需在请求头中携带 Ex-sign 与 Ex-ts，不复用 X-CH-SIGN / X-CH-TS。仅对接机构客户开放，使用前请先联系商务申请密钥对。

Header	说明
`Ex-ts`	时间戳（毫秒）
`Ex-sign`	对 `JSON.stringify(body) + Ex-ts` 做 RSA 签名后的 Base64 字符串

方法	路径	说明
POST	`/fapi/v1/futures_transfer`	现货 ↔ 合约账户资金划转
POST	`/fapi/v1/futures_balance`	查询合约账户余额

合约交易 ​

公共 ​

安全类型: NONE ​

测试连接 ​

获取服务器时间 ​

合约列表 ​

行情 ​

安全类型: NONE ​

订单薄 ​

行情ticker ​

全部合约 ticker ​

获取指数 / 标记价格 ​

全部合约指数价格 ​

全部合约指数 + 标记价格 ​

K 线/蜡烛图数据 ​

交易 ​

安全类型: TRADE ​

创建订单 ​

创建条件单 ​

撤销订单 ​

批量下单 ​

批量撤单 ​

订单详情 ​

当前委托 ​

当前委托数量 ​

历史委托 ​

盈亏记录 ​

成交记录 ​

主动平仓 / 强平 / 自适应减仓记录 ​

计划委托相关 ​

账户 ​

安全类型: USER_DATA ​

账户信息 ​

持仓信息 ​

资金流水 ​

调整杠杆 / 持仓模式 ​

资金划转（RSA 签名） ​

合约交易

公共

安全类型: NONE

测试连接

获取服务器时间

合约列表

行情

安全类型: NONE

订单薄

行情ticker

全部合约 ticker

获取指数 / 标记价格

全部合约指数价格

全部合约指数 + 标记价格

K 线/蜡烛图数据

交易

安全类型: TRADE

创建订单

创建条件单

撤销订单

批量下单

批量撤单

订单详情

当前委托

当前委托数量

历史委托

盈亏记录

成交记录

主动平仓 / 强平 / 自适应减仓记录

计划委托相关

账户

安全类型: USER_DATA

账户信息

持仓信息

资金流水

调整杠杆 / 持仓模式

资金划转（RSA 签名）