json

Change Log

Version 1.0.5 (6th November 2024)

Version 1.0.4 (16th September 2024)

Version 1.0.3 (6th August 2024)

Version 1.0.2 (1st August 2024)

Version 1.0.1 (10th Jul 2024)

Version 1.0.0 (28th June 2024)

Overview

Migration from v2.1 to v2.2

Generating API Key

You will need to create an API key on the BTSE platform before you can use authenticated APIs. To create API keys, you can follow the steps below:

Endpoints

Authentication

Example 1: Get Wallet

HMAC SHA384 Signature

$ echo -n "/api/v2.2/user/wallet1624984297330" | openssl dgst -sha384 -hmac "848db84ac252b6726e5f6e7a711d9c96d9fd77d020151b45839a5b59c37203bx"
(stdin)= 72021c3b7b6f88dc1bbd1bde253f08d9bb12e4ba7d9b071ae801fee15bc2347a1bab2e3fa0a230ce5fadcd9c616fe44f

Example 2: Place an order

HMAC SHA384 Signature

$ echo -n "/api/v2.2/order1624985375123{\"postOnly\":false,\"price\":8500.0,\"reduceOnly\":false,\"side\":\"BUY\",\"size\":1,\"stopPrice\":0.0,\"symbol\":\"BTC-PERP\",\"time_in_force\":\"GTC\",\"trailValue\":0.0,\"triggerPrice\":0.0,\"txType\":\"LIMIT\",\"type\":\"LIMIT\"}" | openssl dgst -sha384 -hmac "848db84ac252b6726e5f6e7a711d9c96d9fd77d020151b45839a5b59c37203bx"
(stdin)= 3b900afa243651ef07a61cb6f2a4a6779c6d28e9b0a0ff9ffa3524d4945fafaa864670e45559aa01f49e62c9fb96417e

Rate Limits

Rate limits for BTSE is as follows:

Query

Orders

Mechanism Description

Our system implements a tiered blocking mechanism with three distinct durations: 1 second, 5 minutes, and 15 minutes. The duration of the block begins calculation from the moment the first block is imposed. Additionally, the calculation duration will be reset if the IP address or user does not exceed the rate limit within a span of 1 hour or the 15 mins blocking duration is ended.

A Retry-After header is included with a 429 response and will give the unlocked timestamp.

Rate limit tiers

API Status Codes

Each API will return one of the following HTTP status:

API Enum

When connecting up the BTSE API, you will come across number codes that represents different states or status types in BTSE. The following section provides a list of codes that you are expecting to see.

Spam Orders

Spam orders are large number of small order sizes that is placed. In order to ensure that the platform and user's interests are protected from malicious players, we will apply the following for users placing small sized orders.

Spam Order Detection Mechanism : BTSE Support

Public Endpoints

Market Summary

Response

[
  {
    "symbol": "BTC-PERP",
    "last": 36365,
    "lowestAsk": 36377,
    "highestBid": 36376,
    "percentageChange": 4.973731309,
    "volume": 172418318.7575521,
    "high24Hr": 36447,
    "low24Hr": 33989.5,
    "base": "BTC",
    "quote": "USDT",
    "active": true,
    "size": 4916.8266,
    "minValidPrice": 0.5,
    "minPriceIncrement": 0.5,
    "minOrderSize": 0.00001,
    "maxOrderSize": 2000,
    "minSizeIncrement": 0.00001,
    "openInterest": 0,
    "openInterestUSD": 0,
    "contractStart": 0,
    "contractEnd": 0,
    "timeBasedContract": false,
    "openTime": 0,
    "closeTime": 0,
    "startMatching": 0,
    "inactiveTime": 0,
    "fundingRate": 0,
    "contractSize": 0,
    "maxPosition": 0,
    "minRiskLimit": 0,
    "maxRiskLimit": 0,
    "availableSettlement": null,
    "futures": false,
    "fundingIntervalMinutes": 480,
    "fundingTime": 1699347600000
  }
]

GET /api/v2.2/market_summary

Gets market summary information. If no symbol parameter is sent, then all markets will be retrieved.

Request Parameters

Name Type Required Description
symbol string No Market symbol
listFullAttributes boolean No True to return all attributes of the market summary

Response Content

Name Type Required Description
symbol string Yes Market symbol
last double Yes Last price
lowestAsk double Yes Lowest ask price in the orderbook
highestBid double Yes Highest bid price in the orderbook
percentageChange double Yes Percentage change against the price within the last 24hours
volume double Yes Transacted volume
high24Hr double Yes Highest price over the last 24hours
low24Hr double Yes Lowest price over the last 24hours
base string Yes Base currency
quote string Yes Quote currency
active boolean Yes Indicator if market is active
size double Yes Transacted size
minValidPrice double Yes Minimum valid price
minPriceIncrement double Yes Price increment
minOrderSize double Yes Minimum tick size
minSizeIncrement double Yes Tick size
maxOrderSize double Yes Maximum order size
openInterest double No Number of open positions in the futures market
openInterestUSD double No Number of open positions in the futures market in USD notional value
contractStart long No Contract start time
contractEnd long No Contract end time
timeBasedContract boolean No Indicator to indicate if it is a time based contract
openTime long Yes Market opening time
closeTime long Yes Market closing time
startMatching long Yes Matching start time
inactiveTime long Yes Time where market is inactive
fundingRate double No The funding rate
contractSize double No Size of one contract
maxPosition double No Maximum position a user is allowed to have Will no longer be applicable after risk limit adjustment
minRiskLimit double No Minimum risk limit in contract size Will be changed to USD value
maxRiskLimit double No Maximum risk limit int contract size Will be changed to USD value
availableSettlement array No Currencies available for settlement
futures boolean Yes Indicator if symbol is a futures contract
fundingIntervalMinutes integer No Funding interval, only display when param listFullAttributes is true
fundingTime long No Next funding time, only display when param listFullAttributes is true

Charting Data

Response

[
  [
    1624987380,
    36477,
    36477,
    36473.5,
    36473.5,
    693.049
  ],
  [
    1624987320,
    36476.5,
    36481.5,
    36466,
    36466,
    2370.8095
  ]
]

GET /api/v2.2/ohlcv

Gets candle stick charting data. Default of 300 data points will be returned at any one time.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
start long No Starting time in milliseconds (eg. 1624987283000)
end long No Ending time in millisecond (eg. 1624987283000)
resolution string Yes Supported resolutions are:
1: 1 min
5: 5 mins
15: 15 mins
30: 30 mins
60: 60 mins
240: 4 hours
360: 6 hours
1440: 1day
10080: 1 week
43200: 1 month

Response Content

Returns a 2D array with the indexes described in the table below

Index Type Required Description
0 long Yes Unix time
1 double Yes Open price
2 double Yes High Price
3 double Yes Low price
4 double Yes Closing price
5 double Yes Volume

Query Market price

Response

[
  {
    "symbol": "BTC-PERP",
    "indexPrice": 36288.949684967,
    "lastPrice": 36286.5,
    "markPrice": 0
  }
]

GET /api/v2.2/price

Retrieve current prices on the platform. If no symbol specified, all symbols will be returned.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol

Response Content

Name Type Required Description
symbol double Yes Market symbol
indexPrice double Yes Index price
lastPrice double Yes Last transacted price
markPrice double Yes Mark price

Orderbook (By grouping)

Response

{
  "buyQuote": [
    {
      "price": "36371.0",
      "size": "100"
    }
  ],
  "sellQuote": [
    {
      "price": "36380.5",
      "size": "100"
    }
  ],
  "timestamp": 1624989459489,
  "symbol": "BTC-PERP"
}

GET /api/v2.2/orderbook

Retrieves a snapshot of the orderbook.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol, entered as a path variable
group integer No Orderbook grouping. Valid values are:
0-8 where 0 indicates level 0 grouping (eg. for BTC-PERP, it will be 0.1)
Level 1 grouping for BTC-PERP would be 0.5
Level 2 grouping for BTC-PERP would be 1

Response Content

Orderbook

Name Type Required Description
symbol string Yes Market symbol
buyQuote Quote Yes Array of Buy quotes
sellQuote Quote Yes Array of Sell quotes
timestamp long Yes Timestamp of orderbook

Quote

Name Type Required Description
price double Yes order price
size double Yes order size

Orderbook

Response

{
  "buyQuote": [
    {
      "price": "36235.0",
      "size": "700"
    }
  ],
  "sellQuote": [
    {
     "price": "36241.5",
      "size": "600"
    }
  ],
  "timestamp": 1624989977940,
  "symbol": "BTC-PERP"
}

GET /api/v2.2/orderbook/L2

Retrieves a Level 2 snapshot of the orderbook

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
depth long No Orderbook depth

Response Content

Orderbook

Name Type Required Description
symbol string Yes Market symbol
buyQuote Quote Yes Array of Buy quotes
sellQuote Quote Yes Array of Sell quotes
timestamp long Yes Timestamp of orderbook

Quote

Name Type Required Description
price double Yes order price
size double Yes order size

Query Trades Fills

Response

[
  {
    "price": 36164,
    "size": 100,
    "side": "SELL",
    "symbol": "BTC-PERP",
    "serialId": 85997835,
    "timestamp": 1624990097000
  }
]

GET /api/v2.2/trades

Get trade fills for the market specified by symbol

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
startTime long No Starting time in milliseconds (eg. 1624987283000)
endTime long No Ending time in milliseconds (eg. 1624987283000)
beforeSerialId long No Used for pagination to retrieve records when the order volume exceeds 500 per millisecond. For typical scenarios, it is recommended to use the startTime and endTime parameters instead.
afterSerialId long No Used for pagination to retrieve records when the order volume exceeds 500 per millisecond. For typical scenarios, it is recommended to use the startTime and endTime parameters instead.
count long Yes Number of records to return
includeOld boolean Yes Retrieve trade history records past 7 days

Response Content

Name Type Required Description
symbol string Yes Market symbol
side string Yes Trade side. Values are: [Buy, SELL]
price double Yes Transacted price
size double Yes Transacted size
serialId double Yes Serial Id, running sequence number
timestamp long Yes Transacted timestamp

Funding History

Response

{
  "BTC-PERP": [
    {
      "time": 1706515200,
      "rate": 0.000011405,
      "symbol": "BTC-PERP"
    }
  ]
}

GET /api/v2.2/funding_history

Get funding rate history for certain symbols

Request Parameters

Name Type Required Description
symbol string No Market symbol (e.g., BTC-PERP)
count int No Number of records to return (mutually exclusive with from/to)
from long No Starting time in milliseconds (e.g., 1624987283000; mutually exclusive with count)
to long No Ending time in milliseconds (e.g., 1624987283000; mutually exclusive with count)

Response Content

Name Type Required Description
symbol string Yes Market symbol
time long Yes The epoch timestamp in second of the funding rate
rate double Yes Funding rate

Trade Endpoints

Create New Order

Request (create MARKET order)

{
  "symbol": "BTC-PERP",
  "size": 1,
  "side": "BUY",
  "type": "MARKET"
}

Request (create LIMIT order)

