Navbar
中文
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.bfx.nu/news/other.do

Change Log

Release Time (Beijing Time UTC +8) API New / Update Description
2019.12.20 16:00 BFX Contract API English Reference New Added Contract 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.12 16:00 BFX Contract API Chinese Reference New Added Contract API Chinese Reference

Access Instructions

Access URLs

REST API

https://api.bfx.nu/

Websocket Feed (market)

wss://api.bfx.nu/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.bfx.nu/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.bfx.nu/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.bfx.nu/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 Contract Names And Precision

This interface returns the contract name and precision supported by all platforms.

HTTP Request

curl "https://api.bfx.nu/v1/common/symbols.do?type=contract"

Request Parameter

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

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "symbol":"btc",
        "showName":"BTC",
        "multiples":"20",
        "pricePrecision":1,
        "amountPrecision":2
      },
      {
        "symbol":"eth",
        "showName":"ETH",
        "multiples":"20",
        "pricePrecision":2,
        "amountPrecision":2
      },
      ...
   ]
}

Return Parameter

Field Name Data Type Description
symbol string Trading Symbol
showName string Show Name
multiples string Supported multiples, separated by ","
pricePrecision integer Quote currency precision when quote price(decimal places)
amountPrecision integer Base currency precision when quote amount(decimal places)

Market Data

Get Klines(Candles)

This endpoint retrieves all klines in a specific range.

HTTP Request

curl "https://api.bfx.nu/v1/market/kline.do?symbol=btc&interval=15min&type=contract"

Request Parameter

Parameter Name Data Type Mandatory Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btc, eth, ht...
interval string true NA Kline Period 1min, 3min, 5min, See below for details

Response:

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

Return Parameter

Field Name Data Type Description
code string Contract Type
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.bfx.nu/v1/market/ticker.do?symbol=btc&type=contract"

Request Parameter

Parameter Name Data Type Mandatory Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btc, eth, ht...

Response:

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

Return Parameter

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.bfx.nu/v1/market/tickers.do?type=contract"

Request Parameter

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

Response:

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

Return Parameter

Field Name Data Type Description
symbol string Trading Symbol
change string Increase of position (contract transaction)
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.bfx.nu/v1/market/depth.do?symbol=btc&type=contract"

Request Parameter

Parameter Name Data Type Mandatory Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btc, eth, ht...
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],
      ...
    ]
  }
}

Return Parameter

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 Contract History

This interface returns the contract transaction record to obtain the contract historical transaction record, Quantity: 50.

HTTP Request

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

Request Parameter

Parameter Name Data Type Mandatory Default Description Value Range
type string false contract Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btc, eth, ht...
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,
        "change":3.26,
        "tid":5509739
      },
      {
        "type":"sell",
        "amount":0.07,
        "date":1568876900,
        "price":9861.47,
        "change":0,
        "tid":5509742
      },
      ...
   ]
}

Return Parameter

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
change float Increase of position (contract transaction)
tid long id

Account

Query All Contract Assets

This interface returns to query all contract assets.

HTTP Request

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

Request Parameter

Parameter Name Data Type Mandatory 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
      },
      ...
   ]
}

Return Parameter

Field Name Data Type Description
symbol string Trading Symbol
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.bfx.nu/v1/account/account.do?AppKey=c5fe0cc7d3434efb817fef0ba63ea614&Timestamp=1571209967&symbol=btc&type=contract&Signature=c7d3dc4bddf8b530c355a930ce41af3e"

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...

Response:

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

Return Parameter

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

Transfer Asset (Between currency and contract)

Transfer in and out of contract account (Between currency and contract).

HTTP Request

{
  "AppKey": "c5fe0cc7d3434efb817fef0ba63ea614",
  "Timestamp": 1571212250,
  "Signature": "c5ac81af7f18d465232652ccee98b7fa",
  "type": "contract",
  "symbol": "btc",
  "operation": "out",
  "amount": "0.1"
}

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
operation string true NA Operation Direction in, out
amount string true NA Amount

Response:

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

Return Parameter

Field Name Data Type Description
data long Record id

Transfer Fund History Query

This interface queries the history of transfer fund.

HTTP Request

curl "https://api.bfx.nu/v1/account/transfer/records.do?AppKey=c5fe0cc7d3434efb817fef0ba63ea614&Timestamp=1571213734&direct=prev&endTime=1571213617&from=20&side=all&size=100&startTime=1557543620&symbol=btc&type=contract&Signature=3645b48620adfe0f5c784f7a1196ec7a"

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
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": [
      {
        "symbol":"btc",
        "amount":0.1,
        "operation":2,
        "recordId":1688,
        "recordTime":1571212250
      },
      {
        "symbol":"btc",
        "amount":15.6,
        "operation":2,
        "recordId":1671,
        "recordTime":1565674096
      },
      ...
   ]
}

Return Parameter

Field Name Data Type Description
symbol string Trading Symbol
amount float Transfer Amount
operation integer Operation Direction, (1: in, 2: out)
recordId long Record id
recordTime long Operation Timestamp

