NAV
代码示例

更新日志

2024-01-16

2023-12-26

2023-12-12

2023-09-19

2023-08-01

2023-07-07

2023-06-20

2023-06-13

2023-06-06

2023-05-18

2023-03-23

2023-03-16

2022-09-22

2022-08-31

2022-08-23

2022-08-18

介绍

API Key 申请

PNG

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

PNG

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

API Key 权限设置

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
提现权限:
接口名称 说明 鉴权类型
/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/v1/cancel_order 取消一个未完成的订单 SIGNED
/spot/v3/cancel_order 取消一个未完成的订单 SIGNED
/spot/v1/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
子账号权限:

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

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/sub/v1/sub-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. "

联系我们

基本信息

API基本信息

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

请求参数设置

HTTP 返回代码

API 返回内容

详细参见参见 错误码列表

签名

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

鉴权类型

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()

body参数设置

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"}'

则设置如下:

假设您申请的key如下:

则右边是一个完整的请求

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

频率限制

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

具体接口限制详细如下:

公开行情接口 接口名称 限制目标 速率
/contract/public/details 获取合约列表详情 IP 12次/2s
/contract/public/depth 获取合约深度 IP 12次/2s
/contract/public/open-interest 获取合约深度 IP 2次/2s
/contract/public/funding-rate 查询当前资金费率 IP 2次/2s
/contract/public/kline 查询K线数据 IP 12次/2s
交易接口 接口名称 限制目标 速率
/contract/private/submit-order 合约下单 X-BM-KEY 24次/2s
/contract/private/cancel-order 取消单个合约订单 X-BM-KEY 40次/2s
/contract/private/cancel-orders 批量撤销合约订单 X-BM-KEY 2次/2s
/contract/private/submit-plan-order 合约计划委托下单 X-BM-KEY 24次/2s
/contract/private/cancel-plan-order 取消单个合约计划委托订单 X-BM-KEY 40次/2s
/contract/private/get-open-orders 查询合约委托订单 X-BM-KEY 50次/2s
/contract/private/order 查询合约订单详情 X-BM-KEY 50次/2s
/contract/private/order-history 查询合约历史订单 X-BM-KEY 6次/2s
/contract/private/trades 查询合约成交明细 X-BM-KEY 6次/2s
/contract/private/assets-detail 查询合约资产明细 X-BM-KEY 12次/2s
/contract/private/position 查询仓位详情 X-BM-KEY 6次/2s
/contract/private/submit-leverage 合约杠杆调整 X-BM-KEY 24次/2s
/account/v1/transfer-contract 合约账户划转现货 X-BM-KEY 1次/2s
/account/v1/transfer-contract-list 查询划转记录 X-BM-KEY 1次/2s
/contract/private/current-plan-order 查询合约计划委托订单记录 X-BM-KEY 50次/2s
子母账户接口 接口名称 限制目标 速率
/account/contract/sub-account/main/v1/sub-to-main 子账户划转到主账户(主账户适用,合约账户) X-BM-KEY 8次/2s
/account/contract/sub-account/main/v1/main-to-sub 主账户划转到子账户(主账户适用,合约账户) X-BM-KEY 8次/2s
/account/contract/sub-account/sub/v1/sub-to-main 子账户划转到主账户(子账户适用,合约账户) X-BM-KEY 8次/2s
/account/contract/sub-account/main/v1/wallet 子账户合约余额(主账户适用,合约账户) X-BM-KEY 12次/2s
/account/contract/sub-account/main/v1/transfer-list 子账户划转历史(主账户适用,合约账户) X-BM-KEY 8次/2s
/account/contract/sub-account/v1/transfer-history 账户划转历史(主,子账户适用,合约账户) X-BM-KEY 8次/2s

REST API

限速判断:

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

Example:

X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
上面的设置,意思是 60 秒内可调用 600 次,当前已调用 10 次
Response Header 说明
X-BM-RateLimit-Remaining 当前时间窗口内已使用的次数
X-BM-RateLimit-Limit 当前时间窗口内最大可调用次数
X-BM-RateLimit-Reset 当前时间窗口,秒为单位

