未来计划

现货websocket的KeepAlive机制, 现支持客户端发送ping帧和ping文本来保持连接。未来我们将只支持ping文本，不再支持ping帧
2024-06-28 后，BitMart将停止提供以下接口：

下架接口	接口描述	替换接口
/spot/v1/submit_order	下单v1	/spot/v2/submit_order
/spot/v1/batch_orders /spot/v2/batch_orders	批量下单v1 批量下单v2	/spot/v4/batch_orders
/spot/v1/cancel_order /spot/v2/cancel_order	撤单v1 撤单v2	/spot/v3/cancel_order
/spot/v1/cancel_orders	批量撤单v1	/spot/v4/cancel_orders /spot/v4/cancel_all
/spot/v2/order_detail	查单v2	/spot/v4/query/order
/spot/v3/orders	当前委托v3	/spot/v4/query/open-orders
/spot/v2/trades	成交记录v2	/spot/v4/query/trades

2024-06-30 后，BitMart将停止提供以下接口：

下架接口	接口描述	替换接口
/spot/v1/ticker /spot/v2/ticker	获取所有交易对行情(V1) 获取所有交易对行情(V2)	/spot/quotation/v3/tickers
/spot/v1/ticker_detail	获取单一交易对行情(V1)	/spot/quotation/v3/ticker
/spot/v1/steps	获取支持的 K 线周期(V1)	固定枚举不再需要接口查询
/spot/v1/symbols/kline	获取 K 线(V1)	/spot/quotation/v3/lite-klines /spot/quotation/v3/klines
/spot/v1/symbols/book	获取深度(V1)	/spot/quotation/v3/books
/spot/v1/symbols/trades	获取最近成交记录(V1)	/spot/quotation/v3/trades

更新日志

2024-10-09

REST API

[更新] /spot/v1/user_fee 用户基础费率接口 (KEYED)
- 新增响应字段 taker_fee_rate_D
- 新增响应字段 maker_fee_rate_D

2024-08-06

REST API

[新增] /spot/v4/cancel_all 全量撤单(v4) (SIGNED)

2024-07-24

REST API

[删除] 公共行情 (历史版本) 文档目录删除
[删除] 现货 / 杠杆交易 (历史版本) 文档目录删除

2024-06-30

WebSocket Steam 用户私有频道将实施下面的限频限流规则

[更新] 用户-余额变动推送 频道限流规则
[更新] 用户-订单成交进度 频道限流规则

具体限制规则如下：

每个IP最多能和BitMart私有频道服务器保持10个连接
连接建立后，允许客户端在每个连接上订阅最多100个频道
发送速率限制：
1. 发起连接: 客户端1分钟内最多能发起30次连接BitMart服务器的请求
2. 连接成功后: 客户端发送订阅请求10秒内最多能发送100条消息, 包括：PING帧，PONG帧，PING文本，JSON格式的消息（订阅和取消订阅）
3. 连接成功后: 客户端发送单次订阅的消息数组最大上限是20个
如果用户发送的消息超过限制，连接会被断开连接。反复被断开连接的IP有可能被服务器屏蔽

2024-05-28

Websocket Stream

[更新] 用户-订单成交进度 频道
- 功能：支持发送1个订阅请求，就能订阅全部交易对的订单成交进度

2024-05-17

REST API

[新增] /spot/v4/batch_orders 批量下单(v4) (SIGNED)
[新增] /spot/v4/cancel_orders 批量撤单(v4) (SIGNED)

2024-04-23

Websocket Stream

[更新] 用户-余额变动频道
- 余额变动类型新增 BMX_DEDUCTION=BMX手续费抵扣

2024-04-03

REST API

[更新] /account/v1/withdraw/charge 提币额度查询 (KEYED)
- 新增响应字段 withdraw_Precision_GeTen

2024-03-12

REST API

[更新] /spot/v4/query/order orderId查单(v4)(SIGNED)
- 响应字段 state 新增类型值 failed

2024-03-17

REST API

[删除] /account/sub-account/sub/v1/sub-to-sub 子划转到子（子账户适用）(SIGNED)

2024-02-29

Websocket Stream

[更新] 公共-Ticket频道
- 增加订阅成功消息
- 新增响应字段ms_t
- 新增响应字段fluctuation
- 新增响应字段bid_px
- 新增响应字段bid_sz
- 新增响应字段ask_px
- 新增响应字段ask_sz
- 新增响应字段quote_volume_24h
- bug修复,响应字段base_volume_24h值错误
[更新] 公共-K线频道
- 增加订阅成功消息
- 生成k线时间改为这根K线的开盘时间
[更新] 公共-全量深度频道
- 增加订阅成功消息
[更新] 公共-增量深度频道
- 增加订阅成功消息
[更新] 公共-交易频道
- 增加订阅成功消息
- 新增响应字段ms_t
[更新] 用户-订单成交进度频道
- 增加订阅成功消息
- 新增响应字段create_time
- 新增响应字段update_time
- 新增响应字段order_mode
- 新增响应字段entrust_type
- 新增响应字段order_state
[更新] 用户-余额变动频道
- 增加订阅成功消息

2024-02-19

REST API

[更新] /account/v1/withdraw/apply 提币 (SIGNED)
- 功能：提现到交易所内注册的账户

2023-10-27

Websocket Stream

[新增] spot/depth/increase100:<symbol>【私人】深度增量推送频道
- 功能：现货深度增量推送

2023-09-08

Websocket Stream

[新增] spot/user/balance:BALANCE_UPDATE【私人】余额变动推送
- 功能：现货余额变动推送

2023-08-14

REST API

[新增] /spot/quotation/v3/tickers 获取所有交易对行情(V3)
[新增] /spot/quotation/v3/ticker 获取指定交易对行情(V3)
[新增] /spot/quotation/v3/lite-klines 获取最新K线(V3)
[新增] /spot/quotation/v3/klines 获取历史K线(V3)
[新增] /spot/quotation/v3/books 获取深度(V3)
[新增] /spot/quotation/v3/trades 获取最近成交记录(V3)

2023-05-09

REST API

[新增] /spot/v4/query/order orderId查单 (v4)
[新增] /spot/v4/query/client-order clientOrderId查单 (v4)
[新增] /spot/v4/query/open-orders 当前委托 (v4)
[新增] /spot/v4/query/history-orders 历史委托 (v4)
[新增] /spot/v4/query/trades 成交记录 (v4)
[新增] /spot/v4/query/order-trades 单笔成交记录 (v4)

2023-03-03

REST API

[更新] /spot/v4/query/order-trades 资金账户接口
- 新增响应字段 taker_fee_rate_C、maker_fee_rate_C

2022-12-22

更新现货交易接口
- WebSocket订阅-【私人】订单成交进度添加了订单成交进度状态 12 = 部分成交后撤销

2022-11-03

更新现货交易接口
- /spot/v3/orders /spot/v2/trades添加了开始、结束时间字段用于更灵活的范围查询
- 添加了新增订单状态 11 = 部分成交后退还剩余

2022-11-01

更新账户接口
- /account/v1/currencies新增返回字段 contract_address、withdraw_minsize、withdraw_minfee

2022-10-11

新增现货行情接口
- /spot/v2/ticker
- /spot/v1/ticker_detail

2022-09-29

新增现货交易接口
- /spot/v2/submit_order
- /spot/v2/batch_orders
- /spot/v3/cancel_order
- /spot/v2/order_detail
- /spot/v3/orders
- /spot/v2/trades

2022-08-16

新增交易手续费查询接口
- /spot/v1/trade_fee
新增基础手续费查询接口
- /spot/v1/user_fee

2022-07-07

新增杠杆借贷还款相关接口
- /spot/v1/margin/isolated/borrow
- /spot/v1/margin/isolated/repay
- /spot/v1/margin/isolated/borrow_record
- /spot/v1/margin/isolated/repay_record
- /spot/v1/margin/isolated/pairs
新增杠杆交易下单接口
- /spot/v1/margin/submit_order
新增杠杆账户相关接口
- /spot/v1/margin/isolated/account
- /spot/v1/margin/isolated/transfer
更新现货 / 杠杆交易接口
- 以下接口新增了“order_mode”字段用于区分订单来源是现货订单还是杠杆交易订单
- /spot/v1/order_detail
- /spot/v2/orders
- /spot/v1/trades

2022-05-24

更新现货接口
- /spot/v2/orders新增返回字段clientOrderId
- /spot/v1/trades新增返回字段clientOrderId
- /spot/v1/order_detail新增返回字段clientOrderId

2022-04-19

新增子账户接口
- /sub-account/main/v1/sub-to-main
- /sub-account/sub/v1/sub-to-main
- /sub-account/main/v1/main-to-sub
- /sub-account/sub/v1/sub-to-sub
- /sub-account/main/v1/sub-to-sub
- /sub-account/main/v1/transfer-list
- /sub-account/v1/transfer-history
- /sub-account/main/v1/wallet
- /sub-account/main/v1/subaccount-list
更新WebSocket成交进度频道
- 新增返回字段client_order_id
- 新增返回字段detail_id

2022-03-29

WebSocket订阅，【私人】订单频道更名为【私人】订单成交进度
【私人】订单成交进度频道新增返回参数exec_type，表示流动性类型

2022-03-08

Websocket连接保持机制完善
目录层级修缮，增强可读性

2022-03-01

支持用户通过自定义OrderId下单、查单、撤单

2022-02-15

根据用户反馈提高了限流频率上限制
文档UI优化调整

2022-01-20

更新现货接口
- /spot/v1/symbols/details增加返回字段trade_status，用来区分交易对状态

2022-01-18

websocket公共频道访问地址wss://ws-manager-compress.bitmart.com?protocol=1.1将于UTC时间 2022-02-28 日下架，新地址为wss://ws-manager-compress.bitmart.com/api?protocol=1.1

2021-11-24

新增现货接口
- /spot/v2/orders获取用户最近订单记录V2
- /spot/v1/batch_orders批量下单
更新现货接口
- /spot/v1/symbols/kline新增返回字段 quote_volume 成交额
- /spot/v1/symbols/trades新增可选参数 N 返回条数，默认最大50条
- /spot/v1/order_detail返回字段增加未成交数量
- /spot/v1/submit_order请求参数type新增limit_maker和ioc订单类型
新增资金账户接口
- /account/v2/deposit-withdraw/history查询冲提记录v2
更新资金账户接口
- /account/v1/wallet去掉账户类型，只响应币币账户；可以带币种参数(可选)

2021-11-06

更新现货WebSocket接口
- 深度频道:
- spot/depth50 50档深度频道 (返回前五十档的深度数据)
- spot/depth100 100档深度频道 (返回前一百档的深度数据)
- 用户-交易频道:
- 符合条件的推送新增下单成功

2021-01-19

新增现货WebSocket接口
- 公共-Ticket频道
- 公共-K线频道
- 公共-交易频道
- 公共-深度频道
- 登录
- 用户-交易频道

2020-07-15

新增现货接口
- /spot/v2/cancel_order现货取消订单接口，第2版

2020-06-29

新增资金账户接口
- /account/v1/currencies获取资产币种
- /account/v1/wallet查询账户资产
- /account/v1/deposit/address查询充币地址
- /account/v1/withdraw/charge查询提币额度
- /account/v1/withdraw/apply提币
- /account/v1/recharge-withdraw/history查询充提历史记录
- /account/v1/recharge-withdraw/detail查询单条充提记录

2020-05-14

新增现货接口
- /spot/v1/currencies获取平台所有的加密货币列表
- /spot/v1/symbols获取平台所有的交易对列表
- /spot/v1/symbols/details获取平台所有交易对的详情列表
- /spot/v1/tickerTicker 是交易对市场状态的概览，包含最新成交价、买一价、卖一价和 24 小时交易量的快照信息
- /spot/v1/steps获取平台支持的全部 k 线周期，用分钟表示，最小 1 分钟
- /spot/v1/symbols/kline获取指定交易对的指定时间范围内的 k 线数据
- /spot/v1/symbols/book获取交易对完整的深度
- /spot/v1/symbols/trades获取指定交易对的最近成交记录
- /spot/v1/wallet获取用户所有币种钱包余额
- /spot/v1/submit_order委托下单
- /spot/v1/cancel_order取消一个未完成的订单
- /spot/v1/cancel_orders取消指定交易对指定方向的所有未完成的订单
- /spot/v1/order_detail获取订单详情
- /spot/v1/orders查询用户最近订单
- /spot/v1/trades用户成交历史

介绍

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/v1/order_detail	查询订单详情	KEYED
/spot/v2/order_detail	查询订单详情	KEYED
/spot/v1/orders	查询用户最近订单	KEYED
/spot/v2/orders	查询用户最近订单	KEYED
/spot/v3/orders	查询用户最近订单	KEYED
/spot/v1/trades	查询用户成交历史	KEYED
/spot/v2/trades	查询用户成交历史	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/order	查询合约订单详情	KEYED
/contract/private/order-history	查询合约历史订单	KEYED
/contract/private/trades	查询合约成交明细	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

子账号权限:

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

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.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状态：请求太频繁。

具体接口限制详细如下:

系统接口	接口名称	限制目标	速率
/system/time	获取系统时间	IP	10次/秒
/system/service	获取系统服务状态	IP	10次/秒

