未来计划

期货交易的V1 OpenAPI服务将于2024年11月30日全面停止
- 域名 api-cloud.bitmart.com 将不会提供合约1.0 HTTP服务，请您使用 api-cloud-v2.bitmart.com 域名访问合约2.0 HTTP服务
- 域名 wss://openapi-ws.bitmart.com 将不会提供合约1.0 Websocket服务，请您使用 wss://openapi-ws-v2.bitmart.com 域名访问合约2.0 Websocket服务

更新日志

2024-12-17

REST API

[新增] /contract/private/submit-trail-order 支持设置跟踪委托单(SIGNED)
- 功能：支持合约设置跟踪委托单
[新增] /contract/private/cancel-trail-order 支持取消跟踪委托单(SIGNED)
- 功能：支持合约取消跟踪委托单
[更新] /contract/private/submit-order 适用于用户进行合约订单下单(SIGNED)
- 功能：移除跟踪委托单下单相关字段

2024-12-12

REST API

[新增] /contract/public/funding-rate-history 获取资金费率历史(NONE)
- 功能：获取资金费率历史
[新增] /contract/private/transaction-history 合约查询资金流水记录 (SIGNED)
- 功能：查询划转，盈亏，资金费用，手续费等资金记录

2024-12-11

Websocket Stream

[新增]【公共】按Symbol的最优挂单频道
- 支持BBO推送
[更新]【公共】深度频道
- 支持可选 @100ms,@200ms 的更新速度
[更新]【公共】深度全量频道
- 支持可选 @100ms,@200ms 的更新速度
[更新]【公共】深度增量频道
- 支持可选 @100ms,@200ms 的更新速度

2024-12-04

REST API

[更新] /account/v1/transfer-contract 划转 (SIGNED)
- 功能：支持子账户调用

2024-11-28

REST API

[更新] /contract/private/modify-plan-order 合约修改计划委托单 (SIGNED)
- 移除客户端id字段

Websocket Order

[更新]【私有】订单频道
- 状态字段增加类型 审批中

2024-11-25

Websocket Stream

[新增]【公共】资金费率频道
- 支持资金费率推送

2024-11-01

Websocket Stream

[新增]【公共】深度全量频道
- 支持全量深度同时推送
[新增]【公共】深度增量推送频道
- 支持深度增量推送

2024-10-29

REST API

[更新] /contract/public/kline 查询K线数据
- 单次请求限制500条数据

2024-10-24

REST API

[更新] /contract/public/details 获取合约列表详情
- 新增响应字段 market_max_volume

2024-10-17

REST API

[新增] /contract/private/trade-fee-rate 支持查询交易费率(KEYED)
- 功能：支持查询交易费率
[更新] /contract/public/funding-rate 查询资金费率
- 更新限流从 2次/2秒到 12次/2秒
[更新] /contract/public/details 获取合约列表详情
- 新增响应字段 funding_interval_hour
- 支持获取资金费率收取间隔

2024-10-10

REST API

[更新] /contract/private/submit-tp-sl-order 支持设置仓位止盈止损单(SIGNED)
- 修改止盈止损类型默认值为全仓止盈止损

2024-09-26

文档

[删除] 合约1.0 文档

2024-09-19

REST API

[新增] /contract/private/submit-tp-sl-order 支持设置仓位止盈止损单(SIGNED)
- 功能：支持合约设置仓位止盈止损委托单
[新增] /contract/private/modify-plan-order 支持设置仓位止盈止损单(SIGNED)
- 功能：支持合约修改计划委托单
[新增] /contract/private/modify-preset-plan-order 修改预设止盈止损(SIGNED)
- 功能：支持合约修改计划委托单和普通订单预设止盈止损
[新增] /contract/private/modify-tp-sl-order 合约修改止盈止损委托单(SIGNED)
- 功能：支持合约修改止盈止损委托单接口
[更新] /contract/private/cancel-order 取消订单
- 新增字段 client_order_id
- 支持按照交易对批量取消订单
[更新] /contract/private/cancel-plan-order 取消计划委托订单
- 新增字段 client_order_id
- 支持按照交易对批量取消订单
[更新] /contract/private/current-plan-order 查询合约计划委托订单
- 新增字段 plan_type

2024-07-23

新增查询合约计划委托订单记录接口
- /contract/private/current-plan-order支持查询合约计划委托订单（止盈止损、普通计划委托）
新增合约杠杆调整接口
- /contract/private/submit-leverage合约杠杆调整 (SIGNED)
新增合约子账户接口
- /account/contract/sub-account/main/v1/transfer-list子划转历史（主账户适用）(KEYED)
- /account/contract/sub-account/v1/transfer-history划转历史（主,子账户适用）(KEYED)
新增合约子账户接口
- /account/contract/sub-account/main/v1/sub-to-main子划转到主（主账户适用）(SIGNED)
- /account/contract/sub-account/main/v1/main-to-sub主划转到子（主账户适用）(SIGNED)
- /account/contract/sub-account/sub/v1/sub-to-main子划转到主（子账户适用）(SIGNED)
- /account/contract/sub-account/main/v1/wallet子合约余额（主账户适用）(KEYED)
新增合约订单接口
- /contract/private/get-open-orders
新增合约账户划转接口
- /account/v1/transfer-contract
- /account/v1/transfer-contract-list
新增websocket订单通知接口
- /contract/public/websocket/order
新增合约计划委托下单接口
- /contract/private/submit-plan-order
新增合约计划委托单取消接口
- /contract/private/cancel-plan-order
新增查询合约历史订单接口
- /contract/private/orders-history
新增查询合约成交明细接口
- /contract/private/trades
新增查询合约资产明细接口
- /contract/private/assets-detail
新增查询K线数据接口
- /contract/public/kline
新增查询当前资金费率接口
- /contract/public/funding-rate
新增查询仓位详情接口
- /contract/private/position
新增websocket接口
- /contract/public/websocket
新增查询合约持仓量接口
- /contract/public/open-interest
新增合约接口
- /contract/public/details
新增深度列表接口
- /contract/public/depth

介绍

API Key 申请

很多接口需要API Access Key才可以访问. 请参考这个页面来设置.
设置API Access Key的同时，为了安全，建议设置IP访问白名单.
永远不要把你的API Access key/secret key告诉给任何人.

PNG

创建API Key后，您将获得3个必须记住的信息：

PNG

Access Key 表示账号的身份, 是您的API KEY
Secret Key 用于接口签名
Memo 用于接口签名

Access Key和Secret Key将由BitMart随机生成和提供，Memo将由您提供以确保API访问的安全性。

API Key 权限设置

新创建的API的默认权限是 只读。
如果需要通过API提款, 需要在UI修改权限, 选中 提现。
权限说明：
- 只读（查询现货交易订单、查询合约交易订单、资金查询)
- 现货（下单，撤单)
- 提现 (提现)
- 杠杆 (还款、借款、下单等)
- 合约 (做多，做空，平仓等)

PNG

只读权限:

接口名称	说明	鉴权类型
/account/v1/wallet	查询账户资产	KEYED
/account/v1/deposit/address	查询各个币种的充值地址	KEYED
/account/v2/deposit-withdraw/history	查询充提历史记录	KEYED
/account/v1/deposit-withdraw/detail	查询充提明细	KEYED
/spot/v1/wallet	查询用户所有币种钱包余额	KEYED
/spot/v4/query/order	orderId查单 (v4)	SIGNED
/spot/v4/query/client-order	clientOrderId查单 (v4)	SIGNED
/spot/v4/query/open-orders	当前委托 (v4)	SIGNED
/spot/v4/query/history-orders	历史委托 (v4)	SIGNED
/spot/v4/query/trades	成交记录 (v4)	SIGNED
/spot/v4/query/order-trades	单笔成交记录 (v4)	SIGNED
/spot/v1/user_fee	查询当前用户的基础费率	KEYED
/spot/v1/trade_fee	查询用户特定交易对的费率	KEYED
/spot/v1/margin/isolated/pairs	查询交易对借款利率与额度	KEYED
/spot/v1/margin/isolated/account	查询逐仓杠杆账户信息	KEYED
/spot/v1/margin/isolated/borrow_record	查询逐仓杠杆账户信息	KEYED
/spot/v1/margin/isolated/repay_record	查询逐仓杠杆账户信息	KEYED
/contract/private/get-open-orders	查询合约委托订单	KEYED
/contract/private/trade-fee-rate	查询用户交易费率	KEYED
/contract/private/order	查询合约订单详情	KEYED
/contract/private/order-history	查询合约历史订单	KEYED
/contract/private/trades	查询合约成交明细	KEYED
/contract/private/transaction-history	查询合约资金流水	KEYED
/contract/private/assets-detail	查询合约资产明细	KEYED
/contract/private/position	查询仓位详情	KEYED
/contract/private/current-plan-order	查询合约计划委托订单	KEYED
/contract/private/position-risk	查询合约的仓位风险信息	KEYED

提现权限:

接口名称	说明	鉴权类型
/account/v1/withdraw/charge	查询提币额度	KEYED
/account/v1/withdraw/apply	提币	SIGNED

现货交易权限:

接口名称	说明	鉴权类型
/spot/v1/submit_order	委托下单	SIGNED
/spot/v2/submit_order	委托下单	SIGNED
/spot/v1/batch_orders	批量下单	SIGNED
/spot/v2/batch_orders	批量下单	SIGNED
/spot/v4/batch_orders	批量下单	SIGNED
/spot/v1/cancel_order	取消一个未完成的订单	SIGNED
/spot/v3/cancel_order	取消一个未完成的订单	SIGNED
/spot/v1/cancel_orders	批量撤单	SIGNED
/spot/v4/cancel_orders	批量撤单	SIGNED

杠杆交易权限:

接口名称	说明	鉴权类型
/spot/v1/margin/submit_order	杠杆下单	SIGNED
/spot/v1/margin/isolated/transfer	杠杆账户和现货账户之间的资金划转	SIGNED
/spot/v1/margin/isolated/borrow	逐仓借款	SIGNED
/spot/v1/margin/isolated/repay	逐仓还款	SIGNED

合约交易权限:

接口名称	说明	鉴权类型
/contract/private/submit-order	合约下单	SIGNED
/contract/private/cancel-order	取消单个合约订单	SIGNED
/contract/private/cancel-orders	批量撤销合约订单	SIGNED
/contract/private/submit-plan-order	提交合约计划委托订单	SIGNED
/contract/private/cancel-plan-order	撤销合约计划委托订单	SIGNED
/account/v1/transfer-contract	现货账户与合约账户之间的划转	SIGNED
/account/v1/transfer-contract-list	查询合约账户划转列表	SIGNED
/contract/private/submit-tp-sl-order	合约设置仓位止盈止损单	SIGNED
/contract/private/modify-plan-order	合约修改计划委托单订单	SIGNED
/contract/private/modify-preset-plan-order	合约修改预设止盈止损	SIGNED
/contract/private/modify-tp-sl-order	合约修改止盈止损委托单	SIGNED
/contract/private/submit-trail-order	提交合约跟踪委托订单	SIGNED
/contract/private/cancel-trail-order	撤销合约跟踪委托订单	SIGNED

子账号权限:

需要进下机构认证，才能使用创建子账号并设置权限。(默认包含只读权限)

PNG

子账户现货权限:

同上面现货交易权限

子账户合约权限:

同上面合约交易权限

子账户账户间划转权限:

接口名称	说明	鉴权类型
/account/sub-account/main/v1/sub-to-main	子账户划转到主账户（主账户适用，现货账户)	SIGNED
/account/sub-account/sub/v1/sub-to-main	子账户划转到主账户（子账户适用，现货账户）	SIGNED
/account/sub-account/main/v1/main-to-sub	主账户划转到子账户（主账户适用，现货账户)	SIGNED
/account/sub-account/main/v1/sub-to-sub	子账户划转到子账户（主账户适用，现货账户）	SIGNED
/account/sub-account/main/v1/transfer-list	子账户划转历史（主账户适用，现货账户）	KEYED
/account/sub-account/v1/transfer-history	账户划转历史 (主子账户通用，现货账户)	KEYED
/account/sub-account/main/v1/wallet	子账户现货余额（主账户适用，现货账户）	KEYED
/account/sub-account/main/v1/subaccount-list	子账户列表（主账户适用，现货账户）	KEYED
/account/contract/sub-account/main/v1/sub-to-main	子账户划转到主账户（主账户适用，合约账户）	SIGNED
/account/contract/sub-account/main/v1/main-to-sub	主账户划转到子账户（主账户适用，合约账户）	SIGNED
/account/contract/sub-account/sub/v1/sub-to-main	子账户划转到主账户（子账户适用，合约账户）	SIGNED
/account/contract/sub-account/main/v1/wallet	子账户合约余额（主账户适用，合约账户）	KEYED
/account/contract/sub-account/main/v1/transfer-list	子账户划转历史（主账户适用,合约账户）	KEYED
/account/contract/sub-account/v1/transfer-history	账户划转历史（主,子账户适用,合约账户）	KEYED

API 代码库

为了方便接入，我们提供了一些语言的SDK供参考。更多编程代码，请参考页面上的快速接入 API。

可用的 SDK:

除了 SDK以外，我们还提供了多种语言的代码示例，示例主要演示了如何使用签名接口。它可以单独构建和运行，也可以作为您的代码库的一部分。

常见问题答疑

以下是收集到的经常遇到的问题以及解答。

问题1.同一个账户里的不同的API KEY，返回的账户信息数据，会不同吗？

问题2.申请APIKEY时如何填写?

问题3.HTTP状态码429是怎样造成的？

问题4. 使用ccxt，正确填写了API KEY，但是还会提示 'message': 'Header X-BM-SIGN is wrong'

问题5. 我自己写的程序，老是提示 'message': 'Header X-BM-SIGN is wrong'

问题6. BitMart 服务器部署在哪里？

问题7. 我申请的VIP费用什么时候生效？

问题8. 为什么提示"IP is forbidden. We recommend enabling IP whitelist for API trading. "

联系我们

官方Telegram社群 BitMart API Club
请花1分钟时间帮助我们提升我们的服务: API 满意度调研

基本信息

API基本信息

本篇列出接口的rest baseurl: https://api-cloud-v2.bitmart.com
所有接口的响应都是 JSON 格式。

请求参数设置

GET, DELETE 方法的接口, 参数必须在 query string中发送, 即URL?后拼接的参数。
POST, PUT 方法的接口, 参数在 request body 中发送，格式是JSON。

HTTP 返回代码

HTTP 4XX 错误码用于指示错误的请求内容、行为、格式。问题在于请求者。
HTTP 403 错误码表示违反限制(被禁止调用)。
HTTP 429 错误码表示警告访问频次超限，即将被封IP。
HTTP 418 表示收到429后继续访问，于是被封了。
HTTP 5XX 错误码用于指示BitMart服务出现的问题。

API 返回内容

code 错误码
message 错误描述
trace 每次请求事件跟踪ID，服务端对每次请求都会返回
data 用户数据

详细参见参见错误码列表

签名

接口后面会标注鉴权类型，遇到 SIGNED 标记，说明这个接口需要签名才能访问。遇到 KEYED 标记，说明这个接口只需要在请求头设置API KEY即可。

鉴权类型

NONE:不需要鉴权的接口, 所有人都可以访问
KEYED:需要有效的X-BM-KEY
SIGNED:需要有效的X-BM-KEY 和签名X-BM-SIGN

1.设置请求参数

header key设置

X-BM-TIMESTAMP 生成

// Java
System.currentTimeMillis();

// Python
int(time.time() * 1000)

// Golang
time.Now().UnixNano() / int64(time.Millisecond)

// Nodejs & TypeScript
Date.now();

// Javascript
Date.now();

// PHP
round(microtime(true) * 1000)

// C#
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()

X-BM-KEY (你创建的API Access KEY)
X-BM-SIGN (使用Sha-256签名)
X-BM-TIMESTAMP (发起请求的当前时间戳, 精确到毫秒)

body参数设置

GET/DELETE的请求方式，query string 是symbol=BMX&side=BUY的form表单格式
POST/PUT的请求方式，query string 是{"symbol":"BMX","side":"BUY"}的json格式

2.例子

Shell 完整请求示例

echo -n '1589793796145#test001#{"symbol":"BTC_USDT","price":"8600","count":"100"}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
    (stdin)= c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d

    curl --location --request POST 'localhost:8080/spot/v1/test-post'
    --header 'Content-Type: application/json'
    --header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
    --header 'X-BM-SIGN: c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d'
    --header 'X-BM-TIMESTAMP: 1589793796145'
    --d '{"symbol":"BTC_USDT","price":"8600","count":"100"}'

