NAV
代码示例

未来计划

更新日志

2026-04-14

REST API

介绍

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/v1/withdraw/address/list KEYED 查询提币地址
/account/v2/deposit-withdraw/history KEYED 查询充提历史记录
/account/v1/deposit-withdraw/detail KEYED 查询充提明细
/spot/v1/wallet KEYED 查询用户所有币种钱包余额
/spot/v4/query/order SIGNED orderId查单 (v4)
/spot/v4/query/client-order SIGNED clientOrderId查单 (v4)
/spot/v4/query/open-orders SIGNED 当前委托 (v4)
/spot/v4/query/history-orders SIGNED 历史委托 (v4)
/spot/v4/query/trades SIGNED 成交记录 (v4)
/spot/v4/query/order-trades SIGNED 单笔成交记录 (v4)
/spot/v4/query/algo/order SIGNED 策略委托orderId查单 (v4)
/spot/v4/query/algo/client-order SIGNED 策略委托clientOrderId查单 (v4)
/spot/v4/query/algo/open-orders SIGNED 策略委托当前委托 (v4)
/spot/v4/query/algo/history-orders SIGNED 策略委托历史委托 (v4)
/spot/v1/user_fee KEYED 查询当前用户的基础费率
/spot/v1/trade_fee KEYED 查询用户特定交易对的费率
/spot/v1/margin/isolated/pairs KEYED 查询交易对借款利率与额度
/spot/v1/margin/isolated/account KEYED 查询逐仓杠杆账户信息
/spot/v1/margin/isolated/borrow_record KEYED 查询逐仓杠杆账户信息
/spot/v1/margin/isolated/repay_record KEYED 查询逐仓杠杆账户信息
/contract/private/get-open-orders KEYED 查询合约委托订单
/contract/private/trade-fee-rate KEYED 查询用户交易费率
/contract/private/order KEYED 查询合约订单详情
/contract/private/order-history KEYED 查询合约历史订单
/contract/private/trades KEYED 查询合约成交明细
/contract/private/transaction-history KEYED 查询合约资金流水
/contract/private/assets-detail KEYED 查询合约资产明细
/contract/private/position KEYED 查询仓位详情
/contract/private/position-v2 KEYED 查询仓位详情 V2
/contract/private/current-plan-order KEYED 查询合约计划委托订单
/contract/private/position-risk KEYED 查询合约的仓位风险信息
/contract/private/get-position-mode KEYED 查询合约的持仓模式
/newearn/cloud/v1/saving/product KEYED 查询活期余币宝产品列表
/newearn/cloud/v1/saving/earn KEYED 查询理财持仓
/newearn/cloud/v1/saving/record 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/v4/algo/submit_order SIGNED 策略委托下单
/spot/v4/algo/cancel_order SIGNED 撤销策略委托
/spot/v4/algo/cancel_all SIGNED 全部撤销策略委托
杠杆交易权限:
接口名称 鉴权类型 说明
/spot/v1/margin/submit_order SIGNED 杠杆下单
/spot/v1/margin/isolated/transfer SIGNED 杠杆账户和现货账户之间的资金划转
/spot/v1/margin/isolated/borrow SIGNED 逐仓借款
/spot/v1/margin/isolated/repay SIGNED 逐仓还款
合约交易权限:
接口名称 鉴权类型 说明
/contract/private/submit-order SIGNED 合约下单
/contract/private/cancel-order SIGNED 取消单个合约订单
/contract/private/cancel-orders SIGNED 批量撤销合约订单
/contract/private/submit-plan-order SIGNED 提交合约计划委托订单
/contract/private/cancel-plan-order SIGNED 撤销合约计划委托订单
/account/v1/transfer-contract SIGNED 现货账户与合约账户之间的划转
/account/v1/transfer-contract-list SIGNED 查询合约账户划转列表
/contract/private/submit-tp-sl-order SIGNED 合约设置仓位止盈止损单
/contract/private/modify-plan-order SIGNED 合约修改计划委托单订单
/contract/private/modify-preset-plan-order SIGNED 合约修改预设止盈止损
/contract/private/modify-tp-sl-order SIGNED 合约修改止盈止损委托单
/contract/private/submit-trail-order SIGNED 提交合约跟踪委托订单
/contract/private/cancel-trail-order SIGNED 撤销合约跟踪委托订单
/contract/private/modify-limit-order SIGNED 修改限价委托订单
/contract/private/cancel-all-after SIGNED 限时撤销所有订单设置
/contract/private/set-position-mode SIGNED 设置合约的持仓模式
/contract/private/interest SIGNED 计息记录
/contract/private/auto_repayment SIGNED 自动还款记录
金融权限:
接口名称 鉴权类型 说明
/newearn/cloud/v1/saving/subscribe SIGNED 理财余币宝申购
/newearn/cloud/v1/saving/redeem 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 账户划转历史(主,子账户适用,合约账户)
合约代理商权限:
接口名称 鉴权类型 说明
/contract/private/affiliate/rebate-list KEYED 查询返佣记录
/contract/private/affiliate/rebate-api KEYED 查询API返佣数据
/contract/private/affiliate/rebate-user KEYED 查询用户返佣数据
/contract/private/affiliate/trade-list KEYED 查询交易记录
/contract/private/affiliate/deposit-withdrawal-list KEYED 查询邀请用户出入金记录
/contract/private/affiliate/rebate-inviteUser 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如下:

则右边是一个完整的请求

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

理财余币宝

查询产品列表 (KEYED)

查询活期余币宝产品列表

请求格式

GET https://api-cloud.bitmart.com/newearn/cloud/v1/saving/product

请求限制

基于UID,10次/2秒

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
"https://api-cloud.bitmart.com/newearn/cloud/v1/saving/product?currentPage=1&sizePage=10"
字段 类型 是否必填 描述
coinName String 币种名称
currentPage Int 当前分页号,默认1
sizePage Int 分页大小,默认1,最大:100

响应详情

响应

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": {
        "total": 10,
        "list": [
            {
                "productId": "1001",
                "coinName": "USDT",
                "productTag": "[\"HOT\"]",
                "apy": "5.00%",
                "minPurchaseAmount": "1",
                "maxPurchaseAmount": "100000",
                "additionalApy": "1.00%",
                "hasTierRate": true,
                "tierRate": [
                    {
                        "minPurchaseAmount": "1",
                        "maxPurchaseAmount": "10000",
                        "apy": "5.00%"
                    },
                    {
                        "minPurchaseAmount": "10000",
                        "maxPurchaseAmount": "100000",
                        "apy": "4.00%"
                    }
                ]
            }
        ]
    }
}
字段 类型 描述
total Long 记录总数
productId String 产品id
coinName String 币种名称
productTag String 产品标签
apy String 利率
minPurchaseAmount String 最小申购金额
maxPurchaseAmount String 最大申购金额
additionalApy String 额外收益
hasTierRate Boolean 是否存在阶梯利率
minPurchaseAmount String 阶梯利率左区间
maxPurchaseAmount String 阶梯利率右区间
apy String 阶梯利率

申购 (SIGNED)

余币宝活期理财产品申购

请求格式

POST https://api-cloud.bitmart.com/newearn/cloud/v1/saving/subscribe

请求限制

基于UID,10次/2秒

请求参数

请求

curl -X POST -H 'X-BM-KEY:{{AccessKey}}' \
     -H 'X-BM-SIGN:{{Signature}}' \
     -H 'X-BM-TIMESTAMP:{{Timestamp}}' \
     -H 'Content-Type: application/json' \
     -d '{"productId":"1001","amount":"100","requestNo":"unique-request-id-001"}' \
     "https://api-cloud.bitmart.com/newearn/cloud/v1/saving/subscribe"
字段 类型 是否必填 描述
productId String 产品id
amount String 数量
requestNo String 请求唯一键,长度20,允许为0-9数字,如:20000009000000300000

响应详情

响应

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": true
}
字段 类型 描述
data Boolean 是否成功

赎回 (SIGNED)

余币宝活期理财产品赎回

请求格式

POST https://api-cloud.bitmart.com/newearn/cloud/v1/saving/redeem

请求限制

基于UID,10次/2秒

请求参数

请求

curl -X POST -H 'X-BM-KEY:{{AccessKey}}' \
     -H 'X-BM-SIGN:{{Signature}}' \
     -H 'X-BM-TIMESTAMP:{{Timestamp}}' \
     -H 'Content-Type: application/json' \
     -d '{"earnId":"200001","amount":"50","requestNo":"unique-request-id-002"}' \
     "https://api-cloud.bitmart.com/newearn/cloud/v1/saving/redeem"
