入门指引

欢迎使用BitMart开发者文档。此文档为用户提供了一整套简单而又强大的开发工具,旨在帮助用户快速、高效地将BitMart交易功能整合到自己的应用当中。

Restful API分成两类,分别是交易和行情。交易API需要认证才能交易并获取其他账户信息。行情API提供的市场数据是公开的。

访问BitMart市场数据API, 您需要同意 市场数据协议.

 

免责声明

所有API均由您自担风险和费用使用。 对于此环境下相关的任何疏忽,错误,安全性损害,故障,网络攻击或其他不可抗力,我们概不负责。 因此你不能向我们追责,并索赔因您使用此环境造成的任何损害或损失。

 

联系我们

加入我们的 Telegram API Group.

 

Q&A

Q: 我们能同时使用多个有效token吗?

A: 可以。你可以请求多个token,并同时使用它们。

Q: 每次调用API都需要请求token吗?

A: 不需要。Token的有效期是2小时,也就是说在token失效前您可以一直调用API。但是token的请求不能超出次数限制(5次/分钟)。

Q: REST API的请求次数限制是多少?

A: token 的请求是 5次/分钟,其他 RESTful api endpoint 的请求最多为1000次/秒。 我们通过IP限制API的请求次数。

Q: API还有其他限制吗?

A: 有,我们的后台会评估用户的交易行为。对于滥用API的用户,我们会对该账号做冻结处理,冻结时长通常是1到7天。

评估基于以下规则:

  • 频繁占据深度图的bid1与ask1
  • 频繁不间断的挂单与撤单, 而没有任何成交
  • 成交率(交易单数/总下单数)以及成交量比例(成交额/下单总额)远远低于用户的正常水平
  • 与BMX相关交易对会进行放大处理
 

更新日志

 

2019-08-28

  • 新的websocket已经上线,我们将不再维护旧的接口。更多详细信息请参考Websocket
 

2019-02-14

  • 下单和撤单必须带上X-BM-SIGNATURE的http头
  • 新增交易历史API, 方便用户跟踪成交历史。
  • 深度 API的precision参数是可选的。
  • Ticker API 新增symbol_id
  • 提升下单性能。
 

API 说明

BitMart Rest API包括现货交易API和合约交易API,

 

请求地址

现货交易: https://openapi.bitmart.com

合约交易: https://api-cloud.bitmart.com

 

参数

POST请求的参数,需要放在请求Body里面(form表单或json形式)。

GET请求的参数,以下面格式追加到URL后面。 /<endpoint>/?parameter=value

 

认证和验签

在使用认证接口前,需要进行认证得到access token,然后才能使用该access token来访问相关的接口。 要获取到access token,首选需要申请API KEY和API SECRET

 

API KEY和API SECRET

1、首先需要在登录账户 '账户信息'->'安全设置'-'API' 中设置里申请API KEY 和API SECRET Contract API KEY

2、然后添加相应类型API KEY,如下图所示操作 Contract API KEY

注:图中为获取合约api key,现货api key需要另外选择'现货交易'申请。

3、请妥善保管你得到的API KEY 和API SECRET

 

获取 Access Token

通过上面操作得到的备注名(memo)、API KEY 和API SECRET 首先生成Client Secret。 使用API SECRET作为密钥,对 apiKey + ":" + apiSecret + ":" + memo 进行HMAC_SHA256加密。

字段
API Key 6591f7c2491db0a23a1d8ad6911c825e
API Secret 8c08d9d5c3d15b105dbddaf96e427ac6
memo mymemo (memo是生成api key时由用户填写, 您可以登录bitmart.com,在账户页面查看你的api key对应的memo)

下面演示使用Linux命令来生成Client Secret

[linux]$ echo -n "6591f7c2491db0a23a1d8ad6911c825e:8c08d9d5c3d15b105dbddaf96e427ac6:mymemo" | openssl dgst -sha256 -hmac "8c08d9d5c3d15b105dbddaf96e427ac6"
(stdin)= 18b9beb027d9ee75202655f37344ea5829c5c0d66a0781bf642bb3e944cf5019

生成Client Secret后,下一步是请求BitMart开放平台获取Access Token。 客户端需要将以下参数以application/x-www-form-urlencoded的格式发送到认证接口。

 

请求URL

现货交易

Header: Content-Type: application/x-www-form-urlencoded

URL: POST https://openapi.bitmart.com/v2/authentication

合约交易

Header: Content-Type: application/x-www-form-urlencoded

URL: POST https://api-cloud.bitmart.com/v1/authentication

 

请求参数

curl -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=xxxxxxxxxxx&client_secret=cccccccccccc"  https://api-cloud.bitmart.com/v1/authentication
import requests
import json
import hmac
import hashlib

def create_sha256_signature(key, message): 
    return hmac.new(key, message, hashlib.sha256).hexdigest()

def get_access_token(api_key, api_secret, memo):
    url = "https://openapi.bitmart.com/v2/authentication"
    message = api_key + ':' + api_secret + ':' + memo
    data = {"grant_type": "client_credentials", "client_id": api_key, "client_secret": create_sha256_signature(api_secret, message)}
    response = requests.post(url, data = data)
    print(response.content)
    accessToken = response.json()['access_token']
    return accessToken

if __name__ == '__main__':
    access_token = get_access_token(api_key, client_secret, memo)
    print access_token

package main

