Navbar
Contract API Spot API
中文
shell

Introduction

API Introduction

Welcome to the BFX API! You can use this API to get market data, trade, and manage your account.

On the right side of the document is the code example, which we currently only provide for the shell.

You can use the following link to switch between old API documents:

https://www.bfxnu.com/news/other.do

Change Log

Release Time (Beijing Time UTC +8) API New / Update Description
2019.12.20 16:00 BFX Spot API English Reference New Added Spot API English Reference
2019.12.03 16:50 Websocket market.$type.$symbol.trade Update Push messages add subscription addresses and timestamps
2019.11.01 19:00 GET /v1/history/orders.do Update Added the "state" return field to indicate the order status
2019.10.11 18:00 BFX Spot API Chinese Reference New Added Spot API Chinese Reference

Access Instructions

Access URLs

REST API

https://api.bfxnu.com/

Websocket Feed (market)

wss://api.bfxnu.com/v1/ws

Rate Limiting Rule

Authentication

Overview

The API request may be tampered during internet, therefore all private API must be signed by your API Key (Secrete Key).

Each API Key has permission property, please check the API permission, and make sure your API key has proper permission.

A valid request consists of below parts:

Create API Key

You can be here https://www.bfxnu.com/center/bindAppKey.do Create API Key.

API Key includes the following two parts:

Signature Method

Normative request for Signature calculation Different contents will get totally different results when use MD5 to calculate Signature, therefore, please normalize the requests before doing Signature calculation. Take the request of inquering order details as an example:

query details of one order

https://api.bfxnu.com/v1/trade/order.do?

AppKey=8e9e4b10413f49f682001c530beea232

&Timestamp=1568189479

&orderId=1082752

&symbol=bfxusdt

&Signature=a49c6053d05826f29356b189e1200f2a

1. Generation of signature parameter: sort all other parameter names in ASCII order, and splice parameter values and parameter names together. For example below is the original parameters:

Timestamp=1568189479

symbol=bfxusdt

orderId=1082752

AppKey=8e9e4b10413f49f682001c530beea232

2. Sorted by parameter name:

AppKey=8e9e4b10413f49f682001c530beea232

Timestamp=1568189479

orderId=1082752

symbol=bfxusdt

3. According to the above order, after splicing parameter name and parameter value:

AppKey8e9e4b10413f49f682001c530beea232Timestamp1568189479orderId1082752symbolbfxusdt

4. Add appsecret (for example, appsecret: 7c304b6b86f8403abc8091720a2415f2) to the above assembled string before and after, and encode UTF-8. Use MD5 algorithm to summarize the encoded byte stream:

MD5(7c304b6b86f8403abc8091720a2415f2AppKey8e9e4b10413f49f682001c530beea232
Timestamp1568189479orderId1082752symbolbfxusdt7c304b6b86f8403abc8091720a2415f2)

Signature result of hexadecimal string obtained: a49c6053d05826f29356b189e1200f2a

5. Add the above signature value to the API request as the value of the parameter signature:

Finally, the API request sent to the server should be:

https://api.bfxnu.com/v1/trade/order.do?AppKey=8e9e4b10413f49f682001c530beea232&Timestamp=1568189479&orderId=1082752&symbol=bfxusdt&Signature=a49c6053d05826f29356b189e1200f2a

  1. Add all required authentication parameters to the path parameters of the interface call.

  2. Add the digital signature to the path parameter after the URL is encoded. The parameter is called "signature".

Request Format

  1. All API requests are sent in the form of get or post.

  2. Please use FormData to transfer parameters and set User-Agent in Header:
    "Content-Type": "application/x-www-form-urlencoded",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 UBrowser/6.0.1471.813 Safari/537.36"

Response Format

The response is JSON format.There are three fields in the top level: "code", "data", and "msg". The business data is is under data field.

Return Content Format

The returned content will be in the following format:

{
  "code": 0,
  "msg": "",
  "data": // per API response data in nested JSON object
}
Field Name Data Type Description
code int Error code (0- success, others - failure)
msg string Error message (when code=0 succeeds, this parameter is "")
data array Interface returns the data body (no value on failure)

Error Message

General status code description

Error Message Description
Code: 10000 Other errors (MSG returns specific error message)
Code: 10001 Wrong parameters submitted
Code: 10020 Token invalid or error, need to login again

Code: Other error codes (MSG returns specific error message)

Reference Data

Get All Supported Trading Symbol

This endpoint returns all BFX's supported trading symbol.

HTTP Request

curl "https://api.bfxnu.com/v1/common/symbols.do?type=spot"

Request Parameters

Parameter Data Type Required Default Description Value Range
type string false contract Market Types contract, spot, vcontract

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "symbol":"btcusdt",
        "coin":"btc",
        "market":"usdt",
        "pricePrecision":2,
        "amountPrecision":4
      },
      {
        "symbol":"ethusdt",
        "coin":"eth",
        "market":"usdt",
        "pricePrecision":2,
        "amountPrecision":4
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
symbol string Trading Symbol
coin string Base currency in a trading symbol
market string Quote currency in a trading symbol
pricePrecision integer Quote currency precision when quote price(decimal places)
amountPrecision integer Base currency precision when quote amount(decimal places)

Get All Supported Currencies

This endpoint returns all BFX's supported trading currencies.

HTTP Request

curl "https://api.bfxnu.com/v1/common/currencys.do"

Request Parameters

No parameter is needed for this endpoint.

Response:

{
  "code": 0,
  "msg": "",
  "data": [
        "btc",
        "usdt",
        "eth",
        "bfx",
      ...
   ]
}

Response Content

Market Data

Get Klines(Candles)

This endpoint retrieves all klines in a specific range.

HTTP Request

curl "https://api.bfxnu.com/v1/market/kline.do?symbol=btcusdt&interval=15min&type=spot"

Request Parameters

Parameter Data Type Required Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
interval string true NA Kline Period 1min, 3min, 5min, See below for details

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "code":"btcusdt",
        "first":10205.58,
        "high":10210.01,
        "last":10192.18,
        "low":10190.28,
        "time":1568705400,
        "vol":23.23
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
code string Trading Symbol
first float The opening price
high float The high price
last float The closing price
low float The low price
time long Timestamp
vol float The trading volume in base currency of last 24 hours

Get Market Information (Ticker)

This interface returns the contract market situation (Ticker), last price, high price, low price, trading volume, best bid and best ask.

HTTP Request

curl "https://api.bfxnu.com/v1/market/ticker.do?symbol=btcusdt&type=spot"

Request Parameters

Parameter Data Type Required Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...

Response:

{
  "code": 0,
  "msg": "",
  "data": {
    "symbol":"btcusdt",
    "buy":10191.65,
    "sell":10193.72,
    "high":10268.48,
    "last":10192.5,
    "low":10141.53,
    "trades":50584730.78,
    "vol":4954.56
  }
}

Response Content

Field Name Data Type Description
symbol string Trading Symbol
buy float Best bid
sell float Best ask
high float The high price
last float The last price
low float The low price
trades float Aggregated trading value (in quote currency)
vol float The trading volume in base currency of last 24 hours

Get All The Market Information (Tickers)

This interface returns all contract market quotations (Tickers), last price, high price, low price, trading volume, best bid and best ask.

HTTP Request

curl "https://api.bfxnu.com/v1/market/tickers.do?type=spot"

Request Parameters

Parameter Data Type Required Default Description Value Range
type string false contract Market Types contract, spot, vcontract

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "symbol":"btcusdt",
        "buy":10195.79,
        "sell":10197.88,
        "high":10268.48,
        "last":10196.55,
        "low":10141.53,
        "trades":50445638.61,
        "vol":4940.96
      },
      {
        "symbol":"ethusdt",
        "buy":214.09,
        "sell":214.38,
        "high":214.92,
        "last":214.23,
        "low":196.78,
        "trades":8222181.8,
        "vol":39749.57
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
symbol string Trading Symbol
buy float Best bid
sell float Best ask
high float The high price
last float The last price
low float The low price
trades float Aggregated trading value (in quote currency)
vol float The trading volume in base currency of last 24 hours

Get Market Depth

This endpoint retrieves the current order book of a specific pair.

HTTP Request

curl "https://api.bfxnu.com/v1/market/depth.do?symbol=btcusdt&type=spot"

Request Parameters

Parameter Data Type Required Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
bfx string false "" Return precision or not "" or any string

Response:

{
  "code": 0,
  "msg": "",
  "amountDigits": 4,
  "digits": 2,
  "data": {
    "bids": [
      [7964.12, 0.0678], // [price, amount]
      [7963.4, 0.9162],
      [7961, 0.1],
      [7960.6, 12.8898],
      [7958, 1.2],
      ...
    ],
    "asks": [
      [7979.55, 0.0736],
      [7980.6, 1.0292],
      [7981, 5.5652],
      [7986.1, 0.2416],
      [7990.66, 1.9970],
      ...
    ]
  }
}

Response Content

Field Name Data Type Description
amountDigits integer Quantities retain decimal places
digits integer Prices retain decimal places
bids object The current all bids in format [price, quote volume]
asks object The current all asks in format [price, quote volume]

Get Spot History

This interface returns the spot transaction record to obtain the spot transaction history, Quantity: 50.

HTTP Request

curl "https://api.bfxnu.com/v1/market/trades.do?symbol=btcusdt&type=spot"

Request Parameters

Parameter Data Type Required Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
bfx string false "" Return precision or not "" or any string

Response:

{
  "code": 0,
  "msg": "",
  "amountDigits": 4,
  "digits": 2,
  "data": [
      {
        "type":"buy",
        "amount":0.47,
        "date":1568876917,
        "price":9862.44,
        "vol":4635.3468
      },
      {
        "type":"sell",
        "amount":0.07,
        "date":1568876900,
        "price":9861.47,
        "vol":690.3029
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
amountDigits integer Quantities retain decimal places
digits integer Prices retain decimal places
type string Transaction direction (buy or sell)
amount float Aggregated trading volume during the interval (in base currency)
date long Last trade time
price float The limit price of limit order
vol float The trading volume in base currency of last 24 hours

Account

Query All Currency Assets

This interface returns to query all currency assets.

HTTP Request

curl "https://api.bfxnu.com/v1/account/accounts.do?AppKey=b779e1982b77478d8d23e69f7e7df10f&Timestamp=1570601407&type=spot&Signature=4469ee0fef8a34161956c42ce29746d7"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "symbol":"btc",
        "available":0,
        "frozen":0
      },
      {
        "symbol":"usdt",
        "available":214,
        "frozen":0
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
symbol string Currency name
available float Available Balance
frozen float Frozen Balance

Query Single Currency Assets

This interface returns to query a single contract asset.

HTTP Request

curl "https://api.bfxnu.com/v1/account/account.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1571388790&symbol=btc&type=spot&Signature=bbad4f07325803bcfd44c29f09552442"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Currency name btc, eth, ht...

Response:

{
  "code": 0,
  "msg": "",
  "data": {
      "symbol":"btc",
      "available":1.64916,
      "frozen":0
   }
}

Response Content

Field Name Data Type Description
symbol string Currency Name
available float Available Balance
frozen float Frozen Balance

Stable Coin Exchange

Exchange For Stable Coin

Send an exchange order request to BFX.

HTTP Request

{
  "AppKey": "284e7228ab324e1f82a13faada3cf431",
  "Timestamp": 1570777192,
  "Signature": "bad4d08be4cf4ce62bd45f7fffa80e73",
  "originCoinName": "btc",
  "targetCoinName": "usdt",
  "quantity": "100"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
originCoinName string true NA Origin Coin Name btc, eth, usdt...
targetCoinName string true NA Target Coin Name btc, eth, usdt...
quantity string true NA Quantity

Response:

{
  "code": 0,
  "msg": "",
  "data": 4
}

Response Content

Field Name Data Type Description
data long Record id

Stable Coin Single Exchange Record Query

This interface queries the single exchange record of stable coin.

HTTP Request

curl "https://api.bfxnu.com/v1/exchange/record.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570779234&recordId=4&Signature=7d0429244626cbdf179110e78d30f10e"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
recordId long true NA Record id

Response:

{
  "code": 0,
  "msg": "",
  "data": {
    "avgPrice":0,
    "obtainAmount":0,
    "oriAmount":0.0139,
    "originCoinName":"btc",
    "presentPrice":7200,
    "recordId":4,
    "recordTime":1570777192,
    "state":"processing",
    "targetAmount":100,
    "targetCoinName":"usdt"
  }
}

Response Content

Field Name Data Type Description
avgPrice float Average Price
obtainAmount float Obtain Amount
oriAmount float Exchange Amount
originCoinName string Origin Coin Name
presentPrice float Exchange Price
recordId long Record id
recordTime long Record Timestamp
state string state: processing, success, canceled
targetAmount float Target Amount
targetCoinName string Target Coin Name

Stable Coin Multiple Exchange Records Query

This interface queries multiple exchange records of stable coin.

HTTP Request

curl "https://api.bfxnu.com/v1/exchange/records.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570783684&direct=next&endTime=1570783588&from=20&originCoinName=btc&size=100&startTime=1557543620&targetCoinName=usdt&Signature=be90eb75537fe8ff8edc5155a3f7eed5"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
originCoinName string true NA Origin Coin Name btc, eth, usdt...
targetCoinName string true NA Target Coin Name btc, eth, usdt...
size integer false 10 Order Quantity [1-100]
from long false NA The Start Order ID It needs to be used together with the direct parameter
direct string false NA Query Direction prev, next (Query direction should be used with the from parameter at the same time)
startTime long false NA Start Timestamp (s) Second Timestamps
endTime long false NA End Timestamp (s) Second Timestamps

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "avgPrice":0,
        "obtainAmount":0,
        "oriAmount":0.0327,
        "originCoinName":"btc",
        "presentPrice":7200,
        "recordId":5,
        "recordTime":1570782620,
        "state":"processing",
        "targetAmount":235,
        "targetCoinName":"usdt"
      },
      {
        "avgPrice":0,
        "obtainAmount":0,
        "oriAmount":0.0139,
        "originCoinName":"btc",
        "presentPrice":7200,
        "recordId":4,
        "recordTime":1570777192,
        "state":"processing",
        "targetAmount":100,
        "targetCoinName":"usdt"
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
avgPrice float Average Price
obtainAmount float Obtain Amount
oriAmount float Exchange Amount
originCoinName string Origin Coin Name
presentPrice float Exchange Price
recordId long Record id
recordTime long Record Timestamp
state string state: processing, success, canceled
targetAmount float Target Amount
targetCoinName string Target Coin Name

Spot Trade Interface

Place A New Order

Send a new open order to bfx for matching.

HTTP Request

{
  "AppKey": "284e7228ab324e1f82a13faada3cf431",
  "Timestamp": 1570612482,
  "Signature": "8c7f41c192a0ae564a5972ee18482fe0",
  "type": "spot",
  "symbol": "btcusdt",
  "price": "14000",
  "amount": "0.01",
  "operation": "sell"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
price string true NA Order Price
amount string true NA Order Amount
operation string true NA Order direction buy, sell

Response:

{
  "code": 0,
  "msg": "",
  "data": "1562141102549109"
}

Response Content

Field Name Data Type Description
data string Order ID

Cancel Order

This interface sends a request to cancel an order.

HTTP Request

{
  "AppKey": "284e7228ab324e1f82a13faada3cf431",
  "Timestamp": 1570678375,
  "Signature": "2a2596461b75a85278c86fe3960ca4d8",
  "type": "spot",
  "symbol": "btcusdt",
  "orderId": "1570612201371537"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
orderId string true NA Order ID

Response:

{
  "code": 0,
  "msg": "",
  "data": "1570612201371537"
}

Response Content

Field Name Data Type Description
data string Order ID

Submit Cancel for Multiple Orders by IDs

This endpoint submit cancellation for multiple orders at once with given ids.

HTTP Request

{
  "AppKey": "284e7228ab324e1f82a13faada3cf431",
  "Timestamp": 1570678375,
  "Signature": "2a2596461b75a85278c86fe3960ca4d8",
  "type": "spot",
  "symbol": "btcusdt",
  "side": "sell"
}

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
side string true NA Order Type all, buy, sell

Response:

{
  "code": 0,
  "msg": "",
  "data": {
    "successCount":4,
    "failedCount":0
  }
}

Response Content

Field Name Data Type Description
successCount integer Cancel Successful Order Quantity
failedCount integer Cancel Failed Order Quantity

Get the Order Detail of an Order

This endpoint returns the detail of one order.

HTTP Request

curl "https://api.bfxnu.com/v1/trade/order.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570699502&orderId=1570612201371537&symbol=btcusdt&type=spot&Signature=5db1d808593145f45af05c97ce5300ad"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
orderId string true NA Order ID

Response:

{
  "code": 0,
  "msg": "",
  "data": {
    "amount":0.01,
    "createTime":1570612201,
    "dealAmount":0,
    "delegation_id":0,
    "deposit":0,
    "direction":2,
    "multiple":0,
    "orderId":"1570612201371537",
    "price":14000,
    "priority":0,
    "state":"canceled",
    "symbol":"btcusdt",
    "undealAmount":0.01
  }
}

Response Content

Field Name Data Type Description
amount float Order Amount
createTime long Order Create Time
dealAmount float Deal Amount
delegation_id long Delegation ID
deposit float deposit (Contract only, spot is 0)
direction integer Order direction, 1-buy, 2-sell
multiple integer Leverage Ratio (Contract only, spot is 0)
orderId string Order ID
price float Order Price
priority integer Order type, 1-open, 2-close (Contract only, spot is 0)
state string Order State, submitting, submitted, filled, canceled
symbol string Trading Symbol
undealAmount float Undeal Amount

Query Current Pending Orders

This interface queries current pending orders based on search criteria.

HTTP Request

curl "https://api.bfxnu.com/v1/trade/orders.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570765354&endTime=1570762820&size=100&startTime=1557543620&states=submitted%2Csubmitting&symbol=btcusdt&type=spot&Signature=0d8a6517077bae18b9c0576571496f3f"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
size integer false 10 Order Quantity [1-100]
states string false submitted Order Status Set (separated by ",") submitting, submitted
startTime long false NA Start Timestamp (s) Second Timestamps
endTime long false NA End Timestamp (s) Second Timestamps

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "amount":0.01,
        "createTime":1570762591,
        "dealAmount":0,
        "delegation_id":8917995,
        "deposit":0,
        "direction":2,
        "multiple":0,
        "orderId":"1570762591618249",
        "price":14000,
        "priority":0,
        "state":"submitted",
        "symbol":"btcusdt",
        "undealAmount":0.01
      },
      {
        "amount":0.01,
        "createTime":1570762579,
        "dealAmount":0,
        "delegation_id":8917994,
        "deposit":0,
        "direction":2,
        "multiple":0,
        "orderId":"1570762579853648",
        "price":14000,
        "priority":0,
        "state":"submitted",
        "symbol":"btcusdt",
        "undealAmount":0.01
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
amount float Order Amount
createTime long Order Create Time
dealAmount float Deal Amount
delegation_id long Delegation ID
deposit float deposit (Contract only, spot is 0)
direction integer Order direction, 1-buy, 2-sell
multiple integer Leverage Ratio (Contract only, spot is 0)
orderId string Order ID
price float Order Price
priority integer Order type, 1-open, 2-close (Contract only, spot is 0)
state string Order State: submitting, submitted, filled, canceled
symbol string Trading Symbol
undealAmount float Undeal Amount

Query History Order

This interface queries for historical orders based on search criteria.

HTTP Request

curl "https://api.bfxnu.com/v1/trade/history/orders.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1571390736&direct=prev&endTime=1571389895&from=20&size=100&startTime=1557543620&symbol=btcusdt&type=spot&Signature=e7e486f20c36d5070c54f7c262905fd5"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
size integer false 10 Order Quantity [1-100]
from long false NA The Start Order ID It needs to be used together with the direct parameter
direct string false NA Query Direction prev, next (Query direction should be used with the from parameter at the same time)
startTime long false NA Start Timestamp (s) Second Timestamps
endTime long false NA End Timestamp (s) Second Timestamps

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "amount":0.01,
        "dealAmount":0.01,
        "deposit":0,
        "direction":1,
        "multiple":0,
        "price":10685.35,
        "recordId":156,
        "tradeAvgPrice":10685.35,
        "undealAmount":0,
        "orderId":"1570771804268987",
        "symbol":"btcusdt",
        "createTime":1570771804,
        "updateTime":1570771804,
        "tradeType":0
      },
      {
        "amount":0.01,
        "dealAmount":0,
        "deposit":0,
        "direction":2,
        "multiple":0,
        "price":14000,
        "recordId":148,
        "tradeAvgPrice":0,
        "undealAmount":0.01,
        "orderId":"1570612201371537",
        "symbol":"btcusdt",
        "createTime":1570612201,
        "updateTime":1570678375,
        "tradeType":0
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
amount float Order Amount
dealAmount float Deal Amount
deposit float deposit (Contract only, spot is 0)
direction integer Direction, 1- buy, 2- sell
multiple integer Leverage Ratio (Contract only, spot is 0)
price float Order price
recordId integer Record ID
tradeAvgPrice float Trade Average Price
undealAmount float Undeal Amount
orderId string Order Id
symbol string Trading Symbol
createTime long Create Timestamp
updateTime long Operation Timestamp
tradeType integer Trade Type: 1- multiple single open positions, 2- multiple single unwinding positions, 3- empty single open positions, 4- empty single unwinding positions (Contract only, spot is 0)
state string Order State, submitting, submitted, filled, canceled

Query Transaction Records

This interface queries for transaction records based on search criteria.

HTTP Request

curl "https://api.bfxnu.com/v1/trade/history/trades.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570774448&direct=prev&from=20&size=100&symbol=btcusdt&type=spot&Signature=6dc09282a1d9eb8a20c45557e0a27956"

Request Parameters

Parameter Data Type Required Default Description Value Range
AppKey string true NA It is used in API request The 'Access Key' in your API Key
Timestamp long true NA Timestamp Second Timestamps
Signature string true NA Signature Calculated value by signature
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
size integer false 10 Order Quantity [1-100]
from long false NA The Start Order ID It needs to be used together with the direct parameter
direct string false NA Query Direction prev, next (Query direction should be used with the from parameter at the same time)
startTime long false NA Start Timestamp (s) Second Timestamps
endTime long false NA End Timestamp (s) Second Timestamps

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "direction":1,
        "holdPrice":0,
        "multiple":0,
        "symbol":"btcusdt",
        "tradeBfxFee":0,
        "tradeCount":0.01,
        "tradeDeposit":0,
        "tradeFee":0.0002,
        "tradeId":86,
        "tradeIncome":0,
        "tradePrice":10685.35,
        "tradeTime":1570771804,
        "tradeType":0
      },
      {
        "direction":2,
        "holdPrice":0,
        "multiple":0,
        "symbol":"btcusdt",
        "tradeBfxFee":0,
        "tradeCount":0.1,
        "tradeDeposit":0,
        "tradeFee":21.37026,
        "tradeId":84,
        "tradeIncome":0,
        "tradePrice":10685.13,
        "tradeTime":1570771031,
        "tradeType":0
      },
      ...
   ]
}

Response Content

Field Name Data Type Description
direction integer Direction, 1- buy, 2- sell
holdPrice float Hold Price (Contract only, spot is 0)
multiple integer Leverage Ratio (Contract only, spot is 0)
symbol string Trading Symbol
tradeBfxFee float Bfx platform coin offset transaction fee
tradeCount float Trade Count
tradeDeposit float Trade Deposit (Contract only, spot is 0)
tradeFee float Trade Fee
tradeId long Trade ID
tradeIncome float Trade Income (Contract only, spot is 0)
tradePrice float Trade price
tradeTime long Last trade time
tradeType integer Trade Type: 1- multiple single open positions, 2- multiple single unwinding positions, 3- empty single open positions, 4- empty single unwinding positions (Contract only, spot is 0)

Websocket Market Data

General

Websocket URL

Websocket Market Feed

wss://api.bfxnu.com/v1/ws

Heartbeat and Connection

Response

{
  "ping": 1570697959
}

After connected to BFX's Websocket server, the server will send heartbeat periodically (currently at 5s interval). The heartbeat message ping will have an integer in it, e.g.
  {
    "ping": 1570697959
  }

Subscribe request

{
  "pong": 1570697959
}

When client receives this heartbeat message, it should response with a matching pong message which has the same integer in it, e.g.
  {
    "pong": 1570697959
  }

Subscribe to Topic

{
  "sub": "kline.spot.btcusdt.15min"
}

To receive data you have to send a "sub" message first.
  {
    "sub": "topic to sub"
  } 

{
  "code": 10000,
  "msg": "Subscription failed, unsupported type: kline.spot.btcusdtcccc.15min",
  "ts": 1571378705
}

If the subscription fails, the Websocket client will receive it
  {
    "code": "Error code (0- success, others - failure)",
    "msg": "Error message (when code=0 succeeds, this parameter is "")",
    "ts": "Second timestamp"
  } 

{
  "code": 0,
  "msg": "ok",
  "subbed": "kline.spot.btcusdt.15min",
  "ts": 1571373335
}

After successful subscription, the Websocket client receives confirmation:
  {
    "code": "Error code (0- success, others - failure)",
    "msg": "Error message (when code=0 succeeds, this parameter is "")",
    "subbed": "Subscription Address",
    "ts": "Second Timestamps"
  } 

{
  "ch": "kline.spot.btcusdt.15min",
  "ts": 1571373361,
  "tick": [
    {
      "code": "btcusdt",
      "first": 8070.65,
      "high": 8072.18,
      "id": 3453,
      "last": 8068.52,
      "low": 8068.52,
      "time": 1571373900,
      "vol": 3.56
    }
  ]
}

Then, as soon as the subscribed topic is updated, the Websocket client receives the update message pushed by the server
  {
    "ch": "Subscription Address",
    "ts": "Second Timestamps",
    "tick": "Market Data"
  }

Unsubscribe

{
  "unsub": "kline.spot.btcusdt.15min"
}

Unsubscribe is formatted as follows (unsubscribe successfully with no return value)
  {
    "unsub": "Unsubscribe address"
  }

Pull Data

While connected to websocket, you can also use it in pull style by sending message to the server.

{
  "req": "kline.spot.btcusdt.15min"
}

To request pull style data, you send below message
  {
    "req": "The request url"
  } 

{
  "code": 0,
  "msg": "",
  "rep": "kline.spot.btcusdt.15min",
  "ts": 1571377747,
  "tick": [
    {
      "code": "btcusdt",
      "first": 3600,
      "high": 3900,
      "last": 3900,
      "low": 3600,
      "time": 1551685500,
      "vol": 3.5
    },
    {
      "code": "btcusdt",
      "first": 3894.47,
      "high": 3926.1,
      "last": 3918.01,
      "low": 3870.9,
      "time": 1552024800,
      "vol": 53.28
    }
  ]
}

You will receive a response accordingly and immediately
  {
    "code": "Error code (0- success, others - failure)",
    "msg": "Error message (when code=0 succeeds, this parameter is "")",
    "rep": "Subscription Address",
    "ts": "Second Timestamps"
    "tick": "Market Data"
  }

Market Candlestick

Topic

This topic sends a new candlestick whenever it is available.

kline.$type.$symbol.$interval

Subscribe request

{
  "sub": "kline.spot.btcusdt.15min"
}

Topic Parameter

Parameter Data Type Required Default Description Value Range
type string true NA Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...
interval string true NA Kline Period 1min, 3min, 5min, See below for details

Response

{
  "code": 0,
  "msg": "",
  "subbed": "kline.spot.btcusdt.15min",
  "ts": 1571392927
}

Response Content

Field Name Data Type Description
subbed string Subscription Address
ts long Second Timestamps

Update example

{
  "ch": "kline.spot.btcusdt.15min",
  "tick": [
    {
      "code": "btcusdt",
      "first": 8070.65,
      "high": 8072.18,
      "id": 3453,
      "last": 8068.52,
      "low": 8068.52,
      "time": 1571373900,
      "vol": 3.56
    }
  ]
}

Update Content

Field Name Data Type Description
code string Trading Symbol
first float The opening price
high float The high price
id long Record id
last float The closing price
low float The low price
time long Timestamp
vol float The trading volume in base currency of last 24 hours

Req request

{
  "req": "kline.spot.btcusdt.15min"
}

Pull Request

Pull request is supported.
  {
    "req": "kline.$type.$symbol.$interval"
  }

Market Depth

When market depth changes, this topic sends the latest market depth update data.

Topic

market.$type.$symbol.depth

Subscribe request

{
  "sub": "market.spot.btcusdt.depth"
}

Topic Parameter

Parameter Data Type Required Default Description Value Range
type string true NA Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...

Response

{
  "code": 0,
  "msg": "",
  "subbed": "market.spot.btcusdt.depth",
  "ts": 1571379519
}

Response Content

Field Name Data Type Description
subbed string Subscription Address
ts long Second Timestamps

Update example

{
  "ch": "market.spot.btcusdt.depth",
  "ts": 1571379520,
  "tick": {
    "bids": [
    [7897.38,0.02], // [price, amount]
    [7897.18,0.13]
    // more Market Depth data here
    ],
    "asks": [
    [7901.37,0.2],
    [7901.16,0.05]
    // more Market Depth data here
    ]
  }
}

Update Content

Field Name Data Type Description
bids object The current all bids in format [price, quote volume]
asks object The current all asks in format [price, quote volume]

Req request

{
  "req": "market.spot.btcusdt.depth"
}

Pull Request

Pull request is supported.
  {
    "req": "market.$type.$symbol.depth"
  }

Trade Detail

This topic sends the latest completed trade. It updates in tick by tick mode.

Topic

market.$type.$symbol.trade

Subscribe request

{
  "sub": "market.spot.btcusdt.trade"
}

Topic Parameter

Parameter Data Type Required Default Description Value Range
type string true NA Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btcusdt, ethusdt, htusdt...

Response

{
  "code": 0,
  "msg": "",
  "subbed": "market.spot.btcusdt.trade",
  "ts": 1571383431
}

Response Content

Field Name Data Type Description
subbed string Subscription Address
ts long Second Timestamps

Update example

{
  "ch": "market.spot.btcusdt.trade",
  "ts": 1571379520,
  "tick": [
    {
    "amount": 0.85,
    "date": 1571383457,
    "price": 7895.59,
    "tid": 114202,
    "type": "buy"
    }
  ]
}

Update Content

Field Name Data Type Description
amount float Trade Volume
date long Trade Time
price float Trade Price
tid long Trade ID
type string Aggressive order side of the trade: 'buy' or 'sell'

Req request

{
  "req": "market.spot.btcusdt.trade"
}

Pull Request

Pull request is supported.
  {
    "req": "market.$type.$symbol.trade"
  }






shell