合约公开 API 参数

字段说明

订单状态 (字段:state)

订单方向 (字段:side)

仓位方向 (字段:position_type)

订单类型 (字段:type)

开仓类型 (字段:open_type)

下单方式 (字段:mode)

时间 timestamp

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

公共行情

获取所有合约详情

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/contract/public/details?symbol=BTCUSDT
参数 类型 是否必填 描述
symbol String 选填 交易对名称(选填,默认返回全部)

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "trace": "9b92a999-9463-4c96-91a4-93ad1cad0d72",
  "data": {
    "symbols": [
      {
        "symbol": "BTCUSDT",
        "product_type": 1,
        "open_timestamp": 1594080000,
        "expire_timestamp": 0,
        "settle_timestamp": 0,
        "base_currency": "BTC",
        "quote_currency": "USDT",
        "last_price": "23920",
        "volume_24h": "18969368",
        "turnover_24h": "458933659.7858",
        "index_price": "23945.25191635",
        "index_name": "BTCUSDT",
        "contract_size": "0.001",
        "min_leverage": "1",
        "max_leverage": "100",
        "price_precision": "0.1",
        "vol_precision": "1",
        "max_volume": "500000",
        "min_volume": "1",
        "funding_rate": "0.0001",
        "expected_funding_rate": "0.00011",
        "open_interest": "4134180870",
        "open_interest_value": "94100888927.0433258"
      },
      ...
    ]
  }
}
字段 类型 描述
symbols List 交易对详情数组

交易对详情字段描述:

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

获取深度

获取交易对完整的深度。

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/contract/public/depth?symbol=BTCUSDT
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "trace": "b9bff62d-9ac8-4815-8808-8f745673c096",
  "data": {
    "asks": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "bids": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "timestamp": 1660285421287,
    "symbol": "BTCUSDT"
  }
}
字段 类型 描述
timestamp Long 当前系统时间(时间戳,精确到毫秒)
bids List 买方深度列表
asks List 卖方深度列表
symbol String 交易对

深度详情描述:

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

查询合约持仓量

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/contract/public/open-interest?symbol=BTCUSDT
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)

响应详情

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
    "timestamp": 1661239541734,
    "symbol": "BTCUSDT",
    "open_interest": "4134180870",
    "open_interest_value": "94100888927.0433258"
  }
}
字段 类型 描述
timestamp Long 时间戳
symbol String 合约名称
open_interest String 持仓量
open_interest_value String 持仓量价值

查询当前资金费率

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/contract/public/funding-rate?symbol=BTCUSDT
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "timestamp": 1662518172178,
    "symbol": "BTCUSDT",
    "rate_value": "0.000164",
    "expected_rate": "0.000164",
    "funding_time": 1709971200000,
    "funding_upper_limit": "0.0375",
    "funding_lower_limit": "-0.0375"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
字段 类型 描述
timestamp Long 时间戳
symbol String 合约名称
rate_value String 上一期的资金费率
expected_rate String 下一期的资金费率
funding_time Long 下次结算时间
funding_upper_limit Long 该交易对的资金费率上限
funding_lower_limit Long 该交易对的资金费率下限

查询K线数据

适用于K线数据

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/contract/public/kline?symbol=BTCUSDT&step=5&start_time=1662518172&end_time=1662518172
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
step Long 选填 K线间隔,默认为1分钟 步长: 1, 3, 5, 15, 30, 60, 120, 240, 360, 720, 1440, 4320, 10080
start_time Long 必填 开始时间。时间戳需要是秒级别的
end_time Long 必填 结束时间。时间戳需要是秒级别的

响应详情

响应

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": [{
    "timestamp": 1662518160,
    "open_price": "100",
    "close_price": "120",
    "high_price": "130",
    "low_price": "90",
    "volume": "941008"
    },
    {
    "timestamp": 1662518161,
    "open_price": "99",
    "close_price": "119",
    "high_price": "129",
    "low_price": "89",
    "volume": "941008"
    }
  ]
}
字段 类型 描述
timestamp Long 时间窗口
open_price String 开盘价
close_price String 收盘价
high_price String 最高价
low_price String 最低价
volume String 成交量