import (
    "bytes"
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

var (
    api_key    = "6591f7c2491db0a23a1d8ad6911c825e"
    api_secret = "8c08d9d5c3d15b105dbddaf96e427ac6"
    memo       = "mymemo"
    endpoint   = "https://openapi.bitmart.com"
)

type Token struct {
    AccessToken string  `json:"access_token"`
    ExpiresIn   float64 `json:"expires_in"`
}

#参数需要utf8编码
func create_sha256_signature(key string, message string) string {
    mac := hmac.New(sha256.New, []byte(key))
    _, err := mac.Write([]byte(message))
    if err != nil {
        panic(err)
    }
    return hex.EncodeToString(mac.Sum(nil))
}

func get_access_token(api_key string, api_secret string, memo string) string {
    auth_url := endpoint + "/v2/authentication"
    message := fmt.Sprintf("%s:%s:%s", api_key, api_secret, memo)

    data := url.Values{}
    data.Set("grant_type", "client_credentials")
    data.Set("client_id", api_key)
    data.Set("client_secret", create_sha256_signature(api_secret, message))

    buf := bytes.NewBuffer([]byte(data.Encode()))

    res, err := http.Post(auth_url, "application/x-www-form-urlencoded", buf)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    token := Token{}
    err = json.Unmarshal(body, &token)
    if err != nil {
        panic(err)
    }

    return token.AccessToken
}

func main() {
    access_token := get_access_token(api_key, api_secret, memo)
    fmt.Println(access_token)
}

参数 类型 描述
grant_type String 必须。值必须是 "client_credentials"
client_id String 必须。 您申请的API key
client_secret String 必须。 HMAC-SHA256签名的参数

请求返回值json格式:

{
"access_token": "EQqQa7S48pkwkyIHTo1v6m2ZUqYhSNY1fr77HF2WfColvSXX3V2dr/yJVYsRK3QF/N7I++veKyIDO2SQEG+QcowtXxHeFq4Qq8o7UyBA0+g0PV6rd76hXSxZJIFLNnjbYs2Ko2kefbVZee1PJc0+IplUEqqJ8GOZ/NlxDnivqnfTMMqqHvB8/ePEW2s9Qe6Ke3SffUPsPU0E9PBMuCyhaZua6V8H3Ba5Uea4xnmXjAGw94XlI1EppOQHuXR3HCf/cx4bo0RXKnSV1hcCTjWj7yJ+TqBgRQWy+m7u9Xs8F4EyRVJvd+vJ3+XmMxbAoN1G",
"expires_in": 7200
}
 

调用需要认证的请API

请求必须包含以下两个http头信息:

  • X-BM-AUTHORIZATION
  • X-BM-TIMESTAMP

X-BM-AUTHORIZATION

  • 现货交易:即上一步操作获取到的Bearer+Access Token,例如: 若token=xxxxx1234, 则X-BM-AUTHORIZATION=Bearerxxxxx1234。

  • 合约交易:即上一步操作获取到的Access Token,例如: 若token=xxxxx1234, 则X-BM-AUTHORIZATION=xxxxx1234。

X-BM-TIMESTAMP 头必须是UTC毫秒数,请参考Unix Epoch

  • timestamp必须在服务器时间的60s之内,否者服务器会拒绝你的请求。如果你不确定你的时间是否和BitMart服务器一致,我们推荐使用APItime查询服务器时间。

  • 通常,请求和响应都是application/json的Content-Type, 并且按照通用的http status返回响应,成功返回Http Status=200,其他失败。

  • 另外,部分请求Content-Type=application/x-www-form-urlencoded;部分请求需要进行参数签名。

 

对参数进行签名

部分请求需要进行参数签名(看具体api接口描述),请按照下面方式进行签名认证 1、将所有参数值(转字符串)+时间戳(转字符串)进行字典升序排序;

2、将排序好的参数按照下面方式进行拼接: param1=10value1&timestamp=1585559188970&param2=2value2&param3=3value3

3、使用Client Secret 作为密钥 对上面字符串进行HmacSHA256 签名;

4、将得到的签名放入到Header的 X-BM-SIGNATURE,并且X-BM-TIMESTAMP=上面放入签名参数中的timestamp;

 

现货交易API

 

API 域名

https://openapi.bitmart.com

 

公开访问接口

 

获取Ping

import requests

url = "https://openapi.bitmart.com/v2/ping"

response = requests.request("GET", url)

print(response.text)

测试服务器的连通性

上面的请求会返回如下的json消息:

{}
 

时间接口

import requests

url = "https://openapi.bitmart.com/v2/time"

response = requests.request("GET", url)

print(response.text)

获取服务器时间 (毫秒表示)。

上面的请求会返回如下的json消息:

{
   "server_time": 1527777538000
}
 

获取加密货币接口

import requests

url = "https://openapi.bitmart.com/v2/currencies"

response = requests.request("GET", url)

print(response.text)

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

上面的请求会返回如下的json消息:

[
   {
      "id":"ETH",
      "name":"Ethereum",
      "withdraw_enabled":true,
      "deposit_enabled":true
   },
   ...
]
 

交易对列表接口

import requests

url = "https://openapi.bitmart.com/v2/symbols"

response = requests.request("GET", url)

print(response.text)

获取所有交易度列表。

上面的请求会返回如下的json消息:

[  
   "BMX_ETH",
   "XLM_ETH",
   "MOBI_ETH",
   ...
]
 

全部交易对详情接口

import requests

url = "https://openapi.bitmart.com/v2/symbols_details"

response = requests.request("GET", url)

print(response.text)

获取全部交易对信息。

上面的请求会返回如下的json消息:

[
    {
        "id":"BMX_ETH",
        "base_currency":"BMX",
        "quote_currency":"ETH",
        "quote_increment":"0.1",
        "base_min_size":"0.1",
        "base_max_size":"100000000",
        "price_min_precision":6,
        "price_max_precision":8,
        "expiration":"NA"
    },
    ...
]
 

响应详情

字段 类型 描述
id string 交易对id
base_currency string 交易货币币种
quote_currency string 计价货币币种
quote_increment string 最小下单量,也是最小下单量增量
base_min_size string 最小交易量
base_max_size string 最大交易量
price_min_precision number 最小价格精度(小数位) 用来查询k线和深度
price_max_precision number 最大价格精度(小数位) 用来查询k线和深度
expiration string 交易对的过期时间
 

获取Ticker信息接口

import requests

url = "https://openapi.bitmart.com/v2/ticker?symbol=BMX_ETH"

response = requests.request("GET", url)

print(response.text)

Ticker是市场状态的概览,包含最新成交价、买一价、卖一价和24小时交易量的快照信息。

 

请求参数

参数 类型 描述
symbol query 交易对symbol (可选, 默认返回所有交易对的tiker信息)

上面的请求会返回如下的json消息:

{  
    "volume":"17603607.6",
    "ask_1":"0.00010030",
    "base_volume":"1765.0",
    "lowest_price":"0.00009900",
    "bid_1":"0.00009901",
    "highest_price":"0.00011000",
    "ask_1_amount":"211",
    "current_price":"0.00009944",
    "fluctuation":"-0.0058",
    "symbol_id":"BMX_ETH",
    "url":"https://www.bitmart.com/trade?symbol=BMX_ETH",
    "bid_1_amount":"95"
}
 

响应详情

字段 类型 描述
symbol_id string 交易对symbol
volume string 交易总量
base_volume string //TOOD Target volume
highest_price string 24小时最高价
lowest_price string 24小时最低价
current_price string 当前价
ask_1 string 卖1价
ask_1_amount string 卖1量 |
bid_1 string 买1价
bid_1_amount string 买1量 |
fluctuation string 24小时涨跌幅
url string bitmart.com上的交易页链接
 

Steps

import requests

url = "https://openapi.bitmart.com/v2/steps"

response = requests.request("GET", url)

print(response.text)

获取平台支持的全部k线步长,用分钟表示,最小1分钟。

上面的请求会返回如下的json消息:

[
   1,
   3,
   5,
   15,
   30,
   45,
   60,
   120,
   180,
   240,
   1440,
   10080,
   43200
]
 

K线接口

import requests

url = "https://openapi.bitmart.com/v2/symbols/BMX_ETH/kline?step=15&from=1525760116000&to=1525769116000"

response = requests.request("GET", url)

print(response.text)

获取指定交易对的指定时间范围内的k线列表

 

请求参数

参数 类型 描述
symbol path 交易对symbol
from query 开始时间 (毫秒表示)
to query 结束时间 (毫秒表示)
step query k线步长Steps (用分钟表示, 默认1分钟)

上面的请求会返回如下的json消息:

[  
    {  
        "timestamp":1525761000000,
        "open_price":"0.010130",
        "highest_price":"0.010130",
        "lowest_price":"0.010130",
        "current_price":"0.010130",
        "volume":"0.000000"
    },
    {  
        "timestamp":1525761900000,
        "open_price":"0.010130",
        "highest_price":"0.010130",
        "lowest_price":"0.010130",
        "current_price":"0.010130",
        "volume":"0.000000"
    },
    {  
        "timestamp":1525763700000,
        "open_price":"0.010130",
        "highest_price":"0.010130",
        "lowest_price":"0.010130",
        "current_price":"0.010130",
        "volume":"0.000000"
    },
    ...
]
 

响应详情

字段 类型 描述
data array k线列表
current_price string 当前价格
timestamp numeric 时间戳 (毫秒表示)
volume string 交易总量
highest_price string 最高价
lowest_price string 最低价
open_price string 开盘价
 

深度接口

import requests

url = "https://openapi.bitmart.com/v2/symbols/BMX_ETH/orders?precision=6"

response = requests.request("GET", url)

print(response.text)

获取完整的深度

 

请求参数

参数 类型 描述
symbol path 交易对symbol
precision query 价格精度, 精度范围在交易对详情里定义

precision是可选的。 如果未传, 默认使用 symbols details返回的price_max_precision

上面的请求会返回如下的json消息:

{  
   "buys":[
      {
         "amount":"4800.00",
         "total":"4800.00",
         "price":"0.000767",
         "count":"1"
      },
      {
         "amount":"99996475.79",
         "total":"100001275.79",
         "price":"0.000201",
         "count":"1"
      },
      ...
   ],
   "sells":[
      {
         "amount":"100.00",
         "total":"100.00",
         "price":"0.007000",
         "count":"1"
      },
      {
         "amount":"6997.00",
         "total":"7097.00",
         "price":"1.000000",
         "count":"1"
      },
      ...
   ]
}
 

响应详情

字段 类型 描述
amount string 当前价格深度的总量
total string 当前价格深度之上(包含当前)的总量累加
price string 当前深度的价格
count string 当前价格深度的总订单数
buys array 买单深度列表
sells array 卖单深度列表
 

成交历史接口

import requests

url = "https://openapi.bitmart.com/v2/symbols/BMX_ETH/trades"

response = requests.request("GET", url)

print(response.text)

获取指定交易对的最近成交记录。

 

请求参数

参数 类型 描述
symbol path 交易对symbol

上面的请求会返回如下的json消息:

[  
   {
      "amount":"0.05768509",
      "order_time":1527057452000,
      "price":"0.004811",
      "count":"11.99",
      "type":"buy"
   },
   ...
]
 

响应详情

字段 类型 描述
amount string 当前交易成交的总额
order_time number 成交时间 (毫秒表示)
price string 成交价格
count string 成交数量
type String maker下单类型 (buy or sell)
 

认证接口

 

钱包余额

import requests

url = "https://openapi.bitmart.com/v2/wallet"

// timestamp is in milliseconds and the authorization header is "Bearer " + token
headers = {"X-BM-TIMESTAMP": xxx, "X-BM-AUTHORIZATION": "Bearer xxxx-here-is-the-access-token"}

response = requests.get(url, headers=headers)

print(response.text)
func main() {
    access_token := get_access_token(api_key, api_secret, memo)

    URL := endpoint + "/v2/wallet"

    req, _ := http.NewRequest("GET", URL, nil)

    req.Header.Add("X-Bm-Timestamp", fmt.Sprintf("%d", time.Now().UnixNano()/1000000))
    req.Header.Add("X-Bm-Authorization", "Bearer "+access_token)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

获取钱包余额

上面的请求会返回如下的json消息:

[
   {
        "id": "BTC"
        "available": 10,
        "name": "Bitcoin",
        "frozen": 0,
    }, 
    ...
]
 

响应详情

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

下单接口

创建一个订单。

 

HMAC SHA256签名

HMAC SHA256签名将作为 X-BM-SIGNATURE 头信息随请求发送.

[linux]$ echo -n "amount=1&price=1&side=buy&symbol=BMX_ETH" | openssl dgst -sha256 -hmac "8c08d9d5c3d15b105dbddaf96e427ac6"
(stdin)= 2302088e474141fc7b498d0fa96c9cc2eda39a5a24fd1495d469d0a72e5fd483

使用linux命令行工具 echo, openssl , curl生成签名。

字段 类型 描述
symbol string 交易对symbol
side string buysell
amount string 下单数量
price string 下单价格

签名参数必须先按字母排序,比如此例中顺序是amount, price, side and symbol。 请看示例:

import requests
import hmac
import hashlib
from urllib import urlencode

url = "https://openapi.bitmart.com/v2/orders"

// timestamp is in milliseconds and the authorization header is "Bearer " + token
// X-BM-SIGNATURE is the HMAC SHA256 signature of the request parameters encrypted by API Secret

secret = "***"
headers = {"X-BM-TIMESTAMP": ***, "X-BM-AUTHORIZATION": "***", "Content-Type": "application/json"}

// notice: the price and amount should be formatted as *.******, not scientific notation
// amount = format(amount, ".10f")
// price = format(price, ".10f")
data = {"symbol": "BMX_ETH", "amount": 1,"price": 1,"side": "buy"}

// notice: the parameters should be sorted in alphabetical order
sorted_data = sorted(data.items(), key=lambda d: d[0], reverse=False)
message = str(urlencode(sorted_data))
signed_message = hmac.new(secret, message, hashlib.sha256).hexdigest()

// if you are using python 3, it will be a little different to sign the message
// you can use: 
// signed_message = hmac.new(bytes(secret, "utf-8"), bytes(message, "utf-8"), hashlib.sha256).hexdigest()

// add signed_message to the headers
headers["X-BM-SIGNATURE"] = signed_message

data = json.dumps(data)

response = requests.post(url, data=data, headers=headers)

print(response.text)
func main() {
    amount := 1.0
    price := 1.0
    side := "buy"
    symbol := "BMX_ETH"

    access_token := get_access_token(api_key, api_secret, memo)

    URL := endpoint + "/v2/orders"

    jsdata, err := json.Marshal(map[string]interface{}{
        "amount": amount,
        "price":  price,
        "side":   side,
        "symbol": symbol,
    })
    if err != nil {
        panic(err)
    }

    buf := bytes.NewBuffer(jsdata)

    message := fmt.Sprintf(
        "amount=%s&price=%s&side=%s&symbol=%s",
        strconv.FormatFloat(amount, 'f', -1, 64),
        strconv.FormatFloat(price, 'f', -1, 64),
        side,
        symbol,
    )

    req, _ := http.NewRequest("POST", URL, buf)

    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("X-Bm-Timestamp", fmt.Sprintf("%d", time.Now().UnixNano()/1000000))
    req.Header.Add("X-Bm-Authorization", "Bearer "+access_token)
    req.Header.Add("X-Bm-Signature", create_sha256_signature(api_secret, message))

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

请求json对象如下:

{
   "symbol":"BMX_ETH",
   "amount":1,
   "price":1,
   "side":"buy"
}

上面的请求会返回如下的json消息:

{
   "entrust_id":1223181
}
 

响应详情

字段 类型 描述
entrust_id string 订单id
 

取消订单接口

取消指定订单。

 

HMAC SHA256签名

HMAC SHA256签名将作为 X-BM-SIGNATURE 头信息随请求发送.

[linux]$ echo -n "entrust_id=1223181" | openssl dgst -sha256 -hmac "8c08d9d5c3d15b105dbddaf96e427ac6"
(stdin)= de4ed768cea4eb2f0fe081009eab1f41c5fd6ff6ed53768df7fe252472c257b3
字段
entrust_id 1223181

使用linux命令行工具 echo, openssl , curl生成签名。

import requests
import hmac
import hashlib
from urllib import urlencode

entrust_id = ***
url = "https://openapi.bitmart.com/v2/orders/%s" % entrust_id

// timestamp is in milliseconds and the authorization header is "Bearer " + token
// X-BM-SIGNATURE is the HMAC SHA256 signature of the request parameters encrypted by API Secret

secret = "***"
headers = {"X-BM-TIMESTAMP": ***, "X-BM-AUTHORIZATION": "***"}

data = {"entrust_id": entrust_id}

// notice: the parameters should be sorted in alphabetical order
sorted_data = sorted(data.items(), key=lambda d: d[0], reverse=False)
message = str(urlencode(sorted_data))
signed_message = hmac.new(secret, message, hashlib.sha256).hexdigest()

// add signed_message to the headers
headers["X-BM-SIGNATURE"] = signed_message

response = requests.delete(url, headers=headers)

print(response.text)
func main() {
    entrust_id := "1223181"
    access_token := get_access_token(api_key, api_secret, memo)

    URL := endpoint + "/v2/orders/"
    URL += entrust_id

    message := fmt.Sprintf("entrust_id=%s", entrust_id)

    req, _ := http.NewRequest("DELETE", URL, nil)

    req.Header.Add("X-Bm-Timestamp", fmt.Sprintf("%d", time.Now().UnixNano()/1000000))
    req.Header.Add("X-Bm-Authorization", "Bearer "+access_token)
    req.Header.Add("X-Bm-Signature", create_sha256_signature(api_secret, message))

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

上面的请求会返回如下的json消息:

{}
 

请求参数

字段 类型 描述
entrust_id path 订单id
 

取消所有订单接口

import requests

url = "https://openapi.bitmart.com/v2/orders?symbol=BMX_ETH&side=buy"

// timestamp is in milliseconds and the authorization header is "Bearer " + token
headers = {"X-BM-TIMESTAMP": xxx, "X-BM-AUTHORIZATION": "xxx"}

response = requests.delete(url, headers=headers)

print(response.text)
func main() {
    access_token := get_access_token(api_key, api_secret, memo)

    URL := endpoint + "/v2/orders?symbol=BMX_ETH&side=buy"

    req, _ := http.NewRequest("DELETE", URL, nil)

    req.Header.Add("X-Bm-Timestamp", fmt.Sprintf("%d", time.Now().UnixNano()/1000000))
    req.Header.Add("X-Bm-Authorization", "Bearer "+access_token)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

取消某一类型的订单

上面的请求会返回如下的json消息:

{}
 

请求参数

字段 类型 描述
symbol query 交易对symbol
side query buysell
 

订单详情接口

import requests

url = "https://openapi.bitmart.com/v2/orders/1223181"

// timestamp is in milliseconds and the authorization header is "Bearer " + token
headers = {"X-BM-TIMESTAMP": xxx, "X-BM-AUTHORIZATION": "xxx"}

response = requests.get(url, headers=headers)

print(response.text)
func main() {
    access_token := get_access_token(api_key, api_secret, memo)

    URL := endpoint + "/v2/orders/1223181"

    req, _ := http.NewRequest("GET", URL, nil)

    req.Header.Add("X-Bm-Timestamp", fmt.Sprintf("%d", time.Now().UnixNano()/1000000))
    req.Header.Add("X-Bm-Authorization", "Bearer "+access_token)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

获取订单详情

上面的请求会返回如下的json消息:

{
   "entrust_id":1223181,
   "symbol":"BMX_ETH",
   "timestamp":1528060666000,
   "side":"buy",
   "price":"1.000000",
   "fees":"0.1",
   "original_amount":"1",
   "executed_amount":"1",
   "remaining_amount":"0",
   "status":3
}
 
请求参数
字段 类型 描述
entrust_id path 订单id
 
状态类型
状态 描述
0 所有订单
1 未成交的订单
2 部分成交的订单
3 全部成交的订单
4 取消的订单
5 未成交的订单和部分成交的订单
6 全部成交和取消的订单
 
响应详情
字段 类型 描述
entrust_id string 订单id
symbol string 交易对symbol
timestamp string 创建时间 (毫秒表示)
side string 'buy' 或 'sell'
price string 订单价格
fees string 订单手续费
original_amount string 下单总额
executed_amount string 成交额
remaining_amount string 剩余额
 

用户订单接口

import requests

url = "https://openapi.bitmart.com/v2/orders?symbol=BMX_ETH&status=0&offset=0&limit=100"

// timestamp is in milliseconds and the authorization header is "Bearer " + token
headers = {"X-BM-TIMESTAMP": xxx, "X-BM-AUTHORIZATION": "xxx"}

response = requests.get(url, headers=headers)

print(response.text)
func main() {
    access_token := get_access_token(api_key, api_secret, memo)

    URL := endpoint + "/v2/orders?symbol=BMX_ETH&status=1&offset=0&limit=100"

    req, _ := http.NewRequest("GET", URL, nil)

    req.Header.Add("X-Bm-Timestamp", fmt.Sprintf("%d", time.Now().UnixNano()/1000000))
    req.Header.Add("X-Bm-Authorization", "Bearer "+access_token)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

获取用户订单列表。

请求参数

字段 类型 描述
symbol query 交易对symbol
status query 整型enum,详情请参考下表
offset query 当前页 从0开始
limit query 每页最大返回数量

但是,对于高交易量的成交,强烈建议用户维护自己的当前订单列表,使用websocket更新订单状态。每次交易前您必须拉取一次当前订单列表。

状态类型

状态 描述
1 未成交的订单
2 部分成交的订单
3 全部成交的订单
4 取消的订单
5 未成交的订单和部分成交的订单
6 全部成交和取消的订单

上面的请求会返回如下的json消息:

{
   "orders":[
      {
         "entrust_id":1223181,
         "symbol":"BMX_ETH",
         "timestamp":1528060666000,
         "side":"buy",
         "price":"1.000000",
         "fees":"0.1",
         "original_amount":"1",
         "executed_amount":"1",
         "remaining_amount":"0",
         "status":3
      },
      ...
   ],
   "total_pages":1,
   "total_orders":1,
   "current_page":0,
}

响应详情

字段 类型 描述
orders array 订单列表
entrust_id string 订单id
symbol string 交易对symbol
timestamp string 订单创建时间 (毫秒表示)
side string 'buy' 或 'sell'
price string 订单价格
fees string 订单手续费
original_amount string 订单总额
executed_amount string 已成交额
remaining_amount string 剩余额
total_pages string 总页数 (废弃)
total_orders string 总个数 (废弃)
current_page string 当前页
status string 整型enum,请参考状态类型表
 

用户成交历史

import requests

url = "https://openapi.bitmart.com/v2/trades?symbol=BMX_ETH&limit=10&offset=0"

// timestamp is in milliseconds and the authorization header is "Bearer " + token
headers = {"X-BM-TIMESTAMP": xxx, "X-BM-AUTHORIZATION": "xxx"}

response = requests.get(url, headers=headers)

print(response.text)
func main() {
    access_token := get_access_token(api_key, api_secret, memo)

    URL := endpoint + "/v2/trades?symbol=BMX_ETH&limit=10&offset=0"

    req, _ := http.NewRequest("GET", URL, nil)

    req.Header.Add("X-Bm-Timestamp", fmt.Sprintf("%d", time.Now().UnixNano()/1000000))
    req.Header.Add("X-Bm-Authorization", "Bearer "+access_token)

    res, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer res.Body.Close()

    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(string(body))
}

获取用户成交历史。

 

请求参数

字段 类型 描述
symbol query 交易对symbol
entrust_id query 订单id
offset query 分页页码,0开始
limit query 单页数量

entrust_id也是可选的。 如果传了entrust_id, 那么offsetlimit 将被忽略。

上面的请求会返回如下的json消息:

{
    "total_trades": 216,
    "total_pages": 22,
    "current_page": 0,
    "trades": [
        {
            "symbol": "BMX_ETH",
            "amount": "1.0",
            "fees": "0.0005000000",
            "trade_id": 2734956,
            "price": "0.00013737",
            "active": true,
            "entrust_id": 5576623,
            "timestamp": 1545292334000
        },
        {
            "symbol": "BMX_ETH",
            "amount": "100.0",
            "fees": "0.0500000000",
            "trade_id": 2664776,
            "price": "0.00013472",
            "active": true,
            "entrust_id": 5389422,
            "timestamp": 1543964304000
        },
        ...
    ]
}
 

响应详情

字段 类型 描述
trades array 成交历史列表
entrust_id string 订单id
trade_id string 成交id
symbol string 交易对symbol
timestamp string 成交时间 (毫秒表示)
active boolean 订单状态
entrustType int 订单类型 0:买 1:卖
price string 成交价格
fees string 成交费率
amount string 成交总额
total_pages string 总页数 (废弃)
total_trades string 总个数 (废弃)
current_page string 当前页数
 

Websocket

实时市场数据提供了最快的订单和交易数据流。这意味着用户需要自己负责获取消息流,并根据相应的消息构建实时的深度和交易数据。

 

URL

wss://ws-manager.bitmart.com

 

协议概述

Websocket实现了客户端与服务器全双工通信,消息都是以JSON对象的格式传送。

错误消息: 大多数的错误都会返回一个error 消息 (一条包含"message"字段的消息)。 它能帮助你调试和定位问题。

 

订阅

一条订阅消息示例:

{
    "subscribe":"depth",
    "symbol":"55",
    "precision":6
}

订阅消息会随着订阅信息一起返回, 比如

{
    "code": 0,
    "data": {
        "buys": [{
            "amount": "1.33",
            "count": "1",
            "price": "0.015710",
            "total": "1.33"
        }],
        "sells": [{
            "amount": "14.03",
            "count": "1",
            "price": "0.015730",
            "total": "14.03"
        }]
    },
    "time":1534141852,
    "version":"20180810001",
    "pre_version":"20180810000"
    "precision": 6,
    "subscribe": "depth",
    "symbol": 53
}

您必须首先发送一条subscribe消息,来指明需要接受哪个频道和产品的消息。如果5秒内没有收到订阅消息,我们会断开websocket连接。

一旦服务器收到一条subscribe消息, 服务器便会返回你订阅的消息流。

取消订阅只需要发送一条unsubscribe消息,消息结构和subscribe消息一致.

如果unsubscription成功,您将不会再收到后续的订阅消息。

 

订阅频道

 

According频道

订阅返回格式

{
    "code": 0,//返回码
    "data": {
        "total24HourVolume": "154547896.36 CNY",//24小时成交量
        "totalCoin": "7192819944.43 CNY",//累计成交量
        "totalTrade": 78,//交易对数目
        "time":1534141852 //时间戳精确到秒
    },
    "local": "zh_CN",//语言:语言决定了统计的成交量币种
    "subscribe": "according"//订阅数据类型:成交总量
}

订阅

{"subscribe": "according","local": "zh_CN"}

取消订阅

{"subscribe": "according_cancel","local": "zh_CN"}

 

Price频道

订阅返回格式

{
    "code": 0,
    "data": {
        "c": "6274.37",// 收盘价
        "fluctuation": "0.0245", // 涨跌幅
        "h": "6465.00",// 最高价
        "increase": "1",// 102
        "l": "6080.00",// 最低价
        "o": "6124.49",// 开盘价
        "rate": "43100.53",// 对应法币金额
        "sign": "CNY",// 对应法币单位
        "v": "5775350.53",// 交易数量
        "time":1534141852 //时间戳精确到秒
    },
    "version":"20180810001",
    "pre_version":"20180810000",
    "local": "zh_CN",//语言
    "subscribe": "price",//订阅数据类型:价格
    "symbol": 55//交易对编码
}

订阅

{"subscribe": "price","symbol": 55, "local": "zh_CN"}

{"subscribe": "price", "symbol": "55|22|33", "local": "zh_CN"}

取消订阅

{"subscribe": "price_cancel","symbol": 55,"local": "zh_CN"}

 

Market频道

参数 参数说明
event 操作的事件 取值:[ping addChannel cancelChannel]
binary 二进制压缩 0-非二进制 1-二进制
type 订阅信息类型 kline depth ticker
product 产品类型 spot现货 futures期货
quote 计价币种(类似USD,USDT,BTC,ETH,BMX)
base 基础币种(各种虚拟币或者合约币种)
period kline周期步长
sign 币种符号 CNY JPY GBP HKD CAD USD EUR KRW AUD -暂时保留这个参数,后期汇率放在前端计算,这个参数取消
 

订阅示例:

订阅所有现货交易对行情价格

{event:'addChannel',parameters:{product:"spot","binary":"0","type":"all_ticker","sign":"CNY"}}

取消所有现货交易对行情价格

{event:'cancelChannel',parameters:{product:"spot","binary":"0","type":"all_ticker","sign":"CNY"}}

订阅某个交易区的所有交易对行情价格

{event:'addChannel',parameters:{product:"spot","binary":"0","quote":"usdt","type":"all_ticke","sign":"CNY"}}

取消订阅某个交易区的所有交易对行情价格

{event:'cancelChannel',parameters:{product:"spot","binary":"0","quote":"usdt","type":"all_ticker","sign":"CNY"}}

订阅bmx/usdt交易对的行情-暂未实现

{event:'addChannel',parameters:{product:"spot","binary":"0","quote":"usdt","base":"bmx","type":"ticker","sign":"CNY"}}

取消订阅bmx/usdt交易对的行情-暂未实现

{event:'cancelChannel',parameters:{product:"spot","binary":"0","quote":"usdt","base":"bmx","type":"ticker","sign":"CNY"}}

 

Depth频道

订阅返回格式

{
    "code": 0,
    "data": {
        "buys": [{
            "amount": "1.33",// price*count
            "count": "1",//数量
            "price": "0.015710",//单价
            "total": "1.33"//累计
        }],
        "sells": [{
            "amount": "14.03",
            "count": "1",
            "price": "0.015730",
            "total": "14.03"
        }]
    },
    "time":1534141852, //时间戳精确到秒
    "version":"20180810001",
    "pre_version":"20180810000"
    "precision": 6,//精度
    "subscribe": "depth",
    "symbol": 53
}

订阅

{"subscribe": "depth","symbol":55,"precision": 6}

取消订阅

{"subscribe": "depth_cancel","symbol": 55,"precision": 6}

 

Trade频道

订阅返回格式

{
    "symbol":118,
    "code":0,
    "data":{
        "trades":[
            {
                "isBuy":"1",
                "amount":"8.90016491",
                "count":"3359.25",
                "price":"0.00264945",
                "time":1542337219109,
                "version":"",
                "pre_version":""
            }
        ]
    },
    "subscribe":"trade",
    "firstSubscribe":"1",
    "precision":4,
    "uuid":"51f79e6b-53fb-471c-bb81-4f5aa3b5210c"
}

订阅

{"subscribe":"trade", "symbol":12, "precision": 0}

取消订阅

{"subscribe":"trade_cancel", "symbol":12, "precision": 0}

 

Kline频道

订阅返回格式

{
"subscribe":"kline",
"symbol": 12,
"step": "3",//选择的k线step
"code": 0,
"data":{
    "o":"0.0000100", // 开盘价
    "h":"0.0000100", // 最高价
    "l":"0.0000100", // 最低价
    "v":"0.0000100", // 交易数量
    "c":"0.0000100", // 收盘价
    "t": 12312231,// 精确到秒的时间撮
    "ot":12312231, // 开盘时间
    "ct":12312231// 收盘时间
    }
}

订阅

{"subscribe":"kline", "symbol":12, "step": 3}

取消订阅

{"subscribe":"kline_cancel", "symbol":12, "step": 3}

step:

1 => 1分钟

3 => 3分钟

5 => 5分钟

15 => 15分钟

30 => 30分钟

45 => 45分钟

60 => 1小时

120 => 2小时

180 => 3小时

240 => 4小时

1d => 1天

1w => 1周

1m => 1月

 

Notify频道

新订单通知

{
    "code": 0,
    "subscribe":"notify",
    "uid":100,
    "data":{
        "event":"new_entrust",
        "symbol": 12,
        "entrustId": 12,
        "time": 13333333,
        "version":"20180810001",
        "pre_version":"20180810000"
    }
}

订单撤销通知


{
    "code": 0,
    "subscribe":"notify",
    "uid":100,
    "data":{
        "event":"cancel_entrust",
        "symbol": 12,
        "entrustId": 12,
        "time": 13333333,
        "version":"20180810001",
        "pre_version":"20180810000"
    }
}

订单成交通知

{
    "code": 0,
    "subscribe":"notify",
    "uid":100,
    "data":{
        "event":"trade_success",
        "symbol": 12,
        "entrustId": 12,
        "time": 13333333,
        "version":"20180810001",
        "pre_version":"20180810000"
    }
}

订阅

{"subscribe":"notify", "token":"123123dsfsd123"}

 

用户交易频道(采用新版的订阅规范协议)

获取用户交易数据,需用用户登录获取Token

send示例

{
"op": "subscribe",
"token":"GnHvFd5XBQc3iPqXv83siDaef4Ln9Pyv19gywmBuTiVh/FO4bv3IcmhW/Fu/JO0ZGTg1/FqR6tIt3HB0dp9RtB8DvsjvlfB7LY/P3xafsBTfD7pz9TBrHOlOPhQmO6QRn2ES8sV+d2t/Npz15IDC0rNV90j8o0nV2SW8O+otOwNvqn5OEktNJdn6yAfBDnkfJx7cH/NgG4t5n+KwhbYP2auHA/RWOoR3G4/9naa1F+Yo+gfZeLcO0MaNFMoB4FfDkAAolimsIV/rYADypCQ0AgfLydXChksIiXVhj3dCtbH4dLaziWOxkwho1GExHQOD0jNMhGZ9WqSS3Xu1XQJjwvNLXU2VNswpDvyVA2RSOVg=",
"args": ["spot/order:BMX_USDT","spot/order:BTC_USDT"]
}

其中spot/order为频道名, BMX_USDT为trademapping_name

返回参数

参数名 类型 描述
order_id String 订单ID
client_oid String 由用户设置的订单ID 暂不支持
price String 委托价格
count String 委托数量(交易货币数量)
notional String 买入金额或者卖出数量 市价买入卖出时返回
trademapping_id String 币对ID
trademapping_name String 币对名称
side String 0-buy or 1-sell
order_type String 市价单或限价单 0-limit or 1-market
timestamp String 订单创建时间 毫秒
filled_count String 已成交数量
filled_amount String 已成交金额
margin_trade String 1-币币交易订单 2-杠杆交易订单
entrust_type String 订单委托方式 0-普通委托 1-只做Maker(Post only) 2-全部成交或者立即取消(FOK) 3-立即成交并取消剩余(IOC)
state String 推送订单状态("-2":失败,"-1":撤单成功,"0":等待成交 ,"1":部分成交, "2":完全成交,"3":下单中,"4":撤单中)
last_fill_price String 最新成交价格(如果没有,推0)
last_fill_count String 最新成交数量(如果没有,推0)
last_fill_time String 最新成交时间(如果没有,推0) 毫秒

返回示例

{
    "data": {
        "trademapping_id": "52",
        "side": "1",
        "last_fill_time": "1568641347329",
        "count": "500.0000000000",
        "filled_count": "500.0000000000",
        "client_oid": "spot/user-channel",
        "last_fill_price": "0.0229",
        "price": "0.0229000000",
        "margin_trade": "0",
        "last_fill_count": "500.0",
        "state": "2",
        "trademapping_name": "BMX_USDT",
        "order_id": "2458056",
        "order_type": "1",
        "filled_amount": "11.4500000000",
        "timestamp": "1568641346000",
        "entrust_type": "0"
    },
    "table": "spot/order"
}
 

WebSocket错误码

desc code
成功 0
系统错误 -1
订阅参数缺失 -8101
订阅参数错误 -8102
订阅主题错误 -8103
 

自动交易

以下是支持BitMart的自动交易软件和服务。

  • CCXT

    CCXT库用于在全球范围内与加密货币交易所和支付处理服务进行连接和交易。 它提供对市场数据的快速访问,以进行存储,分析,可视化,指标开发,算法交易,策略回测,自动程序编程和相关软件工程。

  • FMZ发明者量化

    发明者量化(fmz.com)是亚洲目前唯一支持商品期货与数字货币的量化交易平台,专注于量化软件平台开发和量化交易策略研究与服务,对目前市场上超过50家主流交易所提供支持。支持JavaScript/Python/C++/My语言/可视化五种编程语言

更多的工具正在建立中。 如果你使用的代码库或软件不支持 BitMart,请告知其维护人员与我们联系并开始使用我们的 API。 我们的员工很乐意帮忙。
















 

合约交易

BitMart支持多种数字货币的永续合约交易

 

API域名

https://api-cloud.bitmart.com

 

公共接口

不需要验签的接口

 

获取合约列表

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/contracts?exchange=bitmart

GET /contract/v1/ifcontract/contracts

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID 如果合约ID参数为空或为0,标识获取所有合约
exchange string 固定为bitmart
 

响应详情

返回json消息数据格式:

 {
        "errno": "OK",
        "message": "Success",
        "data": {
            "contracts": [
                {
                    "contract": {
                        "contract_id": 1,
                        "index_id": 1,
                        "name": "BTCUSDT",
                        "display_name": "BTCUSDT永续合约",
                        "display_name_en": "BTCUSDT_SWAP",
                        "contract_type": 1,
                        "base_coin": "USDT",
                        "quote_coin": "BTC",
                        "price_coin": "USDT",
                        "contract_size": "1",
                        "delivery_cycle": 0,
                        "min_leverage": "1",
                        "max_leverage": "100",
                        "price_unit": "0.01",
                        "vol_unit": "1",
                        "min_vol": "1",
                        "value_unit": "0.01",
                        "max_vol": "100000",
                        "liquidation_warn_ratio": "0.85",
                        "fast_liquidation_ratio": "0.3",
                        "settle_type": 1,
                        "open_type": 3,
                        "status":3,
                        "compensate_type": 1,
                        "created_at": "2018-07-12T19:16:57Z"
                    },
                    "risk_limit": {
                        "contract_id": 1,
                        "base_limit": "10",
                        "step": "5",
                        "initial_margin": "0.1" 
                    },
                    "fee_config": {
                        "contract_id": 1,
                        "maker_fee": "0.00025",
                        "taker_fee": "0.00075",
                        "settlement_fee": "0",
                        "long_funding": "0.03",
                        "short_funding": "0.06",
                        "funding_interval": 28800,
                        "created_at": "2018-07-12T20:47:22Z"
                    }
                }
            ]
        }
   }
字段 类型 描述
contract_id long contract id. 合约ID
index_id int contract's index id.指数ID
name string contract's name 合约名称
display_name string contract's chinese display name.合约中文显示名称
display_name_en string 合约英文显示名称
contract_type int 合约类型,永续还是期货 1:永续,2:期货
base_coin string 基础币
quote_coin string 计价币
price_coin string 合约大小的单位币
contract_size decimal 合约大小,表示一张合约值多少个基础币
delivery_cycle int 交割周期 单位秒
min_leverage decimal 合约支持的最小杠杆
max_leverage decimal 合约支持的最大杠杆
price_unit decimal 价格精度
vol_unit decimal 量精度
value_unit decimal 价值精度
min_vol decimal 合约支持的最小交易量
max_vol decimal 合约支持的最大交易量
liquidation_warn_ratio decimal 平仓预警系数
fast_liquidation_ratio decimal 快速平仓系数
settle_type int 结算类型 1:自动,2:手动
open_type int 开仓类型,1:全仓,2:逐仓,3:都支持
status int 1 审批中,系统内部使用 2 测试中,系统内部使用 3 可用,正在撮合的合约 4 暂停,合约可见,但是撮合暂停了 5 交割中,期货合约到期后,暂停撮合,开始结算 6 交割完成,结算完成 7 下线,合约已经下线,合约的生命周期结束
compensate_type int 穿仓补偿方式 1:ADL方式,2:盈利均摊方式
created_at time 创建时间
base_limit decimal 风险限额基础
step decimal 步长
maintenance_margin decimal 基本维持保证金率
initial_margin decimal 基本开仓保证金率
maker_fee decimal makefee系数
taker_fee decimal takefee系数
settlement_fee decimal 交割手续费率,到期合约才有
long_funding decimal 多仓资金费率,掉期合约才有
short_funding decimal 空仓资金费率,掉期合约才有
funding_interval int64 资金费率时间段,掉期合约才有,单位秒
created_at string 创建时间
 

获取合约的最新行情

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/tickers?contractID=1

GET /contract/v1/ifcontract/tickers

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID 如果合约ID参数为空或为0,标识获取所有合约
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        "tickers": [
            {
                "last_price": "6277.5"| 最后成交价
                "open": "6074.5"| 当天的开盘价
                "close": "6277.5"| 当前的收盘价
                "low": "6261.3"| 当天的最低价
                "high": "6279"| 当天的最高加
                "avg_price": "6274.67",// 均价
                "volume": "20000", 
                "total_volume": "45462"| 24小时总量,单位张数
                "base_coin_volume":"163.9"| 基础币的交易量(币值对前面的币为基础币)
                "quote_coin_volume":"34555.38199999999999998882"| 计价币的交易量(币值对后面的币为计价币)
                "timestamp": 1534315695| 时间戳
                "rise_fall_rate": "0.033"| 涨幅比例
                "rise_fall_value": "203"| 涨幅值
                "contract_id": 1| 合约id
                "position_size": "374266"| 未平仓位量
                "volume_day": "45270"| 当天交易量
                "amount24":"28520.77363"| 24小时交易额
                "index_price": "6406.53"| 指数价格
                "fair_basis": "0.000000690"| 基差率
                "fair_value": "0.00442673"| 基差
                "fair_price": "6406.5344267"| 标记价
                "rate": {
                    "quote_rate": "0.0003"| 计价币借贷利率
                    "base_rate": "0.0006"| 基础币借贷利率
                    "interest_rate": "-0.00009999" // 利率
                },
                "premium_index": "-0.0309530479798782534"| 溢价指数
                "funding_rate": "0.0001"| 当前资金费率
                "next_funding_rate": "-0.0304530"| 下一个预计资金费率
                "next_funding_at": "2018-08-15T08:00:01Z" | 下一个结算时间(UTC时间)
            }
        ]
    }
}
字段 类型 描述
last_price string 最后成交价
open string 当天的开盘价
close string 当前的收盘价
low string 当天的最低价
high string 当天的最高加
avg_price string 均价
volume string 最后一笔交易量,单位张数,如果要显示btc交易量,需要volume乘以合约的大小
total_volume string 24小时总量,单位张数
base_coin_volume string 基础币的交易量(币值对前面的币为基础币)
quote_coin_volume string 计价币的交易量(币值对后面的币为计价币)
timestamp long 时间戳
rise_fall_rate string 涨幅比例
rise_fall_value string 涨幅值
contract_id long 合约id
position_size string 未平仓位量
volume_day string 当天交易量
amount24 string 24小时交易额
index_price string 指数价格
fair_basis string 基差率
fair_value string 基差
fair_price string 标记价
quote_rate string 计价币借贷利率
base_rate string 基础币借贷利率
interest_rate string 利率
premium_index string 溢价指数
funding_rate string 当前资金费率
next_funding_rate string 下一个预计资金费率
next_funding_at string 下一个结算时间(UTC时间)
 

交易价格K线

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/quote?contractID=1&startTime=1584343602&endTime=1585343602&unit=5&resolution=M

GET /contract/v1/ifcontract/quote

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
startTime long 开始时间
endTime long 结束时间
unit int 频率
resolution string 频率单位,M:分钟,H:小时,D:天
 

响应详情

返回json消息数据格式:

 {
     "errno": "OK",
     "message": "Success",
     "data": [
         {
             "low": "130",
             "high": "130",
             "open": "130",
             "close": "130",
             "last_price": "130",
             "avg_price": "130",
             "volume": "0",
             "base_coin_volume":"163.9", 
             "quote_coin_volume":"34555.38199999999999998882",
             "timestamp": 1532610000, 
             "rise_fall_rate": "0",
             "rise_fall_value": "0"
         }
     ]
 }
字段 类型 描述
low string 最低价
high string 最高价
open string 开盘价
close string 收盘价
last_price string 最后一次交易价
avg_price string 均价
volume string 交易量
base_coin_volume string 基础币的交易量(币值对前面的币为基础币)
quote_coin_volume string 计价币的交易量(币值对后面的币为计价币)
timestamp string 时间戳,单位秒
rise_fall_rate string 涨跌幅比例
rise_fall_value string 涨跌幅值
 

指数价格K线

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/indexquote?indexID=1&startTime=1584343602&endTime=1585343602&unit=5&resolution=M

GET /contract/v1/ifcontract/indexquote

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
startTime long 开始时间
endTime long 结束时间
unit int 频率
resolution string 频率单位,M:分钟,H:小时,D:天
 

响应详情

返回json消息数据格式:

 {
     "errno": "OK",
     "message": "Success",
     "data": [
         {
             "low": "130",
             "high": "130",
             "open": "130",
             "close": "130",
             "last_price": "130",
             "avg_price": "130",
             "volume": "0",
             "timestamp": 1532610000, 
             "rise_fall_rate": "0",
             "rise_fall_value": "0"
         }
     ]
 }
字段 类型 描述
low string 最低价
high string 最高价
open string 开盘价
close string 收盘价
last_price string 最后一次交易价
avg_price string 均价
volume string 交易量
timestamp string 时间戳,单位秒
rise_fall_rate string 涨跌幅比例
rise_fall_value string 涨跌幅值
 

合约交易记录

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/trades?contractID=1

GET /contract/v1/ifcontract/trades

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        "trades": [
            {
                "order_id": 10116361, // taker order id
                "trade_id": 10116363, // trade id
                "contract_id": 1,     // 合约ID
                "deal_price": "16",   // 成交价
                "deal_vol": "10",     // 成交的合约张数
                "make_fee": "0.04",   // make fee
                "take_fee": "0.12",   // take fee
                "created_at": null,   // 创建时间
                "way": 5,             // 交易方向
                "fluctuation": "0"    // 对行情的影响
            }
        ]
    }
}
字段 类型 描述
order_id long taker order id
trade_id long trade id
contract_id long 合约ID
deal_price string 成交价
deal_vol string 成交的合约张数
make_fee string make fee
take_fee string take fee
created_at string 创建时间
way string 交易方向 1:买为taker,开多买开空卖 2:买为taker,开多买平多卖 3:买为taker,平空买开空卖 4: 买为taker,平空买平多卖 5:卖为taker,开空卖,开多买 6: 卖为taker,开空卖,平空买 7:卖为taker,平多卖,开多买 8: 卖为taker,平多卖,平空买
fluctuation string 对行情的影响

备注

way 1~4都是买为taker ,5~8都是卖为taker

fluctuation,对行情的影响,如本次交易前的最新交易价是10,本次交易的交易价是11,则fluctuation为"1"

 

获取合约深度

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/depth?contractID=1&count=10

GET /contract/v1/ifcontract/depth

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
count int 获取数量,不传表示获取全部
 

响应详情

返回json消息数据格式:

 {
     "errno": "OK",
     "message": "Success",
     "data": {
         "sells": [
             {
                 "price": "60", 
                 "vol": "20"
             }
         ],
         "buys": []
     }
 }
字段 类型 描述
price long 价格
vol long 合约的张数
 

查询合约自动减仓排序表

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/pnls?contractID=1

GET /contract/v1/ifcontract/pnls

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
 

响应详情

返回json消息数据格式:

{
    "errno":"OK",
    "message":"Success",
    "data":{
        "pnls":[
            {
                "contract_id":1,
                "long_pnls":[
                    {
                        "min_pnl":"-0.0379107725788900979",
                        "max_pnl":"-0.0103298131866111136",
                        "quan_tile":40
                    },
                    {
                        "min_pnl":"-0.0103298131866111136",
                        "max_pnl":"0",
                        "quan_tile":60
                    }
                ],
                "short_pnls":[
                    {
                        "min_pnl":"-49962.3980439671407168788",
                        "max_pnl":"0",
                        "quan_tile":20
                    }
                ]
            }
        ]
    }
}
字段 类型 描述
contract_id int 合约ID
min_pnl string 仓位pnl范围min
max_pnl string 仓位pnl范围max
quan_tile int 五分位值
 

指数列表

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/indexes

GET /contract/v1/ifcontract/indexes

 

请求参数

 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": [
        {
            "index_id": 1, // 指数ID
            "name": "BTC", // 指数名称
            "base_coin": "BTC", // 指数基础币
            "quote_coin": "USDT", // 指数计价币
            "brief_en": "", // 英文简称
            "brief_zh": "", // 中文简称
            "price_unit": "0.000001", // 价格精度
            "created_at": "2018-07-30T16:04:08Z",
            "contract": [
                {
                    // 跟指数关联的合约对象
                    // 数据与获取合约接口的结构一致
                },
                {

                },
                {

                }
            ]
        }
    ]
}
字段 类型 描述
index_id int 指数ID
name string 指数名称
base_coin string 指数基础币
quote_coin string 指数计价币
brief_en string 英文简称
brief_zh string 中文简称
price_unit string 价格精度
created_at string 创建时间
 

获取资金费率

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/fundingrate?contractID=2

GET /contract/v1/ifcontract/fundingrate

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
 

响应详情

返回json消息数据格式:

 {
     "errno": "OK",
     "message": "Success",
     "data": [
         {
             "rate": "-0.0060483184843194741",
             "timestamp": 1534320000
         },
         {
             "rate": "0.1041766553400505803",
             "timestamp": 1534291200
         }
     ]
 }
字段 类型 描述
rate string 资金费率
timestamp long 时间戳
 

认证接口

需要认证才能访问的接口

 

查询用户仓位

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/userPositions?contractID=1&status=3&offset=0&size=0

GET /contract/v1/ifcontract/userPositions

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        "trades": [
            {
                "order_id": 10116361, // taker order id
                "trade_id": 10116363, // trade id
                "contract_id": 1,     // 合约ID
                "deal_price": "16",   // 成交价
                "deal_vol": "10",     // 成交的合约张数
                "make_fee": "0.04",   // make fee
                "take_fee": "0.12",   // take fee
                "created_at": null,   // 创建时间
                "way": 5,             // 交易方向
                "fluctuation": "0"    // 对行情的影响
            }
        ]
    }
}
字段 类型 描述
position_id long 仓位ID
account_id int 用户ID
contract_id long 合约ID
hold_vol string 当前持有量
freeze_vol string 冻结量
close_vol string 已平仓量
hold_avg_price string 开仓均价
close_avg_price string 已平仓,平仓均价
liquidate_price string 强平价
im string 开仓保证金
mm string 维持保证金
realised_profit string 以实现盈亏
earnings string 已结算收益
hold_fee string 持仓产生的资金费用
open_type int 开仓方式,1:逐仓,2:全仓
position_type int 仓位类型,1:开多,2:开空
status int 状态,1:持仓中,2:系统托管中,4:已平仓 如果请求参数中的status值为3,标识同时请求持仓中和系统委托中的仓位,如果请求参数中的status值为0或者7,标识同时请求所有状态的仓位
errno int 平仓原因 1 平仓委托中 2 破产委托中 3 平仓委托结束 4 破产委托结束 5 爆仓 6 自动减仓(主动发起方) 7 自动减仓(被动接收方)
created_at string created_at
updated_at string updated_at