资金账户接口	接口名称	限制目标	速率
/account/v1/currencies	获取资产币种	IP	2次/2秒
/account/v1/wallet	查询账户资产	X-BM-KEY	12次/2秒
/account/v1/deposit/address	查询充币地址	X-BM-KEY	2次/2秒
/account/v1/withdraw/charge	查询提币额度	X-BM-KEY	2次/2秒
/account/v1/withdraw/apply	提币	X-BM-KEY	8次/2秒
/account/v2/deposit-withdraw/history	查询充提历史记录V2	X-BM-KEY	8次/2秒
/account/v1/deposit-withdraw/detail	查询单个充提记录	X-BM-KEY	8次/2秒
/spot/v1/margin/isolated/account	查询逐仓账户信息	X-BM-KEY	12次/2秒
/spot/v1/margin/isolated/transfer	杠杆资金划转	X-BM-KEY	2次/2秒
/spot/v1/user_fee	用户基础费率接口	X-BM-KEY	2次/2秒
/spot/v1/trade_fee	用户交易费率接口	X-BM-KEY	2次/2秒

现货行情接口	接口名称	限制目标	速率
/spot/v1/currencies	获取平台所有的加密货币列表	IP	8次/2秒
/spot/v1/symbols	获取平台所有的交易对列表	IP	8次/2秒
/spot/v1/symbols/details	获取平台所有交易对的详情列表	IP	12次/2秒
/spot/quotation/v3/tickers	获取所有交易对行情(V3)	IP	10次/2秒
/spot/quotation/v3/ticker	获取指定交易对行情(V3)	IP	15次/2秒
/spot/quotation/v3/lite-klines	获取最新K线(V3)	IP	15次/2秒
/spot/quotation/v3/klines	获取历史K线(V3)	IP	10次/2秒
/spot/quotation/v3/books	获取深度(V3)	IP	15次/2秒
/spot/quotation/v3/trades	获取最近成交记录(V3)	IP	15次/2秒

现货接口	接口名称	限制目标	速率
/spot/v1/wallet	获取用户所有币种钱包余额(KEYED)	X-BM-KEY	12次/2秒
/spot/v2/submit_order	现货下单(v2)(SIGNED)	UID	100次/2秒
/spot/v4/batch_orders	批量下单(v4)(SIGNED)	UID	30次/2秒
/spot/v1/margin/submit_order	杠杆下单(SIGNED)	X-BM-KEY	1次/1秒
/spot/v3/cancel_order	撤销指定订单(V3)(SIGNED)	UID	150次/2秒
/spot/v4/cancel_orders	撤销批量订单(v4)(SIGNED)	UID	40次/2秒
/spot/v4/cancel_all	撤销所有订单(v4)(SIGNED)	UID	1次/3秒
/spot/v4/query/order	orderId查单(v4)(SIGNED)	X-BM-KEY	50次/2秒
/spot/v4/query/client-order	clientOrderId查单(v4)(SIGNED)	X-BM-KEY	50次/2秒
/spot/v4/query/open-orders	当前委托(v4)(SIGNED)	X-BM-KEY	12次/2秒
/spot/v4/query/history-orders	历史委托(v4)(SIGNED)	X-BM-KEY	12次/2秒
/spot/v4/query/trades	成交记录(v4)(SIGNED)	X-BM-KEY	12次/2秒
/spot/v4/query/order-trades	单笔成交记录(v4)(SIGNED)	X-BM-KEY	12次/2秒

子母账户接口	接口名称	限制目标	速率
/account/sub-account/main/v1/sub-to-main	子账户向主账户划转（主账户适用）	X-BM-KEY	2次/2秒
/account/sub-account/sub/v1/sub-to-main	子账户向主账户划转（子账户适用）	X-BM-KEY	2次/2秒
/account/sub-account/main/v1/main-to-sub	主账户向子账户划转（主账户适用）	X-BM-KEY	2次/2秒
/account/sub-account/sub/v1/sub-to-sub	子账户向统一体系下的子账户划转（子账户适用）	X-BM-KEY	2次/2秒
/account/sub-account/main/v1/sub-to-sub	子账户向子账户划转（主账户适用）	X-BM-KEY	2次/2秒
/account/sub-account/main/v1/transfer-list	查询子账户划转历史（主账户适用）	X-BM-KEY	8次/2秒
/account/sub-account/v1/transfer-history	查询账户划转历史	X-BM-KEY	8次/2秒
/account/sub-account/main/v1/wallet	获取子账户现货钱包余额（主账户适用）	X-BM-KEY	12次/2秒
/account/sub-account/main/v1/subaccount-list	查询子账户列表（主账户适用）	X-BM-KEY	8次/2秒

杠杆借还款接口	接口名称	限制目标	速率
/spot/v1/margin/isolated/borrow	逐仓借款	X-BM-KEY	2次/2秒
/spot/v1/margin/isolated/repay	逐仓还款	X-BM-KEY	2次/2秒
/spot/v1/margin/isolated/borrow_record	查询逐仓借款订单	X-BM-KEY	60次/2秒
/spot/v1/margin/isolated/repay_record	查询逐仓还款订单	X-BM-KEY	60次/2秒
/spot/v1/margin/isolated/pairs	查询交易对借款利率与额度	X-BM-KEY	2次/2秒

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	当前时间窗口,秒为单位

标准规范关于 recvWindow, timestamp

当前仅仅适用于 v4 接口

时间同步安全

签名接口都需要传递timestamp参数，其值应当是请求发送时刻的unix时间戳(毫秒)，设置在请求头X-BM-TIMESTAMP中。服务器收到请求时会判断请求中的时间戳，如果是5000毫秒之前发出的，则请求会被认为无效。这个时间空窗值可以通过发送可选参数 recvWindow来定义。

逻辑伪代码如下:

  if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow)
  {
    // process request
  } 
  else 
  {
    // reject request
  }

关于交易时效性

互联网状况并不完全稳定可靠,因此你的程序本地到BitMart服务器的时延会有抖动。这是我们设置recvWindow的目的所在，如果你从事高频交易，对交易时效性有较高的要求，可以灵活设置recvWindow以达到你的要求。

公开 API 参数

字段说明

currency 币种是指能够转入转出的基本单位，如BTC,ETH,EOS等
symbol 交易对名称, 由交易货币和计价货币组成。以BTC_USDT 为例，BTC 为交易货币，USDT 为计价货币，交易对主要在现货交易使用
orderId 订单编号，每个业务线的同一币对下的订单ID是唯一的
tradeId 成交的唯一编号

订单状态（字段:state)

new=未成交。系统已接受订单委托
partially_filled=部分成交。订单还在委托中，已经有一部分成交
filled=完全成交。订单已完成交易
canceled=完全撤销。订单未完成交易，已经撤销
partially_canceled=部分成交已撤销。订单已经撤销，但是其中有一部分已经成交，剩余的部分已撤销

订单方向（字段:side)

buy=买入
sell=卖出

订单类型（字段:type)

limit=现价单
market=市价单
limit_maker=PostOnly单
ioc=IOC单

交易角色（字段:tradeRole)

taker=吃单,主动成交
maker=挂单,被动成交

时间 timestamp

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

系统状态

获取系统时间

获取系统时间

请求URL

GET https://api-cloud.bitmart.com/system/time

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/system/time

无

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "server_time": 1527777538000
  }
}

字段	类型	描述
server_time	Long	当前系统时间(时间戳，精确到毫秒)

获取系统服务状态

获取系统服务状态

请求URL

GET https://api-cloud.bitmart.com/system/service

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/system/service

无

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "service":[
      {
         "title": "Spot API Stop",
         "service_type": "spot",
         "status": "2",
         "start_time": 1527777538000,
         "end_time": 1527777538000
     },
     {
        "title": "Contract API Stop",
        "service_type": "contract",
        "status": "2",
        "start_time": 1527777538000,
        "end_time": 1527777538000
    }
   ]
  }
}

字段	类型	描述
title	String	系统维护说明的标题
status	Long	系统维护的状态 - `0`=等待中 - `1`=进行中 - `2`=已完成
service_type	String	服务类型 - `spot`=现货API服务 - `contract`=合约API服务 - `account`=资产API服务
start_time	Long	系统维护的开始时间,UTC-0,时间戳精确到毫秒
end_time	Long	系统维护的结束时间,UTC-0,时间戳精确到毫秒

公共行情

获取币种列表(V1)

获取平台所有的加密货币列表

请求URL

GET https://api-cloud.bitmart.com/spot/v1/currencies

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/v1/currencies

无

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "currencies": [
      {
        "id": "BTC",
        "name": "Bitcoin",
        "withdraw_enabled": true,
        "deposit_enabled": true
      },
      {
        "id": "ETH",
        "name": "Ethereum",
        "withdraw_enabled": true,
        "deposit_enabled": true
      }
    ]
  }
}

字段	类型	描述
id	String	币种简称，如 `BTC`
name	String	币种全称，如 `Bitcoin`
withdraw_enabled	Boolean	此币种是否可在平台上提现 -`true`=可提现 -`false`=不可以
deposit_enabled	Boolean	此币种是否可在平台上充值 -`true`=可充值 -`false`=不可以

获取交易对列表(V1)

获取平台所有的交易对列表

请求URL

GET https://api-cloud.bitmart.com/spot/v1/symbols

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/v1/symbols

无

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "symbols": [
       "BMX_ETH",
       "XLM_ETH",
       "MOBI_ETH",
       ...
    ]
  }
}

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

获取交易对详情(V1)

获取平台所有交易对的详情列表

请求URL

GET https://api-cloud.bitmart.com/spot/v1/symbols/details

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/v1/symbols/details

无

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "symbols": [
        {
            "symbol":"GXC_BTC",
             "symbol_id":1024,
             "base_currency":"GXC",
             "quote_currency":"BTC",
             "quote_increment":"1.00000000",
             "base_min_size":"1.00000000",
             "price_min_precision":6,
             "price_max_precision":8,
             "expiration":"NA",
             "min_buy_amount":"0.00010000",
             "min_sell_amount":"0.00010000",
             "trade_status":"trading"
        },
        ...
    ]
  }
}

字段	类型	描述
symbols	List	交易对详情数组
symbol	String	交易对
symbol_id	Int	交易对 id
base_currency	String	交易货币币种
quote_currency	String	计价货币币种
quote_increment	String	最小下单量，也是最小下单量增量
base_min_size	String	最小下单数量
price_min_precision	Number	最小价格精度(小数位) 用来查询 k 线和深度
price_max_precision	Number	最大价格精度(小数位) 用来查询 k 线和深度
expiration	String	交易对的过期时间
min_buy_amount	String	最小下单金额
min_sell_amount	String	最小卖出金额
trade_status	String	状态 -`trading`=交易中 -`pre-trade`=预开盘

获取所有交易对行情(V3)

获取所有24小时内成交量大于0的交易对行情。行情数据包含: 最新成交价、买一价、卖一价和 24 小时交易量的快照信息等。注意接口不是实时数据，如果需要实时，请使用websocket订阅Ticker频道

请求URL

GET https://api-cloud.bitmart.com/spot/quotation/v3/tickers

请求限制

参见速率限制详细

请求参数

无

请求

curl https://api-cloud.bitmart.com/spot/quotation/v3/tickers

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": [
    [
      "BTC_USDT",  // symbol
      "30000.00",  // last
      "582.08066", // v_24h
      "4793098.48", // qv_24h
      "28596.30", // open_24h
      "31012.44", // high_24h
      "12.44", // low_24h
      "0.04909", // fluctuation
      "30000", // bid_px
      "1",  // bid_sz
      "31012.44",  // ask_px
      "69994.75267", // ask_sz
      "1691671091933" // ts
    ],
    [
      "ETH_USDT",
      "1840.00",
      "2.00000",
      "3680.00",
      "1842.18",
      "1842.18",
      "1840.00",
      "-0.00118",
      "1812.35",
      "4.61989",
      "1859.34",
      "4.07793",
      "1691671094213"
    ]
  ]
}

字段	类型	描述
symbol	String	交易对
last	String	最新成交价
v_24h	String	24小时成交量，按交易货币统计
qv_24h	String	24小时成交量，按计价货币统计
open_24h	String	24小时开盘价
high_24h	String	24小时最高价
low_24h	String	24小时最低价
fluctuation	String	24小时涨幅
bid_px	String	买一价
bid_sz	String	买一价挂单量
ask_px	String	卖一价
ask_sz	String	卖一价挂单量
ts	String	数据产生时间(时间戳, 精确到毫秒)

获取指定交易对行情(V3)

适用于查询某个交易对的聚合行情, 返回最新ticker信息。注意接口不是实时数据，如果需要实时，请使用websocket订阅Ticker频道

请求URL

GET https://api-cloud.bitmart.com/spot/quotation/v3/ticker

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/quotation/v3/ticker?symbol=BTC_USDT

参数	类型	是否必填	描述
symbol	String	必填	交易对, 如 `BTC_USDT`

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": {
    "symbol": "BTC_USDT",
    "last": "30000.00",
    "v_24h": "582.08066",
    "qv_24h": "4793098.48",
    "open_24h": "28596.30",
    "high_24h": "31012.44",
    "low_24h": "12.44",
    "fluctuation": "0.04909",
    "bid_px": "30000",
    "bid_sz": "1",
    "ask_px": "31012.44",
    "ask_sz": "69994.75267",
    "ts": "1691671061919"
  }
}