资金账户

查询合约资产明细 (KEYED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

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

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
    "currency": "USDT",
    "position_deposit": "100",
    "frozen_balance": "100",
    "available_balance": "100",
    "equity": "100",
    "unrealized": "100"
    },
    {
      "currency": "BTC",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    },
    {
      "currency": "ETH",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    }
  ],
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
字段 类型 描述
currency String 币种
position_deposit String 仓位保证金
frozen_balance String 交易冻结金额
available_balance String 可用金额
equity String 总权益
unrealized String 未实现盈亏

合约交易

查询合约订单详情 (KEYED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/order?symbol=BTCUSDT&order_id=220609666322019
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
order_id String 必填 订单编号

响应详情

响应

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

查询合约历史订单 (KEYED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/order-history?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
start_time Long 选填 开始时间,默认最近7天
end_time Long 选填 结束时间,默认最近7天

响应详情

响应

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

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

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/get-open-orders?symbol=BTCUSDT&order_state=partially_filled&type=market&limit=10
参数 类型 是否必填 描述
symbol String 选填 合约交易对(如BTCUSDT)
type String 选填 订单类型
-limit=限价单
-market=市价单
-trailing=跟踪委托
默认返回全部
order_state String 选填 订单状态
-all=全部(默认)
-partially_filled=部分成交
limit int 选填 返回结果的数量,最大为100,默认100条

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "order_id": "220908185908509",
      "client_order_id": "BM123",
      "price": "14277",
      "size": "7216",
      "symbol": "BTCUSDT",
      "state": 4,
      "side": 3,
      "type": "limit",
      "leverage": "0",
      "open_type": "isolated",
      "deal_avg_price": "14277",
      "deal_size": "7216",
      "create_time": 1662368173000,
      "update_time": 1662368173000
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}
字段 类型 描述
symbol String 合约交易对(如BTCUSDT)
order_id String 订单编号
client_order_id String 用户自定义ID(如果该字段未定义,则返回空)
side Int 订单方向
-1=开多
-2=平空
-3=平多
-4=开空
type String 订单类型
-limit=限价单
-market=市价单
-trailing=跟踪委托单
size String 订单数量
leverage String 杠杆下单倍数
open_type String 开仓类型
-cross=全仓
-isolated=逐仓
deal_avg_price String 成交均价
deal_size String 成交数量
price String 委托价格
size String 委托数量
state Int 订单状态
-2=委托中
activation_price String 激活价格,跟踪委托单返回
callback_rate String 回调幅度,跟踪委托单返回
activation_price_type Int 激活价格类型,跟踪委托单返回
-1=最新成交价
-2=标记价格
create_time Long 创建时间
update_time Long 更新时间

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

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/current-plan-order?symbol=BTCUSDT&type=market&limit=10
参数 类型 是否必填 描述
symbol String 选填 合约交易对(如BTCUSDT)
type String 选填 订单类型
-limit=限价单
-market=市价单
默认返回全部
limit int 选填 返回结果的数量,最大为100,默认100条

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "order_id": "220908185908509",
      "client_order_id": "BM123",
      "executive_price": "14277",
      "trigger_price": "14277",
      "size": "7216",
      "symbol": "BTCUSDT",
      "state": 4,
      "side": 3,
      "mode": 1,
      "price_way": 2,
      "price_type": 1,
      "plan_category": 2,
      "type": "stop_loss",
      "leverage": "0",
      "open_type": "isolated",
      "create_time": 1662368173000,
      "update_time": 1662368173000
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}
字段 类型 描述
symbol String 合约交易对(如BTCUSDT)
order_id String 订单编号
client_order_id String 用户自定义ID(如果该字段未定义,则返回空)
side Int 订单方向
-1=开多
-2=平空
-3=平多
-4=开空
type String 订单类型
-plan=普通计划委托单
-take_profit=止盈委托单
-stop_loss=止损委托单
plan_category Int 止盈止损类型
-1=部分仓位止盈止损
-2=全仓止盈止损
size String 订单数量
leverage String 杠杆下单倍数
open_type String 开仓类型
-cross=全仓
-isolated=逐仓
executive_price String 委托价格
trigger_price String 触发价格
state Int 订单状态
-1=审批中
-2=委托中
preset_take_profit_price_type Int 预设止盈委托价格类型
-1=最新成交价
-2=标记价格
preset_stop_loss_price_type Int 预设止损委托价格类型
-1=最新成交价
-2=标记价格
preset_take_profit_price String 预设止盈价格
preset_stop_loss_price String 预设止损价格
create_time Long 创建时间
update_time Long 更新时间