{
  "symbol": "BTC-PERP",
  "size": 1,
  "price": 21000,
  "side": "BUY",
  "type": "LIMIT"
}

Request (create LIMIT TRIGGER order)

{
  "symbol": "BTC-PERP",
  "size": 1,
  "price": 21000,
  "side": "BUY",
  "type": "LIMIT",
  "txType": "TRIGGER",
  "triggerPrice": 30000
}

Request (create LIMIT STOP order)

{
  "symbol": "BTC-PERP",
  "size": 1,
  "price": 21000,
  "side": "BUY",
  "type": "LIMIT",
  "txType": "STOP",
  "triggerPrice": 30000
}

Request (create OCO order)

{
  "symbol": "BTC-PERP",
  "size": 1,
  "price": 21000,
  "side": "BUY",
  "type": "OCO",
  "txType": "LIMIT",
  "trigger": "markPrice",
  "stopPrice": 30010,
  "triggerPrice": 30000
}

Request (create Limit order with TP/SL)

{
    "symbol": "BTC-PERP",
    "size": 10,
    "price": 29000,
    "side": "BUY",
    "type": "LIMIT",
    "takeProfitPrice": 31000,
    "takeProfitTrigger": "markPrice",
    "stopLossPrice": 27000,
    "stopLossTrigger": "lastPrice"
}

Request (create Limit order with TP only)

{
    "symbol": "BTC-PERP",
    "size": 10,
    "price": 29000,
    "side": "BUY",
    "type": "LIMIT",
    "takeProfitPrice": 31000,
    "takeProfitTrigger": "markPrice"
}

Request (create Limit order with SL only)

{
    "symbol": "BTC-PERP",
    "size": 10,
    "price": 29000,
    "side": "BUY",
    "type": "LIMIT",
    "stopLossPrice": 27000,
    "stopLossTrigger": "lastPrice"
}

Request (create hedge mode long position MARKET order)

{
  "symbol": "BTC-PERP",
  "size": 1,
  "side": "BUY",
  "type": "MARKET",
  "positionMode": "HEDGE"
}

Request (create hedge mode short position MARKET reduce order)

{
  "symbol": "BTC-PERP",
  "size": 1,
  "side": "BUY",
  "type": "MARKET",
  "reduceOnly": true,
  "positionMode": "HEDGE"
}

Response (general)

[
  {
    "status": 4,
    "symbol": "BTC-PERP",
    "orderType": 76,
    "price": 21000.0,
    "side": "BUY",
    "size": 1,
    "orderID": "abb3f457-fdc0-4bdb-a46b-8e4aa49a57c2",
    "timestamp": 1660558270207,
    "triggerPrice": 0.0,
    "trigger": false,
    "deviation": 100.0,
    "stealth": 100.0,
    "message": "",
    "avgFillPrice": 21000.0,
    "fillSize": 1.0,
    "clOrderID": "",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 0.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT",
    "time_in_force": "GTC"
  }
]

Response (for OCO order)

[
  {
    "status": 9,
    "symbol": "BTC-PERP",
    "orderType": 76,
    "price": 23000.0,
    "side": "BUY",
    "size": 1,
    "orderID": "4c9d16c1-9869-4734-bfb8-56318e961ef2",
    "timestamp": 1660558185243,
    "triggerPrice": 30000.0,
    "trigger": true,
    "deviation": 100.0,
    "stealth": 100.0,
    "message": "",
    "avgFillPrice": 0.0,
    "fillSize": 0.0,
    "clOrderID": "",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 1.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT",
    "time_in_force": "GTC"
  },
  {
    "status": 2,
    "symbol": "BTC-PERP",
    "orderType": 76,
    "price": 21000.0,
    "side": "BUY",
    "size": 1,
    "orderID": "53749446-39d3-4b72-87c9-92e9fc7e4b8c",
    "timestamp": 1660558185225,
    "triggerPrice": 0.0,
    "trigger": false,
    "deviation": 100.0,
    "stealth": 100.0,
    "message": "",
    "avgFillPrice": 0.0,
    "fillSize": 0.0,
    "clOrderID": "",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 1.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT",
    "time_in_force": "GTC"
  }
]

Response (for hedge mode order)

[
  {
    "status": 4,
    "symbol": "BTC-PERP",
    "orderType": 76,
    "price": 21000.0,
    "side": "BUY",
    "size": 1,
    "orderID": "abb3f457-fdc0-4bdb-a46b-8e4aa49a57c2",
    "timestamp": 1660558270207,
    "triggerPrice": 0.0,
    "trigger": false,
    "deviation": 100.0,
    "stealth": 100.0,
    "message": "",
    "avgFillPrice": 21000.0,
    "fillSize": 1.0,
    "clOrderID": "",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 0.0,
    "positionMode": "HEDGE",
    "positionDirection": "LONG",
    "positionId": "BTC-PERP-USDT|LONG",
    "time_in_force": "GTC"
  }
]

POST /api/v2.2/order

Creates a new order. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
price double No Mandatory unless creating a MARKET order. Order price
size long Yes Order size in contract size (this remains unchanged even after risk limit adjustment)
side string Yes 'BUY' or 'SELL'
time_in_force string No Time validity of the order
GTC: Good till Cancel
IOC: Immediate or Cancel
FOK: Fill or Kill
HALFMIN: Order valid for 30 seconds
FIVEMIN: Order valid for 5 mins
HOUR: Order valid for an hour
TWELVEHOUR: Order valid for 12 hours
DAY: Order valid for a day
WEEK: Order valid for a week
MONTH: Order valid for a month
type string Yes Order type
LIMIT: Limit Orders
MARKET: Market Orders
OCO: One cancel the other
txType string No Used for Stop orders or trigger orders
STOP: Stop Order, triggerPrice is mandatory
TRIGGER: Trigger order, triggerPrice is mandatory
LIMIT: Default, used when its not a Stop order nor Trigger order
stopPrice double No Mandatory when creating an OCO order. Indicates the stop price
triggerPrice double No Mandatory when creating a Stop, Trigger, OCO order. Indicates the trigger price
trailValue double No Trail value
postOnly boolean No Boolean to indicate if this is a post only order. For post only orders, traders are charged maker fees
reduceOnly boolean No Boolean to indicate if this is a reduce only order, if in hedge mode, it is used to reduce the specified position, ex: sell to reduce long position, buy to reduce short position.
clOrderID string No Custom order Id
trigger string No For creating order with txType: STOP or TRIGGER. Valid options: markPrice (default) or lastPrice
takeProfitPrice double No Mandatory when creating new order with take profit order. Indicates the trigger price
takeProfitTrigger string No For creating order with take profit order. Valid options: markPrice (default) or lastPrice
stopLossPrice double No Mandatory when creating new order with stop loss order. Indicates the trigger price
stopLossTrigger string No For creating order with stop loss order. Valid options: markPrice (default) or lastPrice
positionMode string No For creating order and wanting to specify the positionMode. Valid options: ONE_WAY (default) , HEDGE , ISOLATED

Response Content

Name Type Required Description
symbol string Yes Market symbol
clOrderID string Yes Customer tag sent in by trader
fillSize number Yes Trade filled size
orderID string Yes Order ID
orderType integer Yes Order type
76: Limit Order
77: Market order
80: Algo order
postOnly boolean Yes Indicates if order is a post only order
price double Yes Order price
side string Yes Order side
BUY or SELL
size long Yes Order size in contract size (this remains unchanged even after risk limit adjustment)
status long Yes Order status
2: Order Inserted
3: Order Transacted
4: Order Fully Transacted
5: Order Partially Transacted
6: Order Cancelled
7: Order Refunded
9: Trigger Inserted
10: Trigger Activated
15: Order Rejected
16: Order Not Found
17: Request failed
time_in_force string Yes Order validity
timestamp long Yes Order timestamp
trigger boolean Yes Indicator if order is a trigger order
triggerPrice double Yes Order trigger price, returns 0 if order is not a trigger order
avgFillPrice double Yes Average filled price. Returns the average filled price for partially transacted orders
message string Yes Trade messages
stealth double Yes Only valid for Algo orders
deviation double Yes Only valid for Algo orders
remainingSize double Yes Size left to be transacted
originalSize double Yes Original order size
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes The current order belongs to the id of position.

Create new algo order

Request

{
  "symbol": "BTC-PERP",
  "price": 21500,
  "size": 1,
  "side": "BUY",
  "clOrderID": "60a30188-f2a2-4498-b061-7d72126c18c2",
  "stealth": 10,
  "deviation": -10
}

Response

[
  {
    "status": 2,
    "symbol": "BTC-PERP",
    "orderType": 80,
    "price": 21500.0,
    "side": "BUY",
    "size": 1,
    "orderID": "de9f94bb-0ca0-470b-830e-9bc2e109c719",
    "timestamp": 1660554373317,
    "triggerPrice": 0.0,
    "trigger": false,
    "deviation": -10.0,
    "stealth": 10.0,
    "message": "",
    "avgFillPrice": 0.0,
    "fillSize": 0.0,
    "clOrderID": "60a30188-f2a2-4498-b061-7d72126c18c2",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 1.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT",
    "time_in_force": "GTC"
  }
]

POST /api/v2.2/order/peg

Creates a new algo order. Algo order is an order that price will change according to market price. To create an algo order, user will need to enter additional parameters:

This API Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
price double Yes Minimum price for a sell order, this is the lowest price that a user is willing to sell at. Maximum price for a buy order, this is the maximum price a user is willing to buy at.
size long Yes Order size
side string Yes Order side
BUY or SELL
clOrderID string No Custom order Id
deviation double No How much should the order price deviate from index price. Value is in percentage and can range from -10 to 10
stealth double No How many percent of the order is to be displayed on the orderbook.
positionMode string No For creating order and wanting to specify the positionMode. Valid options: ONE_WAY (default) , HEDGE , ISOLATED

Response Content

Name Type Required Description
symbol string Yes Market symbol
clOrderID string Yes Customer tag sent in by trader
fillSize number Yes Trade filled size
orderID string Yes Order ID
orderType integer Yes Order type
76: Limit Order
77: Market order
80: Algo order
postOnly boolean Yes Indicates if order is a post only order
price double Yes Order price
side string Yes Order side
BUY or SELL
size long Yes Order size in contract size (this remains unchanged even after risk limit adjustment)
status long Yes Order status
2: Order Inserted
3: Order Transacted
4: Order Fully Transacted
5: Order Partially Transacted
6: Order Cancelled
7: Order Refunded
9: Trigger Inserted
10: Trigger Activated
15: Order Rejected
16: Order Not Found
17: Request failed
time_in_force string Yes Order validity
timestamp long Yes Order timestamp
trigger boolean Yes Indicator if order is a trigger order
triggerPrice double Yes Order trigger price, returns 0 if order is not a trigger order
avgFillPrice double Yes Average filled price. Returns the average filled price for partially transacted orders
message string Yes Trade messages
stealth double Yes Stealth value of order
deviation double Yes Deviation value of order
remainingSize double Yes Size left to be transacted
originalSize double Yes Original order size
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes The current order belongs to the id of position.

Query Order

Response