字段	类型	描述
symbol	String	交易对
last	String	最新成交价
v_24h	String	24小时成交量，按交易货币统计
qv_24h	String	24小时成交量，按计价货币统计
open_24h	String	24小时开盘价
high_24h	String	24小时最高价
low_24h	String	24小时最低价
fluctuation	String	24小时涨幅
bid_px	String	买一价
bid_sz	String	买一价挂单量
ask_px	String	卖一价
ask_sz	String	卖一价挂单量
ts	String	数据产生时间(时间戳, 精确到毫秒)

获取最新K线(V3)

查询最新的K线，最大返回1000条数据，注意接口的最近一根K线不是实时数据，如果要实时数据，请使用websocket订阅Kline频道

请求URL

GET https://api-cloud.bitmart.com/spot/quotation/v3/lite-klines

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/quotation/v3/lite-klines?symbol=BMX_ETH&step=15&limit=10

参数	类型	是否必填	描述
symbol	String	必填	交易对, 如 `BTC_USDT`
before	Long	否	查询时间戳（单位：秒, 如：1525760116），查询该时间点之前的数据
after	Long	否	查询时间戳（单位：秒, 如：1525769116），查询该时间点之后的数据
step	Long	可选	k 线步长, 取值`[1, 3, 5, 15, 30, 45, 60,` `120, 180, 240, 1440, 10080, 43200]`单位：分钟，不填写默认1分钟
limit	Long	否	返回数量，最大值200，默认100

响应详情

响应

{
  "code":1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data":[
    [
      "1689736680",  // t
      "3.721",  // o
      "3.743",  // h
      "3.677",  // l
      "3.708",  // c
      "22698348.04828491",  // v
      "12698348.04828491"  // qv
    ],
    [
      "1689736620",
      "3.731",
      "3.799",
      "3.494",
      "3.72",
      "67632347.24399722",
      "37632347.24399722"
    ]
  ]
}

字段	类型	描述
t	String	K线开盘时间(时间戳，精确到秒), 可以当作K线的唯一标识
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
v	String	成交量（按交易币算）
qv	String	成交额（按计价币算）

获取历史K线(V3)

获取指定交易对的指定时间范围内的 k 线数据。

请求URL

GET https://api-cloud.bitmart.com/spot/quotation/v3/klines

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/quotation/v3/klines?symbol=BMX_ETH&step=15&limit=10

参数	类型	是否必填	描述
symbol	String	必填	交易对, 如 `BTC_USDT`
before	Long	否	查询时间戳（单位：秒, 如：1525760116），查询该时间点之前的数据
after	Long	否	查询时间戳（单位：秒, 如：1525769116），查询该时间点之后的数据
step	Int	可选	k 线步长, 取值`[1, 3, 5, 15, 30, 45, 60,` `120, 180, 240, 1440, 10080, 43200]`单位：分钟，默认1
limit	Int	否	返回数量，最大值200，默认100

响应详情

响应

{
  "code":1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data":[
    [
      "1689736680",  // t
      "3.721",  // o
      "3.743",  // h
      "3.677",  // l
      "3.708",  // c
      "22698348.04828491",  // v
      "12698348.04828491"  // qv
    ],
    [
      "1689736620",
      "3.731",
      "3.799",
      "3.494",
      "3.72",
      "67632347.24399722",
      "37632347.24399722"
    ]
  ]
}

字段	类型	描述
t	String	K线开盘时间(时间戳，精确到秒), 可以当作K线的唯一标识
o	String	开盘价格
h	String	最高价格
l	String	最低价格
c	String	收盘价格
v	String	成交量（按交易币算, 如：BTC_USDT, 单位是BTC)
qv	String	成交额（按计价币算，如：BTC_USDT, 单位是USDT)

获取深度(V3)

获取交易对完整的深度。注意接口不是实时数据，如果需要实时，请使用websocket订阅Depth频道

请求URL

GET https://api-cloud.bitmart.com/spot/quotation/v3/books

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/quotation/v3/books?symbol=BMX_ETH&limit=50

参数	类型	是否必填	描述
symbol	String	必填	交易对, 如 `BTC_USDT`
limit	Int	可选	深度档位数量，最大值可传50，即买卖深度共100条. 不填写此参数，默认返回35档深度数据

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": {
    "ts": "1691672864874",
    "symbol": "BTC_USDT",
    "asks": [
      [
        "31012.44",  // price
        "69994.75267"  // amount
      ]
    ],
    "bids": [
      [
        "30000.00", // price
        "1.00000"  // amount
      ]
    ]
  }
}

字段	类型	描述
ts	String	深度产生时间(时间戳，精确到毫秒)
symbol	String	交易对
asks	List[]	卖方深度列表
bids	List[]	买方深度列表
amount	String	挂单数量
price	String	价格

获取最近成交记录(V3)

获取指定交易对的最近成交记录。注意接口不是实时数据，如果需要实时，请使用websocket订阅Trade频道

请求URL

GET https://api-cloud.bitmart.com/spot/quotation/v3/trades

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/spot/quotation/v3/trades?symbol=BMX_ETH&limit=10

参数	类型	是否必填	描述
symbol	String	必填	交易对, 如 `BTC_USDT`
limit	Int	可选	返回条数,取值[1,50],最大50条, 默认50

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": [
    [
      "BMX_ETH", // symbol
      "1691743270994", // ts
      "1.00000000", // price
      "1.0", // size
      "sell" // side
    ]
  ]
}

字段	类型	描述
symbol	String	交易对名称
ts	String	成交时间 (时间戳，精确到毫秒)
price	String	成交价格
size	String	成交数量
side	String	成交方向 - `buy` - `sell`

资金账户

查询总账户资金 (KEYED)

查询账户资产

请求格式

GET https://api-cloud.bitmart.com/account/v1/wallet

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/wallet?currency=USDT

字段	类型	是否必填	描述
currency	String	否	币种,如：`BTC`

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"ef834248-51d3-4223-9481-f862aa9dd39f",
    "data":{
        "wallet":[
            {
                "currency":"USDT",
                "name":"Tether USD",
                "available":"1000.00000000",
                "frozen":"0.00000000"
            }
        ]
    }
}

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

获取资产币种详情

获取资产币种,用于充提

请求URL

GET https://api-cloud.bitmart.com/account/v1/currencies

请求限制

参见速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/account/v1/currencies

无

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "currencies": [
      {
        "currency": "USDT",
        "name": "Tether USD",
        "contract_address": null,
        "network": "OMNI",
        "withdraw_enabled": false,
        "deposit_enabled": false,
        "withdraw_minsize": null,
        "withdraw_minfee": null
      },
      {
        "currency": "USDT-TRC20",
        "name": "USDT-TRC20",
        "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "network": "TRC20",
        "withdraw_enabled": true,
        "deposit_enabled": true,
        "withdraw_minsize": "10",
        "withdraw_minfee": "1"
      },
      {
        "currency": "USDT-ERC20",
        "name": "USDT-ERC20",
        "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "network": "ERC20",
        "withdraw_enabled": true,
        "deposit_enabled": true,
        "withdraw_minsize": "26",
        "withdraw_minfee": "13"
      }
    ]
  }
}

字段	类型	描述
currency	String	币种，如 `BTC`
name	String	币种全称，如 `Bitcoin`
contract_address	String	合约地址
network	String	提币网络，如 `ERC20`
withdraw_enabled	Boolean	此币种是否可在平台上提现 -`true`=可提现 -`false`=不可以提现
deposit_enabled	Boolean	此币种是否可在平台上充值 -`true`=可充值 -`false`=不可以充值
withdraw_minsize	String	最小提币数量
withdraw_minfee	String	提现手续费下限

获取现货账户余额 (KEYED)

获取用户所有币种钱包余额

请求URL

GET https://api-cloud.bitmart.com/spot/v1/wallet

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}' 
https://api-cloud.bitmart.com/spot/v1/wallet

无

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "wallet": [
         {
              "id": "BTC",
              "available": "10.000000",
              "name": "Bitcoin",
              "frozen": "10.000000",
          },
          ...
    ]
  }
}

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

查询充值地址 (KEYED)

查询各个币种的充值地址

请求URL

GET https://api-cloud.bitmart.com/account/v1/deposit/address

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/deposit/address?currency=USDT-TRC20

字段	类型	是否必填	描述
currency	String	必填	币种，如 `BTC`

解释说明

PNG

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"0e6edd79-f77f-4251-abe5-83ba75d06c1a",
    "data":{
        "currency":"USDT-TRC20",
        "chain":"USDT-TRC20",
        "address":"TGR3ghy2b5VLbyAYrmiE15jasR6aPHTvC5",
        "address_memo":""
    }
}

字段	类型	描述
currency	String	币种
chain	String	链名称
address	String	充值地址
address_memo	String	标签(tag/payment_id/memo); 部分币种提币需要则返回数据，若不需要则返回空字符串；

充值忘记填写memo或者填错怎么办?

提币额度查询 (KEYED)

查询提币额度

请求URL

GET https://api-cloud.bitmart.com/account/v1/withdraw/charge

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}' 
https://api-cloud.bitmart.com/account/v1/withdraw/charge?currency=BTC

字段	类型	是否必填	描述
currency	String	必填	币种，如: `BTC`

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"62a80bde-0cb4-4bf1-b8e5-5ad2c71463e7",
    "data":{
        "today_available_withdraw_BTC":"100.0000",
        "min_withdraw":"0.00000000",
        "withdraw_precision":8,
        "withdraw_fee":"0.00000000",
        "withdraw_Precision_GeTen": 10
    }
}

字段	类型	描述
today_available_withdraw_BTC	String	今日可提现额度,单位: BTC
min_withdraw	String	最小可提币数量
withdraw_precision	Int	提现金额需要精确到小数点后几位
withdraw_fee	String	提币手续费
withdraw_Precision_GeTen	Long	提现金额必须是这个值的整数倍, 如果是null则表示没有这个要求

提币 (SIGNED)

创建从现货账户到外部地址的提现请求

API只能提币到免认证地址，通过 WEB/APP 可以设置免认证地址

请求格式

POST https://api-cloud.bitmart.com/account/v1/withdraw/apply

请求限制

参见速率限制详细

请求参数

字段	类型	是否必填	描述
currency	String	必填	币种，如: `BTC`
amount	String	必填	申请金额

提现到区块链上

请求示例：提现到区块链上

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}'
 -X POST -d '{
    "currency": "USDT-TRC20",
    "amount": "100.000",
    "destination": "To Digital Address",
    "address": "0x1EE6FA5A3803608fc22a1f3F76********",
    "address_memo": ""
}'
https://api-cloud.bitmart.com/account/v1/withdraw/apply

字段	类型	是否必填	描述
address	String	是	提现地址(仅支持在官网上添加过的地址)
address_memo	String	是	地址标签(tag/payment_id/memo统一填这里)
destination	String	否	备注

提现到BitMart账户

请求示例：提现到BitMart账户

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}'
 -X POST -d '{
    "currency": "USDT-TRC20",
    "amount": "100.000",
    "type": 1,
    "value": "876940329",
    "areaCode": ""
}'
https://api-cloud.bitmart.com/account/v1/withdraw/apply

字段	类型	是否必填	描述
type	Int	是	账号类型 `1`=CID `2`=邮箱 `3`手机号
value	String	是	账号
areaCode	String	是	手机区号，type是手机号时传

请求参数说明

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "withdraw_id": "121212"
  }
}

字段	类型	描述
withdraw_id	String	提币ID

说明

1. 返回 withdraw_id 时，说明提现请求成功发送。

2. 你使用查询充提记录接口查看到本次提现的tx_id, 用它来查询区块链上的提现进度。

3. 如果你遇到错误， message=This address is not verified. Please add and verify this address on the client
则需要将地址按照下面的3个步骤添加到白名单地址中。

步骤一、在网页或APP，登录账号后，进入提现页面

步骤二、点击【添加提现地址】

PNG

步骤三、在提现地址管理页面，保存提现地址为【已认证地址】，支持API提现

PNG PNG

4. 地址类型：

1. 普通地址：可提现至指定币种、指定网络的地址
2. 通用地址：可提现至指定网络上所有币种的地址
3. EVM地址：可提现至EVM类型网络币种的地址

5. 已认证地址：

1. 在保存地址时，可以提前认证以跳过提现时的认证（已认证的地址，将不需要在提现时再次进行认证）
2. API提现必须使用已认证的地址，未认证的地址无法通过API进行提现

查询充提记录 (KEYED)

原 /account/v1/deposit-withdraw/history 接口，老接口将不再进行支持，请尽快切换至新接口

查询充提记录

请求URL

GET https://api-cloud.bitmart.com/account/v2/deposit-withdraw/history

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v2/deposit-withdraw/history?N=100&operation_type=withdraw

字段	类型	是否必填	描述
currency	String	可选	币种，如 `BTC`
operation_type	String	必填	类型 -`deposit`=充值 -`withdraw`=提现
N	Int	必填	最近N条记录(取值范围1-100)

响应详情

响应

{
  "message":"OK",
  "code":1000,
  "trace":"142bf92a-fc50-4689-92b6-590886f90b97",
  "data":{
    "records":[
      {
        "withdraw_id":"1679952",
        "deposit_id":"",
        "operation_type":"withdraw",
        "currency":"BMX",
        "apply_time":1588867374000,
        "arrival_amount":"59.000000000000",
        "fee":"1.000000000000",
        "status":0,
        "address":"0xe57b69a8776b37860407965B73cdFFBDFe668Bb5",
        "address_memo":"",
        "tx_id":""
      },
      ...
    ]
  }
}