备注

**仓位价值的计算:

a.如果是正向合约,仓位价值 = 持仓量 合约大小 开仓均价

b.如果是反向合约,仓位价值 = 持仓量*合约大小/开仓均价

附上简易代码 func calculatePV:

vol:持仓量;

price:开仓均价;

contractSize:合约大小;

isReverse:是否是反向合约,见:[合约公共信息]的[获取合约列表];

func calculatePV(vol,price,contractSize,isReverse bool) {
     if isReverse {
         pv = vol*contractSize/price
         return pv
     }
     pv = vol*contractSize*price
     return pv
 }

** 仓位的逻辑开仓方向 func PositionLogicType

func PositionLogicType(position,isReverse) POSITION_TYPE {
     if !isReverse {
         return position.PositionType
     }
     if position.PositionType == POSITION_TYPE_LONG {
         return POSITION_TYPE_SHORT
     }
     return POSITION_TYPE_LONG
 }

** 仓位强平价的计算 func CalculateLiquidatePrice:

// position:仓位对象

// availableAssetsVol:合约资产的有效可用余额,如果仓位是逐仓,不需要考虑余额,该值为零;只有当仓位是全仓时才需要;

// contractSize:合约大小

// takeFeeRatio:合约配置的take fee 手续费比例

// isReverse:是否是反向合约

 func CalculateLiquidatePrice( position, availableAssetsVol, contractSize, takeFeeRatio, isReverse) {
     S = contractSize
     T = takeFeeRatio
     HV = position.HoldVol
     HP = position.HoldAvgPrice

// 计算仓位价值 PV = calculatePV(HV, HP,S,isReverse)

// 当前仓位剩余的保证金 IM = position.IM.Add(availableAssetsVol)

// restM:达到强平线时,仓位出现的亏损 restM = IM.Sub(position.MM) D = 0 M = 0

if PositionLogicType(position,isReverse) == POSITION_TYPE_LONG { M = PV - restM D = HV*S*(1-T) } else { M = PV+restM D = HV*S*(1+T) } if D <= 0 { if position.PositionType == POSITION_TYPE_LONG { return 10000000000000000 } else { return 0 } }

LP = M.Div(D) // 反向合约价格是1/P if isReverse { LP = 1/LP } return LP } ```

** 按合理价格计算仓位的未实现盈亏 func CalculatePositionUnrealizedProfit:

// CalculatePositionUnrealizedProfit 未实现盈亏

 func CalculatePositionUnrealizedProfit(
     position,
     fairPrice
     contractSize,
     isReverse)  {
     if position.PositionType == POSITION_TYPE_LONG {
         return CalculateLongPositionUnrealizedProfit(position,fairPrice,contractSize,isReverse)
     } else{
         return CalculateShortPositionUnrealizedProfit(position,fairPrice, contractSize,isReverse)
     }
 }

// func CalculateLongPositionUnrealizedProfit 计算多仓未实现盈亏

 func CalculateLongPositionUnrealizedProfit(position,fairPrice,contractSize,isReverse) {
     if isReverse {
         openValue := position.HoldVol*contractSize/(position.HoldAvgPrice)
         closeValue := position.HoldVol*contractSize/(fairPrice)
         return openValue - (closeValue)
     }
     openValue := position.HoldVol*(contractSize)*(position.HoldAvgPrice)
     closeValue := position.HoldVol*(contractSize)*(fairPrice)
     return closeValue - (openValue)
 }

// func CalculateShortPositionUnrealizedProfit 计算空仓未实现盈亏

 func CalculateShortPositionUnrealizedProfit( position,fairPrice,contractSize,isReverse) {
     if isReverse {
         openValue := position.HoldVol*(contractSize)/(position.HoldAvgPrice)
         closeValue := position.HoldVol*(contractSize)/(fairPrice)
         return closeValue - (openValue)
     }
     openValue := position.HoldVol*(contractSize)*(position.HoldAvgPrice)
     closeValue := position.HoldVol*(contractSize)*(fairPrice)
     return openValue- (closeValue)
 }
 

用户交易订单

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/userOrders?contractID=1&offset=0&size=0&status=0

GET /contract/v1/ifcontract/userOrders

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
offset int offset
size int size 请求数量,如果size不传或size为0,系统最多返回60条
status int 订单状态 1:申报中 2:委托中 4:完成 如果请求参数status=3,标识同时请求申报中和委托中的订单,如果请求参数status=0或者7,标识同时请求所有状态的订单
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        "orders": [
            {
                "order_id": 10284160,
                "contract_id": 1,
                "price": "8",
                "vol": "4",
                "done_avg_price": "0",
                "done_vol": "0",
                "way": 1,
                "category": 1,
                "open_type": 2,
                "make_fee": "0",
                "take_fee": "0",
                "origin": "", // 来源
                "created_at": "2018-07-17T07:24:13.410507Z",
                "finished_at": null,
                "status": 2,
                "errno": 0
            }
        ]
    }
}
字段 类型 描述
order_id long 订单ID
contract_id long 合约ID
price string 订单价格
vol string 订单量
done_avg_price string 成交均价
done_vol string 成交量
way int 订单方向
category int 订单类型 1:限价委托 2:市价委托 7:被动委托 category,订单类型 该字段采用二进制按位表示法 0~5位表示订单的基本类型,第6位预留,第7位为1表示:强平委托单,第8位为1表示:爆仓委托单,第9位为1表示:自动减仓委托单
make_fee string make fee
take_fee string take fee
origin string 来源
created_at string created_at
finished_at string 结束时间
status int 状态 1:申报中 2:委托中,表示订单已经进撮合队列,订单信息中的done_vol表示订单成交部分,只要done_vol不为0就表示订单有成交. 4:完成
errno int 订单结束的原因 1 用户取消 2 超时,(暂时没有用) 3 用户资产不够,转撤销 4 破产委托结束 5 系统部分转撤销 6 部分平仓导致的部分转撤销 7 自动减仓导致的部分转撤销 8 盈利补偿导致的部分转撤销(暂时没有用) 9 仓位错误导致的部分转撤销 10 类型非法 11 反方向订单存在
 