查询仓位详情 (KEYED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/position?symbol=BTCUSDT
参数 类型 是否必填 描述
symbol String 选填 合约交易对(如BTCUSDT)

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol": "BTCUSDT",
      "leverage": "5",
      "timestamp": 1663814313531,
      "current_fee": "5.00409471",
      "open_timestamp": 1662714817820,
      "current_value": "16680.3157",
      "mark_price": "16673.27053207877",
      "position_value": "18584.272343943943943944339",
      "position_cross": "3798.397624451826977945",
      "maintenance_margin": "4798.397624451826977945",
      "close_vol": "100",
      "close_avg_price": "20700.7",
      "open_avg_price": "20200",
      "entry_price": "20201",
      "current_amount": "899",
      "unrealized_value": "1903.956643943943943944339",
      "realized_value": "55.049173071454605573",
      "position_type": 2
    }
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}
字段 类型 描述
leverage String 杠杆倍数
symbol String 合约名称
current_fee String 当前仓位总费用
open_timestamp Long 开仓时间戳
current_value String 最新价格计算的仓位价值
mark_price String 标记价格计算的仓位价值
position_value String 持仓均价计算的仓位价值
open_avg_price String 开仓均价
close_avg_price String 平仓均价
entry_price String 持仓均价
close_vol String 平仓量
position_cross String 追加到仓位的保证金
maintenance_margin String 维持保证金
current_amount String 当前仓位数量
unrealized_value String 未实现盈亏
realized_value String 已实现盈亏
position_type Int 仓位方向
-1=开多
-2=开空
timestamp Long 当前时间戳

查询合约成交明细 (KEYED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/trades?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
start_time Long 选填 开始时间,默认最近7天
end_time Long 选填 结束时间,默认最近7天

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": [{
    "order_id": "220921197409432",
    "trade_id": "1141853921",
    "symbol": "BTCUSDT",
    "side": 1,
    "price": "19313.3",
    "vol": "108",
    "exec_type": "Maker",
    "profit": false,
    "realised_profit": "-0.00832",
    "paid_fees": "0",
    "create_time": 1663663818589
  }],
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
字段 类型 描述
symbol String 合约交易对(如BTCUSDT)
order_id String 订单编号
trade_id String 成交明细编号
side Int 订单方向
-1=开多
-2=平空
-3=平多
-4=开空
price String 成交价格
vol String 成交量
exec_type String 流动性类型
-Taker
-Maker
profit Boolean 是否盈利
realised_profit String 已实现盈亏
paid_fees String 手续费
create_time Long 创建时间

查询划转列表 (SIGNED)

查询合约账户划转记录

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "currency":"USDT",
    "time_start":1684391137804,
    "time_end":1684392577804,
    "page":1,
    "limit":10,
    "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract-list
参数 类型 是否必填 描述
currency String 币种, 如 BTC
time_start Long 起始时间, 精确到毫秒, 如: 1681701557927
time_end Long 结束时间, 精确到毫秒, 如: 1681701557927
page Int 必填 第几页,取值范围[1,10000]
limit Int 必填 每页返回条数,取值范围[10,100]
recvWindow Long 交易时效时间,取值范围(0,60000], 默认:5000 毫秒
注意

响应详情