字段	类型	描述
withdraw_id	String	提现ID
deposit_id	String	充值ID
operation_type	String	类型 -`deposit`=充值 -`withdraw`=提现
currency	String	币种，如 `BTC`
apply_time	Long	请求时间戳精确到毫秒(UTC-0)
arrival_amount	String	实际到账金额
fee	String	手续费
status	Int	状态 -`0`-创建 -`1`-已提交,等待提现 -`2`-处理中 -`3`-处理成功 -`4`-已撤销 -`5`-处理失败
address	String	地址
address_memo	String	地址标签
tx_id	String	提币哈希记录

查询单个充提记录 (KEYED)

查询单个充提记录

请求URL

GET https://api-cloud.bitmart.com/account/v1/deposit-withdraw/detail

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/deposit-withdraw/detail?id=1679952

字段	类型	是否必填	描述
id	String	必填	提现ID或者是充值ID， `withdraw_id` 或者 `deposit_id`

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
        "record":{
            "withdraw_id":"1679952",
            "deposit_id":"",
            "operation_type":"withdraw",
            "currency":"BMX",
            "apply_time":1588867374000,
            "arrival_amount":"59.000000000000",
            "fee":"1.000000000000",
            "status":0,
            "address":"0xe57b69a8776b37860407965B73cdFFBDFe668Bb5",
            "address_memo":"",
            "tx_id":""
        }
    }
}

字段	类型	描述
withdraw_id	String	提现ID
deposit_id	String	充值ID
operation_type	String	类型 -`deposit`=充值 -`withdraw`=提现
currency	String	币种简称，如 `BTC`
apply_time	Long	请求时间戳精确到秒(UTC-0)
arrival_amount	String	实际到账金额
fee	String	手续费
status	Int	状态 -`0`-创建 -`1`-已提交,等待提现 -`2`-处理中 -`3`-处理成功 -`4`-已撤销 -`5`-处理失败
address	String	地址
address_memo	String	地址标签
tx_id	String	提币哈希记录

查询逐仓账户信息 (KEYED)

适用于查询逐仓杠杆账户信息

请求URL

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/account

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}' 
https://api-cloud.bitmart.com/spot/v1/margin/isolated/account?symbol=BTC_USDT

字段	类型	是否必填	描述
symbol	String	否	交易对，如 `BTC_USDT`，不传symbol则返回所有杠杆逐仓资产

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "symbols":[
        {
          "symbol": "BTC_USDT",
          "risk_rate": "18.77",
          "risk_level": "1",
          "buy_enabled": true,
          "sell_enabled": true,
          "liquidate_price": "-0.09408905",
          "liquidate_rate": "1.1",
          "base": {
            "currency": "BTC",
            "borrow_enabled": false,
            "borrowed": "2.00000000",
            "borrow_unpaid": "0.84478234",
            "interest_unpaid": "0.01385763",
            "available": "112.89603334",
            "frozen": "0.00000000",
            "net_asset": "110.89603334",
            "net_assetBTC": "0.00000000",
            "total_asset": "112.89603334"
          },
          "quote": {
            "currency": "USDT",
            "borrow_enabled": true,
            "borrowed": "0.00000000",
            "borrow_unpaid": "0.84478234",
            "interest_unpaid": "0.01385763",
            "available": "10.00000000",
            "frozen": "0.00000000",
            "net_asset": "10.00000000",
            "net_assetBTC": "0.00000000",
            "total_asset": "10.00000000"
          }
        },
        ...
      ]
    }
}

字段	类型	描述
symbol	String	交易对
risk_rate	String	当前风险率
risk_level	String	风险等级
buy_enabled	Boolean	是否可以买入
sell_enabled	Boolean	是否可以卖出
liquidate_price	String	平仓价格（精度：8位小数）
liquidate_rate	String	平仓风险率
currency	String	币种
borrow_enabled	Boolean	能否借出
borrowed	String	已借资产（精度：8位小数）
borrow_unpaid	String	未还本金金额（精度：8位小数）
interest_unpaid	String	未还利息（精度：8位小数）
available	String	可用资产（精度：8位小数）
frozen	String	交易冻结资产（精度：8位小数）
net_asset	String	净资产（精度：8位小数）
net_assetBTC	String	折合BTC净资产（精度：8位小数）
total_asset	String	总资产（精度：8位小数）

杠杆资金划转 (SIGNED)

适用于杠杆账户和现货账户之间的资金划转

请求URL

POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}' 
 -H 'X-BM-TIMESTAMP:{{currentTime}}' 
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1",
    "side":"in"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer

字段	类型	是否必填	描述
symbol	String	是	交易对, 如 `BTC_USDT`
currency	String	是	币种
amount	String	是	划转数量（精度：8位小数）
side	String	是	转账方向 -`in`=转入 -`out`=转出

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
        "transfer_id":"124532"
    }
}

字段	类型	描述
transfer_id	String	划转id（只有划转成功才会返回）

用户基础费率接口 (KEYED)

用于查询当前用户的基础费率

请求URL

GET https://api-cloud.bitmart.com/spot/v1/user_fee

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/user_fee

响应详情

响应

{
  "message":"OK",
  "code":1000,
  "trace":"0187ba0c876e4236ac191d9848a0f719.94.16778301620100121",
  "data":{
    "user_rate_type":0,
    "level":"LV1",
    "taker_fee_rate_A":"0.001",
    "maker_fee_rate_A":"0.001",
    "taker_fee_rate_B":"0.0025",
    "maker_fee_rate_B":"0.0025",
    "taker_fee_rate_C":"0.004",
    "maker_fee_rate_C":"0.004",
    "taker_fee_rate_D":"0.006",
    "maker_fee_rate_D":"0.006"
  }
}

字段	类型	描述
user_rate_type	Long	费率类型： -`0`=普通用户 -`1`=专业用户 -`2`=特殊用户
level	String	用户等级
taker_fee_rate_A	String	A类交易对吃单手续费
maker_fee_rate_A	String	A类交易对挂单手续费
taker_fee_rate_B	String	B类交易对吃单手续费
maker_fee_rate_B	String	B类交易对挂单手续费
taker_fee_rate_C	String	C类交易对吃单手续费
maker_fee_rate_C	String	C类交易对挂单手续费
taker_fee_rate_D	String	D类交易对吃单手续费
maker_fee_rate_D	String	D类交易对挂单手续费

用户交易费率接口 (KEYED)

用于查询当前用户特定交易对的费率

请求URL

GET https://api-cloud.bitmart.com/spot/v1/trade_fee

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/trade_fee?symbol=BTC_USDT

字段	类型	是否必填	描述
symbol	String	是	交易对，如: `BTC_USDT`

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "87614aa8-5327-4fe2-aafc-02e2ddca7210",
  "data": {
    "symbol": "BTC_USDT",
    "buy_taker_fee_rate": "0.0008",
    "sell_taker_fee_rate": "0.0008",
    "buy_maker_fee_rate": "0.0006",
    "sell_maker_fee_rate": "0.0006"
  }
}

字段	类型	描述
symbol	String	交易对
buy_taker_fee_rate	String	Taker费率（买）
sell_taker_fee_rate	String	Taker费率（卖）
buy_maker_fee_rate	String	Maker费率（买）
sell_maker_fee_rate	String	Maker费率（卖）

现货 / 杠杆交易

下单(v2) (SIGNED)

委托下单

请求URL

POST https://api-cloud.bitmart.com/spot/v2/submit_order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "side":"buy",
    "type":"limit",
    "size":"10",
    "price":"7000"
}'
https://api-cloud.bitmart.com/spot/v2/submit_order

字段	类型	是否必填	描述
symbol	String	是	交易对, 如 `BTC_USDT`
side	String	是	订单方向 -`buy`=买入 -`sell`=卖出
type	String	是	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
client_order_id	String	否	用户自定义ID(支持小于32位数字+字母的组合)

限价单/只做maker单/IOC单特殊参数 (`type`=limit/limit_maker/ioc)

字段	类型	是否必填	描述
size	String	是	买入或卖出的数量
price	String	是	价格

市价单特殊参数 (`type`=market)

字段	类型	是否必填	描述
size	String	否	按数量下单必填
notional	String	否	按金额下单必填

两个都填, 卖单以size为准，买单以notional为准

解释说明

Buy-limit-maker

当“下单价格”>=“市场最低卖出价”，订单提交后，系统将撤单；
当“下单价格”<“市场最低卖出价”，提交成功后，此订单将被系统接受；
当“下单价格”*“下单数量”<最低应成交数量，订单提交后，系统将撤单。

Sell-limit-maker

当“下单价格”<=“市场最高买入价”，订单提交后，系统将撤单；
当“下单价格”>“市场最高买入价”，提交成功后，此订单将被系统接受；
当“下单价格”*“下单数量”<最低应成交数量，订单提交后，系统将撤单。

Buy-ioc，Sell-ioc

下单后，未能立即成交的订单部分立即全部撤单。

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "order_id":"1223181"
  }
}

字段	类型	描述
order_id	String	订单ID

撤单(v3) (SIGNED)

适用于撤销一个未完成的订单

请求URL

POST https://api-cloud.bitmart.com/spot/v3/cancel_order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol": "BTC_USDT",
    "order_id": "112121212"
}'
https://api-cloud.bitmart.com/spot/v3/cancel_order

字段	类型	是否必填	描述
symbol	String	是	交易对, 如 `BTC_USDT`
order_id	String	否	订单 id
client_order_id	String	否	用户自行定义的订单ID

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "result": true
  }
}

字段	类型	描述
result	Boolean	撤单结果 -`true`=成功 -`false`=撤单失败

批量下单(v4) (SIGNED)

批量下单

请求URL

POST https://api-cloud.bitmart.com/spot/v4/batch_orders

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "orderParams":[{
          "clientOrderId":"123456789",
          "size":"0.1",
          "price":"8800",
          "side":"buy",
          "type":"limit"
    }],
    "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/batch_orders

字段	类型	是否必填	描述
symbol	String	是	交易对, 如 `BTC_USDT`
orderParams	List	是	下单参数，笔数不能超过10笔
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

orderParams

字段	类型	是否必填	描述
side	String	是	订单方向 -`buy`=买入 -`sell`=卖出
type	String	是	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
clientOrderId	String	否	用户自定义ID(支持小于32位数字+字母的组合)

限价单/只做maker单/IOC单特殊参数 (`type`=limit/limit_maker/ioc)

字段	类型	是否必填	描述
size	String	是	买入或卖出的数量
price	String	是	价格

市价单特殊参数 (`type`=market)

字段	类型	是否必填	描述
size	String	否	按数量下单必填
notional	String	否	按金额下单必填

两个都填, 卖单以size为准，买单以notional为准

解释说明

Buy-limit-maker

当“下单价格”>=“市场最低卖出价”，订单提交后，系统将撤单；
当“下单价格”<“市场最低卖出价”，提交成功后，此订单将被系统接受；
当“下单价格”*“下单数量”<最低应成交数量，订单提交后，系统将撤单。

Sell-limit-maker

当“下单价格”<=“市场最高买入价”，订单提交后，系统将撤单；
当“下单价格”>“市场最高买入价”，提交成功后，此订单将被系统接受；
当“下单价格”*“下单数量”<最低应成交数量，订单提交后，系统将撤单。

Buy-ioc，Sell-ioc

下单后，未能立即成交的订单部分立即全部撤单。

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "5fc697fb817a4b5396284786a9b2609a.263.17022620476480263",
  "data": {
    "code": 0,
    "msg": "success",
    "data": {
      "orderIds": [
        "212751308355553320"
      ]
    }
  }
}

字段	类型	描述
orderIds	List	订单ID

批量撤单(v4) (SIGNED)

取消指定交易对指定方向的所有未完成的订单或者根据订单id来取消

请求URL

POST https://api-cloud.bitmart.com/spot/v4/cancel_orders

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"BTC_USDT",
  "orderIds":[
    "5e925f3981"
  ],
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/cancel_orders

字段	类型	是否必填	描述
symbol	String	是	交易对, 如 `BTC_USDT`
orderIds	List	否	订单id列表 (orderIds 或 clientOrderIds 必须被提供)
clientOrderIds	List	否	自定义订单id列表 (orderIds 或 clientOrderIds 必须被提供)
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "c4edbce860164203954f7c3c81d60fc6.309.17022669632770001",
  "data": {
    "successIds": [
      "213055379155243012"
    ],
    "failIds": [],
    "totalCount": 1,
    "successCount": 1,
    "failedCount": 0
  }
}

字段	类型	描述
successIds	List	成功撤销的订单ID
failIds	List	撤销失败的订单ID
totalCount	Int	总提交数量
successCount	Int	成功数量
failedCount	Int	失败数量

全量撤单(v4) (SIGNED)

取消所有订单

请求URL

POST https://api-cloud.bitmart.com/spot/v4/cancel_all

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"BTC_USDT",
  "side":"buy"
}'
https://api-cloud.bitmart.com/spot/v4/cancel_all

字段	类型	是否必填	描述
symbol	String	否	交易对, 如 `BTC_USDT`
side	String	否	订单方向 -`buy`=买入 -`sell`=卖出

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
  }
}

code 返回 1000 表示撤销成功。

杠杆下单(v1) (SIGNED)

杠杆账户的下单操作

请求URL

POST https://api-cloud.bitmart.com/spot/v1/margin/submit_order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "side":"buy",
    "type":"limit",
    "size":"10",
    "price":"7000"
}'
https://api-cloud.bitmart.com/spot/v1/margin/submit_order