{
    "orderType": 76,
    "price": 1,
    "size": 111,
    "side": "BUY",
    "filledSize": 0,
    "orderValue": 0.111,
    "pegPriceMin": 0,
    "pegPriceMax": 0,
    "pegPriceDeviation": 1,
    "timestamp": 1698757024617,
    "orderID": "<Order UUID>",
    "stealth": 1,
    "triggerOrder": false,
    "triggered": false,
    "triggerPrice": 0,
    "triggerOriginalPrice": 0,
    "triggerOrderType": 0,
    "triggerTrailingStopDeviation": 0,
    "triggerStopPrice": 0,
    "symbol": "BTC-PERP",
    "trailValue": 0,
    "remainingSize": 111,
    "clOrderID": "<Order clOrderID>",
    "reduceOnly": false,
    "status": 2,
    "triggerUseLastPrice": false,
    "avgFilledPrice": 0,
    "timeInForce": "GTC",
    "takeProfitOrder": null,
    "stopLossOrder": null,
    "closeOrder": false,
    "contractSize": 0.001
}

GET /api/v2.2/order

Query order detail for a specified orderID/clOrderID, please note that a canceled order will only exist for 30 minutes. Requires Trading permission.

Request Parameters

Name Type Required Description
orderID String No Unique identifier for an order. Mandatory when clOrderID is not provided. If orderID is provided, clOrderID will be ignored.
clOrderID String No Client custom order ID. Mandatory when orderID is not provided.

Response Content

Name Type Required Description
orderID String Yes Order ID
symbol String Yes Market symbol
quote String Yes Quote symbol
orderType Integer Yes Order type
side String Yes Order side
price Double Yes Order price
size Double Yes Order size
orderValue Double Yes Total value of of this order
filledSize Double Yes Filled Size
pegPriceMin Double Yes Minimum possible peg price this takes precedence over pegPriceDeviation
pegPriceMax Double Yes Peg Price Max (New Entry)
pegPriceDeviation Double Yes Percentage deviation from Index price
timestamp Long Yes Order timestamp
triggerOrder Boolean Yes Indicator if order is a trigger order
triggerPrice Double Yes Order trigger price, returns 0 if order is not a trigger order
triggerOriginalPrice Double Yes Price of the original order. Only valid if it's a triggered order
triggerOrderType Integer Yes Order type
triggerTrailingStopDeviation Double Yes Percentage deviation from stop price
triggerStopPrice Double Yes Stop price, Algo Order only
triggered Boolean Yes Indicate whether the order is triggered
trailValue Double Yes Trail value
clOrderID String Yes Customer tag sent in by trader
averageFillPrice Double Yes Average filled price. Returns the average filled price for partially transacted orders
remainingSize Double Yes remainingSize
status Integer Yes Order status. Please refer to API Enum
takeProfitOrder TakeProfitOrder object No Take profit order info
stopLossOrder StopLossOrder object No Stop loss order info
closeOrder bool Yes Whether it is an order to close this position
timeInForce String Yes Order validity
contractSize double Yes The order contract size

Amend Order

Request (amend price)

{
  "symbol": "BTC-PERP",
  "orderID": "604c3ebf-d7fa-468d-9ff0-f6ad030221b4",
  "type": "PRICE",
  "value": 22000
}

Request (amend all)

{
  "symbol": "BTC-PERP",
  "orderID": "604c3ebf-d7fa-468d-9ff0-f6ad030221b4",
  "type": "ALL",
  "orderPrice": 30010,
  "orderSize": 1,
  "triggerPrice": 30000
}

Response

[
  {
    "status": 123,
    "symbol": "BTC-PERP",
    "orderType": 76,
    "price": 20000.0,
    "side": "BUY",
    "size": 1,
    "orderID": "604c3ebf-d7fa-468d-9ff0-f6ad030221b4",
    "timestamp": 1660639762254,
    "triggerPrice": 0.0,
    "trigger": true,
    "deviation": 100.0,
    "stealth": 100.0,
    "message": "",
    "avgFillPrice": 0.0,
    "fillSize": 0.0,
    "clOrderID": "",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 1.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT",
    "time_in_force": "GTC"
  }
]

PUT /api/v2.2/order

Amend the price or size or trigger price of an order. For trigger orders, if the order has already been triggered, the trigger price cannot be further amended. Amend order does not apply to algo orders

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
orderID string No Internal order ID. Mandatory when clOrderID is not provided. If orderID is provided, clOrderID will be ignored.
clOrderID string No Custom order ID. Mandatory when orderID is not provided.
type string Yes Type of amendmend
PRICE: To amend order price
SIZE: To amend order size
TRIGGERPRICE: To amend trigger price
ALL: to amend multiple fields
value number Yes The value to be amended to. Value depends on the type being set.
orderPrice number No For type: ALL, order price to be amended
orderSize number No For type: ALL, order size in contract size to be amended
triggerPrice number No For type: ALL, trigger price to be amended

Response Content

Name Type Required Description
symbol string Yes Market symbol
clOrderID string Yes Customer tag sent in by trader
fillSize string Yes Trade filled size
orderID string Yes Order ID
orderType integer Yes Order type
76: Limit Order
77: Market order
80: Algo order
postOnly boolean Yes Indicates if order is a post only order
price double Yes Order price
side string Yes Order side
BUY or SELL
size long Yes Order size in contract size (this remains unchanged even after risk limit adjustment)
status long Yes Order status
2: Order Inserted
3: Order Transacted
4: Order Fully Transacted
5: Order Partially Transacted
6: Order Cancelled
7: Order Refunded
9: Trigger Inserted
10: Trigger Activated
15: Order Rejected
16: Order Not Found
17: Request failed
time_in_force string Yes Order validity
timestamp long Yes Order timestamp
trigger string Yes Indicator if order is a trigger order
triggerPrice string Yes Order trigger price, returns 0 if order is not a trigger order
avgFillPrice string Yes Average filled price. Returns the average filled price for partially transacted orders
message string Yes Trade messages
stealth double Yes Stealth value of order
deviation string Yes Deviation value of order
remainingSize double Yes Size left to be transacted
originalSize double Yes Original order size
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes The current order belongs to the id of position.

Cancel Order

Request

/api/v2.2/order?symbol=BTC-PERP&clOrderID=my-order-id

Response

[
  {
    "status": 6,
    "symbol": "BTC-PERP",
    "orderType": 76,
    "price": 19000.0,
    "side": "BUY",
    "size": 1,
    "orderID": "ae5b1b27-d5fe-41e2-89f8-f17b60fb3def",
    "timestamp": 1660640879996,
    "triggerPrice": 0.0,
    "trigger": false,
    "deviation": 100.0,
    "stealth": 100.0,
    "message": "",
    "avgFillPrice": 0.0,
    "fillSize": 0.0,
    "clOrderID": "string",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 1.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT",
    "time_in_force": "GTC"
  }
]

DELETE /api/v2.2/order

Cancels pending orders that has not yet been transacted. The orderID is a unique identifier to cancel a particular order. clOrderID is a custom ID sent in by the trader. When cancel by clOrderID, all orders having the same ID will be cancelled. If orderID and clOrderID is not sent in, then cancellation will be for all orders in the current market. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
orderID string No Unique identifier for an order. Mandatory when clOrderID is not provided. If orderID is provided, clOrderID will be ignored.
clOrderID string No Client custom order ID. Mandatory when orderID is not provided.

Response Content

Name Type Required Description
symbol string Yes Market symbol
clOrderID string Yes Customer tag sent in by trader
fillSize double Yes Trade filled size
orderID string Yes Order ID
orderType integer Yes Order type
76: Limit Order
77: Market order
80: Algo order
postOnly boolean Yes Indicates if order is a post only order
price double Yes Order price
side string Yes Order side
BUY or SELL
size long Yes Order size in contract size (this remains unchanged even after risk limit adjustment)
status long Yes Order status
2: Order Inserted
3: Order Transacted
4: Order Fully Transacted
5: Order Partially Transacted
6: Order Cancelled
7: Order Refunded
9: Trigger Inserted
10: Trigger Activated
15: Order Rejected
16: Order Not Found
17: Request failed
time_in_force string Yes Order validity
timestamp long Yes Order timestamp
trigger boolean Yes Indicator if order is a trigger order
triggerPrice double Yes Order trigger price, returns 0 if order is not a trigger order
avgFillPrice double Yes Average filled price. Returns the average filled price for partially transacted orders
message string Yes Trade messages
stealth double Yes Stealth value of order
deviation double Yes Deviation value of order
remainingSize double Yes Size left to be transacted
originalSize double Yes Original order size
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes The current order belongs to the id of position.

Dead Man's Switch (Cancel All After)

Request

{
  "timeout": 60000
}

POST /api/v2.2/order/cancelAllAfter

Dead-man's switch allows the trader to send in a timeout value which is a Time to live (TTL) value for an order. Extension of the timeout is done by sending another cancelAllAfter request. If the server does not receive another request before the timeout is reached, all orders will be cancelled. Requires Trading permission.

Request Parameters

Name Type Required Description
timeout long Yes Timeout value in milliseconds

Response Content

Query Open Orders

Request

/api/v2.2/user/open_orders?symbol=BTC-PERP

Response

[
  {
    "orderType": 76,
    "price": 21000.0,
    "size": 1,
    "side": "BUY",
    "filledSize": 0,
    "orderValue": 21.0,
    "pegPriceMin": 0.0,
    "pegPriceMax": 0.0,
    "pegPriceDeviation": 1.0,
    "cancelDuration": 0,
    "timestamp": 1660645487032,
    "orderID": "2eb1c6f5-2ab2-4706-ab88-eea6b710a78b",
    "stealth": 1.0,
    "triggerOrder": false,
    "triggered": false,
    "triggerPrice": 0.0,
    "triggerOriginalPrice": 0.0,
    "triggerOrderType": 0,
    "triggerTrailingStopDeviation": 0.0,
    "triggerStopPrice": 0.0,
    "symbol": "BTC-PERP",
    "trailValue": 0.0,
    "clOrderID": "string",
    "reduceOnly": false,
    "orderState": "STATUS_ACTIVE",
    "triggerUseLastPrice": false,
    "avgFilledPrice": 0.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT",
    "timeInForce": "GTC",
    "averageFillPrice": 0.0,
    "contractSize": 0.0001,
    "takeProfitOrder": {
        "orderId": "ea1ab233-c79a-4503-a475-f8633ecc9d79",
        "side": "SELL",
        "triggerPrice": 31000.0,
        "triggerUseLastPrice": false
    },
    "stopLossOrder": {
        "orderId": "48523190-77b9-44ea-bee0-d67a428a51b8",
        "side": "SELL",
        "triggerPrice": 27000.0,
        "triggerUseLastPrice": true
    },
    "closeOrder": false
  }
]

GET /api/v2.2/user/open_orders

Retrieves open orders that have not yet been matched or matched recently. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string No Market symbol
orderID string No Query using internal order ID
clOrderID string No Query using custom order ID. If orderID is provided, clOrderID will be ignored.

Response Content