响应

{
    "message":"OK",
    "code":1000,
    "trace":"82abff12-b9d9-4f66-89ea-3b604c6d84",
    "data":{
        "records":[{
            "transfer_id":"664651258694168576",
            "currency":"USDT",
            "amount":"0.1",
            "type":"contract_to_spot",
            "state":"FINISHED",
            "timestamp":1638631674326
        }]
    }
}
字段 类型 描述
transfer_id String 划转ID
currency String 币种
amount String 成功划转的金额
type String 划转方向
-spot_to_contract=现货到合约
-contract_to_spot=合约到现货
state String 划转结果
-PROCESSING=等待执行
-FINISHED=成功划转
-FAILED=划转失败
timestamp Long 创建时间戳,精确到毫秒

合约下单 (SIGNED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "client_order_id":"BM1234",
  "side":4,
  "type":"limit",
  "mode":1,
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "price":"2000"
}'
https://api-cloud.bitmart.com/contract/private/submit-order
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
client_order_id String 选填 用户自定义ID(支持小于32位数字+字母的组合)
type String 选填 订单类型
-limit=限价单(默认)
-market=市价单
-trailing=跟踪委托
side Int 必填 订单方向
-1=开多
-2=平空
-3=平多
-4=开空
leverage String 必填 杠杆下单倍数
open_type String 必填 开仓类型
-cross=全仓
-isolated=逐仓
mode Int 选填 下单方式
-1=GTC(默认)
-2=FOK
-3=IOC
-4=Maker Only
price String 必填 下单价格,限价单模式必填。
size Int 必填 订单数量 张数
activation_price String 选填 激活价格,跟踪委托单必填
callback_rate String 选填 回调幅度,跟踪委托单必填,最小值为0.1,最大值为5,其中1表示1%
activation_price_type Int 选填 激活价格类型,跟踪委托单必填
-1=最新成交价
-2=标记价格
preset_take_profit_price_type Int 选填 预设止盈委托价格类型
-1=最新成交价(默认)
-2=标记价格
preset_stop_loss_price_type Int 选填 预设止损委托价格类型
-1=最新成交价(默认)
-2=标记价格
preset_take_profit_price String 选填 预设止盈价格
preset_stop_loss_price String 选填 预设止损价格

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019,
    "price": "25637.2"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
字段 类型 描述
order_id Int 订单编号
price String 订单价格,若提交市价单,将直接返回固定字符串:"market price"

取消单个合约订单 (SIGNED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-order
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
order_id String 必填 订单编号

响应详情

code 返回 1000 表示撤销成功。

响应

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

批量撤销合约订单 (SIGNED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT"
}'
https://api-cloud.bitmart.com/contract/private/cancel-orders
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)

响应详情

code 返回 1000 表示撤销成功。

响应

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

合约计划委托下单 (SIGNED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "side":4,
  "type":"limit",
  "mode":1,
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "price_way":1
}'
https://api-cloud.bitmart.com/contract/private/submit-plan-order
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
type String 选填 订单类型
-limit=限价单(默认)
-market=市价单
-take_profit=止盈单
-stop_loss=止损单
side Int 必填 订单方向
-1=开多
-2=平空
-3=平多
-4=开空
leverage String 必填 杠杆下单倍数
open_type String 必填 开仓类型
-cross=全仓
-isolated=逐仓
mode Int 选填 下单方式
-1=GTC(默认)
-2=FOK
-3=IOC
-4=Maker Only
size Int 必填 订单数量 张数
trigger_price String 必填 触发价格
executive_price String 选填 下单价格,限价单模式必填
price_way Int 必填 价格方向
-1=看涨
-2=看跌
price_type Int 必填 触发价格类型
-1=最新成交价
-2=标记价格
plan_category Int 选填 止盈止损类型
-1=部分仓位止盈止损
-2=全仓止盈止损
preset_take_profit_price_type Int 选填 预设止盈委托价格类型
-1=最新成交价(默认)
-2=标记价格
preset_stop_loss_price_type Int 选填 预设止损委托价格类型
-1=最新成交价(默认)
-2=标记价格
preset_take_profit_price String 选填 预设止盈价格
preset_stop_loss_price String 选填 预设止损价格

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
字段 类型 描述
order_id Int 订单编号

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

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