获取订单详情

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/userOrderInfo?contractID=1&orderID=10539098

GET /contract/v1/ifcontract/userOrderInfo

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
orderID long 订单ID
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        "orders": [
            {
                "order_id": 10539098,
                "contract_id": 1,
                "position_id": 10539088,
                "account_id": 10,
                "price": "16",
                "vol": "1",
                "done_avg_price": "16",
                "done_vol": "1",
                "way": 3,
                "category": 1,
                "make_fee": "0.00025",
                "take_fee": "0.012",
                "origin": "",
                "created_at": "2018-07-23T11:55:56.715305Z",
                "finished_at": "2018-07-23T11:55:56.763941Z",
                "status": 4,
                "errno": 0
            }
        ]
    }
}
字段 类型 描述
order_id long 订单ID
contract_id long 合约ID
position_id long 仓位ID
account_id long 账号ID
price string 价格
vol string 成交量
done_avg_price string 已完成均价
done_vol string 已完成量
way int 方式
category int 类别
make_fee string make_fee
take_fee string take_fee
origin string 来源
created_at string 创建时间
finished_at string 完成时间
status int 状态
errno int 错误码
 

查询用户账户信息

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/accounts?coinCode=USDT

GET /contract/v1/ifcontract/accounts

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
coinCode string USDT 合约账号的coinCode
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        "trades": [
            {
                "order_id": 10116361, // taker order id
                "trade_id": 10116363, // trade id
                "contract_id": 1,     // 合约ID
                "deal_price": "16",   // 成交价
                "deal_vol": "10",     // 成交的合约张数
                "make_fee": "0.04",   // make fee
                "take_fee": "0.12",   // take fee
                "created_at": null,   // 创建时间
                "way": 5,             // 交易方向
                "fluctuation": "0"    // 对行情的影响
            }
        ]
    }
}
字段 类型 描述
account_id int 账号ID
coin_code string 代币名称
freeze_vol string 冻结量
available_vol string 可用余额
cash_vol string 净现金余额
realised_vol string 已实现盈亏
unrealised_vol string 未实现盈亏
created_at string created_at
updated_at string updated_at