Name Type Required Description
symbol string Yes Market symbol
clOrderID string Yes Customer tag sent in by trader
filledSize long Yes Trade filled size
orderValue double Yes Notional value
pegPriceMin double Yes peg price min
pegPriceMax double Yes peg price max
pegPriceDeviation double Yes Deviation percentage. Only for Algo orders
cancelDuration long Yes Expire in milliseconds.
0: GTC
-1: IOC
orderID string Yes Order ID
orderType integer Yes Order type
76: Limit Order
77: Market order
80: Algo order
timeInForce string Yes Order validity
price double Yes Order price
side string Yes Order side
BUY or SELL
size long Yes Order size in contract size
timestamp long Yes Order timestamp
triggerOrder bool Yes Indicate if this is a trigger order
triggered bool Yes Indicate if this order has been triggered
triggerUseLastPrice bool Yes Indicate if this trigger order uses last price
triggerPrice double Yes Order trigger price, returns 0 if order is not a trigger order
triggerOriginalPrice double Yes Original trigger price
triggerOrderType string Yes Trigger order type
1001: Trigger stop loss
1002: Trigger take profit
triggerTrailingStopDeviation double Yes Reserved attribute
triggerStopPrice double Yes Reserved attribute
trailValue double Yes Reserved attribute
reduceOnly bool Yes Indicate if this order is reduce only
avgFilledPrice double Yes Average filled price. Returns the average filled price for partially transacted orders
averageFillPrice double Yes Average fill price
stealth double Yes Stealth value of order
orderState string Yes STATUS_ACTIVE, STATUS_INACTIVE
takeProfitOrder TakeProfitOrder object No Take profit order info
stopLossOrder StopLossOrder object No Stop loss order info
closeOrder bool Yes Whether it is an order to close this position
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes The current order belongs to the id of position.
contractSize double Yes The order contract size

Query Trades Fills

Request

/api/v2.2/user/trade_history?symbol=BTC-PERP

Response

[
  {
    "base": "string",
    "clOrderID": "string",
    "feeAmount": 0,
    "feeCurrency": "string",
    "filledPrice": 0,
    "filledSize": 0,
    "averageFillPrice": 0,
    "orderId": "string",
    "orderType": 0,
    "price": 0,
    "quote": "string",
    "realizedPnl": 0,
    "serialId": 0,
    "side": "string",
    "size": 0,
    "symbol": "string",
    "timestamp": 0,
    "total": 0,
    "tradeId": "string",
    "triggerPrice": 0,
    "triggerType": 0,
    "username": "string",
    "positionId": null,
    "wallet": "string",
    "tradeId": "string",
    "orderId": "string",
    "contractSize": "number"
  }
]

GET /api/v2.2/user/trade_history

Retrieves a user's trade history. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string No Market symbol
startTime long No Starting time (eg. 1624987283000)
endTime long No Ending time (eg. 1624987283000)
beforeSerialId long No Used for pagination to retrieve records when the order volume exceeds 500 per millisecond. For typical scenarios, it is recommended to use the startTime and endTime parameters instead.
afterSerialId long No Used for pagination to retrieve records when the order volume exceeds 500 per millisecond. For typical scenarios, it is recommended to use the startTime and endTime parameters instead.
count long No Number of records to return
includeOld boolean No Retrieve trade history records past 7 days
orderID string No Query trade history by order ID
clOrderID string No Query trade history by custom order ID
Time Interval Maximum Days Explanation
startTime / endTime 7 Maximum 7 days within the specified interval. If specified interval exceeds 7 days, the start time will be set to 7 days before the end time
startTime / - 7 If the end time is not specified, then 7 days after the start time
- / endTime 7 If the start time is not specified, then 7 days before the end time
- / - 7 If neither start nor end time is specified, then 7 days before the current time

Response Content

Name Type Required Description
symbol string Yes Market symbol
side string Yes Trade side. Values are: [BUY, SELL]
price double Yes Transacted price
size long Yes Original order size
serialId long Yes Serial Id, running sequence number
tradeId string Yes Trade identifier
timestamp long Yes Transacted timestamp
base string Yes Base currency
quote string Yes Quote currency
wallet string Yes Wallet name
CROSS@: Cross wallet
ISOLATED@market: Market refers to the current symbol with -USDT appended. Eg. BTC-PERP isolated wallet would be ISOLATED@BTC-PERP-USDT
clOrderID string Yes Custom order ID
orderId string Yes Order ID
username string Yes btse username
triggerType long Yes Trigger type
1001: Stop Loss
1002: Take Profit
feeAmount long Yes Fee amount
feeCurrency long Yes Fee currency
filledPrice double Yes Filled price
averageFillPrice double Yes Average filled price
triggerPrice double Yes Trigger price
filledSize long Yes Filled size
orderType integer Yes Order Type
realizedPnL double Yes Not used in Spot
total long Yes Not used in Spot
positionId string Yes The current order belongs to the id of position.
contractSize double Yes The trade contract size

Query Position

Request

/api/v2.2/user/positions

Response

[
  {
    "marginType": 0,
    "entryPrice": 0,
    "markPrice": 29286.4,
    "symbol": "BTC-PERP",
    "side": "BUY",
    "orderValue": 441.8492,
    "settleWithAsset": "BTC",
    "unrealizedProfitLoss": -0.23538014,
    "totalMaintenanceMargin": 2.366912551,
    "size": 62,
    "liquidationPrice": 0,
    "isolatedLeverage": 25,
    "adlScoreBucket": 2,
    "liquidationInProgress": false,
    "timestamp": 1576661434072,
    "currentLeverage": 0,
    "takeProfitOrder": {
        "orderId": "ea1ab233-c79a-4503-a475-f8633ecc9d79",
        "side": "SELL",
        "triggerPrice": 31000.0,
        "triggerUseLastPrice": false
    },
    "stopLossOrder": {
        "orderId": "48523190-77b9-44ea-bee0-d67a428a51b8",
        "side": "SELL",
        "triggerPrice": 27000.0,
        "triggerUseLastPrice": true
    },
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": "BTC-PERP-USDT"
  },{
     "marginType": 91,
     "entryPrice": 1631.106666667,
     "markPrice": 1630.398947255,
     "symbol": "ETH-PERP",
     "side": "BUY",
     "orderValue": 48.9119684176,
     "settleWithAsset": "USDT",
     "unrealizedProfitLoss": -0.02123158,
     "totalMaintenanceMargin": 0.254871114,
     "size": 3,
     "liquidationPrice": 0,
     "isolatedLeverage": 0,
     "adlScoreBucket": 2,
     "liquidationInProgress": false,
     "timestamp": 0,
     "takeProfitOrder": null,
     "stopLossOrder": null,
     "positionMode": "HEDGE",
     "positionDirection": "LONG",
     "positionId": "ETH-PERP-USDT|LONG",
     "currentLeverage": 0.0340349245,
     "takeProfitOrder": null,
     "stopLossOrder": null
     }
]

GET /api/v2.2/user/positions

Queries user's current position. When no symbol is specified, positions for all markets will be returned. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string No Market symbol

Response Content

Name Type Required Description
symbol string Yes Market symbol
side string Yes Position side. Values are: [Buy, SELL]
size long Yes Position size
entryPrice double Yes Entry price
markPrice double Yes Mark price
marginType long Yes Margin Type. Values as follows
91: CROSS wallet
92: Isolated wallet
orderValue double Yes Notional value
settleWithAsset string Yes Settlement currency
totalMaintenanceMargin double Yes Maintenance margin
unrealizedProfitLoss double Yes Unrealized profit and loss
liquidationPrice double Yes Liquidation Price
isolatedLeverage double Yes Isolated leverage value
adlScoreBucket double Yes ADL Score probability
liquidationInProgress boolean Yes Indicator if liquidation is in progress
currentLeverage double Yes Current leverage
timestamp long Yes Timestamp when position was queried
takeProfitOrder TakeProfitOrder object No Take profit order info
stopLossOrder StopLossOrder object No Stop loss order info
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes Position id

Close Position

Request

{
  "price": 0,
  "symbol": "BTC-PERP",
  "type": "MARKET"
}

Request(For hedge mode position)

{
  "price": 0,
  "symbol": "BTC-PERP",
  "type": "MARKET",
  "positionId": "BTC-PERP-USDT|LONG"
}

Response

[
  {
    "status": 4,
    "symbol": "BTC-PERP",
    "orderType": 76,
    "price": 24010.0,
    "side": "SELL",
    "size": 1,
    "orderID": "93cf814a-595e-4b20-bba9-5c5340ca947d",
    "timestamp": 1660710188450,
    "triggerPrice": 0.0,
    "trigger": false,
    "deviation": 100.0,
    "stealth": 100.0,
    "message": "",
    "avgFillPrice": 24010.0,
    "fillSize": 1.0,
    "clOrderID": "",
    "originalSize": 1.0,
    "postOnly": false,
    "remainingSize": 0.0,
    "positionMode": "ONE_WAY",
    "positionDirection": null,
    "positionId": null,
    "time_in_force": "GTC"
  }
]

POST /api/v2.2/order/close_position

Closes a user's position for the particular market as specified by symbol. If type is specified as LIMIT, then price is mandatory. When type is MARKET, it closes the position at market price. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
type string Yes Close position type with values:
LIMIT: Close at price
MARKET: Close at market price
price double No Close price. Mandatory when type is LIMIT
postOnly boolean No Boolean to indicate if this is a post only order. For post only orders, traders are charged maker fees
positionId string No The position ID that you want to close. Mandatory when positionMode is HEDGE or ISOLATED

Response Content

Name Type Required Description
symbol string Yes Market symbol
clOrderID string Yes Customer tag sent in by trader
fillSize string Yes Trade filled size
orderID string Yes Order ID
orderType integer Yes Order type
76: Limit Order
77: Market order
80: Algo order
postOnly boolean Yes Indicates if order is a post only order
price double Yes Order price
side string Yes Order side
BUY or SELL
size long Yes Cancelled size
status long Yes Order status
2: Order Inserted
3: Order Transacted
4: Order Fully Transacted
5: Order Partially Transacted
6: Order Cancelled
7: Order Refunded
9: Trigger Inserted
10: Trigger Activated
15: Order Rejected
16: Order Not Found
17: Request failed
time_in_force string Yes Order validity
timestamp long Yes Order timestamp
trigger string Yes Indicator if order is a trigger order
triggerPrice string Yes Order trigger price, returns 0 if order is not a trigger order
avgFillPrice string Yes Average filled price. Returns the average filled price for partially transacted orders
message string Yes Trade messages
stealth double Yes Stealth value of order
deviation string Yes Deviation value of order
remainingSize double Yes Size left to be transacted
originalSize double Yes Original order size
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes Position id

Get Risk Limit

Request

/api/v2.2/risk_limit?symbol=BTC-PERP

Response

{
    "symbol": "BTC-PERP",
    "riskLimit": 100000
}

GET /api/v2.2/risk_limit

Query risk limit for the specified market. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol

Response Content

Name Type Required Description
symbol string Yes Market symbol
riskLimit long Yes Risk limit value now in position size, but will be changed to USD value along with futures market name change

Set Risk Limit

Request

{
  "symbol": "BTC-PERP",
  "riskLimit": 0
}