Contract Trade Interface

Place A New Order

Send a new open order to bfx for matching.

HTTP Request

{
  "AppKey": "284e7228ab324e1f82a13faada3cf431",
  "Timestamp": 1570856203,
  "Signature": "bbb7fdff74908fff5e18052acce0612d",
  "type": "contract",
  "symbol": "btc",
  "price": "14000",
  "amount": "0.1",
  "multiple": 20,
  "operation": "sell"
}

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
price string true NA Order Price
amount string true NA Order Amount
multiple integer true NA Leverage Ratio (Contract only, spot is 0)
operation string true NA Order direction buy, sell

Response:

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

Return Parameter

Field Name Data Type Description
data string Order ID

Place Close Order

Send a closing order request to BFX for matchmaking.

HTTP Request

{
  "AppKey": "284e7228ab324e1f82a13faada3cf431",
  "Timestamp": 1570858613,
  "Signature": "ad35471360bbaaeca74f0b02e2860d99",
  "type": "contract",
  "symbol": "btc",
  "price": "8761",
  "amount": "0.1",
  "positionId": 197
}

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
price string true NA Close Order Price
amount string true NA Close Order Amount
positionId long true NA Position Id

Response:

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

Return Parameter

Field Name Data Type Description
data string Order ID

Contract Position Query

This interface returns the latest status and details for specifying a single order.

HTTP Request

curl "https://api.bfx.nu/v1/trade/positions.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570856750&symbol=btc&type=contract&Signature=5b133508bf308424ba9fe4ccff3752f5"

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...

Response:

{
  "code": 0,
  "msg": "",
  "data": [
      {
        "allCount":0.2,
        "avgPrice":10945,
        "deposit":109.45,
        "direction":1,
        "floatingProfitLoss":-524.462,
        "forcedLiquidationPrice":1742.74,
        "holdCount":0.2,
        "lockCount":0,
        "multiple":20,
        "positionId":"198",
        "profitLossRatio":"-479.17%",
        "symbol":"btc",
        "stopLoss":False
      },
      {
        "allCount":0.3,
        "avgPrice":10148.96,
        "deposit":152.2344,
        "direction":2,
        "floatingProfitLoss":547.8819,
        "forcedLiquidationPrice":14650.54,
        "holdCount":0.3,
        "lockCount":0,
        "multiple":20,
        "positionId":"197",
        "profitLossRatio":"359.89%",
        "symbol":"btc",
        "stopLoss":False
      },
      ...
   ]
}

Return Parameter

Field Name Data Type Description
allCount float Total Positions
avgPrice float Average Price Of Position
deposit float Deposit
direction integer Direction, 1-multi position, 2-empty position
floatingProfitLoss float Floating Profit / Loss
forcedLiquidationPrice float Forced Liquidation Price
holdCount float Hold Count
lockCount float Lock Count
multiple integer Leverage Ratio (Contract only, spot is 0)
positionId string position ID
profitLossRatio string Profit / Loss Ratio
symbol string Trading Symbol
stopLoss boolean Whether To Stop Profit Or Loss

Cancel Order

This interface sends a request to cancel an order.

HTTP Request

{
  "AppKey": "284e7228ab324e1f82a13faada3cf431",
  "Timestamp": 1570859741,
  "Signature": "e62466a824ef5025db0e8077f0cf9bb8",
  "type": "contract",
  "symbol": "btc",
  "orderId": "1570859608609294"
}

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
orderId string true NA Order ID

Response:

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

Return Parameter

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": 1570859962,
  "Signature": "038d9669e0eeb4b0736c0671efde2ad1",
  "type": "contract",
  "symbol": "btc",
  "side": "sell"
}

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
side string true NA Order Type all, buy, sell

Response:

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

Return Parameter

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.bfx.nu/order.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570860157&orderId=1570859608609294&symbol=btc&type=contract&Signature=6ff9c32bd3adbb5eef3cea9f5ba2c60a"

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
orderId string true NA Order ID

Response:

{
  "code": 0,
  "msg": "",
  "data": {
    "amount":0.1,
    "createTime":1570859608,
    "dealAmount":0,
    "delegation_id":0,
    "deposit":70,
    "direction":2,
    "multiple":20,
    "orderId":"1570859608609294",
    "price":14000,
    "priority":1,
    "state":"canceled",
    "symbol":"btc",
    "undealAmount":0.1
  }
}

Return Parameter

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 Status: 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.bfx.nu/v1/trade/orders.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570860897&endTime=1570860882&size=100&startTime=1557543620&states=submitted%2Csubmitting&symbol=btc&type=contract&Signature=afb5d55b8bd35c471fea80bffcb0724b"

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
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.15,
        "createTime":1570860856,
        "dealAmount":0,
        "delegation_id":55144733,
        "deposit":105.075,
        "direction":2,
        "multiple":20,
        "orderId":"1570860856236224",
        "price":14010,
        "priority":1,
        "state":"submitted",
        "symbol":"btc",
        "undealAmount":0.15
      },
      {
        "amount":0.1,
        "createTime":1570860647,
        "dealAmount":0,
        "delegation_id":55139855,
        "deposit":70.025,
        "direction":2,
        "multiple":20,
        "orderId":"1570860647390484",
        "price":14005,
        "priority":1,
        "state":"submitted",
        "symbol":"btc",
        "undealAmount":0.1
      },
      ...
   ]
}