请求接口： /spot/v1/test-post (SIGNED)
请求方式: POST
假设当前时间戳: timestamp=1589793796145
request body=`{"symbol":"BTC_USDT","price":"8600","count":"100"}

则设置如下：

X-BM-TIMESTAMP=1589793796145
X-BM-KEY=Your_api_access_key
X-BM-SIGN= hmac_sha256(Your_api_secret_key, X-BM-TIMESTAMP + '#' +Your_api_memo + '#' + '{"symbol":"BTC_USDT","price":"8600","count":"100"}')

假设您申请的key如下:

accessKey=80618e45710812162b04892c7ee5ead4a3cc3e56
secretKey=6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9
memo=test001

则右边是一个完整的请求

你也可以参考快速接入代码来实现

频率限制

公有接口按照IP来限速，私有接口按照API KEY来限速。当访问超过频率限制时，将返回429状态：请求太频繁。

具体接口限制详细如下:

公开行情接口	接口名称	限制目标	速率
/contract/public/details	获取合约列表详情	IP	12次/2s
/contract/public/depth	获取合约深度	IP	12次/2s
/contract/public/open-interest	获取合约深度	IP	2次/2s
/contract/public/funding-rate	查询当前资金费率	IP	12次/2s
/contract/public/funding-rate-history	查询资金费率历史	IP	12次/2s
/contract/public/kline	查询K线数据	IP	12次/2s

交易接口	接口名称	限制目标	速率
/contract/private/submit-order	合约下单	X-BM-KEY	24次/2s
/contract/private/cancel-order	取消单个合约订单	X-BM-KEY	40次/2s
/contract/private/cancel-orders	批量撤销合约订单	X-BM-KEY	2次/2s
/contract/private/submit-plan-order	合约计划委托下单	X-BM-KEY	24次/2s
/contract/private/cancel-plan-order	取消单个合约计划委托订单	X-BM-KEY	40次/2s
/contract/private/get-open-orders	查询合约委托订单	X-BM-KEY	50次/2s
/contract/private/order	查询合约订单详情	X-BM-KEY	50次/2s
/contract/private/order-history	查询合约历史订单	X-BM-KEY	6次/2s
/contract/private/trades	查询合约成交明细	X-BM-KEY	6次/2s
/contract/private/transaction-history	查询合约资金流水	X-BM-KEY	6次/2s
/contract/private/assets-detail	查询合约资产明细	X-BM-KEY	12次/2s
/contract/private/position	查询仓位详情	X-BM-KEY	6次/2s
/contract/private/submit-leverage	合约杠杆调整	X-BM-KEY	24次/2s
/account/v1/transfer-contract	合约账户划转现货	X-BM-KEY	1次/2s
/account/v1/transfer-contract-list	查询划转记录	X-BM-KEY	1次/2s
/contract/private/current-plan-order	查询合约计划委托订单记录	X-BM-KEY	50次/2s
/contract/private/position-risk	查询仓位风险信息	X-BM-KEY	24次/2s
/contract/private/trade-fee-rate	查询交易费率	X-BM-KEY	2次/2s
/contract/private/submit-tp-sl-order	合约止盈止损下单	X-BM-KEY	24次/2s
/contract/private/modify-plan-order	合约修改计划委托单	X-BM-KEY	24次/2s
/contract/private/modify-preset-plan-order	合约修改预设止盈止损单	X-BM-KEY	24次/2s
/contract/private/modify-tp-sl-order	合约修改止盈止损委托单	X-BM-KEY	24次/2s

子母账户接口	接口名称	限制目标	速率
/account/contract/sub-account/main/v1/sub-to-main	子账户划转到主账户（主账户适用，合约账户）	X-BM-KEY	8次/2s
/account/contract/sub-account/main/v1/main-to-sub	主账户划转到子账户（主账户适用，合约账户）	X-BM-KEY	8次/2s
/account/contract/sub-account/sub/v1/sub-to-main	子账户划转到主账户（子账户适用，合约账户）	X-BM-KEY	8次/2s
/account/contract/sub-account/main/v1/wallet	子账户合约余额（主账户适用，合约账户）	X-BM-KEY	12次/2s
/account/contract/sub-account/main/v1/transfer-list	子账户划转历史（主账户适用,合约账户）	X-BM-KEY	8次/2s
/account/contract/sub-account/v1/transfer-history	账户划转历史（主,子账户适用,合约账户）	X-BM-KEY	8次/2s

REST API

限速判断:

每次调用接口都会返回带有限制标记的 3 个 Response Header，如下所示:

Example:

X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
上面的设置，意思是 60 秒内可调用 600 次，当前已调用 10 次

Response Header	说明
X-BM-RateLimit-Remaining	当前时间窗口内已使用的次数
X-BM-RateLimit-Limit	当前时间窗口内最大可调用次数
X-BM-RateLimit-Reset	当前时间窗口,秒为单位

合约公开 API 参数

字段说明

symbol 交易对名称, 由交易货币和计价货币组成。以BTCUSDT 为例，BTC 为交易货币，USDT 为计价货币，交易对主要在合约交易使用
order_id 订单编号，每个业务线的同一币对下的订单ID是唯一的

订单状态（字段:state)

2=委托中
4=已结束

订单方向（字段:side)

1=开多
2=平空
3=平多
4=开空

仓位方向（字段:position_type)

1=开多
2=平空

订单类型（字段:type)

limit=现价单
market=市价单
liquidate=强平单
bankruptcy=爆仓破产单

开仓类型（字段:open_type)

cross=全仓
isolated=逐仓

下单方式（字段:mode)

1=GTC
2=FOK
3=IOC
4=Maker Only

时间 timestamp

系统返回的时间全部都是时间戳形式。

公共行情

获取所有合约详情

适用于查询合约的详细信息

请求URL

GET https://api-cloud-v2.bitmart.com/contract/public/details

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/public/details?symbol=BTCUSDT

参数	类型	是否必填	描述
symbol	String	选填	交易对名称(选填，默认返回全部)

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "trace": "9b92a999-9463-4c96-91a4-93ad1cad0d72",
  "data": {
    "symbols": [
      {
        "symbol": "BTCUSDT",
        "product_type": 1,
        "open_timestamp": 1594080000000,
        "expire_timestamp": 0,
        "settle_timestamp": 0,
        "base_currency": "BTC",
        "quote_currency": "USDT",
        "last_price": "23920",
        "volume_24h": "18969368",
        "turnover_24h": "458933659.7858",
        "index_price": "23945.25191635",
        "index_name": "BTCUSDT",
        "contract_size": "0.001",
        "min_leverage": "1",
        "max_leverage": "100",
        "price_precision": "0.1",
        "vol_precision": "1",
        "max_volume": "500000",
        "market_max_volume": "500000",
        "min_volume": "1",
        "funding_rate": "0.0001",
        "expected_funding_rate": "0.00011",
        "open_interest": "4134180870",
        "open_interest_value": "94100888927.0433258",
        "high_24h": "23900",
        "low_24h": "23100",
        "change_24h": "0.004",
        "funding_interval_hours": 8
      },
      ...
    ]
  }
}

字段	类型	描述
symbols	List	交易对详情数组

交易对详情字段描述:

交易对详情	类型	描述
symbols	List	交易对详情数组
symbol	String	交易对名称
product_type	Int	合约类型 1永续 2期货目前只有永续合约
base_currency	String	合约基础币
quote_currency	String	合约计价币种
volume_precision	String	数量精度
price_precision	String	价格精度
max_volume	String	合约限价下单最大数量
market_max_volume	String	合约市价下单最大数量
min_volume	String	合约下单最小数量
contract_size	String	合约大小
index_price	String	指数价格
index_name	String	指数名称
min_leverage	String	最小杠杆倍数
max_leverage	String	最大杠杆倍数
turnover_24h	String	24小时成交额
volume_24h	String	24小时成交量
last_price	String	最新成交价
open_timestamp	Long	首次开放时间
expire_timestamp	Long	到期日期，如果返回空则为不过期
settle_timestamp	Long	结算日期，如果返回空则不会自动结算
funding_rate	String	上期结算费率
expected_funding_rate	String	预期结算费率
open_interest	String	持仓量
open_interest_value	String	持仓量价值
high_24h	String	24小时最高价
low_24h	String	24小时最低价
change_24h	String	24小时涨跌
funding_interval_hours	Int	资金费率收取间隔

获取深度

获取交易对完整的深度。

请求URL

GET https://api-cloud-v2.bitmart.com/contract/public/depth

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/public/depth?symbol=BTCUSDT

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "trace": "b9bff62d-9ac8-4815-8808-8f745673c096",
  "data": {
    "asks": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "bids": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "timestamp": 1660285421287,
    "symbol": "BTCUSDT"
  }
}

字段	类型	描述
timestamp	Long	当前系统时间(时间戳，精确到毫秒)
bids	List	买方深度列表
asks	List	卖方深度列表
symbol	String	交易对

深度详情描述：

字段	类型	描述
第一位	String	当前深度价格。例如 23935.4
第二位	String	当前价格深度的总量。例如 65
第三位	String	当前价格深度之上（包含当前）的总量累加。例如 65

查询合约持仓量

适用于查询指定合约当前持仓量和持仓总价值

请求URL

GET https://api-cloud-v2.bitmart.com/contract/public/open-interest

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/public/open-interest?symbol=BTCUSDT

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）

响应详情

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
    "timestamp": 1661239541734,
    "symbol": "BTCUSDT",
    "open_interest": "4134180870",
    "open_interest_value": "94100888927.0433258"
  }
}

字段	类型	描述
timestamp	Long	时间戳
symbol	String	合约名称
open_interest	String	持仓量
open_interest_value	String	持仓量价值

查询当前资金费率

适用于查询指定合约当前资金费率

请求URL

GET https://api-cloud-v2.bitmart.com/contract/public/funding-rate

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/public/funding-rate?symbol=BTCUSDT

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "timestamp": 1662518172178,
    "symbol": "BTCUSDT",
    "rate_value": "0.000164",
    "expected_rate": "0.000164",
    "funding_time": 1709971200000,
    "funding_upper_limit": "0.0375",
    "funding_lower_limit": "-0.0375"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
timestamp	Long	时间戳
symbol	String	合约名称
rate_value	String	上一期的资金费率
expected_rate	String	下一期的资金费率
funding_time	Long	下次结算时间
funding_upper_limit	Long	该交易对的资金费率上限
funding_lower_limit	Long	该交易对的资金费率下限

查询K线数据

适用于K线数据, 单次请求限制500条数据

请求URL

GET https://api-cloud-v2.bitmart.com/contract/public/kline

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/public/kline?symbol=BTCUSDT&step=5&start_time=1662518172&end_time=1662518172

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
step	Long	选填	K线间隔，默认为1分钟步长: `1`, `3`, `5`, `15`, `30`, `60`, `120`, `240`, `360`, `720`, `1440`, `4320`, `10080`
start_time	Long	必填	开始时间。时间戳需要是秒级别的
end_time	Long	必填	结束时间。时间戳需要是秒级别的

响应详情

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": [{
    "timestamp": 1662518160,
    "open_price": "100",
    "close_price": "120",
    "high_price": "130",
    "low_price": "90",
    "volume": "941008"
    },
    {
    "timestamp": 1662518161,
    "open_price": "99",
    "close_price": "119",
    "high_price": "129",
    "low_price": "89",
    "volume": "941008"
    }
  ]
}

字段	类型	描述
timestamp	Long	时间窗口
open_price	String	开盘价
close_price	String	收盘价
high_price	String	最高价
low_price	String	最低价
volume	String	成交量

查询资金费率历史

适用于获取历史资金费率

请求URL

GET https://api-cloud-v2.bitmart.com/contract/public/funding-rate-history

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/public/funding-rate-history?symbol=BTCUSDT&limit=10

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
limit	String	选填	每页返回条数，最大100条，默认100条

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "list": [
      {
        "symbol": "BTCUSDT",
        "funding_rate": "0.000090600584",
        "funding_time": "1733979600000"
      }
    ]
  },
  "trace": "4b588ac6b7cb11ef96b16280797cd561.3819021.39457365988950452"
}

字段	类型	描述
list	list	列表详情数组

列表详情字段描述:

字段	类型	描述
symbol	String	合约名称
funding_rate	String	资金费率
funding_time	String	结算时间

资金账户

查询合约资产明细 (KEYED)

适用于查询用户合约资产明细

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/assets-detail

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/assets-detail

无

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
    "currency": "USDT",
    "position_deposit": "100",
    "frozen_balance": "100",
    "available_balance": "100",
    "equity": "100",
    "unrealized": "100"
    },
    {
      "currency": "BTC",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    },
    {
      "currency": "ETH",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    }
  ],
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
currency	String	币种
position_deposit	String	仓位保证金
frozen_balance	String	交易冻结金额
available_balance	String	可用金额
equity	String	总权益
unrealized	String	未实现盈亏

合约交易

查询用户交易费率 (KEYED)

适用于查询用户交易费率

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/trade-fee-rate

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/trade-fee-rate?symbol=BTCUSDT

参数	类型	是否必填?	描述
symbol	String	必填	合约交易对（如BTCUSDT）

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "symbol": "BTCUSDT",
    "taker_fee_rate": "0.0006",
    "maker_fee_rate": "0.0002"
  },
  "trace": "638d5048-ad21-4a4b-1234-d0756fbfc7ba"
}

字段	类型	描述
symbol	String	Symbol of the contract
taker_fee_rate	String	Taker fee rate
maker_fee_rate	String	Maker fee rate

查询合约订单详情 (KEYED)

适用于查询某合约订单详情

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/order

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/order?symbol=BTCUSDT&order_id=220609666322019

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
order_id	String	必填	订单编号

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220906179895578",
    "client_order_id": "BM123",
    "price": "1",
    "size": "1000",
    "symbol": "BTCUSDT",
    "state": 2,
    "side": 1,
    "type": "limit",
    "leverage": "5",
    "open_type": "isolated",
    "deal_avg_price": "0",
    "deal_size": "1000",
    "create_time": 1662368173000,
    "update_time": 1662368173000
  },
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}

字段	类型	描述
symbol	String	合约交易对（如BTCUSDT）
order_id	String	订单编号
client_order_id	String	用户自定义ID（如果该字段未定义，则返回空）
side	Int	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`liquidate`=强平单 -`bankruptcy`=爆仓破产单 -`adl`=adl单 -`trailing`=跟踪委托单
leverage	String	杠杆下单倍数
open_type	String	开仓类型 -`cross`=全仓 -`isolated`=逐仓
deal_avg_price	String	成交均价
deal_size	String	成交数量
price	String	委托价格
size	String	委托数量
state	Int	订单状态 -`1`=审批中 -`2`=委托中 -`4`=已结束
activation_price	String	激活价格,跟踪委托单返回
callback_rate	String	回调幅度,跟踪委托单返回
activation_price_type	Int	激活价格类型,跟踪委托单返回 -`1`=最新成交价 -`2`=标记价格
preset_take_profit_price_type	Int	预设止盈委托价格类型 -`1`=最新成交价 -`2`=标记价格
preset_stop_loss_price_type	Int	预设止损委托价格类型 -`1`=最新成交价 -`2`=标记价格
preset_take_profit_price	String	预设止盈价格
preset_stop_loss_price	String	预设止损价格
create_time	Long	创建时间
update_time	Long	更新时间

查询合约历史订单 (KEYED)

适用于查询某合约订单历史记录

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/order-history

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/order-history?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
start_time	Long	选填	开始时间，默认最近7天
end_time	Long	选填	结束时间，默认最近7天

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "order_id": "220908185908509",
      "client_order_id": "BM123",
      "price": "14277",
      "size": "7216",
      "symbol": "BTCUSDT",
      "state": 4,
      "side": 3,
      "type": "limit",
      "leverage": "0",
      "open_type": "isolated",
      "deal_avg_price": "14277",
      "deal_size": "7216",
      "create_time": 1662368173000,
      "update_time": 1662368173000
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}

字段	类型	描述
symbol	String	合约交易对（如BTCUSDT）
order_id	String	订单编号
client_order_id	String	用户自定义ID（如果该字段未定义，则返回空）
side	Int	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`liquidate`=强平单 -`bankruptcy`=爆仓破产单 -`adl`=adl单 -`trailing`=跟踪委托单
leverage	String	杠杆下单倍数
open_type	String	开仓类型 -`cross`=全仓 -`isolated`=逐仓
deal_avg_price	String	成交均价
deal_size	String	成交数量
price	String	委托价格
size	String	委托数量
state	Int	订单状态 -`2`=委托中 -`4`=已结束
activation_price	String	激活价格,跟踪委托单返回
callback_rate	String	回调幅度,跟踪委托单返回
activation_price_type	Int	激活价格类型,跟踪委托单返回 -`1`=最新成交价 -`2`=标记价格
executive_order_id	String	触发执行订单编号
preset_take_profit_price_type	Int	预设止盈委托价格类型 -`0`=未设置 -`1`=最新成交价 -`2`=标记价格
preset_stop_loss_price_type	Int	预设止损委托价格类型 -`0`=未设置 -`1`=最新成交价 -`2`=标记价格
preset_take_profit_price	String	预设止盈价格
preset_stop_loss_price	String	预设止损价格
create_time	Long	创建时间
update_time	Long	更新时间

查询合约委托订单记录 (KEYED)

适用于查询某合约委托订单记录

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/get-open-orders

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/get-open-orders?symbol=BTCUSDT&order_state=partially_filled&type=market&limit=10

参数	类型	是否必填	描述
symbol	String	选填	合约交易对（如BTCUSDT）
type	String	选填	订单类型 -`limit`=限价单 -`market`=市价单 -`trailing`=跟踪委托默认返回全部
order_state	String	选填	订单状态 -`all`=全部(默认) -`partially_filled`=部分成交
limit	int	选填	返回结果的数量，最大为100，默认100条

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "order_id": "220908185908509",
      "client_order_id": "BM123",
      "price": "14277",
      "size": "7216",
      "symbol": "BTCUSDT",
      "state": 4,
      "side": 3,
      "type": "limit",
      "leverage": "0",
      "open_type": "isolated",
      "deal_avg_price": "14277",
      "deal_size": "7216",
      "preset_take_profit_price_type": 1,
      "preset_stop_loss_price_type": 2,
      "preset_take_profit_price": "68000",
      "preset_stop_loss_price": "60000",
      "create_time": 1662368173000,
      "update_time": 1662368173000
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}

字段	类型	描述
symbol	String	合约交易对（如BTCUSDT）
order_id	String	订单编号
client_order_id	String	用户自定义ID（如果该字段未定义，则返回空）
side	Int	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`trailing`=跟踪委托单
size	String	订单数量
leverage	String	杠杆下单倍数
open_type	String	开仓类型 -`cross`=全仓 -`isolated`=逐仓
deal_avg_price	String	成交均价
deal_size	String	成交数量
price	String	委托价格
size	String	委托数量
state	Int	订单状态 -`2`=委托中
activation_price	String	激活价格,跟踪委托单返回
callback_rate	String	回调幅度,跟踪委托单返回
activation_price_type	Int	激活价格类型,跟踪委托单返回 -`1`=最新成交价 -`2`=标记价格
preset_take_profit_price_type	Int	预设止盈委托价格类型 -`1`=最新成交价 -`2`=标记价格
preset_stop_loss_price_type	Int	预设止损委托价格类型 -`1`=最新成交价 -`2`=标记价格
preset_take_profit_price	String	预设止盈价格
preset_stop_loss_price	String	预设止损价格
create_time	Long	创建时间
update_time	Long	更新时间

查询合约计划委托订单记录 (KEYED)

适用于查询某合约计划委托订单记录

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/current-plan-order

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/current-plan-order?symbol=BTCUSDT&type=market&limit=10

参数	类型	是否必填	描述
symbol	String	选填	合约交易对（如BTCUSDT）
type	String	选填	订单类型 -`limit`=限价单 -`market`=市价单默认返回全部
limit	int	选填	返回结果的数量，最大为100，默认100条
plan_type	String	选填	委托订单类型 -`plan`=计划委托 -`profit_loss`=止盈止损默认返回全部

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "order_id": "220908185908509",
      "client_order_id": "BM123",
      "executive_price": "14277",
      "trigger_price": "14277",
      "size": "7216",
      "symbol": "BTCUSDT",
      "state": 4,
      "side": 3,
      "mode": 1,
      "price_way": 2,
      "price_type": 1,
      "plan_category": 2,
      "type": "stop_loss",
      "leverage": "0",
      "open_type": "isolated",
      "create_time": 1662368173000,
      "update_time": 1662368173000
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}

字段	类型	描述
symbol	String	合约交易对（如BTCUSDT）
order_id	String	订单编号
client_order_id	String	用户自定义ID（如果该字段未定义，则返回空）
side	Int	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
type	String	订单类型 -`plan`=普通计划委托单 -`take_profit`=止盈委托单 -`stop_loss`=止损委托单
plan_category	Int	止盈止损类型 -`1`=部分仓位止盈止损 -`2`=全仓止盈止损
size	String	订单数量
leverage	String	杠杆下单倍数
open_type	String	开仓类型 -`cross`=全仓 -`isolated`=逐仓
executive_price	String	委托价格
trigger_price	String	触发价格
state	Int	订单状态 -`1`=审批中 -`2`=委托中
preset_take_profit_price_type	Int	预设止盈委托价格类型 -`1`=最新成交价 -`2`=标记价格
preset_stop_loss_price_type	Int	预设止损委托价格类型 -`1`=最新成交价 -`2`=标记价格
preset_take_profit_price	String	预设止盈价格
preset_stop_loss_price	String	预设止损价格
create_time	Long	创建时间
update_time	Long	更新时间

查询仓位详情 (KEYED)

适用于查询指定合约的仓位详情

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/position

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/position?symbol=BTCUSDT

参数	类型	是否必填	描述
symbol	String	选填	合约交易对（如BTCUSDT）

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol": "BTCUSDT",
      "leverage": "5",
      "timestamp": 1663814313531,
      "current_fee": "5.00409471",
      "open_timestamp": 1662714817820,
      "current_value": "16680.3157",
      "mark_value": "16673.27053207877",
      "mark_price": "93000.50",
      "position_value": "18584.272343943943943944339",
      "position_cross": "3798.397624451826977945",
      "maintenance_margin": "4798.397624451826977945",
      "margin_type":"Isolated",
      "close_vol": "100",
      "close_avg_price": "20700.7",
      "open_avg_price": "20200",
      "entry_price": "20201",
      "current_amount": "899",
      "unrealized_value": "1903.956643943943943944339",
      "realized_value": "55.049173071454605573",
      "position_type": 2
    }
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}

字段	类型	描述
leverage	String	杠杆倍数
symbol	String	合约名称
current_fee	String	当前仓位总费用
open_timestamp	Long	开仓时间戳
current_value	String	最新价格计算的仓位价值
mark_price	String	标记价格
mark_value	String	标记价格计算的仓位价值
position_value	String	持仓均价计算的仓位价值
open_avg_price	String	开仓均价
close_avg_price	String	平仓均价
entry_price	String	持仓均价
close_vol	String	平仓量
position_cross	String	追加到仓位的保证金
maintenance_margin	String	维持保证金
margin_type	String	仓位保证金类型 -`Cross` -`Isolated`
current_amount	String	当前仓位数量
unrealized_value	String	未实现盈亏
realized_value	String	已实现盈亏
position_type	Int	仓位方向 -`1`=开多 -`2`=开空
timestamp	Long	当前时间戳

查询仓位风险信息 (KEYED)

适用于查询指定合约或者全部合约的仓位风险信息

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/position-risk

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/position-risk?symbol=BTCUSDT

参数	类型	是否必填	描述
symbol	String	选填	合约交易对（如BTCUSDT）

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol":"BTCUSDT",
      "position_amt":"1",
      "mark_price":"67957.7",
      "unrealized_profit":"969.6",
      "liquidation_price":"64245",
      "leverage":"20",
      "max_notional_value":"3000000",
      "margin_type":"Isolated",
      "isolated_margin":"3078.51948691",
      "position_side":"Long",
      "notional":"66988.1",
      "update_time":1712390438}
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}

字段	类型	描述
symbol	String	合约名称
position_amt	String	仓位数量
mark_price	String	标记价格
unrealized_profit	String	未实现盈亏
liquidation_price	String	强平价
leverage	String	当前杠杆
max_notional_value	String	当前最大可持仓价值
margin_type	String	仓位保证金类型 -`Cross` -`Isolated`
isolated_margin	String	逐仓保证金
position_side	String	仓位方向 -`Long` -`Short`
notional	String	仓位净值
update_time	Long	更新时间

查询合约成交明细 (KEYED)

适用于查询某合约订单成交明细

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/trades

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/trades?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
start_time	Long	选填	开始时间，默认最近7天
end_time	Long	选填	结束时间，默认最近7天

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [{
    "order_id": "220921197409432",
    "trade_id": "1141853921",
    "symbol": "BTCUSDT",
    "side": 1,
    "price": "19313.3",
    "vol": "108",
    "exec_type": "Maker",
    "profit": false,
    "realised_profit": "-0.00832",
    "paid_fees": "0",
    "create_time": 1663663818589
  }],
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}

字段	类型	描述
symbol	String	合约交易对（如BTCUSDT）
order_id	String	订单编号
trade_id	String	成交明细编号
side	Int	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
price	String	成交价格
vol	String	成交量
exec_type	String	流动性类型 -`Taker` -`Maker`
profit	Boolean	是否盈利
realised_profit	String	已实现盈亏
paid_fees	String	手续费
create_time	Long	创建时间

查询合约资金流水 (KEYED)

适用于查询合约资金流水记录

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/transaction-history

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/transaction-history?symbol=BTCUSDT&start_time=1662368173000&end_time=1662368179000

参数	类型	是否必填	描述
symbol	String	选填	交易对
flow_type	Int	选填	类型 - `0` = 全部(默认) - `1` = 划转 - `2` = 已实现盈亏 - `3` = 资金费用 - `4` = 手续费 - `5` = 强平清算费
start_time	Long	选填	开始时间戳，单位毫秒
end_time	Long	选填	结束时间戳，单位毫秒
page_size	Int	选填	每页返回的记录数，默认100，最大1000

如果start_time 和 end_time 均未发送, 只会返回最近7天的数据。
如果type没有发送，返回所有类型账户损益资金流水。

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol": "",
      "type": "Transfer",
      "amount": "-0.37500000",
      "asset": "USDT",
      "time": "1570608000000",
      "tran_id": "9689322392"
    },
    {
      "symbol": "BTCUSDT",
      "type": "Commission Fee",
      "amount": "-0.01000000",
      "asset": "USDT",
      "time": "1570636800000",
      "tran_id": "9689322392"
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}

字段	类型	描述
symbol	String	交易对
flow_type	Int	类型 - `0` = 全部(默认) - `1` = 划转 - `2` = 已实现盈亏 - `3` = 资金费用 - `4` = 手续费 - `5` = 强平清算费
type	STRING	类型 - `Transfer` - `Realized PNL` - `Funding Fee` - `Commission Fee` - `Liquidation Clearance`
amount	String	金额，支持正负号
asset	String	资金流水币种
time	String	交易时间戳，单位毫秒
tran_id	String	交易ID

查询划转列表 (SIGNED)

查询合约账户划转记录

请求URL

POST https://api-cloud-v2.bitmart.com/account/v1/transfer-contract-list

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "currency":"USDT",
    "time_start":1684391137804,
    "time_end":1684392577804,
    "page":1,
    "limit":10,
    "recvWindow":5000
}'
https://api-cloud-v2.bitmart.com/account/v1/transfer-contract-list

参数	类型	是否必填	描述
currency	String	否	币种, 如 `BTC`
time_start	Long	否	起始时间, 精确到毫秒, 如: 1681701557927
time_end	Long	否	结束时间, 精确到毫秒, 如: 1681701557927
page	Int	必填	第几页，取值范围[1,10000]
limit	Int	必填	每页返回条数，取值范围[10,100]
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

注意

没有填写时间范围time_start和time_end，则默认展示全部的数据。
填写时间范围的话，time_end 必须比 time_start 的值大。
如果只填写了time_start，则查询从该时间戳开始时间往后的历史记录。
如果只填写了time_end，则查询从该时间戳开始时间往前的历史记录。

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"82abff12-b9d9-4f66-89ea-3b604c6d84",
    "data":{
        "records":[{
            "transfer_id":"664651258694168576",
            "currency":"USDT",
            "amount":"0.1",
            "type":"contract_to_spot",
            "state":"FINISHED",
            "timestamp":1638631674326
        }]
    }
}

字段	类型	描述
transfer_id	String	划转ID
currency	String	币种
amount	String	成功划转的金额
type	String	划转方向 -`spot_to_contract`=现货到合约 -`contract_to_spot`=合约到现货
state	String	划转结果 -`PROCESSING`=等待执行 -`FINISHED`=成功划转 -`FAILED`=划转失败
timestamp	Long	创建时间戳，精确到毫秒

合约下单 (SIGNED)

适用于用户进行合约订单下单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/submit-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "client_order_id":"BM1234",
  "side":4,
  "type":"limit",
  "mode":1,
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "price":"2000"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
client_order_id	String	选填	用户自定义ID, 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间
type	String	选填	订单类型 -`limit`=限价单(默认) -`market`=市价单
side	Int	必填	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
leverage	String	选填	杠杆下单倍数
open_type	String	选填	开仓类型 -`cross`=全仓 -`isolated`=逐仓
mode	Int	选填	下单方式 -`1`=GTC(默认) -`2`=FOK -`3`=IOC -`4`=Maker Only
price	String	必填	下单价格，限价单模式必填。
size	Int	必填	订单数量张数
preset_take_profit_price_type	Int	选填	预设止盈委托价格类型 -`1`=最新成交价(默认) -`2`=标记价格
preset_stop_loss_price_type	Int	选填	预设止损委托价格类型 -`1`=最新成交价(默认) -`2`=标记价格
preset_take_profit_price	String	选填	预设止盈价格
preset_stop_loss_price	String	选填	预设止损价格

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019,
    "price": "25637.2"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
order_id	Int	订单编号
price	String	订单价格，若提交市价单，将直接返回固定字符串："market price"

取消单个合约订单 (SIGNED)

适用于用户进行合约订单撤单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/cancel-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud-v2.bitmart.com/contract/private/cancel-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）,如果不传order_id和client_order_id，则会取消该交易对下所有订单
order_id	String	非必填	订单编号
client_order_id	String	非必填	用户自定义ID

响应详情

code 返回 1000 表示撤销成功。

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

批量撤销合约订单 (SIGNED)

适用于用户进行某合约下的批量订单撤单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/cancel-orders

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT"
}'
https://api-cloud-v2.bitmart.com/contract/private/cancel-orders

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）

响应详情

code 返回 1000 表示撤销成功。

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

合约计划委托下单 (SIGNED)

适用于用户进行合约计划委托订单下单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/submit-plan-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "side":4,
  "type":"limit",
  "mode":1,
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "price_way":1
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-plan-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
type	String	选填	订单类型 -`limit`=限价单(默认） -`market`=市价单 -`take_profit`=止盈单 -`stop_loss`=止损单
side	Int	必填	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
leverage	String	必填	杠杆下单倍数
open_type	String	必填	开仓类型 -`cross`=全仓 -`isolated`=逐仓
mode	Int	选填	下单方式 -`1`=GTC(默认) -`2`=FOK -`3`=IOC -`4`=Maker Only
size	Int	必填	订单数量张数
trigger_price	String	必填	触发价格
executive_price	String	选填	执行价格，订单 type = limit 必填
price_way	Int	必填	价格方向 -`1`=看涨 -`2`=看跌
price_type	Int	必填	触发价格类型 -`1`=最新成交价 -`2`=标记价格
plan_category	Int	选填	止盈止损类型 -`1`=部分仓位止盈止损 -`2`=全仓止盈止损
preset_take_profit_price_type	Int	选填	预设止盈委托价格类型 -`1`=最新成交价(默认) -`2`=标记价格
preset_stop_loss_price_type	Int	选填	预设止损委托价格类型 -`1`=最新成交价(默认) -`2`=标记价格
preset_take_profit_price	String	选填	预设止盈价格
preset_stop_loss_price	String	选填	预设止损价格

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
order_id	Int	订单编号

取消计划委托合约订单 (SIGNED)

适用于用户进行合约计划委托订单撤单

请求格式

POST https://api-cloud-v2.bitmart.com/contract/private/cancel-plan-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421",
  "client_order_id": "123456789"
}'
https://api-cloud-v2.bitmart.com/contract/private/cancel-plan-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
order_id	String	选填	订单编号
client_order_id	String	选填	用户自定义ID

响应详情

code 返回 1000 表示撤销成功。

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

划转 (SIGNED)

现货账户与合约账户之间的划转

请求URL

POST https://api-cloud-v2.bitmart.com/account/v1/transfer-contract

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "currency":"USDT",
  "amount":"10",
  "type":"spot_to_contract",
  "recvWindow":5000
}'
https://api-cloud-v2.bitmart.com/account/v1/transfer-contract

参数	类型	是否必填	描述
currency	String	必填	币种, 如 `USDT` (当前只支持USDT)
amount	String	必填	划转金额，取值范围[0.01,10000000000]
type	String	必填	划转方向 -`spot_to_contract`=现货到合约 -`contract_to_spot`=合约到现货
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

响应详情

响应

{
  "message":"OK",
  "code":1000,
  "trace":"34018ca3-fe24-446a-9e1d-f82edfb3e3",
  "data":{
    "currency":"USDT",
    "amount":"10"
  }
}

字段	类型	描述
currency	String	币种
amount	String	成功划转的金额

合约杠杆调整 (SIGNED)

适用于用户进行合约杠杆调整

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/submit-leverage

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "leverage":"5",
  "open_type":"isolated"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-leverage

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
leverage	String	选填	杠杆下单倍数
open_type	String	必填	开仓类型 -`cross`=全仓 -`isolated`=逐仓

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "symbol":"ETHUSDT",
    "leverage":"5",
    "open_type":"isolated",
    "max_value":"100"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
symbol	String	合约交易对
leverage	String	当前杠杆下单倍数
open_type	String	开仓类型 -`cross`=全仓 -`isolated`=逐仓
max_value	String	最大杠杆

合约止盈止损下单 (SIGNED)

适用于用户进行合约止盈止损订单下单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/submit-tp-sl-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "side":2,
  "type":"take_profit",
  "size":10,
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "plan_category":1,
  "client_order_id":"123456789",
  "category":"limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-tp-sl-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
type	String	必填	订单类型 -`take_profit`=止盈单 -`stop_loss`=止损单
side	Int	必填	订单方向 -`2`=平空 -`3`=平多
size	Int	选填	订单数量张数默认仓位数量（对应仓位止盈止损）
trigger_price	String	必填	触发价格
executive_price	String	必填	执行价格
price_type	Int	必填	触发价格类型 -`1`=最新成交价 -`2`=标记价格
plan_category	Int	选填	止盈止损类型 -`1`=部分仓位止盈止损 -`2`=全仓止盈止损（默认）
client_order_id	String	选填	用户自定义ID, 字母（区分大小写）与数字的组合，可以是纯字母、纯数字且长度要在1-32位之间
category	String	选填	触发订单的类型,全仓止盈止损默认为market -`limit`=限价单 -`market`=市价单

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019",
    "client_order_id": "123456789"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
order_id	String	订单编号
client_order_id	String	客户端自定义id

合约修改计划委托单 (SIGNED)

适用于用户进行合约修改计划委托订单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/modify-plan-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id":"220906179559421",
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "type":"limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-plan-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
order_id	String	选填	订单id(order_id和client_order_id必须提供一个)
trigger_price	String	必填	触发价格
executive_price	String	选填	执行价格，订单 type = limit 必填
price_type	Int	必填	触发价格类型 -`1`=最新成交价 -`2`=标记价格
type	String	必填	订单类型 -`limit`=执行订单为限价单 -`market`=执行订单为市价单

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
order_id	String	订单编号

合约修改预设止盈止损单 (SIGNED)

适用于用户进行合约修改预设止盈止损单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/modify-preset-plan-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id":"220609666322019",
  "preset_take_profit_price":"2000",
  "preset_stop_loss_price":"1900",
  "preset_take_profit_price_type":1,
  "preset_stop_loss_price_type":1
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-preset-plan-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
order_id	String	必填	订单id
preset_take_profit_price_type	Int	选填	预设止盈委托价格类型 -`1`=最新成交价(默认) -`2`=标记价格
preset_stop_loss_price_type	Int	选填	预设止损委托价格类型 -`1`=最新成交价(默认) -`2`=标记价格
preset_take_profit_price	String	选填	预设止盈价格
preset_stop_loss_price	String	选填	预设止损价格

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
order_id	String	订单编号

合约修改止盈止损订单 (SIGNED)

适用于用户进行修改合约止盈止损订单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/modify-tp-sl-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "trigger_price":"2100",
  "executive_price":"2100",
  "price_type":2,
  "order_id":"37758000001",
  "client_order_id":"",
  "plan_category":2,
  "category": "limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-tp-sl-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
order_id	String	选填	订单id(order_id和client_order_id必须提供一个)
client_order_id	String	选填	客户端自定义id, 幂等控制(order_id和client_order_id必须提供一个)
trigger_price	String	必填	触发价格
executive_price	String	选填	执行价格，订单 plan_category = 1 必填
price_type	Int	必填	触发价格类型 -`1`=最新成交价 -`2`=标记价格
category	String	选填	订单类型，全仓止盈止损默认为market，部分仓位止盈止损必传 -`limit`=执行订单为限价单 -`market`=执行订单为市价单
plan_category	Int	选填	止盈止损类型 -`1`=部分仓位止盈止损 -`2`=全仓止盈止损

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
order_id	String	订单编号

合约跟踪委托下单 (SIGNED)

适用于用户进行合约跟踪委托订单下单

请求URL

POST https://api-cloud-v2.bitmart.com/contract/private/submit-trail-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "side":1,
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "activation_price":"2000",
  "callback_rate":"1",
  "activation_price_type":1
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-trail-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
side	Int	必填	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
leverage	String	必填	杠杆下单倍数
open_type	String	必填	开仓类型 -`cross`=全仓 -`isolated`=逐仓
size	Int	必填	订单数量张数
activation_price	String	必填	激活价格,跟踪委托单必填
callback_rate	String	必填	回调幅度,跟踪委托单必填,最小值为0.1,最大值为5,其中1表示1%
activation_price_type	Int	必填	激活价格类型,跟踪委托单必填 -`1`=最新成交价 -`2`=标记价格

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019,
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

字段	类型	描述
order_id	Int	订单编号

取消跟踪委托合约订单 (SIGNED)

适用于用户进行合约跟踪委托订单撤单

请求格式

POST https://api-cloud-v2.bitmart.com/contract/private/cancel-trail-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud-v2.bitmart.com/contract/private/cancel-trail-order

参数	类型	是否必填	描述
symbol	String	必填	合约交易对（如BTCUSDT）
order_id	String	选填	订单编号

响应详情

code 返回 1000 表示撤销成功。

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

子母账户

子划转到主（主账户适用）(SIGNED)

子账户的合约账户向主账户的合约账户划转（主账户适用）

请求URL

POST https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/sub-to-main

请求限制

参见速率限制详细

请求参数

请求

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"USDT",
    "subAccount":"[email protected]"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/sub-to-main`