Request (When positionMode is HEDGE or ISOLATED)

{
    "symbol": "BTC-PERP",
    "riskLimit": 100000,
    "positionMode": "HEDGE"
}

Response

{
  "symbol": "BTC-PERP",
  "timestamp": 1577093486551,
  "status": 20,
  "type": 94,
  "message": "false"
}

POST /api/v2.2/risk_limit

Changes risk limit for the specified market. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
riskLimit long Yes Risk limit value now in position size, but it will be changed to USD value in the future.
positionMode string no ONE_WAY(default) or HEDGE. Mandatory when positionMode is HEDGE or ISOLATED

Response Content

Name Type Required Description
symbol string Yes Market symbol
status long Yes Status of the request. Values are:
8: Insufficient Balance
12: Error in updating risk limit
20: Success
41: Invalid risk limit
type double Yes Value will be 94 indicating that type is Risk Limit
timestamp long Yes Timestamp where risk limit was set
message long Yes Message

Set Leverage

Request

{
  "symbol": "BTC-PERP",
  "leverage": 0,
  "marginMode": "CROSS"
}

Request (When positionMode is HEDGE or ISOLATED)

{
    "symbol": "BTC-PERP",
    "leverage": 0,
    "positionMode": "HEDGE",
    "marginMode": "CROSS"
}

Response

{
  "symbol": "BTC-PERP",
  "timestamp": 1660711246942,
  "status": 20,
  "type": 93,
  "message": ""
}

POST /api/v2.2/leverage

Change leverage values for the specified market. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
leverage double Yes Leverage value, 0 means cross maximum leverage
positionMode string no ONE_WAY(default) or HEDGE. Mandatory when positionMode is HEDGE or ISOLATED
positionId string no The position ID that you want to change. Mandatory when positionMode is HEDGE or ISOLATED
marginMode string no CROSS or ISOLATED(default)

Response Content

Name Type Required Description
symbol string Yes Market symbol
status long Yes Status of the request. Values are:
8: Insufficient Balance
13: Invalid leverage
20: Success
64: Undergoing liquidation
type double Yes Value will be 93 indicating that type is Leverage
timestamp long Yes Timestamp where leverage was set
message long Yes Message

Get Leverage

Response

[
  {
    "symbol": "BTC-PERP",
    "leverage": 10,
    "marginMode": "ISOLATED",
    "positionDirection": "LONG"
  },
  {
    "symbol": "BTC-PERP",
    "leverage": 3,
    "marginMode": "ISOLATED",
    "positionDirection": "SHORT"
  }
]

Get /api/v2.2/leverage

Get leverage value for the specified market. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol

Response Content

Name Type Required Description
symbol string Yes Market symbol
leverage double Yes Current leverage value for the market, return 0 means the leverage is the maximum cross leverage
marginMode string Yes Current margin mode
positionDirection string Yes Current position direction when position mode is Hedge else return null

Change Contract Settlement Currency

Request

{
  "symbol": "BTC-PERP",
  "currency": "BTC"
}

Request (When positionMode is HEDGE or ISOLATED)

{
    "symbol": "BTC-PERP",
    "currency": "USDT",
    "positionId": "BTC-PERP-USDT|LONG"
}

Response (only available when an error occurs)

{
  "status": 0,
  "errorCode": 0,
  "message": "string"
}

POST /api/v2.2/settle_in

Changes the settlement currency for the position in the current market. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
currency string Yes Settlement currency to set
positionId string No The position ID that you want to set. Mandatory when positionMode is HEDGE or ISOLATED

Response Content

Name Type Required Description
status long No Status. Only available when an error occurs.
errorCode long No Error code. Only available when an error occurs.
message string No Response message. Only available when an error occurs.

Query Account Fee

Response

{
  "makerFee": 0,
  "symbol": "BTC-PERP",
  "takerFee": 0
}

GET /api/v2.2/user/fees

Retrieve user's trading fees. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string No Market symbol

Response Content

Name Type Required Description
symbol string Yes Market symbol
makerFee double Yes Maker fees
takerFee double Yes Taker fees

Bind TP/SL

Request

{
    "symbol": "BTC-PERP",
    "takeProfitPrice": 31000,
    "takeProfitTrigger": "markPrice",
    "stopLossPrice": 22000,
    "stopLossTrigger": "lastPrice"
}

Response

[
    {
        "status": 9,
        "symbol": "BTC-PERP",
        "orderType": 77,
        "price": 0.0,
        "side": "SELL",
        "size": 100,
        "orderID": "4820b20a-e41b-4273-b3ad-4b19920aeeb5",
        "timestamp": 1691974463934,
        "triggerPrice": 31000.0,
        "trigger": true,
        "deviation": 100.0,
        "stealth": 100.0,
        "message": "",
        "avgFillPrice": 0.0,
        "fillSize": 0.0,
        "clOrderID": "",
        "originalSize": 100.0,
        "postOnly": false,
        "remainingSize": 100.0,
        "orderDetailType": null,
        "positionMode": "ONE_WAY",
        "positionDirection": null,
        "positionId": "BTC-PERP-USDT",
        "time_in_force": "GTC"
    }
]

POST /api/v2.2/order/bind/tpsl

Bind TP/SL with an existing position. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string yes Market symbol
side string yes "BUY" or "SELL" Mandatory when positionMode is HEDGE, in hedge mode, it is used to clsoe the specified position, ex: sell to close long position, buy to close short position
takeProfitPrice double No Mandatory when creating new order with take profit order. Indicates the trigger price. Must set takeProfitPrice or stopLossPrice at least when using this API.
takeProfitTrigger string No For creating order with take profit order. Valid options: markPrice (default) or lastPrice
stopLossPrice double No Mandatory when creating new order with stop loss order. Indicates the trigger price
stopLossTrigger string No For creating order with stop loss order. Valid options: markPrice (default) or lastPrice
positionMode string no ONE_WAY(default) or HEDGE or ISOLATED. Mandatory when positionMode is HEDGE or ISOLATED
positionId string no The position ID that you want to bind. Mandatory when positionMode is ISOLATED

Response Content

Name Type Required Description
symbol string Yes Market symbol
clOrderID string Yes Customer tag sent in by trader
fillSize number Yes Trade filled size
orderID string Yes Order ID
orderType string Yes Order type
76: Limit Order
77: Market order
80: Algo order
postOnly boolean Yes Indicates if order is a post only order
price double Yes Order price
side string Yes Order side
BUY or SELL
size long Yes Order size in contract size (this remains unchanged even after risk limit adjustment)
status long Yes Order status
2: Order Inserted
3: Order Transacted
4: Order Fully Transacted
5: Order Partially Transacted
6: Order Cancelled
7: Order Refunded
9: Trigger Inserted
10: Trigger Activated
15: Order Rejected
16: Order Not Found
17: Request failed
time_in_force string Yes Order validity
timestamp long Yes Order timestamp
trigger boolean Yes Indicator if order is a trigger order
triggerPrice double Yes Order trigger price, returns 0 if order is not a trigger order
avgFillPrice double Yes Average filled price. Returns the average filled price for partially transacted orders
message string Yes Trade messages
stealth string Yes Only valid for Algo orders
deviation double Yes Only valid for Algo
remainingSize double Yes Size left to be transacted
originalSize double Yes Original order size
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes Position id

Query Position Mode

Response

[
    {
        "symbol": "ETH-PERP",
        "positionMode": "HEDGE"
    },
    {
        "symbol": "BTC-PERP",
        "positionMode": "ONE_WAY"
    }
]

GET /api/v2.2/position_mode

Retrieve user's position mode. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string No Market symbol

Response Content

Name Type Required Description
symbol string Yes Market symbol
positionMode string Yes ONE_WAY, HEDGE or ISOLATED

Change Position Mode

Request

{
  "symbol": "BTC-PERP",
  "positionMode": "HEDGE"
}

POST /api/v2.2/position_mode

Changes position mode. Requires Trading permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol
positionMode string Yes ONE_WAY, HEDGE or ISOLATED

Response Content

Name Type Required Description
symbol string Yes Market symbol
timestamp long No Timestamp where position mode was set
status string No Status of the request. Values are:
20: Success
type string No Value will be 129 indicating that type is Futures Config Mode Change
message string No Message

Query User Initial Margin Percentage And Maintenance Margin Percentage

Response

[
    {
        "symbol": "ETH-PERP",
        "initialMarginPercentage": 0.01,
        "maintenanceMarginPercentage": 0.005
    },
    {
        "symbol": "BTC-PERP",
        "initialMarginPercentage": 0.01,
        "maintenanceMarginPercentage": 0.005
    }
]

GET /api/v2.2/user/margin_setting

Queries user's initial margin percentage and maintenance margin percentage. When no symbol is specified, margin percentage for all markets will be returned. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string No Market symbol

Response Content

Name Type Required Description
symbol string Yes Market symbol
initialMarginPercentage double Yes Current initial margin percentage
maintenanceMarginPercentage double Yes Current maintenance margin percentage

Wallet Endpoints

Query Wallet Balance

Response

[
  {
    "trackingID": 0,
    "queryType": 0,
    "activeWalletName": "string",
    "wallet": "CROSS@",
    "username": "string",
    "walletTotalValue": 0,
    "totalValue": 100,
    "marginBalance": 100,
    "availableBalance": 100,
    "unrealisedProfitLoss": 0,
    "maintenanceMargin": 0,
    "leverage": 0,
    "openMargin": 0,
    "assets": [
      {
        "balance": 0.20183537,
        "assetPrice": 7158.844999999999,
        "currency": "BTC"
      }
    ],
    "assetsInUse": [
      {
        "balance": 0.01,
        "assetPrice": 7158.844999999999,
        "currency": "BTC"
      }
    ]
  }
]

GET /api/v2.2/user/wallet

Query user's wallet balance. Requires Read permissions on the API key.

Request Parameters

Name Type Required Description
wallet string Yes Wallet name
CROSS@: Cross wallet
ISOLATED@market: Market refers to the current symbol with -USDT appended. Eg. BTC-PERP isolated wallet would be ISOLATED@BTC-PERP-USDT

Response Content

Wallet

Name Type Required Description
wallet string Yes Wallet name
activeWalletName string Yes Active wallet name
queryType integer Yes Query type
trackingID long Yes Internal tracking ID, not being used
walletTotalValue double Yes Wallet total value
totalValue double Yes Total value
marginBalance double Yes Margin balance
availableBalance double Yes Available Balance
unrealisedProfitLoss double Yes Unrealised Profit / Loss
maintenanceMargin double Yes Maintenance margin
leverage double Yes Leverage. In CROSS wallet, this field is current leverage, not leverage setting
openMargin double Yes Open margin
assets Asset object Yes Assets available
assetsInUse Asset object Yes Assets in use

Assets / Asset in Use

Name Type Required Description
balance double Yes Balance
assetPrice double Yes Asset price
currency string Yes Currency

Query Wallet History

Response