备注

必须在币币系统登录成功后,才能获取用户的合约账号信息

请求参数有contractID和coinCode.由于系统设计的是多个相同保证金code的合约共用一个合约账号,

所以该接口既可以通过合约ID查询合约账号,也可以通过coinCode查询合约账号.如果请求都不传,则返回用户的所有合约账号

 

查询用户交易

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/userTrades?contractID=1&offset=0&size=100

GET /contract/v1/ifcontract/userTrades

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
offset int 偏移量
size int 请求数量,如果size不传或size为0,系统最多返回60条
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        "trades": [
            {
                "order_id": 10116361, // taker order id
                "trade_id": 10116363, // trade id
                "contract_id": 1,     // 合约ID
                "deal_price": "16",   // 成交价
                "deal_vol": "10",     // 成交的合约张数
                "make_fee": "0.04",   // make fee
                "take_fee": "0.12",   // take fee
                "created_at": null,   // 创建时间
                "way": 5,             // 交易方向
                "fluctuation": "0"    // 对行情的影响
            }
        ]
    }
}
字段 类型 描述
order_id int taker order id
trade_id string trade id
contract_id string 合约ID
deal_price string 成交价
deal_vol string 成交量
make_fee string make fee
take_fee string take fee
created_at string 创建时间
way string 交易方向 1: 开多 买 2: 平空 买 3:平多 卖 4:开空 卖
fluctuation string 对行情的影响