字段	类型	是否必填	描述
requestNo	String	是	uuid或其他通用唯一标识符, 支持长度64
amount	String	是	划转数量
currency	String	是	当前仅支持`USDT`
subAccount	String	是	子账户用户名

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861960436563119",
  "data": {}
}

code 返回 1000 表示划转成功。

主划转到子（主账户适用）(SIGNED)

主账户的合约账户向子账户的合约账户划转（主账户适用）

请求URL

POST https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/main-to-sub

请求限制

参见速率限制详细

请求参数

请求

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"BTC",
    "subAccount":"[email protected]"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/main-to-sub`

字段	类型	是否必填	描述
requestNo	String	是	uuid或其他通用唯一标识符, 支持长度64
amount	String	是	划转数量
currency	String	是	当前仅支持`USDT`
subAccount	String	是	子账户用户名

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861963186213159",
  "data": {}
}

code 返回 1000 表示划转成功。

子划转到主（子账户适用）(SIGNED)

子账户的合约账户向主账户的合约账户划转（子账户适用）

请求URL

POST https://api-cloud-v2.bitmart.com/account/contract/sub-account/sub/v1/sub-to-main

请求限制

参见速率限制详细

请求参数

请求

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"USDT"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/sub/v1/sub-to-main`

字段	类型	是否必填	描述
requestNo	String	是	uuid或其他通用唯一标识符, 支持长度64
amount	String	是	划转数量
currency	String	是	当前仅支持`USDT`

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861970092723253",
  "data": {}
}