请求格式

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-plan-order
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
order_id String 必填 订单编号

响应详情

code 返回 1000 表示撤销成功。

响应

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

划转 (SIGNED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "currency":"USDT",
  "amount":"10",
  "type":"spot_to_contract",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract
参数 类型 是否必填 描述
currency String 必填 币种, 如 USDT (当前只支持USDT)
amount String 必填 划转金额,取值范围[0.01,10000000000]
type String 必填 划转方向
-spot_to_contract=现货到合约
-contract_to_spot=合约到现货
recvWindow Long 交易时效时间,取值范围(0,60000], 默认:5000 毫秒

响应详情

响应

{
  "message":"OK",
  "code":1000,
  "trace":"34018ca3-fe24-446a-9e1d-f82edfb3e3",
  "data":{
    "currency":"USDT",
    "amount":"10"
  }
}
字段 类型 描述
currency String 币种
amount String 成功划转的金额

合约杠杆调整 (SIGNED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "leverage":"5",
  "open_type":"isolated"
}'
https://api-cloud.bitmart.com/contract/private/submit-leverage
参数 类型 是否必填 描述
symbol String 必填 合约交易对(如BTCUSDT)
leverage String 选填 杠杆下单倍数
open_type String 必填 开仓类型
-cross=全仓
-isolated=逐仓

响应详情

响应

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "symbol":"ETHUSDT",
    "leverage":"5",
    "open_type":"isolated",
    "max_value":"100"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
字段 类型 描述
symbol String 合约交易对
leverage String 当前杠杆下单倍数
open_type String 开仓类型
-cross=全仓
-isolated=逐仓
max_value String 最大杠杆

子母账户

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

子账户的合约账户向主账户的合约账户划转(主账户适用)

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"USDT",
    "subAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/contract/sub-account/main/v1/sub-to-main`
字段 类型 是否必填 描述
requestNo String uuid或其他通用唯一标识符, 支持长度64
amount String 划转数量
currency String 当前仅支持USDT
subAccount String 子账户用户名

响应详情

响应

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

code 返回 1000 表示划转成功。

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

主账户的合约账户向子账户的合约账户划转(主账户适用)

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"BTC",
    "subAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/contract/sub-account/main/v1/main-to-sub`
字段 类型 是否必填 描述
requestNo String uuid或其他通用唯一标识符, 支持长度64
amount String 划转数量
currency String 当前仅支持USDT
subAccount String 子账户用户名

响应详情

响应

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

code 返回 1000 表示划转成功。

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

子账户的合约账户向主账户的合约账户划转(子账户适用)

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"USDT"
}'
https://api-cloud.bitmart.com/account/contract/sub-account/sub/v1/sub-to-main`
字段 类型 是否必填 描述
requestNo String uuid或其他通用唯一标识符, 支持长度64
amount String 划转数量
currency String 当前仅支持USDT

响应详情

响应

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

code 返回 1000 表示划转成功。

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

获取子账户的合约钱包余额(主账户适用)

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/contract/sub-account/main/v1/wallet?subAccount=[email protected]&currency=USDT
字段 类型 是否必填 描述
subAccount String 子账户用户名
currency String 币种

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "87db8cd43374470f96aacb0e3fcaf34c.77.16872314088656435",
  "data": {
    "wallet": [
      {
        "currency": "USDT",
        "name": "USDT",
        "available": "204.15216696",
        "frozen": "0.00000000"
      }
    ]
  }
}
字段 类型 描述
currency String 币种
name String 加密货币全称
available String 可用余额
frozen String 冻结额

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

查询子账户划转历史(主账户适用)

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/contract/sub-account/main/v1/transfer-list?subAccount=[email protected]&limit=10
字段 类型 是否必填 描述
subAccount String 子账户用户名
limit Int 最近N条记录(取值范围1-100)