备注

fluctuation,对行情的影响,如本次交易前的最新交易价是10,本次交易的交易价是11,则fluctuation为"1"

 

查询爆仓记录

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/userLiqRecords?contractID=1&orderID=1000232

GET /contract/v1/ifcontract/userLiqRecords

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
orderID long 订单ID,不传查询全部
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
    "records": [
        {
        "order_id": 10539098,
        "contract_id": 1,
        "position_id": 10539088,
        "account_id": 10,
        "type":1, // 爆仓类型,1:部分强平,2:破产,3:ADL主动发起,4:ADL被动发起
        "trigger_price":"16", // 触发价
        "order_price":"16", // 委托价
        "mmr":"0.0013", // 爆仓时的维持保证金率
        "subsidies":"0.018", // 破产系统补贴额度
        "created_at": "2018-07-23T11:55:56.715305Z"
        }
    ]
    }
}
字段 类型 描述
order_id long 订单ID
contract_id long 合约ID
position_id long 仓位id
account_id int 账号ID
type int 爆仓类型,1:部分强平,2:破产,3:ADL主动发起,4:ADL被动发起
trigger_price string 触发价
order_price string 委托价
mmr string 爆仓时的维持保证金率
subsidies string 破产系统补贴额度
created_at string created_at

备注

1.该请求的参数组合有以下几种:

a.不传参数,表示获取用户所有的爆仓记录

b.只传contractID,表示获取用户该合约的爆仓记录

c.只传orderID,表示获取用户该订单的爆仓记录

 

订单成交明细

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/orderTrades?contractID=1&orderID=2064344648

GET /contract/v1/ifcontract/orderTrades

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
orderID long 订单ID
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    "data": {
        // 交易记录列表,按创建时间由近及远排序
        "trades": [
            {
                "order_id": 10116361, // taker order id
                "trade_id": 10116363, // trade id
                "contract_id": 1,     // 合约ID
                "deal_price": "16",   // 成交价
                "deal_vol": "10",     // 成交量
                "make_fee": "0.04",   // make fee
                "take_fee": "0.12",   // take fee
                "created_at": null,   // 创建时间
                "way": 5,             // 交易方向
                "fluctuation": "0"    // 对行情的影响
            }
        ]
    }
}
字段 类型 描述
order_id long taker order id
trade_id long trade id
contract_id ing 合约ID
deal_price string 成交价
deal_vol string 成交量
make_fee string make fee
take_fee string take fee
created_at string 创建时间
way int 交易方向 1 : 开多 买 2 : 平空 买 3 : 平多 卖 4 : 开空 卖
created_at string created_at
fluctuation string 对行情的影响

备注

fluctuation,对行情的影响,如本次交易前的最新交易价是10,本次交易的交易价是11,则fluctuation为"1"

用户必须登录后,才能查询到自己订单的交易记录

 

查询仓位费用情况

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/positionFee?contractID=32785&positionID=2154205116

GET /contract/v1/ifcontract/positionFee

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
positionID long 仓位ID
 

响应详情

返回json消息数据格式:

{
    "errno": "OK",
    "message": "Success",
    // 记录数组按照时间由近及远排序
    "data": [
        {
            "contract_id": 32785, // 合约ID
            "account_id": 2071026819, // 用户ID
            "position_id": 2154205116, // 仓位ID
            "fair_price": "0.849940605285", // 产生仓位费用时的合理价格
            "funding_rate": "0", // 产生仓位费用时的资金费率
            "fee": "-149.8912195248", // 手续费,负数表示赚的,正数表示付出费
            "vol": "1053468", // 产生仓位费用时的仓位持仓量
            "created_at": "2019-01-15T00:00:00.708979Z" // 产生仓位费用的时间,UTC时间
        },
        {
            "contract_id": 32785,
            "account_id": 2071026819,
            "position_id": 2154205116,
            "fair_price": "0.849940605285",
            "funding_rate": "0",
            "fee": "-261.432832752",
            "vol": "1053468",
            "created_at": "2019-01-14T16:00:01.183355Z"
        }
    ]
}
字段 类型 描述
contract_id ing 合约ID
account_id long 用户ID
position_id long 仓位ID
fair_price string 产生仓位费用时的合理价格
funding_rate string 产生仓位费用时的资金费率
fee string 手续费,负数表示赚的,正数表示付出费
vol int 产生仓位费用时的仓位持仓量
created_at string 产生仓位费用的时间,UTC时间