code 返回 1000 表示划转成功。

子合约余额（主账户适用）(KEYED)

获取子账户的合约钱包余额（主账户适用）

请求URL

GET https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/wallet

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/wallet?subAccount=[email protected]&currency=USDT

字段	类型	是否必填	描述
subAccount	String	是	子账户用户名
currency	String	否	币种

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "87db8cd43374470f96aacb0e3fcaf34c.77.16872314088656435",
  "data": {
    "wallet": [
      {
        "currency": "USDT",
        "name": "USDT",
        "available": "204.15216696",
        "frozen": "0.00000000"
      }
    ]
  }
}

字段	类型	描述
currency	String	币种
name	String	加密货币全称
available	String	可用余额
frozen	String	冻结额

子划转历史（主账户适用）(KEYED)

查询子账户划转历史（主账户适用）

请求URL

GET https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/transfer-list

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/transfer-list?subAccount=[email protected]&limit=10

字段	类型	是否必填	描述
subAccount	String	是	子账户用户名
limit	Int	是	最近N条记录(取值范围1-100)

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "ba950ec2bd114fd7bc069cb812b0129f.62.16887213774200649",
  "data": [
    {
      "fromAccount": "[email protected]",
      "toAccount": "[email protected]",
      "toWalletType": "future",
      "fromWalletType": "future",
      "currency": "USDT",
      "amount": "1",
      "submissionTime": 1686207254
    }
  ]
}