Return Parameter

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.bfx.nu/v1/trade/history/orders.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1571216140&direct=prev&endTime=1571213617&from=20&size=100&startTime=1557543620&symbol=btc&type=contract&Signature=2908abbe7559379d44273f47e0299c07"

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
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.15,
        "dealAmount":105.075,
        "deposit":0,
        "direction":0,
        "multiple":20,
        "price":14010,
        "recordId":1314,
        "tradeAvgPrice":0,
        "undealAmount":0.15,
        "orderId":"1570860856236224",
        "symbol":"btc",
        "createTime":1570860856,
        "updateTime":1570860856,
        "tradeType":3
      },
      {
        "amount":0.1,
        "dealAmount":47.5,
        "deposit":0,
        "direction":0,
        "multiple":20,
        "price":9500,
        "recordId":980,
        "tradeAvgPrice":0,
        "undealAmount":0,
        "orderId":"1565581905261969",
        "symbol":"btc",
        "createTime":1565581905,
        "updateTime":1565581905,
        "tradeType":1
      },
      ...
   ]
}

Return Parameter

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.bfx.nu/v1/trade/history/trades.do?AppKey=284e7228ab324e1f82a13faada3cf431&Timestamp=1570861659&direct=prev&from=20&size=100&symbol=btc&type=contract&Signature=0a87b4d9ee8df333d6a93de95051c4a0"

Request Parameter

Parameter Name Data Type Mandatory 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 btc, eth, ht...
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":10148.96333333,
        "multiple":20,
        "symbol":"btc",
        "tradeBfxFee":0,
        "tradeCount":0.1,
        "tradeDeposit":50.74481667,
        "tradeFee":5.839967,
        "tradeId":210729,
        "tradeIncome":180.61533333,
        "tradePrice":8342.81,
        "tradeTime":1570858612,
        "tradeType":4
      },
      {
        "direction":2,
        "holdPrice":0,
        "multiple":20,
        "symbol":"btc",
        "tradeBfxFee":0,
        "tradeCount":0.1,
        "tradeDeposit":42.78445,
        "tradeFee":5.989823,
        "tradeId":207786,
        "tradeIncome":0,
        "tradePrice":8556.89,
        "tradeTime":1570770977,
        "tradeType":3
      },
      ...
   ]
}

Return Parameter

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.bfx.nu/v1/ws

Heartbeat and Connection

Response

{
  "ping": 1570678375
}

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

Subscribe request

{
  "pong": 1570678375
}

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

Subscribe to Topic

{
  "sub": "kline.contract.btc.15min"
}

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

{
  "code": 10000,
  "msg": "Subscription failed, unsupported type: kline.contract.btccccc.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.contract.btc.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.contract.btc.15min",
  "ts": 1571373361,
  "tick": [
    {
      "code": "btc",
      "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.contract.btc.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.contract.btc.15min"
}

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

{
  "code": 0,
  "msg": "",
  "rep": "kline.contract.btc.15min",
  "ts": 1571377747,
  "tick": [
    {
      "code": "btc",
      "first": 3600,
      "high": 3900,
      "last": 3900,
      "low": 3600,
      "time": 1551685500,
      "vol": 3.5
    },
    {
      "code": "btc",
      "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.contract.btc.15min"
}

Topic Parameter

Parameter Name Data Type Mandatory Default Description Value Range
type string true NA Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btc, eth, ht...
interval string true NA Kline Period 1min, 3min, 5min, See below for details

Response

{
  "code": 0,
  "msg": "",
  "subbed": "kline.contract.btc.15min",
  "ts": 1571393156
}

Return Parameter

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

Update example

{
  "ch": "kline.contract.btc.15min",
  "tick": [
    {
      "code": "btc",
      "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 Contract Type
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.contract.btc.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.contract.btc.depth"
}

Topic Parameter

Parameter Name Data Type Mandatory Default Description Value Range
type string true NA Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btc, eth, ht...

Response

{
  "code": 0,
  "msg": "",
  "subbed": "market.contract.btc.depth",
  "ts": 1571379519
}

Return Parameter

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

Update example

{
  "ch": "market.contract.btc.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.contract.btc.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.contract.btc.trade"
}

Topic Parameter

Parameter Name Data Type Mandatory Default Description Value Range
type string true NA Market Types contract, spot, vcontract
symbol string true NA Trading Symbol btc, eth, ht...

Response

{
  "code": 0,
  "msg": "",
  "subbed": "market.contract.btc.trade",
  "ts": 1571383431
}

Return Parameter

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

Update example

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

Update Content

Field Name Data Type Description
amount float Trade Volume
change float Increase of position (contract transaction)
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.contract.btc.trade"
}

Pull Request

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