字段 类型 是否必填 描述
earnId String 理财订单id
amount String 数量
requestNo String 请求唯一键,长度20,允许为0-9数字,如:20000009000000300000

响应详情

响应

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": true
}
字段 类型 描述
data Boolean 是否成功

查询理财持仓 (KEYED)

查询余币宝活期理财持仓

请求格式

GET https://api-cloud.bitmart.com/newearn/cloud/v1/saving/earn

请求限制

基于UID,10次/2秒

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
"https://api-cloud.bitmart.com/newearn/cloud/v1/saving/earn?currentPage=1&sizePage=10"
字段 类型 是否必填 描述
coinName String 币种名称
productId String 产品id
currentPage Int 当前分页号,默认1
sizePage Int 分页大小,默认1,最大:100

响应详情

响应

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": {
        "total": 5,
        "list": [
            {
                "earnId": "200001",
                "productId": "1001",
                "coinId": 1,
                "coinName": "USDT",
                "productTag": "[\"HOT\"]",
                "apy": "5.00%",
                "totalProfit": "10",
                "autoSubscribe": true,
                "additionalApy": "1.00%",
                "hasTierRate": true,
                "tierRate": [
                    {
                        "minPurchaseAmount": "1",
                        "maxPurchaseAmount": "10000",
                        "apy": "5.00%"
                    }
                ]
            }
        ]
    }
}
字段 类型 描述
total Long 记录总数
earnId String 理财订单id
productId String 产品id
coinId Int 币种id
coinName String 币种名称
productTag String 产品标签
apy String 利率
totalProfit String 累计收益
autoSubscribe Boolean 自动申购状态
additionalApy String 额外收益
hasTierRate Boolean 是否存在阶梯利率
minPurchaseAmount String 阶梯利率左区间
maxPurchaseAmount String 阶梯利率右区间
apy String 阶梯利率

查询历史记录 (KEYED)

查询余币宝活期历史记录(申购/赎回/发息)

请求格式

GET https://api-cloud.bitmart.com/newearn/cloud/v1/saving/record

请求限制

基于UID,10次/2秒

请求参数

请求

curl -H 'X-BM-KEY:{{AccessKey}}'
"https://api-cloud.bitmart.com/newearn/cloud/v1/saving/record?type=subscribe&currentPage=1&sizePage=10"
字段 类型 是否必填 描述
type String 类型:subscribe(申购记录)、redeem(赎回记录)、interest(发息记录)
startTime Long 发生时间,精确到毫秒,如:1681701557927
endTime Long 结束时间,精确到毫秒,如:1681701557927
coinName String 币种名称
currentPage Int 当前分页号,默认1
sizePage Int 分页大小,默认1,最大:100

响应详情

响应

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": {
        "total": 20,
        "list": [
            {
                "type": "subscribe",
                "recordId": "300001",
                "productId": "1001",
                "coinName": "USDT",
                "amount": "100",
                "productTag": "[\"HOT\"]",
                "time": 1681701557927,
                "subscribeType": "NORMAL"
            }
        ]
    }
}
字段 类型 描述
total Long 记录总数
type String 记录类型
recordId String 记录id
productId String 产品id
coinName String 币种名称
amount String 数量
productTag String 产品标签
time Long 发生时间,精确到毫秒,如:1681701557927
subscribeType String 申购类型,AUTO为自动申购,NORMAL为普通申购

错误代码

Restful错误码

理财 API 返回错误码

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

message 错误信息 code 错误码 http状态码
请求成功 1000 200
无效请求(可能body为空,或者int参数传了string数据) 80000 400
产品不存在 80001 400
余额不足 80002 400
订单金额错误,如精度异常 80003 400
产品余量不足 80004 400
该时间段不处理订单 80005 400
用户累计订阅超过限制 80006 400
用户累计认购限额应小于总发行量且大于最低认购量 80007 400
风控限制,无权申购 80008 400
风控限制,无权赎回 80009 400
产品售卖时间限制,结束时间小于开始时间 80010 400
产品已停止售卖 80011 400
参数错误 80012 400
幂等请求 80013 400
机构用户不得订阅 80014 400
kyc无效级别,需要验证kyc level2 80015 400
系统错误 80016 400
理财无效国家,服务不可用 80017 400
产品子类型错误 80018 400
风控限制,业务类型无权操作 80019 400
没有该资产 80020 400
申购金额应大于订单最小金额 80021 400
类型参数错误 80022 400