字段	类型	描述
fromAccount	String	转出账户
fromWalletType	String	转出钱包类型 -`future`=合约账户
toAccount	String	转入账户
toWalletType	String	转入钱包类型 -`future`=合约账户
currency	String	币种
amount	String	金额
submissionTime	Long	请求时间戳精确到秒，（UTF-0）

账户划转历史（主,子账户适用）(KEYED)

查询账户的划转历史（主账户适用）

请求URL

GET https://api-cloud-v2.bitmart.com/account/contract/sub-account/v1/transfer-history

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/v1/transfer-history?limit=10

字段	类型	是否必填	描述
limit	Int	是	最近N条记录(取值范围1-100)

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "ba950ec2bd114fd7bc069cb812b0129f.62.16887215218140681",
  "data": [
    {
      "fromAccount": "[email protected]",
      "toAccount": "[email protected]",
      "toWalletType": "future",
      "fromWalletType": "future",
      "currency": "USDT",
      "amount": "1",
      "submissionTime": 1686207254
    }
  ]
}

字段	类型	描述
fromAccount	String	转出账户
fromWalletType	String	转出钱包类型 -`future`=合约账户
toAccount	String	转入账户
toWalletType	String	转入钱包类型 -`future`=合约账户
currency	String	币种
amount	String	金额
submissionTime	Long	请求时间戳精确到秒，（UTC-0）

WebSocket订阅

概述

服务器地址

公共频道: wss://openapi-ws-v2.bitmart.com/api?protocol=1.1

私人频道: wss://openapi-ws-v2.bitmart.com/user?protocol=1.1

指令格式

客户端发送给BitMart服务器的消息格式。

{"action":"<operation>", "args":["<topic1>","<topic2>"]}

解释:

operation 请求动作, 取值:[subscribe=订阅, unsubscribe=取消订阅, login=登录]
args 请求参数，取值: 频道数组或者登录需要的参数
topic 频道主题，由<channel>:<filter>组成
- channel 是以 business/name组成
- filter 是可筛选数据，具体参考每个频道说明

示例:

示例1：{"action": "subscribe", "args": ["futures/depth50:BTCUSDT"]}
- 表示订阅表示合约交易对BTCUSDT的深度数据
示例2：{"action": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556", "web"]}
- 进行私人频道订阅之前的登录请求

成功响应格式

BitMart服务器向客户端返回成功消息的格式。

返回success字段为ture

成功响应格式

当 action=access 时：
{"action":"access","success":true}

当 action=unsubscribe 时：
{"action":"unsubscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/depth50:BTCUSDT"]}}

当 action=subscribe 时：
{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/depth50:BTCUSDT"]}}

示例:

示例1：{"action":"access","success":true}
- 表示登录成功
示例2：{"action":"unsubscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/depth50:BTCUSDT"]}}
- 表示取消合约交易对BTCUSDT的深度50订阅成功
示例3：{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/depth50:BTCUSDT"]}}
- 表示现货交易对BTCUSDT的深度50订阅成功
示例4：{"group":"futures/depth50:BTCUSDT","data":{"symbol":"BTCUSDT","way":2,"depths":[{"price":"30107.7","vol":"234"},{"price":"30107.8","vol":"1587"}]}}
- 表示现货交易对BTCUSDT的深度50订阅返回数据

失败响应格式

BitMart服务器向客户端返回失败消息的格式。

返回 success 字段为 false

失败响应格式

{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":false,"error":"authentication is temporarily unavailable"}

示例1：{"action":"subscribe","group":"futures/order","success":false,"error":"futures/order need authenication"}
- 表示您的订阅需要先登陆
示例2：{"action":"access","success":false,"error":"access failed: openapi auth: apiKey 880d5edecs**** failed: openapi auth failed"}
- 表示登录失败,您的签名不通过
示例3：{"action":"subscribe","group":"sfutures/depth50:BTCUSDT","success":false,"request":{"action":"subscribe","args":["sfutures/depth50:BTCUSDT"]},"error":"group [sfutures/depth50:BTCUSDT] not exist"}
- 表示订阅失败，您的参数是无效的，不存在这个频道

连接保持与限制

保持连接

使用Ping/Pong机制保持连接。一旦连接打开，每过N秒发送一个Ping帧，远程端点会返回一个Pong帧保持响应。这是一种保持活力的方法。它有助于保持连接的打开状态，特别是在非活动连接上存在有短超时代理的情况下。

连接上ws后如果一直没有数据返回，20s 后自动断开链接，为了保持连接有效且稳定，建议您进行以下操作：

每次接收到消息后，用户设置一个定时器，定时N秒 (N<20)。
如果定时器被触发（N 秒内没有收到新消息），发送ping帧或者发送字符串 'ping'。
等待一个文字字符串'pong'作为回应。如果在N秒内未收到，请发出错误或重新连接。
当双方有持续消息交互时，我们不会主动断开连接。

以下是发送的数据格式: (以Java伪代码示例)

标准的Ping帧

ws.send(new PingWebSocketFrame());

文本的 Ping Text

ws.send(new TextWebSocketFrame('{"action":"ping"}'));

连接限制

每个IP最多能和BitMart服务器保持500个连接

需要注意的是?

订阅更少的频道，能响应更快，建议你只订阅你想要的频道
如果发送的消息超过限制，连接会被断开连接。反复被断开连接的IP会被服务器屏蔽

空连接

5分钟内没有发送任务订阅数据的链接，将被认为是空连接，服务器会关闭此连接。

向BitMart服务器发送消息

{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}
BitMart服务器返回订阅结果, success=true 表示订阅成功

{"action":"subscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}}

取消订阅

可以取消一个或者多个频道

取消订阅消息格式

{"action": "unsubscribe", "args": ["<topic>"]}

参数说明

action 的取值是 unsubscribe
args 数组内容为订阅的主题名称topic
topic 由<channel>:<filter>组成
- 其中channel 是以 business/name组成
- filter 是可筛选数据，具体参考每个频道说明

示例

向BitMart服务器发送消息

{"action": "unsubscribe", "args": ["futures/klineBin1m:BTCUSDT"]}
BitMart服务器返回订阅结果, success=true 表示订阅成功

{"action":"unsubscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/klineBin1m:BTCUSDT"]}}

【公共】Ticker频道

获取平台全部永续合约的最新成交价、买一价、卖一价和24交易量。

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送
订阅后1秒发送一次

请求

请求

{
  "action":"subscribe",
  "args":["futures/ticker"]
}

消息格式:

{"action":"subscribe","args":["<channel>"]}

action: subscribe
channel: 此频道只支持全部交易对的ticker订阅, 如: futures/ticker, 固定值

返回

{
    "group":"futures/ticker",
    "data":{
          "symbol":"BTCUSDT",
          "volume_24":"117387.58",
          "fair_price":"146.24",
          "last_price":"146.24",
          "range":"147.17",
          "ask_price": "147.11",
          "ask_vol": "1",
          "bid_price": "142.11",
          "bid_vol": "1"
        }
}

返回data字段说明:

字段	数据类型	描述
symbol	string	合约交易对（如BTCUSDT）
last_price	string	最新价格
volume_24	string	24小时成交张数
range	string	涨跌幅
fair_price	string	合理价格
ask_price	string	卖盘一档（卖一）价格
ask_vol	string	卖盘一档（卖一）挂单张数
bid_price	string	买盘一档（买一）价格
bid_vol	string	买盘一档（买一）挂单张数

【公共】资金费率频道

返回资金费率数据

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后每分钟推送

请求

订阅请求

{
  "action":"subscribe",
  "args":["futures/fundingRate:BTCUSDT"]
}

数据请求

{ 
  "action": "request", 
  "args":["futures/fundingRate:BTCUSDT"]
}

消息格式:

{"action": "<op>", "args": ["<channel:symbol>"]}

op: subscribe=订阅,会收到一个订阅成功的消息及资金费率数据，而后会收到定时推送的资金费率数据, request=单次请求最新资金费率数据,会马上收到一个资金费率数据
channel:频道名, 如futures/fundingRate
symbol: 交易对, 如BTCUSDT

资金费率数据

{
    "data": {
        "symbol": "BTCUSDT",
        "fundingRate": "0.000098800809",
        "fundingTime": 1732525864000,
        "nextFundingRate": "0.0000947",
        "nextFundingTime": 1732550400000,
        "funding_upper_limit": "0.0375",
        "funding_lower_limit": "-0.0375",
        "ts": 1732525864601
    },
    "group": "futures/fundingRate:BTCUSDT"
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
fundingRate	String	当前资金费率
fundingTime	Long	当前资金费率时间戳(精确到毫秒)
nextFundingRate	String	下一次资金费率
nextFundingTime	Long	下一次资金费率时间戳(精确到毫秒)
funding_upper_limit	String	下一次资金费率上限
funding_lower_limit	String	下一次资金费率下限
ts	Long	数据返回时间戳(精确到毫秒)

【公共】深度频道

获取交易对的深度数据。

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/depth20:BTCUSDT@200ms"]
}

消息格式:

{"action":"subscribe","args":["<channel:symbol><@speed>"]}

channel: 频道名, 如futures/depth20
symbol: 交易对, 如BTCUSDT
speed: 更新速度, 支持100ms或200ms

请求其他频道列表

频道名	频道描述
futures/depth5	5档深度频道 (返回前五档的深度数据)
futures/depth20	20档深度频道 (返回前二十档的深度数据)
futures/depth50	50档深度频道 (返回前五十档的深度数据)

返回

{
    "group":"futures/depth20:BTCUSDT@200ms",
    "data":{
            "symbol":"BTCUSDT",
            "way":1,
            "depths":[
              {"price":"5","vol":"97"}
            ],
            "ms_t": 1542337219120
        }
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
way	Long	深度方向 -`1`=买方 -`2`=卖方
depths	List	深度数组
ms_t	Long	时间戳 (精确到毫秒)

解释说明

depths字段描述

字段	类型	描述
price	String	价格
vol	String	数量

【公共】深度全量频道

获取交易对的深度数据。

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/depthAll20:BTCUSDT@200ms"]
}

消息格式:

{"action":"subscribe","args":["<channel:symbol><@speed>"]}

channel: 频道名, 如futures/depth20
symbol: 交易对, 如BTCUSDT
speed: 更新速度, 支持100ms或200ms

请求其他频道列表

频道名	频道描述
futures/depthAll5	5档深度频道 (返回前五档的深度数据)
futures/depthAll20	20档深度频道 (返回前二十档的深度数据)
futures/depthAll50	50档深度频道 (返回前五十档的深度数据)

返回

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70294.4",
                "vol": "455"
            }
        ],
        "bids": [
            {
                "price": "70293.9",
                "vol": "1856"
            }
        ],
        "ms_t": 1730399750402
    },
    "group": "futures/depthAll20:BTCUSDT@200ms"
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
asks	List	卖方深度数组
bids	List	买方深度数组
ms_t	Long	时间戳 (精确到毫秒)

解释说明

asks bids字段描述

字段	类型	描述
price	String	价格
vol	String	数量

【公共】深度增量频道

返回深度数据, 支持维护一个本地的全量深度数据

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送

请求

订阅请求

