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 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.bfxnu.com/
Websocket Feed (market)
wss://api.bfxnu.com/v1/ws
Rate Limiting Rule
- Contract: Each API Key is limited to 100 times per 10 seconds
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:
API Path: https://api.bfxnu.com, for example: https://api.bfxnu.com/v1/account/accounts.do.
API Access Key: The 'Access Key' in your API Key.
Timestamp: Second Timestamps, Please make sure that the time stamp and Internet time do not differ too much.
Required and optional parameters: each request has required and optional parameters. Please refer to API interface description.
Signature: The value calculated by the signature to ensure that the signature is valid and has not been tampered with.
Parameter transfer method: please use formdata to transfer parameters and set user agent in header.
User-Agent settings 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"
Create API Key
You can be here https://www.bfxnu.com/center/bindAppKey.do Create API Key.
API Key includes the following two parts:
AppKey:It is used in API requestAppSecret:It is used to generate the signature (only visible once after creation)
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
Add all required authentication parameters to the path parameters of the interface call.
Add the digital signature to the path parameter after the URL is encoded. The parameter is called "signature".
Request Format
All API requests are sent in the form of get or post.
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
- GET
/v1/common/symbols.do
curl "https://api.bfxnu.com/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
- GET
/v1/market/kline.do
curl "https://api.bfxnu.com/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
- GET
/v1/market/ticker.do
curl "https://api.bfxnu.com/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
- GET
/v1/market/tickers.do
curl "https://api.bfxnu.com/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
- GET
/v1/market/depth.do
curl "https://api.bfxnu.com/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
- GET
/v1/market/trades.do
curl "https://api.bfxnu.com/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
- GET
/v1/account/accounts.do
curl "https://api.bfxnu.com/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
- GET
/v1/account/account.do
curl "https://api.bfxnu.com/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
- POST
/v1/account/transfer.do
{
"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
- GET
/v1/account/transfer/records.do
curl "https://api.bfxnu.com/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
- POST
/v1/trade/orders/place.do
{
"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
- POST
/v1/trade/positions/close.do
{
"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
- GET
/v1/trade/positions.do
curl "https://api.bfxnu.com/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
- POST
/v1/trade/orders/cancel.do
{
"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
- POST
/v1/trade/orders/batchCancel.do
{
"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
- GET
/v1/trade/order.do
curl "https://api.bfxnu.com/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
- GET
/v1/trade/orders.do
curl "https://api.bfxnu.com/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
- GET
/v1/trade/history/orders.do
curl "https://api.bfxnu.com/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
- GET
/v1/trade/history/trades.do
curl "https://api.bfxnu.com/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.bfxnu.com/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"
}