响应详情

响应

{
  "message": "OK",
  "code": 1000,
  "trace": "ba950ec2bd114fd7bc069cb812b0129f.62.16887213774200649",
  "data": [
    {
      "fromAccount": "[email protected]",
      "toAccount": "[email protected]",
      "toWalletType": "future",
      "fromWalletType": "future",
      "currency": "USDT",
      "amount": "1",
      "submissionTime": 1686207254
    }
  ]
}
字段 类型 描述
fromAccount String 转出账户
fromWalletType String 转出钱包类型
-future=合约账户
toAccount String 转入账户
toWalletType String 转入钱包类型
-future=合约账户
currency String 币种
amount String 金额
submissionTime Long 请求时间戳精确到秒,(UTF-0)

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

查询账户的划转历史(主账户适用)

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/contract/sub-account/v1/transfer-history?limit=10
字段 类型 是否必填 描述
limit Int 最近N条记录(取值范围1-100)

响应详情

响应

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

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

WebSocket订阅

概述

服务器地址

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

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

指令格式

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

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

解释:

示例:


成功响应格式

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

返回success字段为ture

成功响应格式

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

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

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

示例:


失败响应格式

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

返回 success 字段为 false

失败响应格式

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

连接保持与限制

保持连接

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

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

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

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

ws.send(new PingWebSocketFrame());

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

连接限制

需要注意的是?

空连接

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

订阅

用户可以选择订阅一个或者多个频道,多个频道总长度不能超过4096个字节

订阅消息格式

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

参数说明

示例

  1. 向BitMart服务器发送消息

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

  2. BitMart服务器返回订阅结果, success=true 表示订阅成功

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

取消订阅

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

取消订阅消息格式

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

参数说明

示例

  1. 向BitMart服务器发送消息

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

  2. BitMart服务器返回订阅结果, success=true 表示订阅成功

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

【公共】Ticker频道

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

推送规则

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

请求

请求

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

消息格式:

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

返回

返回

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

返回data字段说明:

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

【公共】深度频道

获取交易对的深度数据。

推送规则

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

请求

请求

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

消息格式:

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

请求其他频道列表

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

返回

返回

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

返回data字段说明:

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

解释说明

depths字段描述

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

【公共】最新成交频道

获取最新成交数据

推送规则

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

请求

请求

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

消息格式:

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

返回

返回

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

返回data字段说明:

字段 数据类型 描述
symbol string 合约交易对(如BTCUSDT)
deal_price string 最新价格
trade_id long 成交id
deal_vol string 成交数量
way int 订单方向
-1=开多买 开空卖
-2=开多买 平多卖
-3=平空买 开空卖
-4=平空买 平多卖
-5=开空卖 开多买
-6=开空卖 平空买
-7=平多卖 开多买
-8=平多卖 平空买
type int 交易记录类型
-1=部分强平的交易记录
-2=破产的交易记录
-4=自动减仓的交易记录
-8=做市交易记录
created_at string 成交时间

【公共】K线频道

获取交易对K线数据

推送规则

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

请求

请求

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

消息格式:

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

请求其他频道列表

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

返回

返回

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

返回data字段说明:

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

【私有】登录

登录订阅格式

请求格式

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

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

示例

登录示例

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

返回

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

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

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

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

最终的登录参数如下:

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

注意

【私有】资产频道

资产余额变动频道

推送规则

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

请求

请求

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

消息格式:

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

返回

返回

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

返回data字段说明:

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

【私有】仓位频道

仓位变化推送频道

推送规则

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

请求

请求

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

消息格式:

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

返回

返回

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

返回data字段说明:

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

【私有】订单频道

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

推送规则

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

请求

请求

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

消息格式:

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

返回

返回

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

返回data字段说明:

字段 数据类型 描述
action int 操作类型
-1=撮合成交
-2=提交订单
-3=取消订单
-4=强平取消订单
-5=被动ADL取消订单
-6=部分强平
-7=破产委托
-8=被动ADL撮合成交
-9=主动ADL撮合成交
symbol string 合约交易对(如BTCUSDT)
order_id string 订单编号
client_order_id string 用户自定义ID
side int 订单方向
-1=开多
-2=平空
-3=平多
-4=开空
type string 订单类型
-limit=限价单
-market=市价单
leverage string 杠杆下单倍数
open_type string 开仓类型
-cross=全仓
-isolated=逐仓
deal_avg_price string 成交均价
deal_size string 成交数量
price string 委托价格
size string 委托数量
state int 订单状态
-2=委托中
-4=已结束
create_time long 创建时间
update_time long 更新时间
plan_order_id string 对应触发的计划单id
last_trade object 当前订单的最近成交信息,若无则返回null

最近成交信息字段描述:

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

合约代理商接口

查询返佣记录 (KEYED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/contract/private/affiliate/rebate-list?page=1&size=10
字段 类型 是否必填 描述
user_id Long 查询用户ID
page Int 第几页
size Int 每页条数
rebate_start_time Long 查询返佣开始时间戳
rebate_end_time Long 查询返佣结束时间戳
register_start_time Long 查询注册开始时间戳
register_end_time Long 查询注册结束时间戳

响应详情

响应

{
  "total": 2,
  "btc_rebate_sum": 0,
  "size": 10,
  "usdt_rebate_sum": 448.9697507148,
  "page": 1,
  "eth_rebate_sum": 0,
  "rebate_detail_page_data": [{
    "rebate_coin": "USDT",
    "trade_user_id": 4225149,
    "total_rebate_amount": 427.1825970576,
    "user_type":1
  }, {
    "rebate_coin": "USDT",
    "trade_user_id": 4225148,
    "total_rebate_amount": 21.7871536572,
    "user_type":1
  }]
}
字段 类型 描述
btc_rebate_sum Decimal btc总返佣
usdt_rebate_sum Decimal usdt总返佣
eth_rebate_sum Decimal eth总返佣
rebate_detail_page_data Object 反佣详细
rebate_coin String 币种
trade_user_id Long 交易用户ID
total_rebate_amount Decimal 用户总佣金
user_type Int 用户类型
-0=间接邀请用户
-1=直接邀请用户

查询交易记录 (KEYED)

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

请求URL

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

请求限制

参见 速率限制详细

请求参数

请求

curl https://api-cloud.bitmart.com/contract/private/affiliate/trade-list?user_id=123456&type=1&page=1&size=10
字段 类型 是否必填 描述
user_id Long 查询用户ID
type Int 查询类型
-1=U本位
-2=币本位
page Int 第几页
size Int 每页条数
start_time Long 查询开始时间戳
end_time Long 查询结束时间戳

响应详情

响应

{
  "total": 60,
  "size": 10,
  "page": 1,
  "list": [{
    "leverage": 20.000000000000000000,
    "symbol": "BTCUSDT",
    "create_time": 1689933471000,
    "open_type": 2,
    "fee": 0.57162048,
    "deal_price": 29771.900000000000000000,
    "realised_profit": 0,
    "way": 1,
    "deal_vol": 32.000000000000000000,
    "select_copy_trade": 1,
    "user_type": 1,
    "user_id": 10048829,
    "category": 2
  }]
}
字段 类型 描述
user_id Long 用户ID
user_type Int 用户类型:
-1=直客
-2=间接
create_time Long 创建时间
symbol string 交易对
leverage Int 杠杠倍率
select_copy_trade Int 类型:
-1=跟单和
-2=非跟单
open_type Int 仓位类型:
-1=逐仓
-2=全仓
way Int 开仓方向:
-1=开多
-2=平空
-3=平多
-4=开空
category Int 委托类型:
-1=限价委托
-2=市价委托
deal_price Decimal 成交均价
deal_vol Decimal 成交量
fee Decimal 手续费
realised_profit Decimal 已实现盈亏

错误代码

Restful错误码

全局 HTTP 返回代码列表

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

鉴权 返回错误码

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

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

合约 API 返回错误码

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

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