{
  "action":"subscribe",
  "args":["futures/depthIncrease20:BTCUSDT@200ms"]
}

全量请求

{ 
  "action": "request", 
  "args":["futures/depthIncrease20:BTCUSDT@200ms"]
}

消息格式:

{"action":"subscribe","args":["<channel:symbol><@speed>"]}

op: subscribe=订阅,会收到一个订阅成功的消息及全量深度快照，而后会收到实时推送的增量深度数据, request=单次请求最新深度快照,会马上收到一个全量深度的数据
channel:频道名, 如futures/depthIncrease20
symbol: 交易对, 如BTCUSDT
speed: 更新速度, 支持100ms或200ms

请求其他频道列表

频道名	频道描述
futures/depthIncrease5	5档深度频道 (返回前五档的深度数据)
futures/depthIncrease20	20档深度频道 (返回前二十档的深度数据)
futures/depthIncrease50	50档深度频道 (返回前五十档的深度数据)

全量深度快照

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70391.6",
                "vol": "3550"
            }
        ],
        "bids": [
            {
                "price": "70391.2",
                "vol": "1335"
            }
        ],
        "ms_t": 1730400086184,
        "version": 980361,
        "type": "snapshot"
    },
    "group": "futures/depthIncrease20:BTCUSDT@200ms"
}

增量深度数据

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70395.3",
                "vol": "341"
            },
            {
                "price": "70395.4",
                "vol": "323"
            }
        ],
        "bids": [
            {
                "price": "70391.2",
                "vol": "0"
            },
            {
                "price": "70353.4",
                "vol": "11435"
            }
        ],
        "ms_t": 1730400086194,
        "version": 980362,
        "type": "update"
    },
    "group": "futures/depthIncrease20:BTCUSDT@200ms"
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
asks	List	卖方深度数组
bids	List	买方深度数组
ms_t	Long	时间戳 (精确到毫秒)
version	Long	数据版本号
type	String	数据类型 -`snapshot`=全量深度快照 -`update`=增量深度数据

解释说明

asks bids字段描述

字段	类型	描述
price	String	价格
vol	String	数量

如何正确在本地维护一个OrderBook副本:

首先Client端通过订阅请求 {"action": "subscribe", "args": ["futures/depthIncrease20:<symbol>"] }
订阅成功后会收到两种类型的消息，type=snapshot(全量)和type=update(更新)
如果收到type=snapshot类型消息，将深度快照内容全覆盖更新至本地缓存，如果没有本地缓存则创建一个。
如果收到type=update类型消息，将深度快照中的数据更新至本地缓存，更新规则如下：
- 4.1 如果收到的消息里字段version小于等于本地缓存中的version(new version<=local version)，则可以丢弃此数据。
- 4.2 如果收到的消息里字段version等于本地缓存中的version加1(new version==local version+1)，则将对应价格的数量更新到本地缓存中。
- 4.3 如果收到的消息里字段version大于本地缓存中的version加1(new version>local version+1)，请从步骤7获取最新的深度快照，覆盖本地缓存。
每一个返回的消息中的挂单量代表这个价格目前的挂单量绝对值，而不是相对变化。
如何更新本地缓存？在4.2的前提下：
- 6.1 新增操作：如果本地没有对应的价格，说明是新挂单，需要新增到缓存中。
- 6.2 修改或者移除操作：如果本地有对应的价格，说明是挂单量变化，如果挂单量是0，则直接从缓存中移除，否则只修改挂单量即可。
通过request请求{"action": "request", "args": ["futures/depthIncrease20:<symbol>"] }获得一个最新深度快照(消息里type=snapshot)，并将深度快照中的内容覆盖至本地缓存，然后继续从步骤2执行逻辑。

异常情况：
1. 因为深度快照对价格档位数量有限制，初始快照之外的价格档位并且没有数量变化的价格档位不会出现在增量深度的更新信息内。因此，即使应用来自增量深度的所有更新，这些价格档位也不会在本地 order book 中可见，所以本地的 order book 与真实的 order book 可能会有一些差异。

【公共】按Symbol的最优挂单频道

实时推送指定交易对最优挂单信息

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送
实时推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/bookticker:BTCUSDT"]
}

消息格式:

{"action":"subscribe","args":["<channel:symbol>"]}

channel: 频道名, 如futures/bookticker
symbol: 交易对, 如BTCUSDT

返回

{
    "data": {
        "symbol": "BTCUSDT",
        "best_bid_price": "97315",
        "best_bid_vol": "156",
        "best_ask_price": "97315.4",
        "best_ask_vol": "333",
        "ms_t": 1733891542244
    },
    "group": "futures/bookticker:BTCUSDT"
}

返回data字段说明:

字段	类型	描述
symbol	String	合约交易对（如`BTCUSDT`）
best_bid_price	String	买一价格
best_bid_vol	String	买一量
best_ask_price	String	卖一价格
best_ask_vol	String	卖一量
ms_t	Long	时间戳 (精确到毫秒)

【公共】最新成交频道

获取最新成交数据

推送规则

无需用户登录
订阅后有变化才推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/trade:BTCUSDT"]
}

消息格式:

{"action":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}

action: subscribe
channel: 频道名, 如futures/trade, 固定值
symbol: 交易对, 如BTCUSDT

返回

{
    "group":"futures/trade:BTCUSDT",
    "data":[{
          "trade_id":1409495322,
          "symbol":"BTCUSDT",
          "deal_price":"117387.58",
          "deal_vol":"1445",
          "created_at":"2023-02-24T07:54:11.124940968Z"
        }]
}

返回data字段说明:

字段	数据类型	描述
symbol	string	合约交易对（如BTCUSDT）
deal_price	string	最新价格
trade_id	long	成交id
deal_vol	string	成交数量
way	int	订单方向 -`1`=开多买开空卖 -`2`=开多买平多卖 -`3`=平空买开空卖 -`4`=平空买平多卖 -`5`=开空卖开多买 -`6`=开空卖平空买 -`7`=平多卖开多买 -`8`=平多卖平空买
created_at	string	成交时间

【公共】K线频道

获取交易对K线数据

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送

请求

请求

{
  "action":"subscribe",
  "args":["futures/klineBin1m:BTCUSDT"]
}

消息格式:

{"action":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}

action: subscribe
channel: 频道名, 如futures/klineBin1m
symbol: 交易对, 如BTCUSDT

请求其他频道列表

频道名	频道描述
futures/klineBin1m	1分钟K线数据频道
futures/klineBin5m	5分钟K线数据频道
futures/klineBin15m	15分钟K线数据频道
futures/klineBin30m	30分钟K线数据频道
futures/klineBin1H	1小时K线数据频道
futures/klineBin2H	2小时K线数据频道
futures/klineBin4H	4小时K线数据频道
futures/klineBin1D	1天K线数据频道
futures/klineBin1W	1周K线数据频道

返回

{
    "group":"futures/klineBin1m:BTCUSDT",
    "data":{
            "symbol":"ETHUSDT",
            "o":"146.24",
            "h":"146.24",
            "l":"146.24",
            "c":"146.24",
            "v":"146",
            "ts":1700533801
        }
}

返回data字段说明:

字段	数据类型	描述
symbol	string	合约交易对
o	string	开盘价
h	string	最高价
l	string	最低价
c	string	收盘价
v	string	成交量
ts	int64	时间戳

【私有】登录

登录订阅格式

请求格式

{"action":"access","args":["<API_KEY>","<timestamp>","<sign>","<dev>"]}

请注意下面传入的参数都是String类型

API_KEY: 为用户申请的APIKey
timestamp: 为时间戳, 单位是毫秒, 超过 60 秒后会过期
sign: 为签名, sign=CryptoJS.HmacSHA256(timestamp + "#" + your_api_memo + "#" + "bitmart.WebSocket", your_api_secret_key)
dev: 为设备, 比如web

示例

登录示例

