入门指引

欢迎使用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
  • 提升下单性能。
 

Rest API

API可用于订单管理,市场查询。每个请求必须使用描述的认证机制签名。

 

URL

https://openapi.bitmart.com

 

参数

在“授权接口”下所列的API,POST请求的参数需要放在HTTP Boday下面,而不是GET参数。

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

 

认证

认证请求需要您拥有BitMart API key。请登录BitMart网站,在账户页面申请API key。

 

API Key的生成

在签名任何请求前,您必须已有我们平台生成的API key。我们会提供以下两个字段的信息,请自行记住并保存。

  • API Key
  • API Secret
 

API Key 权限

默认情况下, API key可以访问所有本文档所列的API

 

获取Bearer Token (OAuth 2.0)

客户端使用API key和签名的信息来请求access token。 客户端需要将以下参数以application/x-www-form-urlencoded的格式发送到认证接口。

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

请查看代码示例 获取Bearer Token.

 

认证请求

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

  • _**X-BM-AUTHORIZATION**_
  • _**X-BM-TIMESTAMP**_

_**X-BM-AUTHORIZATION**_ 是以下格式的拼接 "Bearer " + Token, token是认证服务返回的字段。

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

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

 

HTTP请求

所有的请求和响应都是application/json的content-type, 并且按照通用的http status返回响应。

 

公开访问接口

 

获取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)
 

认证接口

 

Bearer Token

从认证服务器获取Bearer Token。

 

HMAC SHA256签名

HMAC SHA256签名以client_secret http头发送。

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

这里会演示如果用echo, opensslcurl这几个linux命令, 一步步生成client_secret

字段
API Key 6591f7c2491db0a23a1d8ad6911c825e
API Secret 8c08d9d5c3d15b105dbddaf96e427ac6
memo mymemo (memo是生成api key时由用户填写, 您可以登录bitmart.com,在账户页面查看你的api key对应的memo)
字段
grant_type client_credentials
client_id 6591f7c2491db0a23a1d8ad6911c825e
client_secret 18b9beb027d9ee75202655f37344ea5829c5c0d66a0781bf642bb3e944cf5019 (HMAC SHA256签名)
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)
}

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

{
   "access_token":"m261aeb5bfa471c67c6ac41243959ae0dd408838cdc1a47e945305dd558e2fa78",
   "expires_in":7200
}
 

响应详情

字段 类型 描述
access_token string Bearer token
expires_in numeric Token过期时间 (用秒表示)
 

钱包余额

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 当前页数
 

错误码

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 - 服务器异常
 

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。 我们的员工很乐意帮忙。
















NAV Navbar