备注

记录数组按照时间由近及远排序

 

创建合约账户

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/createContractAccount?contractID=1

GET /contract/v1/ifcontract/createContractAccount

 

请求Headers

详情见签名方式

 

请求参数

参数 类型 是否必须 描述
contractID long 合约ID
 

响应详情

返回json消息数据格式:

{
    "errno": "OK", 
    "message": "Success",
    "data":{}
}
字段 类型 描述
errno int errno
message int 错误原因
 

批量下单

 
请求格式
https://api-cloud.bitmart.com/contract/v1/ifcontract/batchOrders

POST /contract/v1/ifcontract/batchOrders

 

请求Headers

详情见签名方式

 

请求参数

请求body示例

{
    "orders":[
        {
           "contract_id":3,
           "category":1,
           "custom_id":1, // 客户端自定义ID
           "way":4,
           "open_type":1,
           "leverage":100,
           "price":998,
           "vol":10
        },
        {
           "contract_id":3,
           "category":1,
           "custom_id":2,
           "way":4,
           "open_type":1,
           "leverage":100,
           "price":998,
           "vol":10
        }
    ],
   "nonce":1533876299 // 时间戳
}
  • 开仓订单消息的body
参数 类型 是否必须 描述
contract_id long
category int
way int
open_type int
custom_id int
leverage int
price int
vol int
  • 平仓订单消息的body
参数 类型 是否必须 描述
contract_id long
category int
position_id long
way int
custom_id int
price int
vol int
 

响应详情

返回json消息数据格式:

成功:
{
  "errno": "OK",
  "message": "Success",
  "data": {
      "orders": [
          {
              "custom_id": 1,
              "order_id": 10540013
          },
          {
              "custom_id": 2,
              "order_id": 10540014
          }
      ]
  }
}

失败:
{
  "errno": "OK",
  "message": "Success",
  "data": {
      "orders": [
          {
              "custom_id": 1,
              "err": {
                  "http_err":405,
                  "err_code":"LIQUIDATE_ORDER",
                  "err_msg":"订单将触发强平"
              }
          },
          {
              "custom_id": 2,
              "order_id": 10540014
          }
      ]
  }
}
字段 类型 描述
custom_id int 客户端自定义ID
order_id int 订单ID
 

提交订单

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/submitOrder

POST /contract/v1/ifcontract/submitOrder

 

请求Headers

详情见签名方式

 

请求参数

请求body示例

开仓订单消息的body
{
   "contract_id":1, // 合约ID
   "category":1,  // 订单类型
   "way":4,  // 订单方向
   "open_type":1, // 开仓方式
   "leverage":10, // 杠杆
   "price":16,  // 价格
   "vol":10,  // 
   "nonce":1531796011 // 时间戳
}

平仓订单消息的body
{
   "contract_id":1, // 合约ID
   "category":1,  // 订单类型
   "position_id":12121,  // 仓位ID
   "way":3,  // 订单方向
   "price":16,  // 价格
   "vol":10,  // 
   "nonce":1531796011 // 时间戳
}

开仓订单消息的body

参数 类型 是否必须 描述
contract_id long
category int
way int
open_type int
custom_id int
leverage int
price int
vol int

平仓订单消息的body

参数 类型 是否必须 描述
contract_id long
category int
position_id long
way int
custom_id int
price int
vol int

备注

category 订单类型 1:限价单,2:市价单

way 订单方向 1:开多,2:平空,3:平多,4:开空

open_type 开仓方式 1:逐仓,2:全仓

注意:平仓订单不能传open_type,否则返回无效参数

 

响应详情

返回json消息数据格式:

{
  "errno": "OK",
  "message": "Success",
  "data": {
      "order_id": 2707217580
  }
}

字段 类型 描述
order_id int 订单ID
 

取消订单

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/cancelOrders

POST /contract/v1/ifcontract/cancelOrders

 

请求Headers

详情见签名方式

 

请求参数

请求参数body

{
    "orders":[
        {
           "contract_id":1,  // 合约ID
           "orders":[
                10116356, // 订单ID
                10116357
            ]
        }
     ],
    "nonce":1531809458  // 时间戳(单位秒)
}
参数 类型 是否必须 描述
contractID long 合约ID
orders array 订单ID 数组
 

响应详情

返回json消息数据格式:

{
    "errno":"OK",
    "message":"Success",
    "data":{
        "succeed":[
            2707219612
        ],
        "failed":[]
    }
}
字段 类型 描述
succeed list 取消成功的订单列表
failed list 取消失败的订单列表
 

调整保证金

 

请求格式

https://api-cloud.bitmart.com/contract/v1/ifcontract/marginOper

POST /contract/v1/ifcontract/marginOper

 

请求Headers

详情见签名方式

 

请求参数

请求body示例

{
   "contract_id":3,  // 仓位的合约ID
   "position_id":10539974, // 仓位ID
   "vol":10,   // 保证金数额
   "oper_type":1, // 操作类型,1:追加保证金,2:减少保证金
   "nonce":1533871871 // 时间戳,单位秒
}
参数 类型 是否必须 描述
contract_id long 仓位的合约ID
position_id long 仓位ID
vol int 保证金数额
oper_type int 操作类型,1:追加保证金,2:减少保证金
nonce long 时间戳,单位秒
 

响应详情

返回json消息数据格式:

{"errno":"OK","message":"Success"}
字段 类型 描述
 

合约API 返回码

请求失败将返回Http Status 400 BAD REQUEST,并在返回body中显示具体错误码。

"INVALID_TIMESTAMP", "invalid timestamp" "INVALID_SIGNATURE", "invalid signature" "CLOUD_ACCOUNT_NOT_FOUND", "cloud account not found" "CLOUD_APP_NOT_FOUND", "cloud app not found" "CLOUD_TRADE_NO_NOT_FOUND", "out_trade_no not found" "CLOUD_TRADE_NO_EXISTED", "out_trade_no already existed" "CLOUD_APP_NOT_ACTIVED", "cloud app not actived" "CLOUD_APP_DISABLE", "cloud app disable" "CLOUD_ACCOUNT_COUNT_LIMIT", "cloud account count limit" "ORIGIN_UID_HAD_EXISTED", "ORIGIN_UID_HAD_EXISTED" "CLOUD_APP_NO_PUBLICK_KEY", "cloud app no publick key" "CLOUD_API_KEY_NOT_FOUND", "cloud api key not found" "INVALID_EXPIRED_TS", "invalid expired ts" "CLOUD_API_KEY_EXPIRED", "cloud api key expired" "TRANSFER_VOL_PRECISION_ERROR", "transfer vol precision error" "INVALID_IP_ERROR", "invalid ip error"

"PARSE_PARAMETER_ERROR", "parse parameter error" "CHECK_NONCE_ERROR", "check nonce error" "CHECK_VER_ERROR", "check ver error" "NOT_FOUND_FUNC_ERROR", "not found func error"

BAD_REQUEST, "Invalid request" UNAUTHORIZED, "unauthorized" FORBIDDEN, "forbidden" NO_PERMISSION, "no permission" INTERNAL_SERVER_ERROR, "server error" NOT_FOUND, "not found" INVALID_PARAMETER, "Invalid parameter" INVALID_REQUEST_TYPE, "Illegal request" SYSTEM_ERROR, "System error" ACCESS_TOO_OFTEN, "Access too often" CLIENT_TIME_INVALID, "Please check your system time."

CONTRACT_OFFLINE, "This contract is offline!" CONTRACT_PAUSE, "This contract's exchange has been paused!" CONTRACT_ORDER_WILL_LIQUIDATE, "This order would trigger user position liquidate!" CONTRACT_ORDER_HAVE_REVERSE_WAY, "It is not possible to open and close simultaneously in the same position!" CONTRACT_POSITION_IS_CLOSED, "Your position is closed!" CONTRACT_POSITION_IS_DELEGATING, "Your position is in liquidation delegating!" CONTRACT_POSITION_VOLUME_NOT_ENOUGH, "Your position volume is not enough!" CONTRACT_POSITION_NOT_EXSIT, "The position is not exsit" CONTRACT_POSITION_NOT_ISOLATED, "The position is not isolated" CONTRACT_POSITION_LIQUIDATE_WHEN_SUB_MARGIN, "The position would liquidate when sub margin" CONTRACT_POSITION_WARN_WHEN_SUB_MARGIN, "The position would be warnning of liquidation when sub margin" CONTRACT_POSITION_BASE_LIMIT_SUB_MARGIN, "The position’s margin shouldn’t be lower than the base limit" CONTRACT_USER_ASSET_IN_DELEGATE, "You cross margin position is in liquidation delegating." CONTRACT_USER_ASSET_NOT_ENOUGH, "You contract account available balance not enough."

CONTRACT_PLAN_ORDER_COUNT_IS_FULL, "Your plan order's count is more than system maximum limit." CCONTRACT_ORDER_LEVERAGE_TOO_LARGE, "The order's leverage is too large." CCONTRACT_ORDER_LEVERAGE_TOO_SMALL, "The order's leverage is too small." CONTRACT_ORDER_PRICE_WOULD_NOT_TRIGGER, "The deviation between current price and trigger price is too large." CONTRACT_PLAN_ORDER_LIFECYCLE_TOO_LONG, "The plan order's life cycle is too long." CONTRACT_PLAN_ORDER_LIFECYCLE_TOO_SHORT, "The plan order's life cycle is too short." CONTRACT_NOT_FOUND, "This contract not found!"

 

错误码

HTTP响应返回HTTP状态码200表示请求成功,并且会返回一个可选的body。我们会在每个资源下面标注具体的响应body。 除非特别说明,失败请求都会返回HTTP状态码4xx。http body都会包含一个参数message表示具体的错误原因。

通用错误码

Status Code 原因
400 Bad Request - 请求参数不合法
401 Unauthorized - API可以不合法
403 Forbidden - 无权限访问该资源
404 Not Found
500 Internal Server Error - 服务器异常
NAV Navbar