{"action": "access", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556","web"]}

返回

{"action":"access","success":true}

假设用户申请的API的值如下所示：

当前时间：timestamp=1589267764859
申请的API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56"
申请的API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
申请的API_MEMO = "test001";

使用 Javascript 生成签名 sign: sign = CryptoJS.HmacSHA256(1589267764859 + "#" + test001 + "#" + "bitmart.WebSocket", '6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9') = 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556

使用 Shell 生成签名 sign: sign = echo -n '1589267764859#test001#bitmart.WebSocket' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9" (stdin)= 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556

最终的登录参数如下：

{"action": "access", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556", "web"]}

注意

【私有】资产频道

资产余额变动频道

推送规则

需用户登录
订阅后有变化才推送

请求

请求

{
    "action":"subscribe",
    "args":["futures/asset:USDT", "futures/asset:BTC", "futures/asset:ETH"]
}

消息格式:

{"action":"subscribe","args":["<channel:currency>","<channel:currency>"]}

action: subscribe
channel: 频道名, 如futures/asset, 固定值
currency: 币种, 如BTC, 支持订阅的资产类型有：USDT（U本位）、BTC(币本位)、ETH(币本位)

返回

{
  "group": "futures/asset:BTC",
  "data": {
    "currency": "BTC",
    "available_balance": "1000",
    "position_deposit": "1000",
    "frozen_balance": "1000"
  }
}

返回data字段说明:

字段	数据类型	描述
currency	string	币种
available_balance	string	可用金额
position_deposit	string	仓位保证金
frozen_balance	string	交易冻结金额

【私有】仓位频道

仓位变化推送频道

推送规则

需用户登录
订阅后有变化才推送

请求

请求

{
    "action":"subscribe",
    "args":["futures/position"]
}

消息格式:

{"action":"subscribe","args":["<channel>"]}

action: subscribe
channel: 频道名, 如futures/position, 固定值

返回

{
  "group": "futures/position",
  "data": [
    {
      "symbol": "BTCUSDT",
      "hold_volume": "2000",
      "position_type": 1,
      "open_type": 1,
      "frozen_volume": "0",
      "close_volume": "0",
      "hold_avg_price": "19406.2092",
      "close_avg_price": "0",
      "open_avg_price": "19406.2092",
      "liquidate_price": "15621.998406",
      "create_time": 1662692862255,
      "update_time": 1662692862255
    }
  ]
}

返回data字段说明:

字段	数据类型	描述
symbol	string	合约交易对（如 BTCUSDT）
hold_volume	string	持仓数量
position_type	int	仓位类型 -`1`=多 -`2`=空
open_type	int	开仓类型 -`1`=逐仓 -`2`=全仓
frozen_volume	string	冻结量
close_volume	string	平仓量
hold_avg_price	string	持仓均价
close_avg_price	string	平仓均价
open_avg_price	string	开仓均价
liquidate_price	string	爆仓价格
create_time	timestamp	创建时间
update_time	timestamp	更新时间

【私有】订单频道

订单频道，当订单状态，成交金额等发生变化时，会立即推送。

推送规则

需用户登录
订阅后有变化才推送

请求

请求

{
    "action":"subscribe",
    "args":["futures/order"]
}

消息格式:

{"action":"subscribe","args":["<channel>"]}

action: subscribe
channel: 频道名, 如futures/order, 固定值

返回

{
  "group": "futures/order",
  "data": [
    {
      "action": 3,
      "order": {
        "order_id": "220906179895578",
        "client_order_id": "BM1234",
        "price": "1",
        "size": "1000",
        "symbol": "BTCUSDT",
        "state": 2,
        "side": 1,
        "type": "limit",
        "leverage": "5",
        "open_type": "isolated",
        "deal_avg_price": "0",
        "deal_size": "0",
        "create_time": 1662368173000,
        "update_time": 1662368173000,
        "plan_order_id": "220901412155341",
        "last_trade": {
          "lastTradeID": 1247592391,
          "fillQty": "1",
          "fillPrice": "25667.2",
          "fee": "-0.00027",
          "feeCcy": "USDT"
        },
        "trigger_price": "-",
        "trigger_price_type": "-",
        "execution_price": "-",
        "activation_price_type": "-",
        "activation_price": "-",
        "callback_rate": "-"
      }
    }
  ]
}

返回data字段说明:

字段	数据类型	描述
action	int	操作类型 -`1`=撮合成交 -`2`=提交订单 -`3`=取消订单 -`4`=强平取消订单 -`5`=被动ADL取消订单 -`6`=部分强平 -`7`=破产委托 -`8`=被动ADL撮合成交 -`9`=主动ADL撮合成交
symbol	string	合约交易对（如BTCUSDT）
order_id	string	订单编号
client_order_id	string	用户自定义ID
side	int	订单方向 -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
type	string	订单类型 -`limit`=限价单 -`market`=市价单 -`plan_order`=计划委托单 -`trailing_order`=跟踪委托单 -`take_profit`=止盈单 -`stop_loss`=止损单
leverage	string	杠杆下单倍数
open_type	string	开仓类型 -`cross`=全仓 -`isolated`=逐仓
deal_avg_price	string	成交均价
deal_size	string	成交数量
price	string	委托价格
size	string	委托数量
state	int	订单状态 -`1`=审批中 -`2`=委托中 -`4`=已结束
create_time	long	创建时间
update_time	long	更新时间
plan_order_id	string	对应触发的计划单id
last_trade	object	当前订单的最近成交信息，若无则返回null
trigger_price	String	显示止盈止损的触发价格/计划委托的触发价格
trigger_price_type	String	显示止盈止损的触发价格类型/计划委托的触发价格类型 -`last_price` -`fair_price`
execution_price	String	显示止盈止损订单的执行价格/计划委托订单的执行价格
activation_price	String	显示跟踪委托的激活价格
activation_price_type	String	显示跟踪委托的激活价格类型 -`last_price` -`fair_price`
callback_rate	String	显示跟踪委托的回调幅度

最近成交信息字段描述：

字段	类型	描述
lastTradeID	long	最近成交的成交ID
fillQty	string	最新成交的数量
fillPrice	string	最新成交的价格
fee	string	最新成交的手续费
feeCcy	string	最新成交的手续费币种

合约代理商接口

查询返佣记录 (KEYED)

适用于API代理商查询一定时间范围内的合约反佣记录

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/affiliate/rebate-list

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/private/affiliate/rebate-list?page=1&size=10&currency=USDT

字段	类型	是否必填	描述
user_id	Long	否	查询用户ID
page	Int	是	第几页
size	Int	是	每页条数
currency	String	是	查询币种
rebate_start_time	Long	否	查询返佣开始时间戳
rebate_end_time	Long	否	查询返佣结束时间戳
register_start_time	Long	否	查询注册开始时间戳
register_end_time	Long	否	查询注册结束时间戳

响应详情

响应

{
  "total": 2,
  "btc_rebate_sum": 0,
  "size": 10,
  "usdt_rebate_sum": 448.9697507148,
  "page": 1,
  "eth_rebate_sum": 0,
  "rebate_detail_page_data": [{
    "rebate_coin": "USDT",
    "trade_user_id": 4225149,
    "total_rebate_amount": 427.1825970576,
    "user_type":1
  }, {
    "rebate_coin": "USDT",
    "trade_user_id": 4225148,
    "total_rebate_amount": 21.7871536572,
    "user_type":1
  }]
}

字段	类型	描述
btc_rebate_sum	Decimal	btc总返佣
usdt_rebate_sum	Decimal	usdt总返佣
eth_rebate_sum	Decimal	eth总返佣
rebate_detail_page_data	Object	反佣详细
rebate_coin	String	币种
trade_user_id	Long	交易用户ID
total_rebate_amount	Decimal	用户总佣金
user_type	Int	用户类型 -`0`=间接邀请用户 -`1`=直接邀请用户

查询交易记录 (KEYED)

适用于API代理商查询一定时间范围内的邀请用户合约交易记录

请求URL

GET https://api-cloud-v2.bitmart.com/contract/private/affiliate/trade-list

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud-v2.bitmart.com/contract/private/affiliate/trade-list?user_id=123456&type=1&page=1&size=10

字段	类型	是否必填	描述
user_id	Long	是	查询用户ID
type	Int	是	查询类型 -`1`=U本位 -`2`=币本位
page	Int	是	第几页
size	Int	是	每页条数
start_time	Long	否	查询开始时间戳
end_time	Long	否	查询结束时间戳

响应详情

响应

{
  "total": 60,
  "size": 10,
  "page": 1,
  "list": [{
    "leverage": 20.000000000000000000,
    "symbol": "BTCUSDT",
    "create_time": 1689933471000,
    "open_type": 2,
    "fee": 0.57162048,
    "deal_price": 29771.900000000000000000,
    "realised_profit": 0,
    "way": 1,
    "deal_vol": 32.000000000000000000,
    "select_copy_trade": 1,
    "user_type": 1,
    "user_id": 10048829,
    "category": 2
  }]
}

字段	类型	描述
user_id	Long	用户ID
user_type	Int	用户类型: -`1`=直客 -`2`=间接
create_time	Long	创建时间
symbol	string	交易对
leverage	Int	杠杠倍率
select_copy_trade	Int	类型: -`1`=跟单和 -`2`=非跟单
open_type	Int	仓位类型: -`1`=逐仓 -`2`=全仓
way	Int	开仓方向: -`1`=开多 -`2`=平空 -`3`=平多 -`4`=开空
category	Int	委托类型: -`1`=限价委托 -`2`=市价委托
deal_price	Decimal	成交均价
deal_vol	Decimal	成交量
fee	Decimal	手续费
realised_profit	Decimal	已实现盈亏

错误代码

Restful错误码

全局 HTTP 返回代码列表

HTTP	解释
404	Not Found - 找不到请求的接口
403	Forbidden - 无权限访问该资源（可能是KEY没有权限，也有可能是IP限制)
401	Unauthorized - 鉴权没通过(3个头部参数中有问题，没通过)
500	Internal Server Error - 服务器异常,BitMart服务出现问题

鉴权返回错误码

如:httpStatus:200, body:{"code": 1000, "message": "OK", "trace": "12323-3243242-34334534-4353","data":{}}

message 错误信息	code 错误码	http状态码
找不到请求的接口	30000	404
请求头 X-BM-KEY 不能为空	30001	401
请求头 X-BM-KEY 无效	30002	401
请求头 X-BM-KEY 关联的账号已经被冻结，请联系客服处理	30003	401
请求头 X-BM-SIGN 不能为空	30004	401
请求头 X-BM-SIGN 无效的签名	30005	401
请求头 X-BM-TIMESTAMP 不能为空	30006	401
请求头 X-BM-TIMESTAMP 过期（超过1分钟过期)	30007	401
请求头 X-BM-TIMESTAMP 错误的格式	30008	401
无效的ip	30010	403
请求头 X-BM-KEY 过期	30011	403
请求头 X-BM-KEY 没有访问权限	30012	403
请求过于频繁	30013	429
服务不可用	30014	503
服务维护中，功能暂不可用	30016	200
因违反限流规则，您的账号请求暂时被拒绝，请联系客服人员	30017	418
请求body需要是JSON格式	30018	503
您没有执行此操作的权限。请联系客户服务或 BD 寻求帮助	30019	200
合约V1 API已弃用。请使用合约V2 API.您可以查看历史更新记录进行升级	30030	200
此接口已经下架，您可以查看历史更新记录进行升级	30031	200

合约 API 返回错误码

如:httpStatus:400, body:{"code": 40001, "message":"out_trade_no not found", "trace":"8bynjk-nmoew-sd1221-csd-123", "data":{} }

message 错误信息	code 错误码	http状态码
请求成功	1000	200
账号不存在	40001	400
out_trade_no 订单号不存在	40002	400
out_trade_no 订单号已经存在	40003	400
账号超过限制	40004	400
划转的数量超出小数限制	40005	400
无效IP	40006	400
无效请求参数	40007	400
参数 nonce 错误	40008	400
参数 ver 错误	40009	400
没有此服务(检查API路径是否正确)	40010	400
无效参数	40011	400
系统错误	40012	400
无效请求时间	40013	400
合约已经下架	40014	400
合约已经暂停	40015	400
此命令将触发用户头寸平仓	40016	400
不可能在同一位置同时开启和关闭	40017	400
你的头寸已关闭	40018	400
你的持仓清盘委托中	40019	400
你的持仓量不够	40020	400
你的持仓不存在	40021	400
不能全仓	40022	400
该头寸将在低于保证金时平仓	40023	400
该头寸将在低于保证金时发出清算警告	40024	400
持仓保证金不应低于基本限制	40025	400
你的交叉保证金头寸正在清盘委托中	40026	400
合约账户余额不足	40027	400
下单数量超过系统最大限制	40028	400
订单设置杠杆太大	40029	400
订单设置杠杆太小	40030	400
现价与触发价之间的偏差太大	40031	400
计划订单的生命周期太长	40032	400
计划订单的生命周期太短	40033	400
交易对不存在	40034	400
订单不存在	40035	400
订单状态不支持	40036	400
订单ID不存在	40037	400
K线间隔不存在	40038	400
时间戳不合法	40039	400
杠杆倍数不合法	40040	400
订单方向不合法	40041	400
订单类型不合法	40042	400
数值精度不合法	40043	400
数值范围不合法	40044	400
开仓类型不合法	40045	400
账号未开通合约	40046	403
您所在的国家和地区不提供服务	40047	403
ClientOrderId只允许数字和字母的组合	40048	403
ClientOrderId的最大长度不能超过32位	40049	403
Client OrderId 与未完成的委托单重复	40050	403

未来计划

更新日志

2024-12-17

REST API

2024-12-12

REST API

2024-12-11

Websocket Stream

2024-12-04

REST API

2024-11-28

REST API

Websocket Order

2024-11-25

Websocket Stream

2024-11-01

Websocket Stream

2024-10-29

REST API

2024-10-24

REST API

2024-10-17

REST API

2024-10-10

REST API

2024-09-26

文档

2024-09-19

REST API

2024-07-23

介绍

API Key 申请

创建API Key后，您将获得3个必须记住的信息：

API Key 权限设置

只读权限:

提现权限:

现货交易权限:

杠杆交易权限:

合约交易权限:

子账号权限:

子账户现货权限:

子账户合约权限:

子账户账户间划转权限:

API 代码库

可用的 SDK:

常见问题答疑

问题1.同一个账户里的不同的API KEY，返回的账户信息数据，会不同吗？

问题2.申请APIKEY时如何填写?

问题3.HTTP状态码429是怎样造成的？

问题4. 使用ccxt，正确填写了API KEY，但是还会提示 'message': 'Header X-BM-SIGN is wrong'

问题5. 我自己写的程序，老是提示 'message': 'Header X-BM-SIGN is wrong'

问题6. BitMart 服务器部署在哪里？

问题7. 我申请的VIP费用什么时候生效？

问题8. 为什么提示"IP is forbidden. We recommend enabling IP whitelist for API trading. "

联系我们

基本信息

API基本信息

请求参数设置

HTTP 返回代码

API 返回内容

签名

鉴权类型

1.设置请求参数

header key设置

body参数设置

2.例子

频率限制

具体接口限制详细如下:

REST API

合约公开 API 参数

字段说明

订单状态 （字段:state)

订单方向 （字段:side)

仓位方向 （字段:position_type)

订单类型 （字段:type)

开仓类型 （字段:open_type)

下单方式 （字段:mode)

时间 timestamp

公共行情

获取所有合约详情

订单状态（字段:state)

订单方向（字段:side)

仓位方向（字段:position_type)

订单类型（字段:type)

开仓类型（字段:open_type)

下单方式（字段:mode)