字段	类型	是否必填	描述
symbol	String	是	交易对, 如 `BTC_USDT`
side	String	是	订单方向 -`buy`=买入 -`sell`=卖出
type	String	是	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
clientOrderId	String	否	用户自定义ID(支持小于32位数字+子母的组合)

限价单/只做maker单/IOC单特殊参数 (`type`=limit/limit_maker/ioc)

字段	类型	是否必填	描述
size	String	是	买入或卖出的数量
price	String	是	价格

市价单特殊参数 (`type`=market)

字段	类型	是否必填	描述
size	String	否	按数量下单必填
notional	String	否	按金额下单必填

两个都填, 卖单以size为准，买单以notional为准

解释说明

Buy-limit-maker

当“下单价格”>=“市场最低卖出价”，订单提交后，系统将撤单；
当“下单价格”<“市场最低卖出价”，提交成功后，此订单将被系统接受。

Sell-limit-maker

当“下单价格”<=“市场最高买入价”，订单提交后，系统将撤单；
当“下单价格”>“市场最高买入价”，提交成功后，此订单将被系统接受。

Buy-ioc，Sell-ioc

下单后，未能立即成交的订单部分立即全部撤单。

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "order_id":1223181
    }
}

字段	类型	描述
order_id	Long	订单ID

orderId查单(v4)(SIGNED)

根据订单orderId查询单个订单

请求URL

POST https://api-cloud.bitmart.com/spot/v4/query/order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "orderId":"118100034543076010",
  "queryState":"open",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/order

字段	类型	是否必填	描述
orderId	String	是	订单id
queryState	String	否	查询类型 - `open`=当前委托(未成交+部分成交) - `history`=历史委托（完全成交+完全撤销+部分成交已撤销
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

注意

响应详情

响应

{
  "code" : 1000,
  "message" : "success",
  "data" : {
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "filled",
    "price" : "48800.00",
    "priceAvg" : "39999.00",
    "size" : "0.10000",
    "filledSize" : "0.10000",
    "notional" : "4880.00000",
    "filledNotional" : "3999.90000",
    "createTime" : 1681701557927,
    "updateTime" : 1681701559408
  },
  "trace" : "8aab576e50024648ae45e3cfaf90f9cf.60.16817015721880197"
}

字段	类型	描述
orderId	String	订单ID
clientOrderId	String	外部订单号
symbol	String	交易对, 如 `BTC_USDT`
side	String	订单方向 -`buy`=买入 -`sell`=卖出
orderMode	String	订单模式 -`spot`=现货 -`iso_margin`=逐仓杠杆
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
state	String	订单状态 -`new`=未成交 -`partially_filled`=部分成交 -`filled`=完全成交 -`canceled`=完全撤销 -`partially_canceled`=部分成交已撤销 -`failed`=失败
price	String	下单价格
priceAvg	String	平均成交价格
size	String	下单数量
filledSize	String	实际成交数量
notional	String	下单金额
filledNotional	String	实际成交金额
createTime	Long	创建时间, 精确到毫秒如：1681701557927
updateTime	Long	最后更新时间, 精确到毫秒如：1681701557927

clientOrderId查单(v4)(SIGNED)

根据clientOrderId查询单个订单

请求URL

POST https://api-cloud.bitmart.com/spot/v4/query/client-order

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "clientOrderId":"118100034543076010",
  "queryState":"open",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/client-order

字段	类型	是否必填	描述
clientOrderId	String	是	用户自定义订单id
queryState	String	否	查询类型 - `open`=当前委托(未成交+部分成交) - `history`=历史委托（完全成交+完全撤销+部分成交已撤销
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

注意

响应详情

响应

{
  "code" : 1000,
  "message" : "success",
  "data" : {
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "filled",
    "price" : "48800.00",
    "priceAvg" : "39999.00",
    "size" : "0.10000",
    "filledSize" : "0.10000",
    "notional" : "4880.00000",
    "filledNotional" : "3999.90000",
    "createTime" : 1681701557927,
    "updateTime" : 1681701559408
  },
  "trace" : "8aab576e50024648ae45e3cfaf90f9cf.60.16817015721880197"
}

字段	类型	描述
orderId	String	订单ID
clientOrderId	String	外部订单号
symbol	String	交易对, 如 `BTC_USDT`
side	String	订单方向 -`buy`=买入 -`sell`=卖出
orderMode	String	订单模式 -`spot`=现货 -`iso_margin`=逐仓杠杆
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
state	String	订单状态 -`new`=未成交 -`partially_filled`=部分成交 -`filled`=完全成交 -`canceled`=完全撤销 -`partially_canceled`=部分成交已撤销
price	String	下单价格
priceAvg	String	平均成交价格
size	String	下单数量
filledSize	String	实际成交数量
notional	String	下单金额
filledNotional	String	实际成交金额
createTime	Long	创建时间, 精确到毫秒如：1681701557927
updateTime	Long	最后更新时间, 精确到毫秒如：1681701557927

当前委托(v4)(SIGNED)

查询账户当前委托列表, 只包含 new(未成交) 和 partially_filled(部分成交) 的订单

请求URL

POST https://api-cloud.bitmart.com/spot/v4/query/open-orders

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"BTC_USDT",
  "orderMode":"spot",
  "startTime":1682239652931,
  "endTime":1682239657931,
  "limit":10,
  "recvWindow": 5000
}'
https://api-cloud.bitmart.com/spot/v4/query/open-orders

字段	类型	是否必填	描述
symbol	String	否	交易对, 如 `BTC_USDT`
orderMode	String	否	订单模式 - `spot`=现货 - `iso_margin`=逐仓杠杆
startTime	Long	否	起始时间, 精确到毫秒, 如: 1681701557927
endTime	Long	否	结束时间, 精确到毫秒, 如: 1681701557927
limit	Int	否	查询条数, 取值范围[1,200], 默认200条
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

注意

对于高交易量的成交，强烈建议用户维护自己的当前订单列表，使用 websocket 更新订单状态。每次交易前您必须拉取一次当前订单列表。
symbol 不填写，默认查所有交易对。
orderMode 不填写，默认查所有订单模式。
limit 不填写，默认200条，如果设置不能超过200条。
没有填写时间范围startTime和endTime，则默认展示最近7天的数据。
填写时间范围的话，endTime 必须比 startTime 的值大。
如果只填写了startTime，则查询从该时间戳开始时间往后的历史记录。
如果只填写了endTime，则查询从该时间戳开始时间往前的历史记录。

响应详情

响应

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "orderId" : "125213058731346056",
    "clientOrderId" : "125213058731346056",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "new",
    "price" : "800.00",
    "priceAvg" : "0.00",
    "size" : "0.10000",
    "filledSize" : "0.00000",
    "notional" : "80.00000000",
    "filledNotional" : "0.00000000",
    "createTime" : 1681892198608,
    "updateTime" : 1681892198946
  } ],
  "trace" : "5e1c9f98d761443ea559c7af71ca57fa.60.16818922069220005"
}

字段	类型	描述
orderId	String	订单ID
clientOrderId	String	外部订单号
symbol	String	交易对, 如 `BTC_USDT`
side	String	订单方向 -`buy`=买入 -`sell`=卖出
orderMode	String	订单模式 -`spot`=现货 -`iso_margin`=逐仓杠杆
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
state	String	订单状态 -`new`=未成交 -`partially_filled`=部分成交
price	String	下单价格
priceAvg	String	平均成交价格
size	String	下单数量
filledSize	String	实际成交数量
notional	String	下单金额
filledNotional	String	实际成交金额
createTime	Long	创建时间, 精确到毫秒如：1681701557927
updateTime	Long	最后更新时间, 精确到毫秒如：1681701557927

历史委托(v4)(SIGNED)

查询账户历史委托列表, 只包含 filled(完全成交) 、canceled(完全撤销)和 partially_canceled(部分成交已撤销) 的订单

请求URL

POST https://api-cloud.bitmart.com/spot/v4/query/history-orders

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"BTC_USDT",
  "orderMode":"spot",
  "startTime":1682239502394,
  "endTime":1682239507394,
  "limit":10,
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/history-orders

字段	类型	是否必填	描述
symbol	String	否	交易对, 如 `BTC_USDT`
orderMode	String	否	订单模式 - `spot`=现货 - `iso_margin`=逐仓杠杆
startTime	Long	否	起始时间, 精确到毫秒, 如: 1681701557927
endTime	Long	否	结束时间, 精确到毫秒, 如: 1681701557927
limit	Int	否	查询条数, 取值范围[1,200]，默认200条
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

注意

symbol 不填写，默认查所有交易对。
orderMode 不填写，默认查所有订单模式。
limit 不填写，默认100条，如果设置不能超过200条。
没有填写时间范围startTime和endTime，则默认展示最近7天的数据。
填写时间范围的话，endTime 必须比 startTime 的值大。
如果只填写了startTime，则查询从该时间戳开始时间往后的历史记录。
如果只填写了endTime，则查询从该时间戳开始时间往前的历史记录。

响应详情

响应

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "filled",
    "price" : "48800.00",
    "priceAvg" : "39999.00",
    "size" : "0.10000",
    "filledSize" : "0.10000",
    "notional" : "4880.00000000",
    "filledNotional" : "3999.90000000",
    "createTime" : 1681701557927,
    "updateTime" : 1681701559408
  } ],
  "trace" : "acc282ba9e434cc1a90bf6326de9e119.64.16818913787390001"
}

字段	类型	描述
orderId	String	订单ID
clientOrderId	String	外部订单号
symbol	String	交易对, 如 `BTC_USDT`
side	String	订单方向 -`buy`=买入 -`sell`=卖出
orderMode	String	订单模式 -`spot`=现货 -`iso_margin`=逐仓杠杆
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
state	String	订单状态 -`filled`=完全成交 -`canceled`=完全撤销 -`partially_canceled`=部分成交已撤销
price	String	下单价格
priceAvg	String	平均成交价格
size	String	下单数量
filledSize	String	实际成交数量
notional	String	下单金额
filledNotional	String	实际成交金额
createTime	Long	创建时间, 精确到毫秒如：1681701557927
updateTime	Long	最后更新时间, 精确到毫秒如：1681701557927

成交记录(v4)(SIGNED)

查询账户所有成交记录

请求URL

POST https://api-cloud.bitmart.com/spot/v4/query/trades

请求限制

参见速率限制详细

请求参数

请求

 curl 
  -H 'X-BM-KEY:{{AccessKey}}'
  -H 'X-BM-TIMESTAMP:{{currentTime}}'
  -H 'X-BM-SIGN:{{SIGN}}' 
  -X POST -d '{
  "symbol":"BTC_USDT",
  "orderMode":"spot",
  "startTime":1682239845952,
  "endTime":1682239850952,
  "limit":10,
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/trades

字段	类型	是否必填	描述
symbol	String	否	交易对, 如 `BTC_USDT`
orderMode	String	否	订单模式 - `spot`=现货 - `iso_margin`=逐仓杠杆
startTime	Long	否	起始时间, 精确到毫秒, 如: 1681701557927
endTime	Long	否	结束时间, 精确到毫秒, 如: 1681701557927
limit	Int	否	查询条数, 取值范围[1,200]，默认200条
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

注意

symbol 不填写，默认查所有交易对。
orderMode 不填写，默认查所有订单模式。
limit 不填写，默认200条，不能超过200条。
没有填写时间范围startTime和endTime，则默认展示最近7天的数据。
填写时间范围的话，endTime 必须比 startTime 的值大。
如果只填写了startTime，则查询从该时间戳开始时间往后的历史记录。
如果只填写了endTime，则查询从该时间戳开始时间往前的历史记录。

响应详情

响应

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "tradeId" : "125277182593091639",
    "orderId" : "125213058731346053",
    "clientOrderId" : "125213058731346053",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "price" : "39999.00",
    "size" : "0.10000",
    "notional" : "3999.90000000",
    "fee" : "9.99975000",
    "feeCoinName" : "USDT",
    "tradeRole" : "taker",
    "createTime" : 1681891896569,
    "updateTime" : 1681891896569
  } ],
  "trace" : "5e1c9f98d761443ea559c7af71ca57fa.61.16819603026240455"
}

字段	类型	描述
tradeId	String	成交 id
orderId	String	订单ID
clientOrderId	String	外部订单号
symbol	String	交易对, 如 `BTC_USDT`
side	String	订单方向 -`buy`=买入 -`sell`=卖出
orderMode	String	订单模式 -`spot`=现货 -`iso_margin`=逐仓杠杆
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
price	String	下单价格
size	String	成交数量
notional	String	下单金额
fee	String	手续费
feeCoinName	String	手续费币种名称
tradeRole	String	成交角色 -`taker`=吃单,主动成交 -`maker`=挂单,被动成交
createTime	Long	创建时间, 精确到毫秒如：1681701557927
updateTime	Long	最后更新时间, 精确到毫秒如：1681701557927

单笔成交记录(v4)(SIGNED)

查询单笔订单的所有成交记录

请求URL

POST https://api-cloud.bitmart.com/spot/v4/query/order-trades

请求限制

参见速率限制详细

请求参数

请求

 curl 
  -H 'X-BM-KEY:{{AccessKey}}'
  -H 'X-BM-TIMESTAMP:{{currentTime}}'
  -H 'X-BM-SIGN:{{SIGN}}' 
  -X POST -d '{
  "orderId":"118100034543076010",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/order-trades