[
  {
    "amount": 21.35823825,
    "currency": "USD",
    "description": "string",
    "fees": 0.06,
    "orderId": 20181213000239,
    "status": 10,
    "timestamp": 1571630174639,
    "type": 1,
    "username": "btseUser",
    "wallet": "Wallet",
    "txid": "<Blockchain Transaction ID>",
    "currencyNetwork": "<Blockchain currency network>"
  }
]

GET /api/v2.2/user/wallet_history

Get user's wallet history records on the futures wallet. Requires Read permission.

Request Parameters

Name Type Required Description
wallet string No Wallet, if not specified will return all wallets. Valid values are:
CROSS@: Cross wallet
ISOLATED@BTC-PERP-USDT: Isolated wallets
startTime long No Starting time in milliseconds (eg. 1624987283000)
endTime long No Ending time in milliseconds (eg. 1624987283000)
count integer No Number of records to return

Response Content

Name Type Required Description
currency string Yes Currency
amount double Yes Amount in the record
fees double Yes Fees charged if any
orderId string Yes Internal wallet order ID
wallet string Yes Wallet type. For futures will return CROSS@ or ISOLATED@
description string Yes Description of the transaction
status integer Yes 1: PENDING
2: PROCESSING
10: COMPLETED
16: CANCELLED
type integer Yes 105: Wallet Transfer
106: Wallet Liquidation
108: Realized PnL
110: Funding
121: Asset Conversion

Query Unified Wallet Margin

Response

{
  "symbol": "BTC-PERP",
  "walletTotalValue": 1535.10700567,
  "walletTotalUnrealizedProfitLoss": -49.90799449,
  "futuresTotalAvailableBalance": 1836.521306109,
  "wallets": [
    {
      "activeWalletName": "VIRTUAL|5@BTC-PERP-USDT#4",
      "unrealisedProfitLoss": 49.88502177,
      "walletTotalValue": 956.43166194,
      "marginBalance": 1006.31668371,
      "availableBalance": 993.201492938,
      "maintenanceMargin": 13.115190772
    }
  ]
}

GET /api/v2.2/user/unifiedWallet/margin

This API is for the users who have upgraded wallet

Gets margin information for the specified wallet or position. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string No Market symbol
positionId string No Position unique id

Response Contnet

Name Type Require Description
symbol string Yes Market symbol
walletTotalValue number Yes Wallet total value
walletTotalUnrealizedProfitLoss number Yes Wallet total P&L
futuresTotalAvailableBalance number Yes Wallet total available balance
wallets Wallet Object Yes Wallet details

Wallet Details

Name Type Require Description
activeWalletName string Yes Wallet name
unrealisedProfitLoss number Yes Wallet P&L
walletTotalValue number Yes Wallet total P&L
marginBalance number Yes Margin balance
availableBalance number Yes Available balance
maintenanceMargin number Yes Maintenance margin

Query Wallet Margin

Response

[
  {
    "trackingID": 0,
    "requestId": 0,
    "queryType": 0,
    "wallet": "CROSS@",
    "walletTotalValue": 0,
    "totalValue": 100,
    "marginBalance": 100,
    "availableBalance": 100,
    "unrealisedProfitLoss": 0,
    "maintenanceMargin": 0,
    "leverage": 0,
    "openMargin": 0,
    "assets": [
      {
        "balance": 0.20183537,
        "assetPrice": 7158.844999999999,
        "currency": "BTC"
      }
    ],
    "assetsInUse": [
      {
        "balance": 0.01,
        "assetPrice": 7158.844999999999,
        "currency": "BTC"
      }
    ]
  }
]

GET /api/v2.2/user/margin

The users who have upgraded wallet to unified wallet are not allow to use this API. Please use Query Unified Wallet Margin.

Gets margin information for the specified wallet so that users can know which wallet they are currently using in the market. Requires Read permission.

Request Parameters

Name Type Required Description
symbol string Yes Market symbol

Response Content

Wallet

Name Type Required Description
wallet string Yes Wallet name
queryType integer Yes Query type
trackingID long Yes Internal tracking ID, not being used
requestId long Yes Internal request ID, not being used
walletTotalValue double Yes Wallet total value
totalValue double Yes Total value
marginBalance double Yes Margin balance
availableBalance double Yes Available Balance
unrealisedProfitLoss double Yes Unrealised Profit / Loss
maintenanceMargin double Yes Maintenance margin
leverage double Yes Leverage
openMargin double Yes Open margin
assets Asset object Yes Assets available
assetsInUse Asset object Yes Assets in use

Assets / Asset in Use

Name Type Required Description
balance double Yes Balance
assetPrice double Yes Asset price
currency string Yes Currency

Transfer funds between Futures wallet

Request

{
  "walletSrc": "",
  "walletSrcType": "SPOT",
  "walletDest": "",
  "walletDestType": "CROSS",
  "apiWallets": [
    {
      "currency": "USD",
      "allBalance": true
    },
    {
      "currency": "BTC",
      "allBalance": true
    }
  ]
}

Response

[
  {
    "trackingID": 0,
    "queryType": 0,
    "activeWalletName": "",
    "wallet": "CROSS@",
    "username": "string",
    "walletTotalValue": 0,
    "totalValue": 100,
    "marginBalance": 100,
    "availableBalance": 100,
    "unrealisedProfitLoss": 0,
    "maintenanceMargin": 0,
    "leverage": 0,
    "openMargin": 0,
    "assets": [
      {
        "balance": 0.20183537,
        "assetPrice": 7158.844999999999,
        "currency": "BTC"
      }
    ],
    "assetsInUse": [
      {
        "balance": 0.01,
        "assetPrice": 7158.844999999999,
        "currency": "BTC"
      }
    ]
  }
]

POST /api/v2.2/user/wallet/transfer

Transfers funds between user's wallet. User can specify the source and target wallet to transfer funds. Requires Transfer permission.

Request Parameters

Wallet Request

Name Type Required Description
walletSrc string No Source wallet, required if walletSrcType is ISOLATED
walletSrcType string Yes Source type, valid values are:
SPOT: Spot Wallet
CROSS: Cross Wallet
ISOLATED: Isolated wallet for the market where market the market symbol
walletDest string No Destination wallet, required if walletDestType is ISOLATED
walletDestType string Yes Destination type, valid values are:
SPOT: Spot Wallet
CROSS: Cross Wallet
ISOLATED: Isolated wallet for the market where market the market symbol
apiWallets Wallet Detail Yes Transfer details

Wallet Detail Request

Name Type Required Description
currency string Yes Wallet Currency
allBalance boolean Yes Indicator if all wallet balance is to be transferred
balance double No The value of the balance is to be transferred, example: 10

Response Content

Wallet

Name Type Required Description
wallet string Yes Wallet name
activeWalletName string Yes Active wallet name
queryType integer Yes Query type
trackingID long Yes Internal tracking ID, not being used
walletTotalValue double Yes Wallet total value
totalValue double Yes Total value
marginBalance double Yes Margin balance
availableBalance double Yes Available Balance
unrealisedProfitLoss double Yes Unrealised Profit / Loss
maintenanceMargin double Yes Maintenance margin
leverage double Yes Leverage
openMargin double Yes Open margin
assets Asset object Yes Assets available
assetsInUse Asset object Yes Assets in use

Assets / Asset in Use

Name Type Required Description
balance double Yes Balance
assetPrice double Yes Asset price
currency string Yes Currency

Sub-Account Wallet Transfer

POST /api/v2.2/subaccount/wallet/transfer

Transfers funds between user and sub-account wallet. User can specify the source and target wallet to transfer funds, Wallet permission is required. To get supported currency list please check Available currency list for action.

Request Parameters

Wallet Request

Name Type Required Description
walletSrc string No Source wallet, required when walletSrcType is ISOLATED
walletSrcType string Yes Source type, valid values are:
SPOT: Spot Wallet
CROSS: Cross Wallet
ISOLATED: Isolated wallet for the market where market the market symbol
walletDest string No Destination wallet, required when walletDestType is ISOLATED
walletDestType string Yes Destination type, valid values are:
SPOT: Spot Wallet
CROSS: Cross Wallet
ISOLATED: Isolated wallet for the market where market the market symbol
fromUser string Yes Source username
receiver string Yes Receiver username
apiWallets Wallet Detail Yes Transfer details

Wallet Detail Request

Name Type Required Description
currency string Yes Wallet Currency
allBalance boolean Yes Indicator if all wallet balance is to be transferred
balance double No The value of the balance is to be transferred, example: 10

Response Content

Wallet

Name Type Required Description
code integer Yes Response code
msg string Yes Response message
time integer Yes Response Time
data object No
success boolean Yes Is transfer success

Transfer Error Code

Code Description
-2 Invalid request parameter
-1046 Transfer fromUser Futures asset to DestWallet failed
-1047 Transfer fromUser to receiver failed
-1048 Transfer receiver Spot wallet to Futures wallet failed

Order Book Websocket Streams

Endpoints

OSS L1 Snapshot (By grouping)

Request

{
  "op": "subscribe",
  "args": [
    "snapshotL1:BTC-PERP_0"
  ]
}

{
  "op": "unsubscribe",
  "args": [
    "snapshotL1:BTC-PERP_0"
  ]
}

Response

{
  "topic": "snapshotL1:BTC-PERP_0",
  "data": {
    "bids": [
      [
          "28064.9",
          "1268"
      ]
    ],
    "asks": [
      [
          "28065.0",
          "1015"
      ]
    ],
    "type": "snapshotL1",
    "symbol": "BTC-PERP",
    "timestamp": 1680751558529
  }
}

Subscribe to the Level 1 Orderbook through the endpoint wss://ws.btse.com/ws/oss/futures. The format to subscribe to will be symbol_grouping.

Response Content

Orderbook Object

Name Type Required Description
topic string Yes Websocket topic
data Data Object Yes Refer to data object below

Data Object

Name Type Required Description
bids Quote Object Yes Bid quotes
asks Quote Object Yes Asks quotes
symbol string Yes Market symbol
type string Yes snapshotL1 - L1 data refers to the best bid / best ask of a trading pair’s order book.
timestamp long Yes Orderbook timestamp

Orderbook Incremental Updates

Request

{
  "op": "subscribe",
  "args": [
    "update:BTC-PERP_0"
  ]
}

{
  "op": "unsubscribe",
  "args": [
    "update:BTC-PERP_0"
  ]
}

Response

{
  "topic": "update:BTC-PERP_0",
  "data": {
    "bids": [
      [
        "59252.5",
        "0.06865"
      ],
      [
        "59249.0",
        "0.24000"
      ],
      [
        "59235.5",
        "0.16073"
      ],
      [
        "59235.0",
        "0.26626"
      ],
      [
        "59233.0",
        "0.50000"
      ]
    ],
    "asks": [
      [
        "59292.0",
        "0.50000"
      ],
      [
        "59285.5",
        "0.24000"
      ],
      [
        "59285.0",
        "0.15598"
      ],
      [
        "59278.5",
        "0.01472"
      ]
    ],
    "seqNum": 628282,
    "prevSeqNum": 628281,
    "type": "snapshot",
    "timestamp": 1565135165600,
    "symbol": "BTC-PERP"
  }
}

{
  "topic": "update:BTC-PERP",
  "data": {
    "bids": [],
    "asks": [
      [
        "59367.5",
        "2.15622"
      ],
      [
        "59325.5",
        "0"
      ]
    ],
    "seqNum": 628283,
    "prevSeqNum": 628282,
    "type": "delta",
    "timestamp": 1565135165600,
    "symbol": "BTC-PERP"
  }
}

Subscribe to Orderbook incremental updates through the endpoint wss://ws.btse.com/ws/oss/futures. The format of topic will be update:symbol_grouping (eg. update:BTC-PERP_0). The first response received will be a snapshot of the current orderbook (this is indicated in the type field) and 50 levels will be returned. Incremental updates will be sent in subsequent packets with type delta.

Bids and asks will be sent in price and size tuples. The size sent will be the new updated size for the price. If a value of 0 is sent, the price should be removed from the local copy of the orderbook.

To ensure that the updates are received in sequence, seqNum indicates the current sequence and prevSeqNum refers to the packet before. seqNum will always be one after the prevSeqNum. If the sequence is out of order, you will need to unsubscribe and re-subscribe to the topic again.

Also if crossed orderbook ever occurs when the best bid higher or equal to the best ask, please unsubscribe and re-subscribe to the topic again.

Response Content

Orderbook Object

Name Type Required Description
topic string Yes Websocket topic
data Data Object Yes Refer to data object below

Data Object

Name Type Required Description
bids Quote Object Yes Bid quotes
asks Quote Object Yes Asks quotes
seqNum int Yes Current sequence number
prevSeqNum int Yes Previous sequence number
type string Yes snapshot - Snapshot of the orderbook with a maximum of 50 levels
delta - Updates of the orderbook
timestamp long Yes Timestamp of the orderbook
symbol string Yes Orderbook symbol

Orderbook Error Response

Error Code Message
1000 Market pair provided is currently not supported.
1001 Operation provided is currently not supported.
1002 Invalid request. Please check again your request and provide all information required.
1005 Topic provided does not exist.
1007 User message buffer is full.
1008 Reached maximum failed attempts, closing the session.

Websocket Streams

Endpoints

Ping/Pong

For all our WebSocket servers, simply send a 'ping' message, and the WebSocket server will respond with a 'pong' message if the WebSocket connection is established and active.

Request

ping

Response

pong

Subscription

Here is an example for topic subscription.

Request

{
  "op": "subscribe",
  "args": [
    "tradeHistoryApiV2:BTC-PERP"
  ]
}

Response

{
  "event": "subscribe",
  "channel": [
    "tradeHistoryApiV2:BTC-PERP"
  ]
}

To subscribe to a websocket public trade fill

Request Parameters

Name Type Required Description
op string Yes Operation. subscribe will subscribe to the topics provided in args. unsubscribe will unsubscribe from the topics
args array Yes Topics to subscribe to.

Response Content

Name Type Required Description
event string Yes Respond with the event type
channel array Yes Topics which have been sucessfully subscribed

Public Trade Fills

Request

{
  "op": "subscribe",
  "args": [
    "tradeHistoryApiV2:BTC-PERP"
  ]
}

Response

{
  "topic": "tradeHistoryApiV2:BTC-PERP",
  "data": [
  {
    "symbol": "BTC-PERP",
    "side": "SELL",
    "size": 0.007,
    "price": 5302.8,
    "tradeId": 118974855,
    "timestamp": 1584446020295
  }
  ]
}

Subscribe to recent trade feed for a market. The topic will be tradeHistoryApiV2:<market> where <market> is the market symbol.

Response Content

TradeHistory Object

Name Type Required Description
topic string Yes Websocket topic
data Data Object Yes Refer to data object below

Data Object

Name Type Required Description
symbol string Yes Market symbol
side string Yes Trade Side, BUY or SELL
size double Yes Transacted size
price double Yes Transacted price
tradeId long Yes Trade sequence Id
timestamp long Yes Trade timestamp

Authentication

Request

{
  "op":"authKeyExpires",
  "args":["APIKey", "nonce", "signature"]
}

Authenticate the websocket session to subscribe to authenticated websocket topics. Assume we have values as follows:

Our subscription request will be:

{
  "op":"authKeyExpires",
  "args":["4e9536c79f0fdd72bf04f2430982d3f61d9d76c996f0175bbba470d69d59816x", "1624985375123", "c410d38c681579adb335885800cff24c66171b7cc8376cfe43da1408c581748156b89bcc5a115bb496413bda481139fb"]
}

Request Parameters

Below details the arguments needed to be sent in.

Index Type Required Description
0 string Yes First argument is the API key
1 long Yes Nonce which is the current timestamp
2 string Yes Generated signature

Generating a signature

echo -n "/ws/futures1624985375123"  | openssl dgst -sha384 -hmac "848db84ac252b6726e5f6e7a711d9c96d9fd77d020151b45839a5b59c37203bx"
(stdin)= bd8afb8bee58ba0a2c67f84dcfe6e64d0274f55d064bb26ea84a0fe6dd8c621b541b511982fb0c0b8c244e9521a80ea1

Notifications

Request

{
  "op": "subscribe",
  "args": [
    "notificationApiV3"
  ]
}

Response

{
  "topic": "notificationApiV3",
  "data": [
    {
      "symbol": "Market Symbol (eg. BTC-PERP, for topic 'notificationApiV2' will be BTCPFC)",
      "orderID": "BTSE internal order ID",
      "side": "BUY",
      "type": "76",
      "price": "Order price or transacted price",
      "size": "Order size or transacted size",
      "originalSize": "Order size",
      "avgFillPrice": 35000,
      "fillSize": 0.001,
      "status": "<Refer to Status description on the left>",
      "clOrderID": "<Client order ID>",
      "maker": "<Maker flag, if true indicates that trade is a maker trade>",
      "stealth": 1,
      "timestamp": 1624985375123,
      "pegPriceDeviation": "Indicate the deviation percentage. Valid for only algo orders.",
      "remainingSize": "<Remaining size on the order>",
      "time_in_force": "<Time where this order is valid>",
      "txType": "STOP | TAKE_PROFIT",
      "positionId": "BTC-PERP-USDT",
      "triggerPrice": "Trade Trigger Price"
    }
  ]

}

To receive trade notifications, subscribe to the notificationApiV2 or notificationApiV3 topics. It is recommended to use notificationApiV3, which provides market symbols in a more intuitive format, such as BTC-PERP. The WebSocket feed will push real-time, trade-level notifications to authenticated subscribers. Please note, if the topic is subscribed to without proper authentication, no messages will be delivered.

Response Content

Name Type Required Description
symbol string Yes Market symbol
orderID string Yes Internal order ID
side string Yes Trade side. BUY or SELL
type int Yes Order type. Valid values are:
76: Limit Order
77: Market Order
80: Algo orders
price double Yes Order price or transcated price
size double Yes Order size or transacted size
originalSize double Yes Original order size
avgFilledPrice double Yes Average filled price
fillSize double Yes Filled size of order
status integer Yes Status with values as follows:
1: MARKET_UNAVAILABLE, Market is currently unavailable
2: ORDER_INSERTED, Order is inserted successfully
4: ORDER_FULLY_TRANSACTED, Order is fully transacted
5: ORDER_PARTIALLY_TRANSACTED, Order is partially transacted
6: ORDER_CANCELLED, Order is cancelled successfully
8: INSUFFICIENT_BALANCE, Insufficient balance in account
9: TRIGGER_INSERTED, Trigger Order is inserted successfully
10: TRIGGER_ACTIVATED, Trigger Order is activated successfully
12: ERROR_UPDATE_RISK_LIMIT, Error in updating risk limit
15: ORDER_REJECTED, Change made to the order was unsuccessful
20: SUCCESS, Trade finished successfully
27: TRANSFER_SUCCESSFUL, Transfer funds between futures and spot is successful
28: TRANSFER_UNSUCCESSFUL, Transfer funds between spot and futures is unsuccessful
41: ERROR_INVALID_RISK_LIMIT, Invalid risk limit was specified
64: STATUS_LIQUIDATION, Account is undergoing liquidation
96: FUTURES_CONFIG_SETTLE_WITH_ASSET, Set futures settle currency
101: FUTURES_ORDER_PRICE_OUTSIDE_LIQUIDATION_PRICE, Futures order is outside of liquidation price
305: ERROR_ORDER_PRICE_OUT_OF_PRICE_PROTECTION_RANGE, order price is out of the protection range
1003: ORDER_LIQUIDATION, Order is undergoing liquidation
1004: ORDER_ADL, Order is undergoing ADL
clOrderID string Yes Custom order ID
maker boolean Yes Indicator to indicate if trade is a maker trade
remainingSize double Yes Remaining size on the order
time_in_force string Yes Validity of the order
timestamp long Yes Order timestamp or transacted timestamp
txType string Yes Used by trigger or OCO orders. STOP indicates its a Stop order, TAKEPROFIT indicates its a take profit order, and LIMIT is when its not any of the above
stealth double Yes Percentage of orders to show on orderbook. Only for Algo orders
pegPriceDeviation double Yes Deviation percentage. Only for Algo orders
positionId string Yes Position ID

User Trade Fills

Request

{
  "op":"subscribe",
  "args":["fillsV2"]
}

Response

{
    "topic": "fillsV2",
    "id": "",
    "data": [
        {
            "orderId": "6aa36da1-0ed8-46c1-9327-c9d6313b3d12",
            "serialId": 189349157,
            "clOrderId": "_W_ekxogc1711427518228",
            "type": "77",
            "symbol": "BTC-PERP",
            "side": "BUY",
            "price": "69704.4",
            "size": "1.0",
            "feeAmount": "0.0348522",
            "feeCurrency": "USDT",
            "base": "BTC-PERP",
            "quote": "USDT",
            "maker": false,
            "timestamp": 1711427518338,
            "contractSize": 0.0001,
            "tradeId": "e094117f-9f84-4c82-b55d-d3d2a54d0dca"
        }
    ]
}

When a trade has been transacted, this topic will send the trade information back to the subscriber.

Response Content

Name Type Required Description
symbol string Yes Market symbol
orderId string Yes Internal order ID
clOrderId string Yes Custom order ID
serialId string Yes Trade sequence ID
tradeId string Yes Trade unique identifier
type int Yes Order type. Valid values are:
76: Limit Order
77: Market Order
80: Algo orders
side string Yes Trade side. BUY or SELL
price double Yes Transcated price
size double Yes Transacted size
feeAmount double Yes Fee amount charged
feeCurrency string Yes Fee currency
base string Yes Base currency
quote string Yes Quote currency
maker boolean Yes Indicator to indicate if trade is a maker trade
timestamp long Yes Order timestamp or transacted timestamp

All Position

Request

{
  "op":"subscribe",
  "args":["allPositionV3"]
}

Response