字段	类型	是否必填	描述
orderId	String	是	订单id
recvWindow	Long	否	交易时效时间，取值范围(0,60000], 默认：5000 毫秒

注意

orderId 订单号必填写，也不可为空字符串

响应详情

响应

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "tradeId" : "122177405911172002",
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "price" : "39999.00",
    "size" : "0.10000",
    "notional" : "3999.90000000",
    "fee" : "9.99975000",
    "feeCoinName" : "USDT",
    "tradeRole" : "taker",
    "createTime" : 1681701559210,
    "updateTime" : 1681701559210
  } ],
  "trace" : "5e1c9f98d761443ea559c7af71ca57fa.62.16818934219090007"
}

字段	类型	描述
tradeId	String	成交 id
orderId	String	订单ID
clientOrderId	String	外部订单号
symbol	String	交易对, 如 `BTC_USDT`
side	String	订单方向 -`buy`=买入 -`sell`=卖出
orderMode	String	订单模式 -`spot`=现货 -`iso_margin`=逐仓杠杆
type	String	订单类型 -`limit`=限价单 -`market`=市价单 -`limit_maker`=PostOnly单 -`ioc`=IOC单
price	String	成交价格
size	String	成交数量
notional	String	成交金额
fee	String	手续费
feeCoinName	String	手续费币种名称
tradeRole	String	成交角色 -`taker`=吃单,主动成交 -`maker`=挂单,被动成交
createTime	Long	创建时间, 精确到毫秒如：1681701557927
updateTime	Long	最后更新时间, 精确到毫秒如：1681701557927

杠杆借还款

逐仓借款 (SIGNED)

适用于逐仓杠杆账户的借款操作

请求URL

POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow

请求限制

参见速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow

字段	类型	是否必填	描述
symbol	String	是	借入交易对（如BTC_USDT）
currency	String	是	借入币种，根据借入交易对选择（如BTC或USDT）
amount	String	是	借币数量（精度：8位小数）

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "borrow_id":"113896"
    }
}

字段	类型	描述
borrow_id	String	借款订单ID，只有成功会返回

逐仓还款 (SIGNED)

适用于逐仓杠杆账户的还款操作

请求URL

POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay

请求限制

参见速率限制详细

请求参数

请求

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay

字段	类型	是否必填	描述
symbol	String	是	还款交易对（如BTC_USDT）
currency	String	是	还款币种，根据还款交易对选择（如BTC或USDT）
amount	String	是	还款数量（精度：8位小数）

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
        "repay_id":"123165"
    }
}

字段	类型	描述
repay_id	String	还款ID，只有成功会返回

查询逐仓借款订单 (KEYED)

适用于查询逐仓杠杆账户的借款记录

请求URL

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}' 
https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record?symbol=BTC_USDT

字段	类型	是否必填	描述
symbol	String	是	交易对（如BTC_USDT）
borrow_id	String	否	借款订单id
start_time	Long	否	查询开始日期：时间戳
end_time	Long	否	查询结束日期：时间戳
N	Int	否	查询记录条数，取值范围（1-100），默认为50

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data": {
      "records":[
        {
          "borrow_id": "133425",
          "symbol": "BTC_USDT",
          "currency": "BTC",
          "borrow_amount": "1.23854339",
          "daily_interest": "0.05",
          "hourly_interest": "0.00208334",
          "interest_amount": "0.02398474",
          "create_time": 1655345808
        },
        ...
      ]
    }
}

字段	类型	描述
borrow_id	String	借款订单号
symbol	String	交易对
currency	String	币种
borrow_amount	String	借款本金总额（精度：8位小数）
daily_interest	String	日利率
hourly_interest	String	时利率
interest_amount	String	利息总额（精度：8位小数）
create_time	Long	订单创建时间

查询逐仓还款订 (KEYED)

适用于查询逐仓杠杆账户的还款记录

请求URL

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record?symbol=BTC_USDT

字段	类型	是否必填	描述
symbol	String	是	交易对（如BTC_USDT）
repay_id	String	否	还款订单id
currency	String	否	币种
start_time	Long	否	查询开始日期：时间戳
end_time	Long	否	查询结束日期：时间戳
N	Int	否	查询记录条数，取值范围（1-100），默认为50

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "records":[
      {
        "repay_id":"118723",
        "repay_time":1655345808,
        "symbol":"BTC_USDT",
        "currency":"BTC",
        "repaid_amount":"1.1",
        "repaid_principal":"1",
        "repaid_interest":"0.1"
      },
      ...
      ]
    }
}

字段	类型	描述
repay_id	String	还款ID
repay_time	Long	还款时间戳
symbol	String	还款交易对（如BTC_USDT）
currency	String	还款币种
repaid_amount	String	还款金额
repaid_principal	String	该笔还款归还的本金
repaid_interest	String	该笔还款归还的利息

查询交易对借款利率与额度 (KEYED)

适用于查询逐仓杠杆交易对的借款利率和借款额度

请求URL

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs?symbol=BTC_USDT

字段	类型	是否必填	描述
symbol	String	否	可多选，不填则返回全部，如BTC_USDT,ETH_USDT

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "symbols":[
        {
          "symbol": "BTC_USDT",
          "max_leverage": "10",
          "symbol_enabled": true,
          "base": {
            "currency": "BTC",
            "daily_interest": "0.05",
            "hourly_interest": "0.00208334",
            "max_borrow_amount": "1000.00000000",
            "min_borrow_amount": "1.00000000",
            "borrowable_amount": "955.90221219"
          },
          "quote": {
            "currency": "USDT",
            "daily_interest": "0.05",
            "hourly_interest": "0.00208334",
            "max_borrow_amount": "12000.00000000",
            "min_borrow_amount": "0.01000000",
            "borrowable_amount": "12000.00000000"
          }
        },
        ...
      ]
    }
}

字段	类型	描述
symbol	String	交易对
max_leverage	String	杠杆倍数
symbol_enabled	Boolean	是否已开通该交易对
currency	String	币种
daily_interest	String	日利率
hourly_interest	String	时利率
max_borrow_amount	String	最大借出数量（精度：8位小数）
min_borrow_amount	String	最小借出数量（精度：8位小数）
borrowable_amount	String	当前可借数量（精度：8位小数）

子母账户

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

子账户的现货钱包向主账户的现货钱包划转（主账户适用）

请求URL

POST https://api-cloud.bitmart.com/account/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":"BTC",
    "subAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-main

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

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
  }
}

code 返回 1000 表示划转成功。

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

子账户的现货钱包向主账户的现货钱包划转（子账户适用）

请求URL

POST https://api-cloud.bitmart.com/account/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":"BTC"
}'
https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-main

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

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
  }
}

code 返回 1000 表示划转成功。

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

主账户的现货钱包向子账户划转现货钱包（主账户适用）

请求URL

POST https://api-cloud.bitmart.com/account/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.bitmart.com/account/sub-account/main/v1/main-to-sub

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

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
  }
}

code 返回 1000 表示划转成功。

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

子账户的现货钱包向子账户的现货钱包划转（主账户适用）

请求URL

POST https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-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",
    "fromAccount":"[email protected]",
    "toAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-sub

字段	类型	是否必填	描述
requestNo	String	是	uuid或其他通用唯一标识符, 支持长度64
amount	String	是	划转数量
currency	String	是	币种
fromAccount	String	是	划出子账户用户名
toAccount	String	是	划入子账户用户名

响应详情

响应

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
  }
}

code 返回 1000 表示划转成功。

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

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

请求URL

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

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/transfer-list?moveType=spot to spot

字段	类型	是否必填	描述
moveType	String	是	划转类型
			`spot to spot`=现货到现货
accountName	String	否	子账户用户名（默认：查询全部的子账户)
N	Int	是	最近N条记录(取值范围1-100)

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "282fd16e-73ee-464f-adb7-7241345929f6",
  "data": {
    "total": 2,
    "historyList": [
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "1",
        "submissionTime": 1648471522
      },
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "30",
        "submissionTime": 1648466178
      }
    ]
  }
}

字段	类型	描述
fromAccount	String	转出账户
fromWalletType	String	转出钱包类型 -`spot`=现货
toAccount	String	转入账户
toWalletType	String	转入钱包类型 -`spot`=现货
currency	String	币种
amount	String	金额
submissionTime	Long	请求时间戳精确到秒

账户划转历史 (主子账户通用) (KEYED)

查询账户划转历史

请求URL

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

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/sub-account/v1/transfer-history?moveType=spot to spot

字段	类型	是否必填	描述
moveType	String	是	划转类型
			`spot to spot`=现货到现货
N	Int	是	最近N条记录(取值范围1-100)

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "282fd16e-73ee-464f-adb7-7241345929f6",
  "data": {
    "total": 2,
    "historyList": [
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "1",
        "submissionTime": 1648471522
      },
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "30",
        "submissionTime": 1648466178
      }
    ]
  }
}

字段	类型	描述
fromAccount	String	转出账户
fromWalletType	String	转出钱包类型 -`spot`=现货
toAccount	String	转入账户
toWalletType	String	转入钱包类型 -`spot`=现货
currency	String	币种
amount	String	金额
submissionTime	Long	请求时间戳精确到秒

子现货余额（主账户适用）(KEYED)

获取子账户现货钱包余额（主账户适用）

请求URL

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

请求限制

参见速率限制详细

请求参数

请求

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

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

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"ef834248-51d3-4223-9481-f862aa9dd39f",
    "data":{
        "wallet":[
            {
                "currency":"USDT",
                "name":"Tether USD",
                "available":"1000.00000000",
                "frozen":"0.00000000"
            },
            {
                "currency":"BTC",
                "name":"Bitcoin",
                "available":"10000.00000000",
                "frozen":"10.00000000"
            }
        ]
    }
}

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

子账户列表（主账户适用）(KEYED)

查询子账户列表（主账户适用）

请求URL

GET https://api-cloud.bitmart.com/account/sub-account/main/v1/subaccount-list

请求限制

参见速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/subaccount-list

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "c03c22c3-75db-4aaa-9500-6dcd63dd9ccf",
  "data": {
    "subAccountList": [
      {
        "accountName": "[email protected]",
        "status": 1
      },
      {
        "accountName": "[email protected]",
        "status": 1
      }
    ]
  }
}

字段	类型	描述
accountName	String	子账户账户名
status	Int	账户状态 -`0`=被后台禁用 -`1`=正常 -`2`=被主账号冻结

WebSocket订阅

概述

服务器地址

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

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

指令格式

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

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

解释:

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

示例:

示例1：{"op": "subscribe", "args": ["spot/ticker:BTC_USDT"]}
- 表示订阅现货交易对BTC_USDT的ticker数据
示例2：{"op": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556"]}
- 进行私人频道订阅之前的登录请求

成功响应格式

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

返回不包含error_code字段则表示成功。

成功响应格式

当 op=login 时：
{"event":"<operation>"}

当 op=unsubscribe 时：
{"event":"<operation>","topic":"<topic>"}

当 op=subscribe 时：
{"table":"<topic1>","data":"[{"<value1>","<value2>"}]"}
{"table":"<topic2>","data":"[{"<value1>","<value2>"}]"}

示例:

示例1：{"event":"login"}
- 表示登录成功
实例2：{"topic":"spot/ticker:BTC_USDT","event":"subscribe"}
- 表示订阅成功
示例3：{"event":"unsubscribe","topic":"spot/ticker:BTC_USDT"}
- 表示取消现货交易对BTC_USDT的ticker订阅成功
示例4：{"table":"spot/ticker:BTC_USDT","data":"[{"<value1>","<value2>"}]"}
- 表示现货交易对BTCUSDT_USDT的ticker订阅，产生数据，返回给客户端

失败响应格式

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

返回包含errorCode字段则表示失败，失败原因，请参考：WebSocket 错误码

失败响应格式

{"event":"<operation>","errorMessage":"<error_message>","errorCode":"<error_code>"}

示例1：{"event":"login","errorCode":"91002","errorMessage":"API KEY not found"}
- 表示登录失败，您的API KEY 不存在
示例2：{"event":"subscribe","errorCode":"90004","errorMessage":"Invalid channel param"}
- 表示订阅失败，您的参数是无效的，不存在这个频道

连接保持与限制

如何保持连接

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

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

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

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

文本的 Ping Text

ws.send(new TextWebSocketFrame("ping");

连接限制(用户频道和公有频道)

每个IP最多能和BitMart公有频道服务器保持20个连接，私有频道服务器保持10个连接
连接建立后，允许客户端在每个连接上订阅最多100个频道
发送速率限制：
1. 发起连接: 客户端1分钟内最多能发起30次连接BitMart服务器的请求
2. 连接成功后: 客户端发送订阅请求10秒内最多能发送100条消息, 包括：PING文本，JSON格式的消息（订阅和取消订阅）
3. 连接成功后: 客户端发送单次订阅的消息数组最大上限是20个
如果用户发送的消息超过限制，连接会被断开连接。反复被断开连接的IP有可能被服务器屏蔽

如何订阅超过1000的频道？

订阅1000个及以内频道的最佳示例: 使用一个IP可以建立10个和BitMart的服务器连接，每个连接发起100个频道的订阅

订阅1000+个频道的最佳示例: 可以使用多个IP，然后每个IP可以建10个连接，每个连接发起100个频道的订阅

需要注意的是?

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

空连接

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

数据压缩

只有当订阅后，返回市场数据时，远程服务会将数据压缩返回给客户端。远程服务返回数据有两个格式，Binary 格式和 Text 格式，当返回了 Binary 格式表示数据被远程服务压缩过，客户端此时需要解压。

压缩说明

zlib是提供资料压缩之用的库，由Jean-loup Gailly与Mark Adler所开发，初版0.9版在1995年5月1日发表。zlib使用抽象化的DEFLATE算法，最初是为libpng库所写的，后来普遍为许多软件所使用。此库为自由软件。官方链接 http://zlib.net/

解压示例

更多更全的编程代码请参考快速接入代码

Python

import zlib

def inflate(data):
    decompress = zlib.decompressobj(
            -zlib.MAX_WBITS
    )
    inflated = decompress.decompress(data)
    inflated += decompress.flush()
    return inflated.decode('UTF-8')

Nodejs

const zlib = require('zlib');

zlib.inflateRawSync(data);

Golang

import (
    "compress/flate"
)

func zipDecode(in []byte) ([]byte, error) {
    reader := flate.NewReader(bytes.NewReader(in))
    defer reader.Close()

    return ioutil.ReadAll(reader)
}

string(zipDecode(data))

php

@link https://php.net/manual/en/function.gzinflate.php

gzinflate($data)

Java

import java.util.zip.*;

public class StringCompressUtil {

    private static String uncompress(ByteBuf buf) {
        try {
            byte[] temp = new byte[buf.readableBytes()];
            ByteBufInputStream bis = new ByteBufInputStream(buf);
            bis.read(temp);
            bis.close();
            Inflater decompresser = new Inflater(true);
            decompresser.setInput(temp, 0, temp.length);
            StringBuilder sb = new StringBuilder();
            byte[] result = new byte[1024];
            while (!decompresser.finished()) {
                int resultLength = decompresser.inflate(result);
                sb.append(new String(result, 0, resultLength, "UTF-8"));
            }
            decompresser.end();
            return sb.toString();
        }catch (Exception e) {
            e.printStackTrace();
        }
        return "";
    }

    public static String decode(ByteBuf content){
        byte[] bytes = new byte[content.readableBytes()];
        content.readBytes(bytes);
        ByteBuf byteBuf = Unpooled.wrappedBuffer(bytes);
        String str = uncompress(byteBuf);
        return str;
    }

}

StringCompressUtil.decode(data)

取消订阅

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

取消订阅

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

参数说明

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

示例

取消订阅请求

{"op": "unsubscribe", "args": ["spot/ticker:BTC_USDT", "spot/ticker:ETH_USDT"]}

取消订阅成功

{"event":"unsubscribe","topic":"spot/ticker:BTC_USDT"}
{"event":"unsubscribe","topic":"spot/ticker:ETH_USDT"}

【公共】Ticker频道

获取现货交易对的最新成交价、买一价、卖一价和24交易量

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送
推送频率: 最快500ms一次

订阅请求

订阅请求

{
  "op": "subscribe", 
  "args": ["spot/ticker:BTC_USDT"]
}

消息格式:

{"op": "subscribe", "args": ["spot/ticker:<symbol>"]}

symbol: 交易对, 如BTC_USDT

订阅成功

订阅成功

{
  "event":  "subscribe",
  "topic":  "spot/ticker:BTC_USDT"
}

{"event":"subscribe","topic":"spot/ticker:<symbol>"}

订阅成功后，推送数据

推送数据

{
  "data":  [
    {
      "ask_px":  "36000",
      "ask_sz":  "1.021",
      "base_volume_24h":  "2.02000",
      "bid_px":  "35000",
      "bid_sz":  "11",
      "fluctuation":  "-0.0001",
      "high_24h":  "35003.04",
      "last_price":  "35000.00",
      "low_24h":  "35000.00",
      "ms_t":  1709024652967,
      "open_24h":  "35003.03",
      "quote_volume_24h":  "70700.00",
      "s_t":  1709024652,
      "symbol":  "BTC_USDT"
    }
  ],
  "table":  "spot/ticker"
}

返回data字段说明:

字段	类型	描述
symbol	String	交易对名称, `BTC_USDT`
last_price	String	最新成交价
high_24h	String	24小时最高价
low_24h	String	24小时最低价
open_24h	String	24小时开盘价
base_volume_24h	String	24小时成交量，按交易货币统计
quote_volume_24h	String	24小时成交量，按计价货币统计
s_t	Long	时间戳, 精确到秒(字段废弃，后续会下架, 请使用ms_t字段)
ms_t	Long	时间戳, 精确到毫秒
fluctuation	String	24小时涨跌幅
bid_px	String	买一价
bid_sz	String	买一价挂单量
ask_px	String	卖一价
ask_sz	String	卖一价挂单量

注意：此数据是解压后的展示, 详情查看数据压缩

【公共】K线频道

获取现货的K线数据

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送
推送频率: 最快500ms一次

订阅请求

订阅请求

{
  "op": "subscribe", 
  "args": ["spot/kline1m:BTC_USDT"]
}

消息格式:

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

channel: 频道名, 如spot/kline1m
symbol: 交易对, 如BTC_USDT

请求其他频道列表

频道名	频道描述
spot/kline1m	1分钟K线数据频道
spot/kline5m	5分钟K线数据频道
spot/kline15m	15分钟K线数据频道
spot/kline30m	30分钟K线数据频道
spot/kline1H	1小时K线数据频道
spot/kline2H	2小时K线数据频道
spot/kline4H	4小时K线数据频道
spot/kline1D	1天K线数据频道
spot/kline1W	1周K线数据频道
spot/kline1M	1月K线数据频道

订阅成功

订阅成功

{
  "topic":  "spot/kline1m:BTC_USDT",
  "event":  "subscribe"
}

{"event":"subscribe","topic":"<channel>:<symbol>"}

订阅成功后，推送数据

推送数据

{
  "data":  [
    {
      "candle":  [
        1709025360,
        "162.01",
        "162.02",
        "162.03",
        "162.04",
        "336.452694"
      ],
      "symbol":  "BTC_USDT"
    }
  ],
  "table":  "spot/kline1m"
}

返回data字段说明:

字段	类型	描述
symbol	String	交易对名称, `BTC_USDT`
candle	List	k线数据

注意：此数据是解压后的展示, 详情参看数据压缩

【公共】深度全量频道

返回深度数据，每次推送都是全量的数据

推送规则

无需用户登录
订阅后会直接返回当前的数据，之后有变化才推送
推送频率: 最快500ms一次

订阅请求

订阅请求

{
  "op": "subscribe", 
  "args": ["spot/depth5:BTC_USDT"]
}

消息格式:

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

channel: 频道名, 如spot/depth5
symbol: 交易对, 如BTC_USDT

请求其他频道列表

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

订阅成功

订阅成功

{
  "topic":  "spot/depth5:BTC_USDT",
  "event":  "subscribe"
}

{"event":"subscribe","topic":"<channel>:<symbol>"}

订阅成功后，推送数据

推送数据

{
    "table":"spot/depth5",
    "data":[
        {
            "asks":[
                [
                    "161.96",
                    "7.37567"
                ]
            ],
            "bids":[
                [
                    "161.94",
                    "4.552355"
                ]
            ],
            "symbol":"ETH_USDT",
            "ms_t": 1542337219120
        }
    ]
}

返回data字段说明:

字段	类型	描述
symbol	String	交易对名称, `BTC_USDT`
asks	List	卖方深度
bids	List	买方深度
ms_t	Long	时间戳 (精确到毫秒)

注意：此数据是解压后的展示, 详情参看数据压缩

【公共】深度增量频道

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

推送规则

无需用户登录
推送频率: 最快100ms一次

订阅请求

订阅请求

{ 
  "op": "subscribe", 
  "args": ["spot/depth/increase100:BTC_USDT"]
}

全量请求

{ 
  "op": "request", 
  "args": ["spot/depth/increase100:BTC_USDT"]
}

消息格式:

{"op": "<op>", "args": ["spot/depth/increase100:<symbol>"]}

op: subscribe=订阅,会收到一个订阅成功的消息，而后会收到实时推送的增量深度数据, request=单次请求最新深度快照,会马上收到一个全量深度的数据
symbol: 交易对, 如BTC_USDT

订阅成功

订阅成功

{
  "topic":  "spot/depth/increase100:BTC_USDT",
  "event":  "subscribe"
}

{"event":"subscribe","topic":"spot/depth/increase100:<symbol>"}

全量深度快照

{
  "data": [{
    "asks": [
      ["23200", "0.69959"],
      ["28000.00", "0.20000"]
    ],
    "bids": [
      ["23105", "1.80114"]
    ],
    "ms_t": 1698292343610,
    "symbol": "BTC_USDT",
    "type": "snapshot",
    "version": 4
  }],
  "table": "spot/depth/increase100"
}

增量深度数据

{
    "data": [{
        "asks": [
            ["23200", "0.59959"]
        ],
        "bids": [],
        "ms_t": 1698292358292,
        "symbol": "BTC_USDT",
        "type": "update",
        "version": 5
    }],
    "table": "spot/depth/increase100"
}

返回data字段说明:

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

注意：此数据是解压后的展示, 详情参看数据压缩

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

首先Client端通过订阅请求 {"op": "subscribe", "args": ["spot/depth/increase100:<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请求{"op": "request", "args": ["spot/depth/increase100:<symbol>"] }获得一个最新深度快照(消息里type=snapshot)，并将深度快照中的内容覆盖至本地缓存，然后继续从步骤2执行逻辑。

异常情况：
1. 如果一段时间内没有深度更新，将发一条空消息'asks': [], 'bids': []以通知用户连接是正常的。推送的version跟上一条信息的一样，空消息version=本地缓存version。可以直接丢弃
2. 因为深度快照对价格档位数量有限制，初始快照之外的价格档位并且没有数量变化的价格档位不会出现在增量深度的更新信息内。因此，即使应用来自增量深度的所有更新，这些价格档位也不会在本地 order book 中可见，所以本地的 order book 与真实的 order book 可能会有一些差异。

示例图

PNG

【公共】交易频道

获取最新实时成交数据

推送规则

无需用户登录
订阅成功后会推送增量成交消息(taker成交消息)
推送频率: 变动则推送

订阅请求

订阅请求

{
  "op": "subscribe", 
  "args": ["spot/trade:BTC_USDT"]
}

消息格式:

{"op": "subscribe", "args": ["spot/trade:<symbol>"]}

symbol: 交易对, 如BTC_USDT

订阅成功

订阅成功

{
  "event":  "subscribe",
  "topic":  "spot/trade:BTC_USDT"
}

{"event":"subscribe","topic":"spot/trade:<symbol>"}

订阅成功后，推送数据

推送数据

{
    "table": "spot/trade",
    "data": [{
        "symbol": "ETH_USDT",
        "price": "162.12",
        "side": "buy",
        "size": "11.085",
        "s_t": 1542337219,
        "ms_t": 1542337219120
    }]
}

返回data字段说明:

字段	类型	描述
symbol	String	交易对名称, `BTC_USDT`
side	String	taker订单成交方向（`buy` 或 `sell`）
price	String	taker订单成交价格
size	String	taker订单成交数量
s_t	Long	taker订单成交时间(精确到秒) (字段废弃，后续会下架, 请使用ms_t字段)
ms_t	Long	taker订单成交时间(精确到毫秒)

注意：此数据是解压后的展示, 详情参看数据压缩

【私人】登录

登录订阅格式

请求格式

{"op":"login","args":["<YOUR_API_KEY>", "<timestamp>", "<sign>"]}

API_KEY: 为用户申请的APIKey
timestamp: 为时间戳, 单位是毫秒, 超过 60 秒后会过期
sign: 为签名, sign=CryptoJS.HmacSHA256(timestamp + "#" + api_memo + "#" + "bitmart.WebSocket", secret)

示例

登录示例

{"op": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556"]}

返回

{"event":"login"}

假设用户申请的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

最终的登录参数如下：

{"op": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556"]}

注意

【私人】订单成交进度

可以订阅单个交易对的订单成交进度，也可以1次订阅全部交易对的订单成交进度

推送规则

需用户登录
符合条件的订单会被推送(下单成功，撤单成功，完全成交，部分成交)
推送频率: 变动则推送

订阅请求

单个交易对的订单成交进度订阅请求

{
  "op": "subscribe", 
  "args": ["spot/user/order:BTC_USDT"]
}

全部交易对的订单成交进度订阅请求

{
  "op": "subscribe", 
  "args": ["spot/user/orders:ALL_SYMBOLS"]
}

消息格式:

1.单个交易对的订单成交进度订阅：

{"op": "subscribe", "args": ["spot/user/order:<symbol>"]}

channel: 频道名, 如spot/user/order
symbol: 交易对, 如BTC_USDT

2.全部交易对的订单成交进度订阅:

{"op": "subscribe", "args": ["spot/user/orders:ALL_SYMBOLS"]}

channel: 频道名, 如spot/user/orders
symbol: 查询全部交易对, 固定值：ALL_SYMBOLS

注意：单个交易对和全部交易对，订阅的channel是不一样的

订阅成功

单个交易对的订单成交进度订阅成功

{
  "event":  "subscribe",
  "topic":  "spot/user/order:BTC_USDT"
}

1.单个交易对的订单成交进度订阅成功

{"event":"subscribe","topic":"spot/user/order:<symbol>"}

全部交易对的订单成交进度订阅成功

{
  "event":  "subscribe",
  "topic":  "spot/user/orders:ALL_SYMBOLS"
}

2.全部交易对的订单成交进度订阅成功

{"event":"subscribe","topic":"spot/user/orders:ALL_SYMBOLS"}

订阅成功后，推送数据

推送数据

{
    "data":[
        {
            "symbol":"BTC_USDT",
            "side":"buy",
            "type":"market",
            "notional":"",
            "size":"1.0000000000",
            "ms_t":"1609926028000",
            "price":"46100.0000000000",
            "filled_notional":"46100.0000000000",
            "filled_size":"1.0000000000",
            "margin_trading":"0",
            "state":"4",
            "order_id":"2147857398",
            "order_type":"0",
            "last_fill_time":"1609926039226",
            "last_fill_price":"46100.00000",
            "last_fill_count":"1.00000",
            "exec_type":"M",
            "detail_id":"256348632",
            "client_order_id":"order4872191",
            "create_time":"1609926028000",
            "update_time":"1609926044000",
            "order_mode":"0",
            "entrust_type":"normal",
            "order_state":"partially_filled"
        }
    ],
    "table":"spot/user/order"
}

返回data字段说明:

字段	类型	描述
symbol	String	交易对名称, `BTC_USDT`
order_id	String	订单ID
price	String	委托价格, 单位：定价币
size	String	委托数量, 单位：基础币
notional	String	买入金额，市价买入时返回;否则返回空字符串
side	String	方向 -`buy` -`sell`
type	String	类型 -`limit` -`market`
ms_t	String	订单创建时间(精确到毫秒) (字段废弃，后续会下架，请使用create_time字段)
filled_size	String	已成交数量, 单位：基础币
filled_notional	String	已成交金额, 单位：定价币
margin_trading	String	`0`=币币交易订单 (字段废弃，后续会下架, 请使用order_mode字段)
order_type	String	订单委托方式(字段废弃，后续会下架, 请使用entrust_type字段) -`0`=普通委托 -`1`=只做Maker(Post only) -`2`=全部成交或者立即取消（FOK) -`3`=立即成交并取消剩余（IOC)
state	String	推送订单状态(字段废弃，后续会下架, 请使用order_state字段) -`4`=下单成功,等待成交 -`5`=部分成交 -`6`=完全成交 -`8`=撤销成功 -`12`=部分成交后撤销
last_fill_price	String	此订单最新成交价格（如果没有，推0）
last_fill_count	String	此订单最新成交数量（如果没有，推0）
last_fill_time	String	此订单最新成交时间（如果没有，推0）毫秒
exec_type	String	该账单是maker还是taker产生的 -`M`=Maker -`T`=Taker
detail_id	String	成交 id
client_order_id	String	用户自定义ID
create_time	String	创建订单时间，单位毫秒
update_time	String	订单最后更新时间，单位毫秒
order_mode	String	交易模式 -`spot`=现货 -`iso_margin`=逐仓杠杆
entrust_type	String	订单委托类型 -`normal`=普通委托 -`limit_maker`=只做Maker(Post only) -`ioc`=立即成交并取消剩余（IOC)
order_state	String	订单状态 -`new`=未成交 -`partially_filled`=部分成交 -`filled`=完全成交 -`canceled`=完全撤销 -`partially_canceled`=部分成交已撤销

注意：此数据是解压后的展示, 详情参看数据压缩

【私人】余额变动推送

现货账户余额变动订阅频道

推送规则

需用户登录
符合条件的余额变动(充值、提现、划转、成交、BMX手续费抵扣)
推送频率: 变动则推送

订阅请求

订阅请求

{
  "op": "subscribe",
  "args": ["spot/user/balance:BALANCE_UPDATE"]
}

消息格式:

{"op": "subscribe", "args": ["spot/user/balance:BALANCE_UPDATE"]}

包含所有的币种余额的变动

订阅成功

订阅成功

{
  "event":  "subscribe",
  "topic":  "spot/user/balance:BALANCE_UPDATE"
}

{"event": "subscribe","topic": "spot/user/balance:BALANCE_UPDATE"}

订阅成功后，推送数据

推送数据

{
  "data":[
    {
      "event_type":"TRANSACTION_COMPLETED  ",
      "event_time":"1693364237000",
      "balance_details":[{
        "ccy": "BTC",
        "av_bal": "123.22",
        "fz_bal": "12.56"
      }]
    }
  ],
  "table":"spot/user/balance"
}

返回data字段说明:

字段	类型	描述
event_type	String	余额变动类型 -`TRANSACTION_COMPLETED`=交易成交 -`ACCOUNT_RECHARGE`=账户充值 -`ACCOUNT_WITHDRAWAL`=账户提现 -`ACCOUNT_TRANSFER`=账户划转 -`BMX_DEDUCTION`=BMX手续费抵扣
event_time	String	余额变动时间
balance_details	String	余额变动明细
>ccy	String	变动余额币种名称
>av_bal	String	变动后可用余额
>fz_bal	String	变动后冻结余额

注意：此数据是解压后的展示, 详情参看数据压缩

错误代码

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 格式必须是 Long 类型	30006	401
请求头 X-BM-TIMESTAMP 过期（超过1分钟过期)	30007	401
请求头 X-BM-TIMESTAMP 在recvWindow之外	30007	401
请求参数 recvWindow 格式必须是 Long 类型	30007	401
请求参数 recvWindow 设置不能超过60000，也不能小于0	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

资金账户&子母账户 API 返回错误码

如:httpStatus:200, body:{"code": 1000,"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1","message": "OK","data": {}}

message 错误信息	code 错误码	http状态码
请求成功	1000	200
无效请求（可能body为空，或者int参数传了string数据)	60000	400
资产账户类型account_type错误	60001	400
币种currency不存在	60002	400
该币种的充值通道已经关闭，详情请咨询客服	60003	400
该币种的提现通道已经关闭，详情请咨询客服	60004	400
小于允许提现的最小金额	60005	400
提现最大精确到小数点%d位	60006	400
此提现地址不在您的地址列表中	60007	400
提现余额不足	60008	400
今日可提现额度不足	60009	400
充提id不存在	60010	400
提现地址格式不正确	60011	400
该币种不支持次操作(如禁止IOTA，HLX的充值和提现调用)	60012	400
提现金额必须是%s的整数倍	60013	400
错误的memo，请检查你提交的memo是否正确	60014	400
未认证地址，不允许提现,请到网站上认证并添加您的地址管理中	60015	400
此账户已被禁止充值	60020	403
此账户已被禁止提现	60021	403
修改了安全项，此账户24小时内禁止提现	60022	403
子账号没有操作权限	60026	403
仅支持子账户调用	60027	403
账户状态不可用	60028	403
账户被母账户冻结，请联系母账户解冻	60029	403
无效的method请求	60030	405
不支持的content-type请求	60031	415
账户不存在	60050	500
内部服务错误，详情查看message	60051	500
异常，详情查看message	60052	500
请检查邮箱/电话号码/BitMart CID,并重试	60053	403
子账户不支持提现	60054	403
不支持此币种	60055	403
此提币暂停	60056	403
用户状态不可用	60057	403
监控提款是否会导致现货钱包整体跌破追加保证金风险率。请酌情修改提款金额	60058	403
禁止内部提现	60059	403
无效请求	60060	403
不支持的操作	60061	403
禁止	60062	403
由于安全政策，帐户被冻结。请联系客服	60063	403
超出每日提现额度，为了您的安全，请等待24小时后重试	60064	403
提现用户与目标用户不能相同	60065	403
找不到子账号	61003	400
重复的请求(如使用已存在的requestNo)	61004	400
账户间资产划转不可用	61005	403
子母账户API仅支持机构用户	61006	403
请完成您的机构验证以开通提现功能	61007	403
暂停转出	61008	403

现货行情 API 返回错误码

message 错误信息	code 错误码	http状态码
请求成功	1000	200
没有数据	70000	200
请求参数 param 不能为空	70001	200
请求参数 symbol 无效	70002	200
请求参数 after 无效	71001	200
请求参数 before 无效	71002	200
请求参数 after 或者请求参数 before 是无效的	71003	200
请求参数 kline limit 超出	71004	200
请求参数 step 错误	71005	200

现货&杠杆 API 返回错误码

如:httpStatus:200, body:{"code": 1000,"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1","message": "OK","data": {}}

message 错误信息	code 错误码	http状态码
请求成功	1000	200
无效请求（可能body为空，或者int参数传了string数据)	50000	400
交易对参数Symbol错误，找不到交易对	50001	400
参数From 或者参数To 格式错误	50002	400
参数Step 格式错误	50003	400
K线数据最大返回500条	50004	400
订单id找不到对应数据	50005	400
数量size 不能小于 %s	50006	400
数量size 不能大于 %s	50007	400
价格 price 不能小于 %s	50008	400
count*price 不能小于 %s	50009	400
参数 size 不能为空	50010	400
参数 price 不能为空	50011	400
参数 notional 不能为空	50012	400
limit*offset 不能大于 %s	50013	400
参数 limit 不能为空	50014	400
参数 limit 不能小于1	50015	400
参数 limit 不能大于 %d	50016	400
参数 offset 不能为空	50017	400
参数 offset 不能小于1	50018	400
错误的状态 status. 有效的状态有 [1=下单失败, 2=下单成功, 3=冻结失败, 4=冻结成功, 5=部分成交, 6=完全成交, 7=撤销中, 8=撤销成功	50019	400
余额不足	50020	400
请求参数格式错误	50021	400
服务不可用	50022	400
该交易对不能使用API进行下单	50023	400
订单深度最多返回200条	50024	400
价格 price 不能大于 %s	50025	400
买单价格不能高于开盘价	50026	400
卖单价格不能低于开盘价	50027	400
缺少必要参数	50028	400
参数不匹配	50029	400
订单已经取消	50030	400
订单已经完成	50031	400
订单不存在（已成交或已撤销）	50032	400
订单数量应该大于0小于等于10	50033	400
订单价格过高，没有匹配的深度	50034	400
订单价格过低，没有匹配的深度	50035	400
ioc类型的订单不允许撤单	50036	400
用户自定义订单ID位数不能超过32	50037	400
用户自定义订单ID只允许数字和字母的组合	50038	400
Order_id 和 clientOrderId 不能同时为空	50039	400
该交易币对暂不可用	50040	400
超出查询时间限制	50041	400
clientOrderId重复	50042	400
币种参数currency错误，找不到对应币种	51000	400
杠杆未开户	51001	400
杠杆账户不可用，请联系客服	51002	400
账户受限制，请联系客服	51003	400
输入的值超过最大可借数量	51004	400
输入的值小于最小可借数量	51005	400
输入的数量超过应还数量	51006	400
orderMode下单类型不存在	51007	400
操作受限，请稍后再试	51008	400
参数不匹配：限价单/市价单数量应大于最小应买/卖数量	51009	400
参数不匹配：限价单价格应大于最小可买价格	51010	400
参数不匹配：限价单数量*价格应大于最小成交金额	51011	400
参与不匹配：市价单买单数量应大于最小可买数量	51012	400
参数不匹配：市价单买单下单金额过少	51013	400
参数不匹配：市价单卖单下单数量过少	51014	400
借款数量太少	51015	400
不存在杠杆借款	51024	400
不支持的 OrderMode 类型	52000	400
不支持的 Trade 类型	52001	400
不支持的 Side 类型	52002	400
不支持的 State 类型	52003	400
End time 必须大于或者等于 Start time	52004	400
您的账户已被冻结，请联系客服	53000	403
您的kyc认证国家被限制，请联系客服	53001	403
您的账户还未完成kyc高级认证，请先在网站上完成认证	53002	403
账户权限被主账户关闭	53003	403
您所在的国家或地区不支持此交易对的交易	53004	403
没有权限请求当前接口	53005	403
请完成您的个人认证(初级)	53006	403
请完成您的个人认证（高级）	53007	403
服务在您所在的国家和地区不可用	53008	403
您的账号尚未完成二维码认证，请先完成	53009	403
账户借款受限	53010	403
不支持此 Http Method	57001	405
不支持此 Media Type	58001	415
账号不存在	59001	400
服务内部错误	59002	500
现货钱包服务错误	59003	500
杠杆钱包服务超时	59004	500
杠杆钱包服务被拒绝	59005	500
划转失败	59006	500
交易对风险率数据获取失败	59007	500
直接下单失败	59008	500
借款成功，但是下单失败	59009	500
贷款额度不足	59010	500
获取钱包余额服务超时，请稍后再试	59011	500

WebSocket错误码

错误码格式

{"event":"<operation>", "errorMessage":"", "errorCode":""}

错误码

errorMessage 错误信息	errorCode 错误码
无效的文本内容	90001
无效的 op 参数	90002
无效的 args 参数	90003
无效的 channel 参数	90004
单次订阅topic数量达到上限	90005
单链接订阅的topic总数达到上限	90006
上行消息触发限频（包括ping,pong消息）	90007
重复订阅	90008
非法订阅	90009
API KEY 是空的	91001
API KEY 找不到，请确认输入的是正确	91002
API KEY 已经被冻结	91003
API KEY 过期，请重新申请	91004
已经登录过了	91005
您还未登录，请先登录	91006
签名 sign 是空的	91010
签名 sign 错误的	91011
参数 timestamp 是空的	91021
参数 timestamp 限制1分钟内	91022
参数 timestamp 错误的格式	91023
无效的 symbol 参数	92001
短时间内频繁建立链接	94001
单IP和服务器建立的连接数超出上限	94002
系统内部错误	95000