{
  "topic": "allPositionV3",
  "data": [{
    "requestId": 0,
    "username": "btse",
    "marketName": "BTC-PERP-USDT",
    "orderType": 90,
    "orderMode": 66,
    "originalAmount": 0.001,
    "maxPriceHeld": 0.0,
    "pegPriceMin": 0.0,
    "stealth": 1.0,
    "orderID": null,
    "maxStealthDisplayAmount": 0.0,
    "sellexchangeRate": 0.0,
    "triggerPrice": 0.0,
    "closeOrder": false,
    "liquidationInProgress": false,
    "marginType": 91,
    "entryPrice": 29286.404761929,
    "liquidationPrice": 0.0,
    "markedPrice": 29267.967916154,
    "unrealizedProfitLoss": -0.13236859,
    "totalMaintenanceMargin": 3.484381756,
    "totalContracts": 14.0,
    "isolatedLeverage": 0.0,
    "totalFees": 0.0,
    "totalValue": 662.115298076,
    "adlScoreBucket": 2.0,
    "orderTypeName": "TYPE_FUTURES_POSITION",
    "orderModeName": "MODE_BUY",
    "marginTypeName": "FUTURES_MARGIN_CROSS",
    "currentLeverage": 0.02,
    "avgFillPrice": 0.0,
    "positionId": "BTC-PERP-USDT|SHORT",
    "positionMode": "HEDGE",
    "positionDirection": "SHORT",
    "settleWithNonUSDAsset": "BTC",
    "contractSize": 0.001,
    "takeProfitOrder": {
        "orderId": "4820b20a-e41b-4273-b3ad-4b19920aeeb5",
        "side": "SELL",
        "triggerPrice": 31000.0,
        "triggerUseLastPrice": false
    },
    "stopLossOrder": {
        "orderId": "eff2b232-e2ce-4562-b0b4-0bd3713c11ec",
        "side": "SELL",
        "triggerPrice": 27000.0,
        "triggerUseLastPrice": true
    }
  },{
    "requestId": 0,
    "username": "btse",
    "userCurrency": null,
    "marketName": "LTC-PERP-USDT",
    "orderType": 90,
    "orderMode": 83,
    "originalAmount": 0.01,
    "maxPriceHeld": 0,
    "pegPriceMin": 0,
    "stealth": 1,
    "orderID": null,
    "maxStealthDisplayAmount": 0,
    "sellexchangeRate": 0,
    "triggerPrice": 0,
    "closeOrder": false,
    "liquidationInProgress": false,
    "marginType": 91,
    "entryPrice": 69.9,
    "liquidationPrice": 29684.3743872669,
    "markedPrice": 70.062346733,
    "unrealizedProfitLoss": -0.04870402,
    "totalMaintenanceMargin": 0.319484301,
    "totalContracts": 30,
    "isolatedLeverage": 0,
    "totalFees": 0,
    "totalValue": -21.01870402,
    "adlScoreBucket": 1,
    "booleanVar1": false,
    "orderTypeName": "TYPE_FUTURES_POSITION",
    "orderModeName": "MODE_SELL",
    "marginTypeName": "FUTURES_MARGIN_CROSS",
    "currentLeverage": 0.1116510969,
    "takeProfitOrder": null,
    "stopLossOrder": null,
    "settleWithNonUSDAsset": "USDT",
    "contractSize": 0.001,
    "positionId": "LTC-PERP-USDT|SHORT",
    "positionMode": "HEDGE",
    "positionDirection": "SHORT",
}]
}

All futures positions will be pushed via this topic once the position changes.

Response Content

Name Type Required Description
requestId integer Yes request id
username string Yes btse username
marketName string Yes market name
orderType integer Yes 90: Futures Position
orderTypeName string Yes String representation of orderType
orderMode integer Yes 66: BUY
83: SELL
orderModeName string Yes String representation of orderModeName
originalAmount double Yes order amount
maxPriceHeld double Yes max price of all time
pegPriceMin double Yes peg price min
stealth double Yes used for peg order
orderID string Yes order id
maxStealthDisplayAmount double Yes used for peg order
sellexchangeRate double Yes
triggerPrice double Yes OCO order
closeOrder boolean Yes whether it has an order to close this position
liquidationInProgress boolean Yes whether is in liquidation
marginType integer Yes WALLET TYPE:
91: CROSS
92: ISOLDATED
marginTypeName string Yes String representation of marginType
entryPrice double Yes entry price
liquidationPrice double Yes liquidation price
markPrice double Yes mark price
unrealizedProfitLoss double Yes unrealized pnl
totalMaintenanceMargin double Yes maintenance margin
totalContract double Yes size of the contract
isolatedLeverage double Yes
totalFees double Yes
totalValue double Yes
adlScoreBucket double Yes
currentLeverage double Yes
avgFillPrice double Yes
settleWithNonUSDAsset string Yes
takeProfitOrder TakeProfitOrder object No Take profit order info
stopLossOrder StopLossOrder object No Stop loss order info
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes Position id
contractSize double Yes The position contract size

Positions

Request

{
  "op":"subscribe",
  "args":["positionsV2"]
}

Response

{
  "topic": "positionsV2",
  "data": [{
    "orderID": null,
    "requestId": 0,
    "username": "btse",
    "marketName": "BTC-PERP-USDT",
    "orderType": 90,
    "orderMode": 66,
    "originalAmount": 0.001,
    "maxPriceHeld": 0.0,
    "pegPriceMin": 0.0,
    "stealth": 1.0,
    "orderID": null,
    "maxStealthDisplayAmount": 0.0,
    "sellexchangeRate": 0.0,
    "triggerPrice": 0.0,
    "closeOrder": false,
    "liquidationInProgress": false,
    "marginType": 91,
    "entryPrice": 29286.404761929,
    "liquidationPrice": 0.0,
    "markedPrice": 29267.967916154,
    "unrealizedProfitLoss": -0.13236859,
    "totalMaintenanceMargin": 3.484381756,
    "totalContracts": 14.0,
    "isolatedLeverage": 0.0,
    "totalFees": 0.0,
    "totalValue": 662.115298076,
    "adlScoreBucket": 2.0,
    "orderTypeName": "TYPE_FUTURES_POSITION",
    "orderModeName": "MODE_BUY",
    "marginTypeName": "FUTURES_MARGIN_CROSS",
    "currentLeverage": 0.02,
    "avgFillPrice": 0.0,
    "settleWithNonUSDAsset": "BTC",
    "contractSize": 0.001,
    "takeProfitOrder": {
        "orderId": "4820b20a-e41b-4273-b3ad-4b19920aeeb5",
        "side": "SELL",
        "triggerPrice": 31000.0,
        "triggerUseLastPrice": false
    },
    "stopLossOrder": {
        "orderId": "eff2b232-e2ce-4562-b0b4-0bd3713c11ec",
        "side": "SELL",
        "triggerPrice": 27000.0,
        "triggerUseLastPrice": true
    }
  },{
        "orderID": null,
        "requestId": 0,
        "username": "btse",
        "marketName": "LTC-PERP-USDT",
        "orderType": 90,
        "orderMode": 83,
        "originalAmount": 0.01,
        "maxPriceHeld": 0,
        "pegPriceMin": 0,
        "stealth": 1,
        "maxStealthDisplayAmount": 0,
        "sellexchangeRate": 0,
        "triggerPrice": 0,
        "closeOrder": false,
        "liquidationInProgress": false,
        "marginType": 91,
        "entryPrice": 69.9,
        "liquidationPrice": 29682.415101008,
        "markedPrice": 69.685573595,
        "unrealizedProfitLoss": 0.06432792,
        "totalMaintenanceMargin": 0.318744,
        "totalContracts": 30,
        "isolatedLeverage": 0,
        "totalFees": 0,
        "totalValue": -20.905672079,
        "adlScoreBucket": 2,
        "orderTypeName": "TYPE_FUTURES_POSITION",
        "orderModeName": "MODE_SELL",
        "marginTypeName": "FUTURES_MARGIN_CROSS",
        "currentLeverage": 0.1113820366,
        "averageFillPrice": 0,
        "filledSize": 0,
        "contractSize": 0.001,
        "takeProfitOrder": null,
        "stopLossOrder": null,
        "positionId": "LTC-PERP-USDT|SHORT",
        "positionMode": "HEDGE",
        "positionDirection": "SHORT",
        "settleWithNonUSDAsset": "USDT"
    }
  ]
}

Response (The position has been closed)

{
  "topic": "positionsV2",
  "data": [{
    "requestId": 0,
    "username": "btse",
    "marketName": "BTC-PERP-USDT",
    "orderType": 0,
    "orderMode": 0,
    "originalAmount": 0,
    "maxPriceHeld": 0,
    "pegPriceMin": 0,
    "stealth": 0,
    "orderID": null,
    "maxStealthDisplayAmount": 0,
    "sellexchangeRate": 0,
    "triggerPrice": 0,
    "closeOrder": false,
    "liquidationInProgress": false,
    "marginType": 0,
    "entryPrice": 0,
    "liquidationPrice": 0,
    "markedPrice": 0,
    "unrealizedProfitLoss": 0,
    "totalMaintenanceMargin": 0,
    "totalContracts": 0,
    "isolatedLeverage": 0,
    "totalFees": 0,
    "totalValue": 0,
    "adlScoreBucket": 0,
    "orderTypeName": null,
    "orderModeName": null,
    "marginTypeName": null,
    "currentLeverage": 0,
    "avgFillPrice": 0,
    "settleWithNonUSDAsset": "BTC",
    "contractSize": 0.001,
    "takeProfitOrder": null,
    "stopLossOrder": null,
    "positionId": "BTC-PERP-USDT|SHORT",
    "positionMode": null,
    "positionDirection": null,
  }]
}

All futures positions will be pushed via this topic once the position changes. If the user reduces the position to 0, the topic will push data with the totalContracts value of 0 once.

Response Content

Name Type Required Description
requestId integer Yes request id
username string Yes btse username
marketName string Yes market name
orderType integer Yes 90: Futures Position
orderTypeName string Yes String representation of orderType
orderMode integer Yes 66: BUY
83: SELL
orderModeName string Yes String representation of orderModeName
originalAmount double Yes order amount
maxPriceHeld double Yes max price of all time
pegPriceMin double Yes peg price min
stealth double Yes used for peg order
orderID string Yes order id
maxStealthDisplayAmount double Yes used for peg order
sellexchangeRate double Yes
triggerPrice double Yes OCO order
closeOrder boolean Yes whether it has an order to close this position
liquidationInProgress boolean Yes whether is in liquidation
marginType integer Yes WALLET TYPE:
91: CROSS
92: ISOLDATED
marginTypeName string Yes String representation of marginType
entryPrice double Yes entry price
liquidationPrice double Yes liquidation price
markPrice double Yes mark price
unrealizedProfitLoss double Yes unrealized pnl
totalMaintenanceMargin double Yes maintenance margin
totalContract double Yes size of the contract
isolatedLeverage double Yes
totalFees double Yes
totalValue double Yes
adlScoreBucket double Yes
currentLeverage double Yes
avgFillPrice double Yes
settleWithNonUSDAsset string Yes
takeProfitOrder TakeProfitOrder object No Take profit order info
stopLossOrder StopLossOrder object No Stop loss order info
positionMode string Yes Position mode
ONE_WAY, HEDGE or ISOLATED
positionDirection string Yes Position direction
positionId string Yes Position id
contractSize double Yes The position contract size

json