Changelogs

version	time	content
V0.1.5.3	2022 NOV 2	* Support USD-M blocktrade: `POST /linear/v1/blocktrades` `GET /linear/v1/blocktrades` `GET /linear/v1/platform_blocktrades` `GET /linear/v1/user/info` * Support USD-M mmp control: Support mmp field when placing order `GET /linear/v1/mmp_state` `POST /linear/v1/update_mmp_config` `POST /linear/v1/reset_mmp` * Add USD-M websocket `mmp_frozen` channel
V0.1.5.2	2022 OCT 30	Remove USDT-M contents
V0.1.5.1	2022 SEP 29	Query um account with pair margin info
V0.1.5	2022 JUL 29	USD option changes: * Data is stored in different sharding. so order_id/trade_id/transaction id are not globally unique.(instrument+id is unique, See sharding page) * Support USD option auto_price order * Add `GET /linear/v1/option_pairs` * Paging query `has_more` field is deprecated due to db sharding * `GET /linear/v1/user/settlements`: parameter `currency` changed to `settlement_currency` and remove `category`(only futures have settlements) * Add `GET /linear/v1/user/deliveries` * Add `GET /linear/v1/market/deliveries`
V0.1.4	2022 JUL 18	* `POST /linear/v1/amend_orders`: instrument_id is required `POST /linear/v1/amend_batchorders`: instrument_id is required `POST /linear/v1/cancel_orders`: change format of `order_id_list`; if `order_id` is provided, `instrument_id` is required
V0.1.3	2022 JUL 8	* Support USD futures. * /linear/v1/cancel_orders: for conditional order, `instrument_id` is required. * Add `total_position_pnl` in `GET /um/v1/accounts` and websocket `um_account` channel.
V0.1.2	2022 JUN 2	* Add Kline resolutions(minutes): 360, 720
V0.1.1	2022 APR 22	* Add USD-M/USDT-M conditional order; * `GET /um/v1/accounts` amount fields converted to `USD`, the original `USDT` fields are still there for compatibility; USDC fields are no longer exists.
V0.1.0	2022 MAR 2	* Release
V0.0.1	2022 JAN 27	* Init version

Introduction

Welcome to bit.com API. You can retrieve market data, execute trades and manage your bit.com account through bit.com API.

Authentication

API hosts (production)

REST API base url: https://api.bit.com
WS API base url: wss://ws.bit.com

API hosts (testnet)

REST API base url: https://betaapi.bitexch.dev
WS API base url: wss://betaws.bitexch.dev

API rate limits

USDT futures endpoints are divided into three types of rate limit: public, private (trade) and private (others).It Separate rate limits from Coin-M futures&options and spot endpoints.The public interface implements IP-specified frequency limitation , and the private interface implements user-specified frequency limitation. When a breach happens, a prompt will be returned: “429 too many requests”. About the type of API rate limits, please refer to API summary.

Rest API rate limits:
Public API: 10 requests per second per IP.
Private API(trade): 5 requests per second per user.
Private API(Others): 5 requests second per user.

Sharding

Trading instruments are stored across different database shardings.

Id uniqueness

Since data is stored in different sharding. order_id/trade_id/transaction id are not globally unique

Query pagination

Due to sharding, data is gather from different shard db, offset is not available. We keep limit parameter to indicate return record count.

API summary

User defined string fields(label etc): valid characters are [A-Z], [a-z], [0-9], "-", "_"

Path	Method	Description	Scope	Rate Limit Type	Permission
/linear/v1/orders	POST	Place new order	private	trade	USD-M trade
/linear/v1/cancel_orders	POST	Cancel order	private	trade	USD-M trade
/linear/v1/close_positions	POST	Close positions	private	trade	USD-M trade
/linear/v1/amend_orders	POST	Amend order	private	trade	USD-M trade
/linear/v1/batchorders	POST	Place multiple orders	private	trade	USD-M trade
/linear/v1/amend_batchorders	POST	Amend multiple orders	private	trade	USD-M trade
/linear/v1/update_mmp_config	POST	Update MMP config	private	trade	USD-M trade
/linear/v1/reset_mmp	POST	Reset MMP state	private	trade	USD-M trade
/linear/v1/open_orders	GET	Query open orders	private	others	read
/linear/v1/orders	GET	Query order history	private	others	read
/linear/v1/margins	GET	Query estimated margins	private	others	read
/linear/v1/user/trades	GET	Query user trades	private	others	read
/um/v1/account_mode	GET	Query Account mode	private	others	read
/um/v1/accounts	GET	Query um account information	private	others	read
/um/v1/transactions	GET	Query um transaction logs	private	others	read
/um/v1/interest_records	GET	Query um interest records	private.	others	read
/linear/v1/positions	GET	Query positions	private	others	read
/linear/v1/user/deliveries	GET	Query user deliveries	private	others	read
/linear/v1/user/settlements	GET	Query user settlements	private	others	read
/linear/v1/mmp_state	GET	Query Mmp State	private	others	read
/linear/v1/blocktrades	POST	New block trade	private	futures&options block_trade	block_trade
/linear/v1/blocktrades	GET	Get block trades of current user	private	futures&options block_trade	block_trade
/linear/v1/platform_blocktrades	GET	Get block trades of platform	private	futures&options block_trade	block_trade
/linear/v1/user/info	GET	Get user info with blocktrade permission	private	futures&options block_trade	block_trade
/linear/v1/system/time	GET	Get server time	public	public	/
/linear/v1/system/version	GET	Get system version	public	public	/
/linear/v1/system/cancel_only_status	GET	Get cancel only status	public	public	/
/linear/v1/instruments	GET	Query instruments	public	public	/
/linear/v1/market/summary	GET	Query instrument summary	public	public	/
/linear/v1/tickers	GET	Query instrument ticker	public	public	/
/linear/v1/orderbooks	GET	Query orderbook	public	public	/
/linear/v1/market/trades	GET	Query market trades	public	public	/
/linear/v1/klines	GET	Query kline data	public	public	/
/linear/v1/funding_rate	GET	Get latest perpetual funding rate	public	public	/
/linear/v1/funding_rate_history	GET	Get perpetual funding rate history	public	public	/
/linear/v1/settlement_prices	GET	Get settlement/delivery prices	public	public	/
/linear/v1/total_volumes	GET	Get total volumes for all currencies	public	public	/
/linear/v1/option_pairs	GET	Get pairs with active option	public	public	/
/um/v1/index_price	GET	Query index price	public	public	/
/um/v1/loan_rates	GET	Query loan rate	public	public	/

System

Get server timestamp

GET /linear/v1/system/time

curl "https://betaapi.bitexch.dev/linear/v1/system/time"

{
  "code": 0,
  "message": "",
  "data": 1587884283175
}

Get server timestamp

Query Parameters

None

Response

Name	Type	Description
data	integer	Server timestamp

Get system version

GET /linear/v1/system/version

curl "https://betaapi.bitexch.dev/linear/v1/system/version"

{
  "code": 0,
  "message": "",
  "data": "v1.0"
}

Get API version

Query Parameters

None

Response

Name	Type	Description
data	string	Api server version

Get cancel only status

GET /linear/v1/system/cancel_only_status

curl "https://betaapi.bitexch.dev/linear/v1/system/cancel_only_status"


{
    "code": 0,
    "message": "",
    "data": {
        "status": 0,
        "remain_ms": 0
    }
}

Get cancel-only status after system maintenance.

status
status=1: means cancel-only is in effective.
status=0: means cancel-only period is finished, the system is ready to accept orders.

remain_ms
Remain time (in milliseconds) for the cancel-only period to finish. when status=0, remain_ms is 0.

Query parameters

None

Response

Name	Type	Description
status	integer	Cancel-only status.
remain_ms	integer	Remain time (in milliseconds) for the cancel-only period to finish.

Market

Get index

GET /um/v1/index_price

curl "https://betaapi.bitexch.dev/um/v1/index_price?currency=BTC&quote_currency=USDT"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "index_name": "BTC-USDT",
            "index_price": "50000"
        }
    ]
}

Get index price.

currency: base currency of active spot pairs;

quote_currency: quote currency of active spot pairs;

If currency is empty, return all pair index prices associated with quote_currency.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	false	""	Currency
quote_currency	string	true	""	Quote currency

Response

Name	Type	Description
index_name	string	Index name
index_price	string	Index price

Get instruments

GET /linear/v1/instruments

curl "https://betaapi.bitexch.dev/linear/v1/instruments?currency=USDT"

{
  "code": 0,
  "message": "",
  "data": [
    {
      "instrument_id": "BTC-USDT-PERPETUAL",
      "created_at": 1640944328750,
      "updated_at": 1640944328750,
      "base_currency": "BTC",
      "quote_currency": "USDT",
      "strike_price": "",
      "expiration_at": 4102444800000,
      "option_type": "",
      "category": "future",
      "min_price": "0.00050000",
      "max_price": "1000000.00000000",
      "price_step": "0.01000000",
      "min_size": "0.00010000",
      "size_step": "0.00010000",
      "delivery_fee_rate": "",
      "contract_size": "",
      "contract_size_currency": "BTC",
      "active": true,
      "status": "online",
      "groups": [
        1,
        10,
        100,
        10000
      ],
      "group_steps": [
        "0.01000000",
        "0.10000000",
        "1.00000000",
        "100.00000000"
      ],
      "display_at": 1640944328422,
      "is_display": true
    }
  ]
}

Get instrument list by currency or category

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
category	string	false	"future"	Category, input "option" to query option instruments
active	boolean	false	true	Set true to query active instruments
count	int	false	5000	Max return count, only apply for expiration futures/options contracts, not for perpetual

Response

Name	Type	Description
instrument_id	string	Instrument ID
category	string	Category
created_at	integer	Created timestamp
updated_at	integer	Updated timestamp
expiration_at	integer	Expiration timestamp (for perpetual, is timestamp of 2100-01-01)
base_currency	string	Base currency
quote_currency	string	Quote currency
option_type	string	Call/put, option only
strike_price	string	Strike price, option only
min_price	string	System-wise minimum order price, (order price also restricted to min sell/max buy)
max_price	string	System-wise maximum order price, (order price also restricted to min sell/max buy)
price_step	string	Order price should be multiple of price_step
min_size	string	System-wise minimum order size
size_step	string	Order size should be multiple of size_step
delivery_fee_rate	string	Instrument delivery fee rate,option only
contract_size	string	Contract size of the instrument
contract_size_currency	string	Contract size currency
active	bool	Instrument is allowed to trade or not
status	string	Instrument status
groups	array	orderbook output config
group_steps	array	orderbook output config
display_at	integer	For internal use
is_display	bool	For internal use

Get active option pairs

GET /linear/v1/option_pairs

curl "https://betaapi.bitexch.dev/linear/v1/option_pairs?currency=USD"


{
    "code": 0,
    "message": "",
    "data": [
        "BTC-USD",
        "ETH-USD"
    ]
}

Get pairs with active option instruments.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency

Response

Name	Type	Description
data	array	pair list

Get tickers

GET /linear/v1/tickers

curl "https://betaapi.bitexch.dev/linear/v1/tickers?instrument_id=BTC-USDT-PERPETUAL"


{
  "code": 0,
  "message": "",
  "data": {
    "time": 1642994479231,
    "instrument_id": "BTC-USDT-PERPETUAL",
    "best_bid": "35310.40000000",
    "best_ask": "35311.15000000",
    "best_bid_qty": "4.46000000",
    "best_ask_qty": "3.10000000",
    "ask_sigma": "",
    "bid_sigma": "",
    "last_price": "35310.00000000",
    "last_qty": "5.85000000",
    "open24h": "35064.40000000",
    "high24h": "36480.60000000",
    "low24h": "34688.50000000",
    "price_change24h": "0.00700426",
    "volume24h": "2329.37000000",
    "volume_usd24h": "82236990.06700000",
    "open_interest": "94.21840000",
    "funding_rate": "0.00000000",
    "funding_rate8h": "0.00017589",
    "underlying_price": "0.00000000",
    "mark_price": "35310.69417074",
    "index_price": "35313.68900000",
    "min_sell": "34781.03000000",
    "max_buy": "35840.36000000"
  }
}

Get ticker information by instrument

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID

Response

Name	Type	Description
instrument_id	string	Instrument ID
last_price	string	Most recent traded price
last_qty	string	Most recent traded volume
open24h	string	Open price during previous 24 hour
high24h	string	Highest price during previous 24 hour
low24h	string	Lowest price during previous 24 hour
volume24h	string	Sum volume(Base ccy) during previous 24 hour
volume_usd24h	string	Sum volume(USD) during previous 24 hour
price_change24h	string	Price change% during previous 24 hour
open_interest	string	Open interest
best_bid	string	Best bid price
best_ask	string	Best ask price
best_bid_qty	string	Best bid quantity
best_ask_qty	string	Best ask quantity
bid_sigma	string	Top of book bid implied vol, option only
ask_sigma	string	Top of book ask implied vol, option only
underlying_name	string	Underlying index name, option only
underlying_price	string	Underlying price, option only
funding_rate	string	Funding rate, perpetual only
funding_rate8h	string	Past 8H avg funding rate, perpetual only
mark_price	string	Mark price
index_price	string	Index price
sigma	string	Mark price implied vol, option only
delta	string	Mark price delta, option only
vega	string	Mark price vega, option only
theta	string	Mark price theta, option only
gamma	string	Mark price gamma, option only
max_buy	string	Maximum price of buy order
min_sell	string	Minimum price of sell order

Get orderbooks

GET /linear/v1/orderbooks

curl "https://betaapi.bitexch.dev/linear/v1/orderbooks?instrument_id=BTC-USDT-PERPETUAL"

{
  "code": 0,
  "message": "",
  "data": {
    "instrument_id": "BTC-USDT-PERPETUAL",
    "timestamp": 1642994567453,
    "bids": [
      ["35324.15000000","0.47000000"],
      ["35324.10000000","1.67000000"],
      ["35321.95000000","2.40000000"],
      ["35321.90000000","4.36000000"],
      ["35321.85000000","1.24000000"]
    ],
    "asks": [
      ["35325.15000000","4.68000000"],
      ["35327.80000000","0.53000000"],
      ["35351.00000000","1.00000000"],
      ["35352.00000000","1.00000000"],
      ["35353.00000000","1.00000000"]
    ]
  }
}

Get orderbook by instrument

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
level	int	false	5	No. of depth, value range [1,50]

Response

Name	Type	Description
instrument_id	string	Instrument ID
timestamp	integer	Timestamp (data time)
asks	string	Asks array [price, qty]
bids	string	Bids array [price, qty]

Get market trades

GET /linear/v1/market/trades

curl "https://betaapi.bitexch.dev/linear/v1/market/trades?currency=USDT"

{
  "code": 0,
  "message": "",
  "data": [
    {
      "created_at": 1642994704633,
      "trade_id": 1005483402,
      "instrument_id": "ETH-USDT-PERPETUAL",
      "price": "2449.20000000",
      "qty": "1.00000000",
      "side": "sell",
      "sigma": "0.00000000",
      "index_price": "2447.79750000",
      "underlying_price": "0.00000000",
      "is_block_trade": false
    },
    {
      "created_at": 1642994704241,
      "trade_id": 1005483400,
      "instrument_id": "ETH-USDT-PERPETUAL",
      "price": "2449.20000000",
      "qty": "1.00000000",
      "side": "sell",
      "sigma": "0.00000000",
      "index_price": "2447.79750000",
      "underlying_price": "0.00000000",
      "is_block_trade": false
    }
  ]
}

Get market trades by currency, category, option_type, instrument_id

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	true	""	Pair
category	string	false	""	Category
option_type	string	false	""	Option type
instrument_id	string	false	""	Instrument ID
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
limit	int	false	100	Return record count

Response

Name	Type	Description
trade_id	integer	Trade ID
instrument_id	string	Instrument ID
created_at	integer	Creation timestamp of the trade
price	string	Price
qty	string	Quantity
side	string	Order side
index_price	string	Index price
sigma	string	Implied volatility (option only)
underlying_price	string	Underlying price (option only)
is_block_trade	bool	Is block trade or not

Get klines

GET /linear/v1/klines

curl "https://betaapi.bitexch.dev/linear/v1/klines?instrument_id=BTC-USDT-PERPETUAL&timeframe_min=1d"

{
  "code": 0,
  "message": "",
  "data": {
    "volume": [
      61311.6006,
      162957.1496,
      170906.31,
      167930.3642,
      57211.0637,
      95668.4807,
      129106.4048,
      87194.38,
      108983.3256,
      47231.55,
      2616.79
    ],
    "timestamps": [
      1642118400000,
      1642204800000,
      1642291200000,
      1642377600000,
      1642464000000,
      1642550400000,
      1642636800000,
      1642723200000,
      1642809600000,
      1642896000000,
      1642982400000
    ],
    "open": [
      42440,
      43069.2,
      43084.9,
      43074.6,
      42208.6,
      41637.7,
      41673.7,
      40705.05,
      36476.35,
      35068,
      36257.45
    ],
    "low": [
      42440,
      42588.3,
      42606.7,
      41557.9,
      41482.2,
      41000,
      40587,
      35556.25,
      34000.45,
      34688.5,
      35194.6
    ],
    "high": [
      43426.5,
      43773.4,
      43451.3,
      43170.9,
      42413.5,
      42538.2,
      43486.65,
      41093.2,
      36797.7,
      36480.6,
      36255.1
    ],
    "close": [
      43069.2,
      43084.9,
      43074.6,
      42208.6,
      41637.7,
      41673.7,
      40705.05,
      36476.35,
      35068,
      36257.45,
      35216.55
    ]
  }
}

Get klines by instrument. klines endpoint returns 6 time series of data: open price array, high price array, low price array, close price array, timestamp array of each kline, and volume array.

Support timeframes:

Timeframe	Name Desc
1	1 minute
3	3 minute
5	5 minute
15	15 minute
30	30 minute
60	60 minute
240	240 minute
1d	daily
1w	weekly
1m	monthly

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument Id
start_time	integer	true		Start timestamp millisecond
end_time	integer	true		End timestamp millisecond
timeframe_min	string	true	""	Timeframe
count	int	false	100	Result count (default 100, max 1000)

Response

Name	Type	Description
open	float array	Open price series
high	float array	High price series
low	float array	Low price series
close	float array	Close price series
timestamps	float array	Timestamp series
volume	float array	Volume series

Get market deliveries

GET /linear/v1/market/deliveries

curl "https://betaapi.bitexch.dev/linear/v1/market/deliveries?currency=USD"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-110-C",
            "position": "1.00000000",
            "exercise": true,
            "delivery_price": "115.63000000",
            "delivery_pnl": "5.63000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-110-P",
            "position": "1.00000000",
            "exercise": false,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.00000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-115-C",
            "position": "1.00000000",
            "exercise": true,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.63000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-115-P",
            "position": "1.00000000",
            "exercise": false,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.00000000"
        }
    ]
}

Get market delivery position information(delivered positions/pnl, exercise or not).

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID
limit	int	false	100	Return record count

Response

Name	Type	Description
type	string	delivery type("delivery")
timestamp	integer	Delivery time.
instrument_id	string	Instrument Id
position	string	Total delivered position of all long side users.
exercise	bool	Exercise or not
delivery_price	string	Delivery price
delivery_pnl	string	Delivery pnl of all long side users.

Get market settlement price info

GET /linear/v1/settlement_prices

curl "https://betaapi.bitexch.dev/linear/v1/settlement_prices?currency=USDT&start_time=1600421456435&end_time=1603013456435"


{
  "code": 0,
  "message": "",
  "data": {
    "data": {
      "1642204800000": [
        {
          "date": 1642204800000,
          "currency": "USDT",
          "instrument_id": "BCH-USDT-PERPETUAL",
          "settlement_type": "settlement",
          "price": "389.66802679"
        },
        {
          "date": 1642204800000,
          "currency": "USDT",
          "instrument_id": "BTC-USDT-PERPETUAL",
          "settlement_type": "settlement",
          "price": "43076.50631543"
        },
        {
          "date": 1642204800000,
          "currency": "USDT",
          "instrument_id": "ETH-USDT-PERPETUAL",
          "settlement_type": "settlement",
          "price": "3313.20469611"
        }
      ]
    }
  }
}

Get settlement/delivery price history.
Time range filter is within 30 days.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
instrument_id	string	false	""	Instrument ID
start_time	integer	true		Start timestamp
end_time	integer	true		End timestamp

Response

Dictionary key is date in milliseconds, value is delivery/settlement record list

Name	Type	Description
date	integer	Delivery/settlement date in ms
currency	string	Currency
instrument_id	string	Instrument Id
settlement_type	string	`delivery` or `settlement`
price	string	Delivery/settlement price

Get market summary

GET /linear/v1/market/summary

curl "https://betaapi.bitexch.dev/linear/v1/market/summary?currency=USD&category=future"


{
  "code": 0,
  "message": "",
  "data": [
    {
      "instrument_id": "BTC-USD-PERPETUAL",
      "timestamp": 1642995368000,
      "best_bid": "35273.15000000",
      "best_ask": "35274.20000000",
      "best_bid_qty": "6.36000000",
      "best_ask_qty": "3.54000000",
      "last_price": "35274.20000000",
      "last_qty": "2.01000000",
      "open24h": "35064.40000000",
      "high24h": "36480.60000000",
      "low24h": "34688.50000000",
      "volume24h": "35162.74000000",
      "open_interest": "94.21840000",
      "mark_price": "35276.43209068",
      "max_buy": "35805.58000000",
      "min_sell": "34747.28000000",
      "delta": "",
      "gamma": "",
      "vega": "",
      "theta": ""
    }
  ]
}

Get market summary by instrument

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
category	string	true	""	Category
instrument_id	string	false	""	Instrument ID

Response

Name	Type	Description
instrument_id	string	Instrument ID
timestamp	integer	Timestamp
best_bid	string	Best bid price
best_ask	string	Best ask price
best_bid_qty	string	Best bid quantity
best_ask_qty	string	Best ask quantity
last_price	string	Last price
last_qty	string	Last quantity
open24h	string	Open price during previous 24 hour
high24h	string	Highest price during previous 24 hour
low24h	string	Lowest price during previous 24 hour
volume24h	string	Sum volume during previous 24 hour
open_interest	string	Open interest of current instrument_id
mark_price	string	Mark price
max_buy	string	Max price of buy order
min_sell	string	Min price of sell order
delta	string	Option delta
gamma	string	Option gamma
vega	string	Option vega
theta	string	Option theta

Get funding rate

GET /linear/v1/funding_rate

curl "https://betaapi.bitexch.dev/linear/v1/funding_rate?instrument_id=BTC-USDT-PERPETUAL"


{
  "code": 0,
  "message": "",
  "data": {
    "instrument_id": "BTC-USDT-PERPETUAL",
    "time": 1635913370000,
    "funding_rate": "0.00000000",
    "funding_rate_8h": "-0.00102858",
    "index_price": "62989.63000000",
    "mark_price": "62969.83608581"
  }
}

Get latest perpetual funding rate. Funding rate will be refreshed in every 10 seconds.

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID (perpetual only)

Response

Name	Type	Description
instrument_id	string	Instrument ID
time	integer	Timestamp
funding_rate	string	Current perpetual funding rate
funding_rate_8h	string	Past 8H avg funding rate, perpetual only
index_price	string	Index price
mark_price	string	Perpetual Mark price

Get funding rate history

GET /linear/v1/funding_rate_history

curl "https://betaapi.bitexch.dev/linear/v1/funding_rate_history?instrument_id=BTC-USDT-PERPETUAL&start_time=1603260000000&end_time=1603346400000&history_type=1H"


{
    "code": 0,
    "message": "",
    "data": [
        {
            "instrument_id": "BTC-USDT-PERPETUAL",
            "time": 1603263600000,
            "average_funding_rate": "0.00100000",
            "index_price": "8880.17000000",
            "mark_price": "8900.18000000"
        }
    ]
}

Note: Start time must be greater than 2020.10.31 (timestamp: 1604102400000).

Get the funding rate history within a given time period. History type can be 1H/8H/24H.

Returns average funding rate of the past 1 hour at each 3 minutes in the period, or returns average funding rate of the past 8 hours/24 hours at each hour in the period.

For 1H, the query time period cannot exceed 1 days, and for 8H/24H, the query time period cannot exceed 30 days.

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID (perpetual only)
start_time	integer	true		Start timestamp
end_time	integer	true		End timestamp
history_type	string	true		1H/8H/24H

Response

Name	Type	Description
instrument_id	string	Instrument ID
time	integer	Timestamp
average_funding_rate	string	The past 1H/8H/24H average history funding rate for this time
index_price	string	Index price
mark_price	string	Perpetual Mark price

Get all market volume

GET /linear/v1/total_volumes

curl "https://betaapi.bitexch.dev/linear/v1/total_volumes"

{
  "code": 0,
  "message": "",
  "data": {
    "total_usdx_volume_24_hours": "11771592083.60040000",
    "details": [
      {
        "margin_currency": "USD",
        "usdx_option_volume_in_usd": "10000055.21000000",
        "usdx_future_volume_in_usd": "10604770109.18810000"
      },
      {
        "margin_currency": "USDT",
        "usdx_option_volume_in_usd": "0.00000000",
        "usdx_future_volume_in_usd": "1156821919.20230000"
      }
    ]
  }
}

Get all market volumes of previous 24 hours.
This endpoint will be cached with 5 seconds, client request multiple times within sort period of time will get unchanged result.

Query parameters

None

Response

Name	Type	Description
total_usdx_volume_24_hours	string	Total USD-M volume
details	array	Volume details

details

Name	Type	Description
margin_currency	string	Margin Currency
usdx_option_volume_in_usd	string	Option Volume in USD
usdx_future_volume_in_usd	string	Future Volume in USD

Account

Get UM user accounts

GET /um/v1/accounts


curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/um/v1/accounts?timestamp=1589521383462&signature=30f7cf5c8018f5dfee515533e25a1813e9120be7898b62fb85a2f4129f3e9528"


{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 481554,
        "created_at": 1649923879505,
        "total_collateral": "3170125.05978108",
        "total_margin_balance": "3170125.05978108",
        "total_available": "3169721.64891398",
        "total_initial_margin": "403.41086710",
        "total_maintenance_margin": "303.16627631",
        "total_initial_margin_ratio": "0.00012725",
        "total_maintenance_margin_ratio": "0.00009563",
        "total_liability": "0.00000000",
        "total_unsettled_amount": "-0.84400340",
        "spot_orders_hc_loss": "0.00000000",
        "total_position_pnl": "1225.53245820",
        "details": [
            {
                "currency": "BTC",
                "equity": "78.13359310",
                "liability": "0.00000000",
                "index_price": "41311.20615385",
                "cash_balance": "78.13360190",
                "margin_balance": "78.13359310",
                "available_balance": "78.12382795",
                "initial_margin": "0.00976516",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00733859",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.02966586",
                "total_delta": "0.48532539",
                "session_rpl": "0.00001552",
                "session_upl": "-0.00003595",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.02966586",
                "future_session_rpl": "0.00001552",
                "future_session_upl": "-0.00003595",
                "future_session_funding": "0.00001552",
                "future_delta": "0.48532539",
                "future_available_balance": "76.72788921",
                "option_available_balance": "76.72788921",
                "unsettled_amount": "-0.00002043",
                "usdt_index_price": "41311.20615385"
            },
            {
                "currency": "ETH",
                "equity": "1.99960000",
                "liability": "0.00000000",
                "index_price": "3119.01923077",
                "cash_balance": "1.99960000",
                "margin_balance": "1.99960000",
                "available_balance": "1.99960000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.00000000",
                "total_delta": "0.00000000",
                "session_rpl": "0.00000000",
                "session_upl": "0.00000000",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.00000000",
                "future_session_rpl": "0.00000000",
                "future_session_upl": "0.00000000",
                "future_session_funding": "0.00000000",
                "future_delta": "0.00000000",
                "future_available_balance": "1.99960000",
                "option_available_balance": "1.99960000",
                "unsettled_amount": "0.00000000",
                "usdt_index_price": "3119.01923077"
            }
        ],
        "usdt_total_collateral": "3170125.05978108",
        "usdt_total_margin_balance": "3170125.05978108",
        "usdt_total_available": "3169721.64891398",
        "usdt_total_initial_margin": "403.41086710",
        "usdt_total_maintenance_margin": "303.16627631",
        "usdt_total_initial_margin_ratio": "0.00012725",
        "usdt_total_maintenance_margin_ratio": "0.00009563",
        "usdt_total_liability": "0.00000000",
        "usdt_total_unsettled_amount": "-0.84400340"
    }
}

USD-M products can only be traded by UM mode users.
um mode,get account information with this endpoint.

total_initial_margin_ratio

PM	total_initial_margin_ratio calculation formula
true	(total_im + spot_haircut_loss) / collateral
false	(total_im + spot_haircut_loss) / margin_balance

In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation

total_maintenance_margin_ratio

PM	total_maintenance_margin_ratio calculation formula
true	total_maintenance_margin / collateral
false	total_maintenance_margin / margin_balance

In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation

Query parameters

Parameter	Type	Required	Default	Description
with_linear_pair_margins	string	false	""	Return margins grouped by linear pairs in field `linear_pair_margins`. only for Portfolio Margin mode.

Response

Name	Type	Desc
user_id	int	User Id
created_at	int	Timestamp (query time)
total_collateral	string	Total Collateral (USD)
total_margin_balance	string	Total Margin Balance (USD)
total_available	string	Total Available (USD)
total_initial_margin	string	Total Initial Margin (USD)
total_maintenance_margin	string	Total Maintenance Margin (USD)
total_initial_margin_ratio	string	Total Initial Margin Ratio, may returns "infinity" (USD)
total_maintenance_margin_ratio	string	Total Maintenance Margin Ratio, may returns "infinity" (USD)
total_liability	string	Total liability (USD)
total_unsettled_amount	string	Total unsettled amount (USD)
spot_orders_hc_loss	string	Total spot order haircut loss
total_position_pnl	string	Total position PnL in USD [SUM(ccy.pnl * ccy.index-price)]
details	array	Details, array of currency level detail
usdt_total_collateral	string	(For compatibility) equal to total_collateral
usdt_total_margin_balance	string	(For compatibility) equal to total_margin_balance
usdt_total_available	string	(For compatibility) equal to total_available
usdt_total_initial_margin	string	(For compatibility) equal to total_initial_margin
usdt_total_maintenance_margin	string	(For compatibility) equal to total_maintenance_margin
usdt_total_initial_margin_ratio	string	(For compatibility) equal to total_initial_margin_ratio
usdt_total_maintenance_margin_ratio	string	(For compatibility) equal to total_maintenance_margin_ratio
usdt_total_liability	string	(For compatibility) equal to total_liability
usdt_total_unsettled_amount	string	(For compatibility) equal to total_unsettled_amount

Currency level detail

Name	Type	Desc
currency	string	Currency
equity	string	Equity
liability	string	Liability
index_price	string	Index price (USD)
usdt_index_price	string	(For compatibility) equal to index_price
cash_balance	string	Cash Balance
margin_balance	string	Margin Balance
available_balance	string	Account Available Balance
initial_margin	string	Initial Margin
spot_margin	string	Spot Margin
maintenance_margin	string	Maintenance Margin
potential_liability	string	Potential Liability
interest	string	Interest
interest_rate	string	Interest Rate
pnl	string	Currency level position P&L
total_delta	string	Total delta of account
session_rpl	string	Session realized pnl
session_upl	string	Session unrealized pnl
option_value	string	Option market value
option_pnl	string	Option P&L
option_session_rpl	string	Option session realized P&L
option_session_upl	string	Option session unrealized P&L
option_delta	string	Option delta
option_gamma	string	Option gamma
option_vega	string	Option vega
option_theta	string	Option theta
future_pnl	string	Future P&L
future_session_rpl	string	Future session realized P&L
future_session_upl	string	Future session unrealized P&L
future_session_funding	string	Future session funding
future_delta	string	Future delta
future_available_balance	string	Available balance for new futures order
option_available_balance	string	Available balance for new option order
unsettled_amount	string	Unsettled amount

Linear pair margins

returns an array in field linear_pair_margins, when add query param with_linear_pair_margins=true. only for Portfolio Margin mode.

Name	Type	Desc
pair	string	linear pair
initial_margin	string	Initial Margin for pair
maintenance_margin	string	Maintenance Margin for pair

Get UM user transactions

GET /um/v1/transactions

curl -H "X-Bit-Access-Key: ak-8e97ac6c-8075-4a94-b2bb-38bd537619fa" "https://betaapi.bitexch.dev/um/v1/transactions?currency=BTC&type=trade-recv&limit=2&timestamp=1620369292928&signature=35d76033f6e251ce85524ec4310417fd555953fff00cd33f3a94e3d27d062965"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "tx_time": 1631240595162,
            "tx_type": "deposit",
            "ccy": "BTC",
            "instrument_id": "",
            "direction": "",
            "qty": "3.20000000",
            "price": "",
            "position": "",
            "fee_paid": "0.00000000",
            "fee_rate": "",
            "funding": "",
            "change": "3.20000000",
            "balance": "107.00000000",
            "order_id": "",
            "trade_id": "",
            "remark": ""
        },
        {
            "tx_time": 1630722195162,
            "tx_type": "spot-trade-recv",
            "ccy": "BTC",
            "instrument_id": "BTC-USDT",
            "direction": "buy",
            "qty": "2.00000000",
            "price": "60000.00000000",
            "position": "",
            "fee_paid": "0.00030000",
            "fee_rate": "0.00000000",
            "funding": "",
            "change": "2.00000000",
            "balance": "102.00000000",
            "order_id": "9001",
            "trade_id": "3001",
            "remark": ""
        }
    ],
    "page_info": {
        "has_more": false
    }
}

USD-M products can only be traded by UM mode users.
UM mode,user gets transaction logs with this endpoint.

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	false	""	Currency
instrument_id	string	false	""	Instrument ID
start_time	integer	false	One month ago	Start timestamp millisecond
end_time	integer	false	Now	End timestamp millisecond
type	string	false	""	UM Transaction type
offset	int	false	1	Page index, first page = 1
limit	int	false	100	Page size

Response

Name	Type	Desc
tx_time	integer	Transaction time
tx_type	string	UM Transaction type
ccy	string	Currency
instrument_id	string	Instrument Id
direction	string	buy/sell
qty	string	Qty
price	string	Trade price (for trade transactions)
position	string	Futures/Options position
fee_paid	string	Fee paid
fee_rate	string	Fee rate
funding	string	Perpetual funding
change	string	Change
cash_flow	string	Cashflow(spot cash_flow=change, derivatives cash_flow please refer to derivatives doc for transactions)
balance	string	Balance after change
order_id	string	Order ID
trade_id	string	Trade ID
remark	string	Remark

Get interest records

GET /um/v1/interest_records


curl -H "X-Bit-Access-Key: ak-8e97ac6c-8075-4a94-b2bb-38bd537619fa" "https://betaapi.bitexch.dev/um/v1/interest_records?currency=BTC&timestamp=1631669478618&signature=3d4685f07751cd51f42ee631938f189cbe6e9712cc6d559881e5b3b6d1ba1224"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "currency": "BTC",
            "time": 1631559600000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.05000000"
        },
        {
            "currency": "BTC",
            "time": 1631556000000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.06000000"
        },
        {
            "currency": "BTC",
            "time": 1631552400000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.07000000"
        }
    ],
    "page_info": {
        "has_more": true
    }
}

Get UM interest records.

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Currency
start_time	integer	false	One month ago	Start timestamp millisecond
end_time	integer	false	Now	End timestamp millisecond
offset	int	false	1	Page index, first page = 1
limit	int	false	100	Page size

Response

Name	Type	Desc
currency	string	Currency
time	integer	Interest accrual time
loan_rate	string	Annual interest rate
liability	string	liability
interest	string	Accrued interest

Get user positions

GET /linear/v1/positions

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/positions?currency=USDT&instrument_id=BTC-USDT-PERPETUAL&timestamp=1589521619990&signature=9a7f7704cb4d6ec3cd2dccbd55e09ce8abd1ffb48529a742337706dd1a43eea8"

{
    "code": 0,
    "message": "",
    "data": [{
        "instrument_id": "BTC-USDT-PERPETUAL",
        "qty": "-2.00000000",
        "initial_margin": "0.00000000",
        "maintenance_margin": "0.00000000",
        "avg_price": "50000.00000000",
        "session_avg_price": "50000.00000000",
        "mark_price": "50001.00000000",
        "index_price": "50000.00000000",
        "session_funding": "0.00000000",
        "position_pnl": "30.08376782",
        "position_session_upl": "28.08376782",
        "position_session_rpl": "0.00000000",
        "category": "future",
        "roi": "0.00000000",
        "option_delta": "0.00000000",
        "option_gamma": "0.00000000",
        "option_vega": "0.00000000",
        "option_theta": "0.00000000",
        "liq_price": "",
        "leverage:": "50.00000000",
    }]
}

Get user positions. qty and qty_base has direction information, positive value means long, negative value means short.

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID

Response

Name	Type	Desc
instrument_id	string	Instrument ID
qty	string	Signed position size in COIN (base currency)
qty_base	string	Signed position size in COIN (base currency)
avg_price	string	Average filled price
index_price	string	Index price
mark_price	string	Mark price
initial_margin	string	Initial margin
maintenance_margin	string	Maintenance margin
session_avg_price	string	Session average price
session_funding	string	Session funding
position_pnl	string	Position P&L
position_session_upl	string	Position session unrealized P&L
position_session_rpl	string	Position session realized P&L
category	string	Category
roi	string	Return on investment
option_delta	string	Option delta
option_gamma	string	Option gamma
option_vega	string	Option vega
option_theta	string	Option theta
leverage	string	Position leverage

Get user deliveries

GET /linear/v1/user/deliveries

curl -H "X-Bit-Access-Key: ak-8628663d-678c-49b0-8d4e-a8691152a2d0" "https://betaapi.bitexch.dev/linear/v1/user/deliveries?currency=USD&pair=BTC-USD&timestamp=1659186383799&signature=cc17d4d9f67aabb254ba58085ea6bf498122d88cdf0f991e983674c1bb3a1e2b"

{
    "code": 0,
    "message": "",
    "data": [{
        "type": "delivery",
        "timestamp": 1588492890000,
        "instrument_id": "BTC-30JUL22-23000-C",
        "position": "1.00000000",
        "exercise": true,
        "delivery_price": "23950.37000000",
        "delivery_pnl": "170.60000680"
    }]
}

Get user delivery records

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
instrument_id	string	false	""	Instrument ID
start_time	integer	false	0	Start timestamp
end_time	integer	false	0	End timestamp
count	int	false	100	Record count (default 100, max 500)

Response

Name	Type	Desc
type	string	Settlement type (delivery)
instrument_id	string	Instrument ID
position	string	Settled position
timestamp	integer	Delivery timestamp
exercise	boolean	Exercised or not
delivery_price	string	Delivery price
delivery_pnl	string	Delivery P&L

Get user settlements

GET /linear/v1/user/settlements


curl -H "X-Bit-Access-Key: ak-c1d4bc58-37f3-49da-93b5-396ab44b1543" "https://betaapi.bitexch.dev/linear/v1/user/settlements?currency=BTC&offset=1&limit=10&timestamp=1590851451072&signature=538b4ed2b917db4c96e12ddb5daafe84b58f566173f4d003533c19ccc32ff177"

{
    "code": 0,
    "message": "",
    "data": [{
        "type": "settlement",
        "timestamp": 1590825600000,
        "instrument_id": "BTC-USDT-PERPETUAL",
        "position": "-28.00000000",
        "direction": "short",
        "session_upl": "-1000.02754390",
        "session_rpl": "1343.00125935",
        "session_funding": "-973.00028997",
        "price": "32000"
    }]
}

Get user settlements (only for future currently)

Query Parameters

Parameter	Type	Required	Default	Description
settlement_currency	string	true	""	Settlement Currency
instrument_id	string	false	""	Instrument ID
start_time	integer	false	0	Start timestamp
end_time	integer	false	0	End timestamp
offset	int	false	1	Page index, first page = 1
limit	int	false	100	Page size

Response

Name	Type	Desc
type	string	Settlement type (settlement)
timestamp	integer	Timestamp
instrument_id	string	Instrument
position	string	settled Position
direction	string	Position direction
session_upl	string	Session unrealized pnl
session_rpl	string	Session realized pnl
session_funding	string	Future session funding
price	string	Settlement price

Get Mmp State

GET /linear/v1/mmp_state

curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/linear/v1/mmp_state?timestamp=1600050649936&signature=3a3c511ab776674c4a8db31135f22c8bf2bc5aac4eb0070c8c4d577e89e01643"

{
    "code": 0,
    "message": "",
    "data": {
        "mmp_enabled": true,
        "mmp_user_configurable": true,
        "mmp_data": [
            {
                "pair": "BTC-USD",
                "mmp_config": {
                    "window_ms": 2000,
                    "frozen_period_ms": 10000,
                    "qty_limit": "30.00000000",
                    "delta_limit": "10.00000000"
                },
                "mmp_state": {
                    "mmp_frozen_until_ms": -1,
                    "mmp_frozen": false
                }
            },
            {
                "pair": "ETH-USD",
                "mmp_config": {
                    "window_ms": 5000,
                    "frozen_period_ms": 100,
                    "qty_limit": "100.00000000",
                    "delta_limit": "100.00000000"
                },
                "mmp_state": {
                    "mmp_frozen_until_ms": -1,
                    "mmp_frozen": false
                }
            },
            {
                "pair": "BCH-USD",
                "mmp_config": {
                    "window_ms": 5000,
                    "frozen_period_ms": 100,
                    "qty_limit": "100.00000000",
                    "delta_limit": "100.00000000"
                },
                "mmp_state": {
                    "mmp_frozen_until_ms": -1,
                    "mmp_frozen": false
                }
            },
        ]
    }
}

Get Mmp State.

mmp_enabled
Mmp is enabled or not.

mmp_user_configurable
User can edit mmp config or not. if yes, user can change mmp config through POST /linear/v1/update_mmp_config

mmp_data
Mmp configuration & status detail for each currency pair

mmp_frozen_until_ms
mmp_frozen_until_ms indicate mmp frozen status, it's updated by backend.
mmp_frozen_until_ms > 0: frozen until this timestamp or a manual reset
mmp_frozen_until_ms = 0: frozen until a manual reset
mmp_frozen_until_ms = -1: not frozen (a manual reset sets mmp_frozen_until_ms to -1)

mmp_frozen
Indicate mmp is frozen or not.

Query parameters

None

Response

Name	Type	Desc
mmp_enabled	bool	Mmp is enabled or not
mmp_user_configurable	bool	User can edit mmp config or not
mmp_data	array	Array of mmp data (pair name, config & status detail, see below)

mmp_config

Name	Type	Desc
window_ms	integer	Mmp rolling windows time span (milliseconds)
frozen_period_ms	integer	Mmp frozen time span (milliseconds)
qty_limit	string	Mmp quantity limit (in base currency, e.g. BTC)
delta_limit	string	Mmp delta limit (in base currency, e.g. BTC)

mmp_state

Name	Type	Desc
mmp_frozen_until_ms	integer	Mmp frozen until timestamp (backend update automatically)
mmp_frozen	bool	Mmp is frozen or not

Update Mmp Config

POST /linear/v1/update_mmp_config

curl -X POST "https://betaapi.bitexch.dev/linear/v1/update_mmp_config" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"pair": "BTC-USD", "window_ms": 20000, "frozen_period_ms": 30000, "qty_limit": "1000.00000000", "delta_limit": "1000.00000000", "timestamp": 1600050944127, "signature": "661b535fa878633718922fd90b419de4b5d9ae447833876b91bc8bcc7906e0f3"}'

{
    "code": 0,
    "message": "",
    "data": "ok"
}

Update mmp config, only when mmp.user_configurable = true, otherwise returns error.

Mmp frozen state will be triggered when qty >= qty_limit OR abs(delta) >= delta_limit.

window_ms: Mmp rolling windows time span (milliseconds)
frozen_period_ms: Mmp frozen time span (milliseconds)
qty_limit: Mmp quantity limit (in base currency, e.g. BTC)
delta_limit: Mmp delta limit (in base currency, e.g. BTC)

Post json body

Parameter	Type	Required	Default	Description
pair	string	true	""	Currency pair
window_ms	integer	true	0	Mmp rolling windows time span (milliseconds)
frozen_period_ms	integer	true	0	Mmp frozen time span (milliseconds)
qty_limit	string	true	""	Mmp quantity limit (in base currency, e.g. BTC)
delta_limit	string	true	""	Mmp delta limit (in base currency, e.g. BTC)

Response

Name	Type	Desc
data	string	ok

Reset Mmp State

POST /linear/v1/reset_mmp

curl -X POST "https://betaapi.bitexch.dev/linear/v1/reset_mmp" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"pair": "BTC-USD", "timestamp": 1600050689085, "signature": "992507afc30728c2bc55d7bf7f47e76126ce3f40ddebc205594877381c4374fa"}'

{
    "code": 0,
    "message": "",
    "data": "ok"
}

Reset mmp frozen state, then user is able to place new order.

Post json body

Parameter	Type	Required	Default	Description
pair	string	true	""	Currency pair

Response

Name	Type	Desc
data	string	ok

Order

Place new order

POST /linear/v1/orders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id": "BTC-USDT-PERPETUAL", "price": "5000", "qty": "3", "side": "buy", "time_in_force": "gtc", "auto_price": "", "label":"hedge", "hidden": false, "timestamp": 1589523989378, "signature": "68b658eb68f4ce529623bb4505f5c1c6408b37064a9a5f2102d08088e59d917c"}'

{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "17552314",
        "created_at": 1589523803017,
        "updated_at": 1589523803017,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "50000.00000000",
        "qty": "3.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "open",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label":"hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp":false,
        "source": "api",
        "hidden": false
    }
}

Place new order.
For market order, price is not required.
Order type default value is 'limit'.
Time in force default value is 'gtc'.
Order qty unit is coin/base-currency (e.g. BTC)

Conditional order:
* Order type should be trigger-market/trigger-limit.
* stop_price is the target trigger price. price is the order price after triggered
* Support triggered by last-price now.

Auto price type:
base: When place order, set [auto price type] = "base", and [auto price] = base ccy price, order price will be automatically calculated as order_price(usd) = auto_price * underlying_price, and order will be automatically re-quoted every 6s to maintain the usd price

iv: When place order, set [auto price type] = "iv", and [auto price] = implied volatility value, order price will be automatically calculated as order_price = convert_iv_to_usd(auto_price), , and order will be automatically re-quoted every 6s to maintain the implied volatility. Example: input 85.56 for 85.56% implied volatility

bbo order:When bbo is true, auto set limit price (ask0 for buy order, bid0 for sell order), if orderbook is not available, set limit price to mark price. (Batch order not supported)

Post json body

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
qty	string	true	""	Order size (positive number)
side	string	true	""	Order side
price	string	false	"0.0"	Order price, not required for market order
order_type	string	false	"limit"	Order type
time_in_force	string	false	"gtc"	Time in force
auto_price_type	string	false	""	Usdx Auto price type
auto_price	string	false	""	Auto price, only if auto price type in ('usd','implv') *implv is in percentage, ie. input 85.56 for 85.56%
stop_price	string	false	""	Stop price(or conditional order target price)
label	string	false	""	User defined label
post_only	bool	false	false	Indicate post only or not. if `reject_post_only` is true, order can not enter book will be cancelled. if `reject_post_only` is false, price will be changed when order can't enter orderbook.
reject_post_only	bool	false	false	Indicate reject post only or not
bbo	bool	false	false	Indicate bbo order or not
mmp	bool	false	false	Indicate mmp order or not

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not

Place batch orders

POST /linear/v1/batchorders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency":"USDT", "orders_data": [{"instrument_id": "BTC-USDT-", "price": "50000", "qty": "1.5", "side": "buy", "hidden": true}, {"instrument_id": "BTC-USDT-PERPETUAL", "price": "50010", "qty": "2", "side": "sell"}], "timestamp": 1596782252388, "signature": "0b8b64d2f35f9742a17af4ee0b993d0248a27a98f320abbfe8e7316f184e30d5"}'

{
    "code": 0,
    "message": "",
    "data": {
        "orders": [
            {
                "order_id": "",
                "created_at": 0,
                "updated_at": 0,
                "user_id": "",
                "instrument_id": "",
                "order_type": "",
                "side": "",
                "price": "",
                "qty": "",
                "time_in_force": "",
                "avg_price": "",
                "filled_qty": "",
                "status": "",
                "is_liquidation": false,
                "auto_price": "",
                "auto_price_type": "",
                "taker_fee_rate": "",
                "maker_fee_rate": "",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": true,
                "error_code": 18100185,
                "error_msg": "Invalid instrument BTC-USDT-"
            },
            {
                "order_id": "501758",
                "created_at": 1596782252996,
                "updated_at": 1596782252996,
                "user_id": "51140",
                "instrument_id": "BTC-USDT-PERPETUAL",
                "order_type": "limit",
                "side": "sell",
                "price": "50010.00000000",
                "qty": "2.00000000",
                "time_in_force": "gtc",
                "avg_price": "0.00000000",
                "filled_qty": "0.00000000",
                "status": "open",
                "is_liquidation": false,
                "auto_price": "0.00000000",
                "auto_price_type": "",
                "taker_fee_rate": "0.00045000",
                "maker_fee_rate": "0.00025000",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": false,
                "error_code": 0,
                "error_msg": ""
            }
        ]
    }
}

Place batch order.
Provide order array, order parameter details are the same as POST /linear/v1/orders.
conditional order is not supported.
Max order request count is 10.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
orders_data	array	true		Order request list(see below)

order request detail

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
qty	string	true	""	Order size (positive number)
side	string	true	""	Order side
price	string	false	"0.0"	Order price, not required for market order
order_type	string	false	"limit"	Order type
time_in_force	string	false	"gtc"	Time in force
label	string	false	""	User defined label
post_only	bool	false	false	Indicate post only or not
reject_post_only	bool	false	false	Indicate reject post only or not
mmp	bool	false	false	Indicate mmp order or not

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not
error_code	int	New order result code: 0 = no error
error_msg	string	New order error message

Cancel orders

POST /linear/v1/cancel_orders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/cancel_orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"currency": "USDT", "order_id": "44092860", "instrument_id":"BTC-USDT-PERPETUAL", "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}'

{
    "code": 0,
    "message": "",
    "data": {
        "num_cancelled": 1
    }
}

Cancel order.
Currency is required parameter.
To cancel single order, only need to provide order_id and instrument_id parameters.
Batch cancel filters include: order_id_list, label, instrument_id, pair, category, currency.
Batch cancel filter priorities: order_id_list > label > instrument_id > pair > category > currency

To cancel conditional order, provide cond_order_id + instrument_id. conditional order can not be cancelled in batch.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
order_id	string	false	""	Order ID
pair	string	false	Pair
instrument_id	string	false	""	Instrument ID (if order_id is provided, instrument_id is required)
order_id_list	array	false	""	List of (order_id + instrument_id), e.g [{"instrument_id":"BTC-USD-PERPETUAL","order_id":"1001"}, {"instrument_id":"BTC-USD-29JUL22-24250-C","order_id":"1002"}]
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID (if `order_id` if provided, `instrument_id` is required)
label	string	false	""	Order label

order_id_list details

Parameter	Type	Required	Default	Description
order_id	string	true	""	Order ID
instrument_id	string	true	""	Instrument ID

Response

Name	Type	Desc
num_cancelled	integer	number of order cancelled

Amend orders

POST /linear/v1/amend_orders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/amend_orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"currency": "USDT", "order_id": "1206764", "instrument_id":"BTC-USDT-PERPETUAL", "price": "49000", "timestamp": 1590760362688, "signature": "a74dda0f2bdaf1e1587a5e7577a281497cb66607166bd3b7e0cc4c805c750bf1"}'

{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "1206764",
        "created_at": 1590760363846,
        "updated_at": 1590760363846,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "49000.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "49000.00000000",
        "filled_qty": "1.00000000",
        "status": "filled",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "-0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "source": "api",
        "hidden": false,
    }
}

Amend order.
Order id + Instrument id are required.
Need to provide at least one of: price,qty.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
order_id	string	true	""	Order ID
instrument_id	string	true	""	Instrument Id
price	string	false	""	New price of the order
qty	string	false	""	New quantity of the order

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not

Amend batch orders

POST /linear/v1/amend_batchorders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/amend_batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency": "USDT", "orders_data": [{"order_id": "572083", "instrument_id":"BTC-USDT-PERPETUAL", "price": "50000", "qty": "1.3"}, {"order_id": "invalid-order-id", "instrument_id":"BTC-USDT-PERPETUAL", "price": "50000", "qty": "0.2"}], "timestamp": 1597313835731, "signature": "c8b5fddd5f2cfa1517854dc54c51e7c3b79af91f0927ea1389ba43dbeee45652"}'

{
    "code": 0,
    "message": "",
    "data": {
        "orders": [
            {
                "order_id": "572083",
                "created_at": 1597313836214,
                "updated_at": 1597313836214,
                "user_id": "51140",
                "instrument_id": "BTC-USDT-PERPETUAL",
                "order_type": "limit",
                "side": "sell",
                "price": "50000.00000000",
                "qty": "1.30000000",
                "time_in_force": "gtc",
                "avg_price": "0.00000000",
                "filled_qty": "0.00000000",
                "status": "open",
                "is_liquidation": false,
                "auto_price": "0.00000000",
                "auto_price_type": "",
                "taker_fee_rate": "0.00045000",
                "maker_fee_rate": "0.00025000",
                "label": "",
                "reduce_only": false,
                "post_only": true,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": true,
                "error_code": 0,
                "error_msg": ""
            },
            {
                "order_id": "",
                "created_at": 0,
                "updated_at": 0,
                "user_id": "",
                "instrument_id": "",
                "order_type": "",
                "side": "",
                "price": "",
                "qty": "",
                "time_in_force": "",
                "avg_price": "",
                "filled_qty": "",
                "status": "",
                "is_liquidation": false,
                "auto_price": "",
                "auto_price_type": "",
                "taker_fee_rate": "",
                "maker_fee_rate": "",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": false,
                "error_code": 18100113,
                "error_msg": "order id is invalid : invalid-order-id"
            }
        ]
    }
}

Amend order in batch.
For each amend request:
Order id + Instrument id are required.
Need to provide at least one of: price,qty.
Max amend request count is 10.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
orders_data	array	true		Amend request list(see below)

order request detail

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
order_id	string	true	""	Order ID
instrument_id	string	true	""	Instrument Id
price	string	false	""	New price of the order
qty	string	false	""	New quantity of the order

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not
error_code	int	Edited order result code: 0 = no error
error_msg	string	Edited order error message

Close positions

POST /linear/v1/close_positions


curl -X POST "https://betaapi.bitexch.dev/linear/v1/close_positions" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id": "BTC-USDT-PERPETUAL", "price": "51000", "order_type": "limit", "timestamp": 1589524756236, "signature": "5bf4f9f00722d133336e736196c09a8e02c634dc0deacf2cf12413049d8d8b06"}'



{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "17553311",
        "created_at": 1589524757818,
        "updated_at": 1589524757818,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "order_type": "limit",
        "side": "sell",
        "price": "51000.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "51000.50000000",
        "filled_qty": "1.00000000",
        "status": "filled",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "source": "api",
        "hidden": false,
    }
}

Close position by instrument_id, send out order with input instrument_id, order_type, price.

order size is abs(open_position), direction is opposite of open_position side.

Limit order is IOC order.

If user don't want to specify price, input order_type = 'market'

Post json body

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID of closing order
order_type	string	false	"limit"	Order type of closing order, default is limit (IOC) Order type
price	string	false	""	Price of closing order

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled quantity
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not

Get open orders

GET /linear/v1/open_orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/open_orders?currency=USDT&category=future&timestamp=1589522687689&signature=89d5a1d929e7baa247021e090f9f634f02a7fc6c82a44c8de3bb04fa6b005a7b"

{
    "code": 0,
    "message": "",
    "data": [{
        "order_id": "7610691",
        "created_at": 1589183001000,
        "updated_at": 1589183001000,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "50010.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "open",
        "fee": "0.00000000",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "pnl": "0.00000000",
        "cash_flow": "0.00000000",
        "initial_margin": "0.24000000",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "reorder_index": 1,
        "source": "api",
        "hidden": false,
        "is_um": true
        }
    ]
}

Get open orders by currency, category, instrument_id

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID
label	string	false	""	Order label

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
fee	string	Transaction fees
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
pnl	string	Order P&L
cash_flow	string	Order cash flow
initial_margin	string	Order initial margin (open order only)
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
reorder_index	int64	Sorting index for internal use
source	string	Order source
hidden	bool	Indicate hidden order or not
is_um	bool	Always true for USD-M order

Get orders

GET /linear/v1/orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/orders?currency=USDT&instrument_id=BTC-USDT-PERPETUAL&order_id=7718222&start_time=1585270800000&end_time=1589522084000&include_open=true&offset=1&limit=10&timestamp=1589523178651&signature=2092cebba4f082f9c8718344cdad9bed83950b5fe90b3a875b708898bfd89b20"



{
    "code": 0,
    "message": "",
    "data": [{
        "order_id": "7718222",
        "created_at": 1589202185000,
        "updated_at": 1589460149000,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "50010.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "cancelled",
        "fee": "0.00000000",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "pnl": "0.00000000",
        "cash_flow": "0.00000000",
        "initial_margin": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "reorder_index": 1,
        "source": "api",
        "hidden": false,
        "is_um": true
    }]
}

Get order history.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
instrument_id	string	true	""	Instrument ID
order_id	string	false	""	Order ID
label	string	false	""	Order label
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
include_open	boolean	false	true	Include open order or not
limit	int	false	100	Return record count

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled quantity
status	string	Order status
fee	string	Transaction fees
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
pnl	string	Order P&L
cash_flow	string	Order cash flow
initial_margin	string	Order initial margin (open order only)
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
reorder_index	int64	Sorting index for internal use
source	string	Order source
hidden	bool	Indicate hidden order or not
is_um	bool	Always true for USD-M order

Get user trades

GET /linear/v1/user/trades

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/user/trades?currency=USDT&category=future&order_id=17551020&start_time=1585270800000&end_time=1589522084000&offset=1&limit=10&timestamp=1589523590679&signature=c4788e3a77b6000424b55067f9ba38009b34d12e482b1c80186756857c869bb5"


{
    "code": 0,
    "message": "",
    "data": [{
        "trade_id": "23210268",
        "order_id": "17551020",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "qty": "2.00000000",
        "price": "50010.00000000",
        "sigma": "0.00000000",
        "underlying_price": "",
        "index_price": "50012.81000000",
        "usd_price": "",
        "fee": "0.00100000",
        "fee_rate": "0.00050000",
        "side": "buy",
        "created_at": 1589521371000,
        "is_taker": true,
        "order_type": "limit",
        "label": "hedge"
    }]
}

Get user trades

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID
order_id	string	false	""	Order ID
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
start_id	integer	false		Start Id
end_id	integer	false		End Id
count	int	false	100	Trade count, max 1000

Response

Name	Type	Desc
order_id	string	Order ID
trade_id	string	Trade ID
instrument_id	string	Instrument ID
created_at	integer	Create timestamp
order_type	string	Order type
side	string	Order side
price	string	Trade price
qty	string	Trade quantity
fee	string	Transaction fees
fee_rate	string	Fee rate
sigma	string	Implied volatility , option only
is_taker	boolean	Is taker or not
index_price	string	Index price
underlying_price	string	Underlying price (not for future instrument)
usd_price	string	(Not Applicable)
label	string	Order label of related trade

Get estimated margins

GET /linear/v1/margins

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/margins?instrument_id=BTC-USDT-PERPETUAL&price=5000&qty=1&timestamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807"

{
    "code": 0,
    "message": "",
    "data": {
        "buy_margin": "70.93672651",
        "sell_margin": "100.13000000",
        "min_sell": "34890.97000000",
        "max_buy": "35953.65000000",
        "index_price": "35423.91000000"
    }
}

Get margin of orders

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
price	string	true	""	Order price
qty	string	true	""	Order quantity

Response (Margin array)

Name	Type	Desc
buy_margin	string	Estimated buy margin(in margin currency)
sell_margin	string	Estimated sell margin(in margin currency)
min_sell	string	Minimum price for sell order
max_buy	string	Maximum price for buy order
index_price	string	USD index price
usdt_index_price	string	(For compatibility) equal to `index_price`

Get conditional orders

GET /linear/v1/conditional_orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/conditional_orders?currency=USDT&instrument_id=BTC-USDT-PERPETUAL&status=open&timestamp=1590667739793&signature=14c522605de563064ae36933604225730a8b4e254be8ce58ecc2746f5199d77f"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "cond_order_id": "trigger-c8vbgjdlat8f5clahjpg",
            "created_at": 1648277581254,
            "updated_at": 1648277581254,
            "status": "open",
            "stop_price": "40000.00000000",
            "trigger_type": "last-price",
            "reject_reason": "",
            "instrument_id": "BTC-USDT-PERPETUAL",
            "user_id": 8001,
            "qty": "1.00000000",
            "price": "39000.00000000",
            "side": "buy",
            "order_type": "trigger-limit",
            "time_in_force": "gtc",
            "source": "api",
            "hidden": false
        }
    ],
    "page_info": {
        "has_more": false
    }
}

Get conditional order history by currency, instrument_id, or status.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Currency
pair	string	false	""	Pair
instrument_id	string	false	""	Instrument ID
status	string	false	""	Conditional Order status
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
limit	int	false	100	Return record count

Response

Name	Type	Desc
cond_order_id	string	Conditional Order ID (with prefix "trigger-")
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
instrument_id	string	Instrument ID
qty	string	Order quantity
price	string	Price of the triggered new order
side	string	Order side
order_type	string	Order type
stop_price	string	Stop price (conditional order only)
time_in_force	string	Time in force
status	string	ConditionalOrder status
trigger_type	string	Triggered by last price
user_id	int	User ID
source	string	Order source
hidden	bool	Indicate hidden order or not

Block Trade

To use block trade API, user need to create API key with linear block trade permission

New block trade request

POST /linear/v1/blocktrades

# <bt_source> should be replaced with real bt_source

curl -X POST "https://betaapi.bitexch.dev/linear/v1/blocktrades" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a"  -d '{"currency":"USD", "label": "e8db3a92b94c482bb0e30f421415982d", "role": "maker", "counterparty": 1026, "bt_source": "<bt_source>", "trades": [{"instrument_id": "BTC-USD-25SEP20-9000-C", "price": "0.18", "qty": "10", "side": "sell"}, {"instrument_id": "BTC-USD-PERPETUAL", "price": "19000", "qty": "5", "side": "buy"}], "timestamp": 1594447520876, "signature": "7e8b0e7987fcb282b691d9e87c5afa9af578ed0c464190ca1fa466d18c17adde"}'

{
    "code": 0,
    "message": "",
    "data": {
        "label": "e8db3a92b94c482bb0e30f421415982d",
        "status": "pending"
    }
}

Make block trade request.
Label: Unique identifier of block trade, both counterpartys use the same label for given block trade request
Both side needs to call /linear/v1/blocktrades with same label, trades(with opposite side).
The block trade request timeout period is 1 minute, if the other side doesn't answer in given time, the request will expired.
Block trade bt_source is bit.com designated block trade source, contact bit.com for detail.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Currency
bt_source	string	true	""	Block trade source (bit.com designated block trade source)
label	string	true	""	Unique identifier generated for block trade
role	string	true	""	Role: taker/maker
counterparty	integer	true	""	Counterparty user ID
trades	array	true		Trade list of this block trade request(see below)

block trade object

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
side	string	true	""	Order side: buy/sell
price	string	true	""	Order price
qty	string	true	""	Order quantity

Response

Name	Type	Desc
label	string	Block trade label
status	string	pending/filled/rejected/expired

Query block trades

GET /linear/v1/blocktrades

# <bt_source> should be replaced with real bt_source

curl -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" "https://betaapi.bitexch.dev/linear/v1/blocktrades?currency=USD&bt_source=<bt_source>&timestamp=1594447524043&signature=12b1090ea6432e71f2f6d01c6f08f0ff30e3765791ebff87b4183964643d61d2"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "56",
            "label": "8c5d90b6cbd744ceab49d0e66b8fda68",
            "created_at": 1613637677061,
            "updated_at": 1613637678593,
            "user_id": 51140,
            "counterparty": 481554,
            "instrument_id": "BTC-USD-PERPETUAL",
            "side": "buy",
            "price": "19000.00000000",
            "qty": "10.00000000",
            "fee": "0.00000392",
            "status": "filled",
            "role": "maker",
            "bt_source": "<bt_source>",
            "order_id": "6325142",
            "trade_id": "1299120841",
            "index_price": "51723.49000000",
            "sigma": "0.00000000"
        }
    ]
}

Query block trades.

Query parameters

Parameter	Type	Required	Default	Description
bt_source	string	true	""	Block trade source
currency	string	true	""	Currency
instrument_id	string	false	""	Instrument ID
label	string	false	""	Label of the block trade request
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
limit	int	false	100	Return record count

Response

Name	Type	Desc
block_order_id	string	Block order id
label	string	Label of the block trade request
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	integer	User ID
counterparty	integer	Counterparty User ID
instrument_id	string	Instrument ID
side	string	Order side
price	string	Order price
qty	string	Order quantity
fee	string	Transaction fees
status	string	Status
role	string	Order role(taker/maker)
bt_source	string	Block trade source
order_id	string	Exchange order id
trade_id	string	Exchange trade id
index_price	string	Index price
sigma	string	Implied volatility , option only

Query block trades by platform

GET /linear/v1/platform_blocktrades

# <bt_source> should be replaced with real bt_source

curl -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" "https://betaapi.bitexch.dev/linear/v1/platform_blocktrades?currency=USD&bt_source=<bt_source>&timestamp=1594448745124&signature=39078700dbe556df7f34dd6e0fb444b4ead9ef6ddc8e5b24c76555b6758c68d2"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "56",
            "label": "8c5d90b6cbd744ceab49d0e66b8fda68",
            "created_at": 1613637677061,
            "updated_at": 1613637678593,
            "user_id": 51140,
            "counterparty": 481554,
            "instrument_id": "BTC-USD-PERPETUAL",
            "side": "buy",
            "price": "19000.00000000",
            "qty": "10.00000000",
            "fee": "0.00000392",
            "status": "filled",
            "role": "maker",
            "bt_source": "<bt_source>",
            "order_id": "6325142",
            "trade_id": "1299120841",
            "index_price": "51723.49000000",
            "sigma": "0.00000000"
        }   
    ]
}

Query block trades of specific platform.

Query parameters

Parameter	Type	Required	Default	Description
bt_source	string	true	""	Block trade source
currency	string	true	""	Currency
instrument_id	string	false	""	Instrument ID
label	string	false	""	Label of the block trade request
taker	string	false	""	Filtered by taker
maker	string	false	""	Filtered by maker
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
limit	int	false	100	Return record count

Response

Name	Type	Desc
block_order_id	string	Block order id
label	string	Label of the block trade request
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	integer	User ID
counterparty	integer	Counterparty User ID
instrument_id	string	Instrument ID
side	string	Order side
price	string	Order price
qty	string	Order quantity
fee	string	Transaction fees
status	string	Status
role	string	Order role(taker/maker)
bt_source	string	Block trade source
order_id	string	Exchange order id
trade_id	string	Exchange trade id
index_price	string	Index price
sigma	string	Implied volatility , option only

Get blocktrade user info

GET /linear/v1/user/info

curl -H "X-Bit-Access-Key: ak-77fd5728-e7d4-4174-991a-6e9b8f5887e6" "https://betaapi.bitexch.dev/linear/v1/user/info?timestamp=1613713263340&signature=038be893be10e51b7545abacbf669e7569b7de2dcb2693c33f4aa29c956a611a"

{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 10031
    }
}

Get user information with only blocktrade permission.
API key with "read" permission should use GET /linear/v1/accounts instead.

Query Parameters

None

Response

Name	Type	Description
user_id	integer	User ID of bit.com

Websocket subscription

Data subscription is based on Websocket protocol. Users can send subscription requests after established Websocket connections.

Connection will be auto disconnected if no subscription is initiated within 30s.

The data of the USD-M contract and the COIN-M contract are subscribed through the same websocket service address, and the channels can be subscribed together. The websocket service will return the corresponding data according to instruments or pairs/currencies in subscription parameters.

All the responses are based on the following structure.

Name	Type	Description
channel	string	Channel name
timestamp	integer	The timestamp (milliseconds since the Unix epoch)
data	object	Content
module	string	[`linear`, `um`] The module which the subscription data came from

Subscription management

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL",
        "ETH-USDT-PERPETUAL"
    ],
    "channels":[
        "depth",
        "ticker",
        "kline.5",
        "order"
    ],
    "pairs":[
        "BTC-USDT"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"be4ffcc9-2b2b-4c3e-9d47-68bf062cf651"
}

{
    "channel":"subscription",
    "timestamp":1587921122970,
    "data":{
        "code":0,
        "subscription":[
            "depth",
            "ticker",
            "kline.5"
        ]
    }
}

{
    "channel":"subscription",
    "timestamp":1587921122970,
    "data":{
        "code":13200302,
        "message":"auth failed: invalid token"
    }
}

Users can subscribe to different channels, public and private. Private channel requires token and authentication.

Channels have different specifications, see details in the documentations below.

Users can set the push frequency with the parameter interval. * interval=raw, the channel will push the updates immediately. * interval=100ms, the updates within 100ms period will be aggregated and pushed out, note: if no updates within 100ms, no data will be pushed. * interval=fixed100ms, data will be pushed every 100ms no matter has update or not (Only apply to order_book channel currently).

If the subscription request contains more than one channel and one of them failed, you will receive two separate responses.

Users can stop the feed by submitting an unsubscribe request.

Parameters

Name	Type	Description
type	string	[`subscribe`, `unsubscribe`]
channels	string[]	List of channels
pairs	string[]	List of pairs
categories	string[]	List of instrument categories
instruments	string[]	List of instrument IDs
interval	string	[`raw`, `100ms`, `fixed100ms`] default value is `raw`
token	string	Authentication Token for private channel

interval parameter:

All channels support setting interval to raw or 100ms
Only some channels support setting interval to fixed100ms, currently supported channels include：order_book

Response

Name	Type	Description
code	integer	0 means success, !=0 means failure
message	string	Error message, return when failed
subscription	string[]	Subscription list, return when successful

Authentication Token

GET /v1/ws/auth

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/ws/auth?timestamp=1588996062516&signature=9ed1dd821cc6464d2cfc5bf9614df1f22611c977b513e1ffde864a673b6915f0"

{
    "code":0,
    "message":"",
    "data":{
        "token":"be4ffcc9-2b2b-4c3e-9d47-68bf062cf651"
    }
}

To connect private websocket channels, user needs to first call GET /v1/ws/auth to acquire a token, which will be used to fill in private websocket channel subscription for websocket authentication.

Each token is used for single websocket connection, it's not cached in server, can not be reused, user needs to acquire new token if reconnect. (Thus token of user A can not be reused by user B even when the token is compromised)

For websocket connection, user only need to do authentication in first private channel subscription, subsequent private subscription do not need authenticate(and subsequent token will be discarded, so different users can not share private websocket connections)

Parameters

None

Response

Name	Type	Description
token	string	private channel authentication token

Heartbeat

Standard protocol

According to RFC 6455, Websocket protocol uses PING/PONG to indicate that the connection is kept alive.

Server sends PING to client every minute through Websocket, client responds with PONG. Connection will be closed if PONG is not received after one minute.

Client can also send PING to check if the server is still responsive.

PING/PONG are both control frames. PING's opcode is 0x9，PONG's opcode is 0xA. One can refer to this link。

Custom PING/PONG

Since some clients cannot support sending control frames, payload-based PING/PONG is provided in addition to the standard protocol. Refer to "Websocket RPC - PING" for details.

Channel Summary

Channel	Scope	Arguments	Description
depth	public	instruments	Changes to the order book
order_book.{group}.{depth}	public	instruments	Order book based on specified group and depth
depth1	public	instruments	Top of order book bid/ask
ticker	public	instruments	The most recent traded price and trading summary
kline.{timeframe}	public	instruments	Kline data
trade	public	instruments	Trades for an instrument
market_trade	public	categories + pairs	All the trades of available options or futures
index_price	public	pairs	Index price of the specific currency pair
mark_price	public	instruments	Mark price for an instrument
um_account	private		UM user's account information
position	private	categories + pairs	User's position information
order	private	categories + pairs	User's order information
user_trade	private	categories + pairs	User's trade information
mmp_frozen	private	pairs.	MMP frozen event

Depth Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL"
    ],
    "channels":[
        "depth"
    ],
    "interval": "100ms"
}

{
    "channel":"depth",
    "timestamp":1643094930373,
    "module":"linear",
    "data":{
        "type":"snapshot",
        "instrument_id":"BTC-USDT-PERPETUAL",
        "sequence":9,
        "bids":[
            [
                "35731.05000000",
                "6.82000000"
            ]
        ],
        "asks":[
            [
                "35875.00000000",
                "1.00000000""
            ]
        ]
    }
}

{
    "channel":"depth",
    "timestamp":1643094930373,
    "module":"linear",
    "data":{
        "type":"update",
        "instrument_id":"BTC-USDT-PERPETUAL",
        "sequence":10,
        "prev_sequence":9,
        "changes":[
            [
                "sell",
                "35733.00000000",
                "2.10000000"
            ]
        ]
    }
}

Depth channel can have two message types: snapshot and update. Snapshot sends snapshots of the current order book. Updates sends changes of the order book.

The first message will always be a snapshot followed by updates, if there is any sort of disruption, a new snapshot will be sent follow by updates.

A snapshot includes bids and asks depths, each depth layer consists of two elements: price and quantity.

A normal update message contains sequence and prev_sequence, with the prev_sequence matching the previous update.

Changes in update is a result in a change in depth, every changes consists of three elements: side, price and quantity. Quantity=0 means a layer is been removed from the depth.

Channel Information

Channel	Scope	Arguments	Interval
depth	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
type	string	[`snapshot`, `update`]
instrument_id	string	Instrument ID
sequence	integer	Order book update sequence
asks	array of [price, quantity]	Asks, price and quantity are string, return when type=snapshot
bids	array of [price, quantity]	Bids, price and quantity are string, return when type=snapshot
prev_sequence	integer	Previous update sequence number, return when type=update
changes	array of [side, price, quantity]	Depth changes, side、price、quantity are string, quantity=0 means deletion, return when type = update

Order Book Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL"
    ],
    "channels":[
        "order_book.1.20"
    ],
    "interval": "100ms"
}

{
    "channel":"order_book.1.20",
    "timestamp":1643095202401,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-PERPETUAL",
        "sequence":1643010119674372,
        "timestamp":1643095202400,
        "asks":[
            [
                "35725.80000000",
                "2.29000000"
            ],
            [
                "35747.00000000",
                "1.00000000"
            ]
        ],
        "bids":[
            [
                "35724.80000000",
                "5.25000000"
            ],
            [
                "35724.75000000",
                "1.38000000"
            ]
        ]
    }
}

Order Book pushes certain layers of an order book data based on group and depth.

An order book message includes bids and asks depths, each depth layer consists of two elements: price and quantity.

Channel Information

Channel	Scope	Arguments	Interval
order_book.{group}.{depth}	public	instruments	[`raw`, `100ms`,`fixed100ms`]

When subscribing to orderbook channel, user will need to specify group and depth in channel

group value: represents the multiple of the order book price steps, aggregation level = group * price_step.
Valid group value of the instrument can be retrieved via the rest api /linear/v1/instruments.
depth value: 1, 10, 20, 100, represents order book layers

Default is group=1, depth=10

Order book price aggregation example

Assume price_step = 0.01

raw depth:
bids: [[0.13, 3], [0.19, 7], [0.26, 5], [0.77, 12.3]]

for orderbook.10.5, aggregation price level = 0.01 * 10 = 0.1
output bids: [[0.1, 10], [0.2, 5], [0.7, 12.3]]

Response

Name	Type	Description
instrument_id	string	Instrument ID
sequence	integer	Order book update sequence
timestamp	integer	Timestamp at order book update
asks	array of [price, quantity]	Asks, price and quantity are string
bids	array of [price, quantity]	Bids, price and quantity are string

Depth1 Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL"
    ],
    "channels":[
        "depth1"
    ],
    "interval": "100ms"
}

{
    "channel":"depth1",
    "timestamp":1643095202400,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-PERPETUAL",
        "asks":[
            [
                "35725.80000000",
                "2.29000000"
            ]
        ],
        "bids":[
            [
                "35724.80000000",
                "5.25000000"
            ]
        ]
    }
}

Depth1 pushes top of book bid/ask information

Channel Information

Channel	Scope	Arguments	Interval
depth1	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
asks	array of [price, quantity]	Asks, price and quantity are string, return 0 or 1 layer
bids	array of [price, quantity]	Bids, price and quantity are string, return 0 or 1 layer

Ticker Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL"
    ],
    "channels":[
        "ticker"
    ],
    "interval": "100ms"
}

{
    "channel":"ticker",
    "timestamp":1643099422727,
    "module":"linear",
    "data":{
        "ask_sigma":"",
        "best_ask":"36295.00000000",
        "best_ask_qty":"1.00000000",
        "best_bid":"36242.30000000",
        "best_bid_qty":"7.01000000",
        "bid_sigma":"",
        "funding_rate":"0.00203429",
        "funding_rate8h":"0.00009707",
        "high24h":"37377.00000000",
        "instrument_id":"BTC-USDT-PERPETUAL",
        "last_price":"36242.30000000",
        "last_qty":"0.42000000",
        "low24h":"33117.95000000",
        "mark_price":"36261.48392714",
        "max_buy":"36805.41000000",
        "min_sell":"35717.56000000",
        "open24h":"34998.65000000",
        "open_interest":"87.69310000",
        "price_change24h":"0.03553423",
        "time":1643099422727,
        "volume24h":"4422.94140000"
    }
}

Ticker pushes the most recent traded price and the last 24 hrs trading summary.

Channel Information

Channel	Scope	Arguments	Interval
ticker	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
last_price	string	Most recent traded price
last_qty	string	Most recent traded volume
open24h	string	Open price during previous 24 hour
high24h	string	Highest price during previous 24 hour
low24h	string	Lowest price during previous 24 hour
volume24h	string	Sum volume during previous 24 hour
price_change24h	string	Price change% during previous 24 hour
open_interest	string	Open interest
best_bid	string	Best bid price
best_ask	string	Best ask price
best_bid_qty	string	Best bid quantity
best_ask_qty	string	Best ask quantity
bid_sigma	string	Top of book bid implied vol, option only
ask_sigma	string	Top of book ask implied vol, option only
underlying_name	string	Underlying index name, option only
underlying_price	string	Underlying price, option only
funding_rate	string	Funding rate, perpetual only
funding_rate8h	string	Past 8H avg funding rate, perpetual only
mark_price	string	Mark price
sigma	string	Mark price implied vol, option only
delta	string	Mark price delta, option only
vega	string	Mark price vega, option only
theta	string	Mark price theta, option only
gamma	string	Mark price gamma, option only
max_buy	string	Maximum price of buy order
min_sell	string	Minimum price of sell order

Kline Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL"
    ],
    "channels":[
        "kline.5"
    ],
    "interval": "100ms"
}

{
    "channel":"kline.5",
    "timestamp":1643099753388,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-PERPETUAL",
        "close":"36088.00000000",
        "high":"36088.00000000",
        "low":"36081.45000000",
        "open":"36176.90000000",
        "tick":1643099700000,
        "volume":"3.29000000"
    }
}

Kline pushed kline data. If there is no trade during the current period, the previous close will be used for open, high and low.

Channel Information

Channel	Scope	Arguments	Interval
kline.{timeframe}	public	instruments	[`raw`, `100ms`]

When subscribing to kline channel, user will need to specify timeframe.

Support timeframes:

Timeframe	Name Desc
1	1 minute
3	3 minute
5	5 minute
15	15 minute
30	30 minute
60	60 minute
240	240 minute
360	360 minute
720	720 minute
1d	daily
1w	weekly
1m	monthly

Response

Name	Type	Description
instrument_id	string	Instrument ID
tick	integer	Tick starting time
open	string	Open price
close	string	Close price
high	string	High price
low	string	Low price
volume	string	Volume

Trade Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL"
    ],
    "channels":[
        "trade"
    ],
    "interval": "100ms"
}

{
    "channel":"trade",
    "timestamp":1643099734031,
    "module":"linear",
    "data":[
        {
            "instrument_id":"BTC-USDT-PERPETUAL",
            "created_at":1643099733988,
            "is_block_trade":false,
            "price":"36081.45000000",
            "qty":"2.29000000",
            "side":"buy",
            "sigma":"0.00000000",
            "trade_id":"1005590555"
        }
    ]
}

Trade pushes instrument's trading information

Channel Information

Channel	Scope	Arguments	Interval
trade	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
trade_id	string	Trade ID
price	string	Price
qty	string	Quantity
side	string	Taker trade side
sigma	string	Trade implied vol, option only
option_type	string	Option type, option only
is_block_trade	boolean	Is block trade or not
created_at	integer	Trade timestamp (milliseconds since the Unix epoch)

Market Trade Channel

{
    "type":"subscribe",
    "channels":[
        "market_trade"
    ],
    "pairs":[
        "BTC-USDT"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms"
}

{
    "channel":"market_trade",
    "timestamp":1643099734031,
    "module":"linear",
    "data":[
        {
            "instrument_id":"BTC-USDT-PERPETUAL",
            "created_at":1643099733988,
            "is_block_trade":false,
            "price":"36081.45000000",
            "qty":"2.29000000",
            "side":"buy",
            "sigma":"0.00000000",
            "trade_id":"1005590555"
        }
    ]
}

Market Trade pushes all the trading information of available options or futures.

Channel Information

Channel	Scope	Arguments	Interval
market_trade	public	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
trade_id	string	Trade ID
price	string	Price
qty	string	Quantity
side	string	Taker trade side
sigma	string	Trade implied vol, option only
option_type	string	Option type, option only
is_block_trade	boolean	Is block trade or not
created_at	integer	Trade timestamp (milliseconds since the Unix epoch)

Index Price Channel

{
    "type":"subscribe",
    "channels":[
        "index_price"
    ],
    "pairs":[
        "BTC-USDT"
    ],
    "interval": "100ms"
}

{
    "channel":"index_price",
    "timestamp":1643099733988,
    "module":"linear",
    "data":{
        "index_name":"BTC-USDT",
        "index_price":"35866.66000000"
    }
}

index_price pushes index price of the specific currency pair.

Channel Information

Channel	Scope	Arguments	Interval
index_price	public	pairs	[`raw`, `100ms`]

Response

Name	Type	Description
index_name	string	Index name
index_price	string	Index price

Mark Price Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USDT-PERPETUAL"
    ],
    "channels":[
        "mark_price"
    ],
    "interval": "100ms"
}

{
    "channel":"mark_price",
    "timestamp":1643100336677,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-PERPETUAL",
        "mark_price":"36079.52938997"
    }
}

Mark Price pushes mark price of a specific instrument

Channel Information

Channel	Scope	Arguments	Interval
mark_price	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
mark_price	string	Mark price
sigma	string	Mark price implied vol, option only
delta	string	Mark price delta, option only
vega	string	Mark price vega, option only
theta	string	Mark price theta, option only
gamma	string	Mark price gamma, option only

UM Account Channel

{
    "type":"subscribe",
    "channels":[
        "um_account"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"um_account",
    "timestamp":1632439007081,
    "module":"um",
    "data": {
        "user_id": 481554,
        "created_at": 1649923879505,
        "total_collateral": "3170125.05978108",
        "total_margin_balance": "3170125.05978108",
        "total_available": "3169721.64891398",
        "total_initial_margin": "403.41086710",
        "total_maintenance_margin": "303.16627631",
        "total_initial_margin_ratio": "0.00012725",
        "total_maintenance_margin_ratio": "0.00009563",
        "total_liability": "0.00000000",
        "total_unsettled_amount": "-0.84400340",
        "spot_orders_hc_loss": "0.00000000",
        "total_position_pnl": "1225.53245820",
        "details": [
            {
                "currency": "BTC",
                "equity": "78.13359310",
                "liability": "0.00000000",
                "index_price": "41311.20615385",
                "cash_balance": "78.13360190",
                "margin_balance": "78.13359310",
                "available_balance": "78.12382795",
                "initial_margin": "0.00976516",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00733859",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.02966586",
                "total_delta": "0.48532539",
                "session_rpl": "0.00001552",
                "session_upl": "-0.00003595",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.02966586",
                "future_session_rpl": "0.00001552",
                "future_session_upl": "-0.00003595",
                "future_session_funding": "0.00001552",
                "future_delta": "0.48532539",
                "future_available_balance": "76.72788921",
                "option_available_balance": "76.72788921",
                "unsettled_amount": "-0.00002043",
                "usdt_index_price": "41311.20615385"
            },
            {
                "currency": "ETH",
                "equity": "1.99960000",
                "liability": "0.00000000",
                "index_price": "3119.01923077",
                "cash_balance": "1.99960000",
                "margin_balance": "1.99960000",
                "available_balance": "1.99960000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.00000000",
                "total_delta": "0.00000000",
                "session_rpl": "0.00000000",
                "session_upl": "0.00000000",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.00000000",
                "future_session_rpl": "0.00000000",
                "future_session_upl": "0.00000000",
                "future_session_funding": "0.00000000",
                "future_delta": "0.00000000",
                "future_available_balance": "1.99960000",
                "option_available_balance": "1.99960000",
                "unsettled_amount": "0.00000000",
                "usdt_index_price": "3119.01923077"
            }
        ],
        "usdt_total_collateral": "3170125.05978108",
        "usdt_total_margin_balance": "3170125.05978108",
        "usdt_total_available": "3169721.64891398",
        "usdt_total_initial_margin": "403.41086710",
        "usdt_total_maintenance_margin": "303.16627631",
        "usdt_total_initial_margin_ratio": "0.00012725",
        "usdt_total_maintenance_margin_ratio": "0.00009563",
        "usdt_total_liability": "0.00000000",
        "usdt_total_unsettled_amount": "-0.84400340"
    }
}

UM mode: subscribe um_accountchannnel to get UM account information.

Channel Information

Channel	Scope	Arguments	Interval
um_account	private		[`raw`, `100ms`]

Response

Name	Type	Desc
user_id	int	User Id
created_at	int	Timestamp (query time)
total_collateral	string	Total Collateral (USD)
total_margin_balance	string	Total Margin Balance (USD)
total_available	string	Total Available (USD)
total_initial_margin	string	Total Initial Margin (USD)
total_maintenance_margin	string	Total Maintenance Margin (USD)
total_initial_margin_ratio	string	Total Initial Margin Ratio, may returns "infinity" (USD)
total_maintenance_margin_ratio	string	Total Maintenance Margin Ratio, may returns "infinity" (USD)
total_liability	string	Total liability (USD)
total_unsettled_amount	string	Total unsettled amount (USD)
spot_orders_hc_loss	string	Total spot order haircut loss
total_position_pnl	string	Total position PnL in USD [SUM(ccy.pnl * ccy.index-price)]
details	array	Details, array of currency level detail
usdt_total_collateral	string	(For compatibility) equal to total_collateral
usdt_total_margin_balance	string	(For compatibility) equal to total_margin_balance
usdt_total_available	string	(For compatibility) equal to total_available
usdt_total_initial_margin	string	(For compatibility) equal to total_initial_margin
usdt_total_maintenance_margin	string	(For compatibility) equal to total_maintenance_margin
usdt_total_initial_margin_ratio	string	(For compatibility) equal to total_initial_margin_ratio
usdt_total_maintenance_margin_ratio	string	(For compatibility) equal to total_maintenance_margin_ratio
usdt_total_liability	string	(For compatibility) equal to total_liability
usdt_total_unsettled_amount	string	(For compatibility) equal to total_unsettled_amount

Detail object

Name	Type	Desc
currency	string	Currency
equity	string	Equity
liability	string	Liability
index_price	string	Index price (USD)
usdt_index_price	string	(For compatibility) equal to index_price
cash_balance	string	Cash Balance
margin_balance	string	Margin Balance
available_balance	string	Account Available Balance
initial_margin	string	Initial Margin
spot_margin	string	Spot Margin
maintenance_margin	string	Maintenance Margin
potential_liability	string	Potential Liability
interest	string	Interest
interest_rate	string	Interest Rate
pnl	string	Currency level position P&L
total_delta	string	Total delta of account
session_rpl	string	Session realized pnl
session_upl	string	Session unrealized pnl
option_value	string	Option market value
option_pnl	string	Option P&L
option_session_rpl	string	Option session realized P&L
option_session_upl	string	Option session unrealized P&L
option_delta	string	Option delta
option_gamma	string	Option gamma
option_vega	string	Option vega
option_theta	string	Option theta
future_pnl	string	Future P&L
future_session_rpl	string	Future session realized P&L
future_session_upl	string	Future session unrealized P&L
future_session_funding	string	Future session funding
future_delta	string	Future delta
future_available_balance	string	Available balance for new futures order
option_available_balance	string	Available balance for new option order
unsettled_amount	string	Unsettled amount

Position Channel

{
    "type":"subscribe",
    "channels":[
        "position"
    ],
    "pairs":[
        "BTC-USDT"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"position",
    "timestamp":1643101230232,
    "module":"linear",
    "data":[
        {
            "avg_price":"42474.49668874",
            "category":"future",
            "expiration_at":4102444800000,
            "index_price":"36076.66600000",
            "initial_margin":"21.81149685",
            "instrument_id":"BTC-USDT-PERPETUAL",
            "leverage":"50.00000000",
            "maintenance_margin":"16.36076260",
            "mark_price":"36097.57784846",
            "position_pnl":"192.58294898",
            "position_session_rpl":"-0.16699671",
            "position_session_upl":"-1.28505101",
            "qty":"-0.03020000",
            "qty_base":"-0.03020000",
            "roi":"8.82942378",
            "session_avg_price":"36055.02649047",
            "session_funding":"-0.16699671"
        }
    ]
}

Position pushes user's position information

Channel Information

Channel	Scope	Arguments	Interval
position	private	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
qty	string	Position size (for option, qty in base currency, for future, qty in USD)
qty_base	string	Position size in base currency, future only
avg_price	string	Average filled price
position_pnl	string	Position P&L
position_session_upl	string	Position session unrealized P&L
position_session_rpl	string	Position session realized P&L
index_price	string	Index price
mark_price	string	Mark price
initial_margin	string	Initial margin
maintenance_margin	string	Maintenance margin
session_avg_price	string	Session average price
session_funding	string	Session funding, future only
category	string	Instrument category
roi	string	Return on investment
option_delta	string	Option position delta, option only
option_gamma	string	Option position gamma, option only
option_vega	string	Option position vega, option only
option_theta	string	Option position theta, option only
liq_price	string	Estimated liquidation price, future only
leverage	string	Position leverage, future only

Order Channel

{
    "type":"subscribe",
    "channels":[
        "order"
    ],
    "pairs":[
        "BTC-USDT"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"order",
    "timestamp":1643101425658,
    "module":"linear",
    "data":[
        {
            "auto_price":"0.00000000",
            "auto_price_type":"",
            "avg_price":"0.00000000",
            "cash_flow":"0.00000000",
            "created_at":1643101425539,
            "fee":"0.00000000",
            "filled_qty":"0.00000000",
            "hidden":false,
            "initial_margin":"",
            "instrument_id":"BTC-USDT-PERPETUAL",
            "is_liquidation":false,
            "is_um":true,
            "label":"",
            "maker_fee_rate":"0.00010000",
            "mmp":false,
            "order_id":"1034087",
            "order_type":"limit",
            "pnl":"0.00000000",
            "post_only":false,
            "price":"36088.95000000",
            "qty":"0.02000000",
            "reduce_only":false,
            "reject_post_only":false,
            "reorder_index":0,
            "side":"buy",
            "source":"web",
            "status":"pending",
            "stop_order_id":"",
            "stop_price":"0.00000000",
            "taker_fee_rate":"0.00010000",
            "time_in_force":"gtc",
            "updated_at":1643101425539,
            "user_id":"606122"
        }
    ]
}

Order pushes user's order information

Channel Information

Channel	Scope	Arguments	Interval
order	private	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
order_id	string	Order ID
qty	string	Quantity
filled_qty	string	Filled quantity
remain_qty	string	Remaining quantity
price	string	Order price
avg_price	string	Average filled price
side	string	Order side
order_type	string	Order type
time_in_force	string	Order time in force
status	string	Order status
fee	string	Fee
cash_flow	string	Cash flow
pnl	string	P&L
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
is_liquidation	boolean	Is liquidation order or not
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (stop order only)
reduce_only	boolean	Indicate reduce only or not
post_only	boolean	Indicate post only or not
reject_post_only	boolean	Indicate reject post only or not
mmp	boolean	Indicate mmp order or not
reorder_index	integer	Sorting index for internal use
created_at	integer	Timestamp at order creation (milliseconds since the Unix epoch)
updated_at	integer	Timestamp at order update (milliseconds since the Unix epoch)

User Trade Channel

{
    "type":"subscribe",
    "channels":[
        "user_trade"
    ],
    "pairs":[
        "BTC-USDT"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"user_trade",
    "timestamp":1643101722258,
    "module":"linear",
    "data":[
        {
            "created_at":1643101722020,
            "fee":"0.00000000",
            "fee_rate":"0.00010000",
            "index_price":"36214.05400000",
            "instrument_id":"BTC-USDT-PERPETUAL",
            "is_block_trade":false,
            "is_taker":true,
            "label":"",
            "order_id":"1034149",
            "order_type":"limit",
            "price":"36219.85000000",
            "qty":"0.00100000",
            "side":"buy",
            "sigma":"0.00000000",
            "trade_id":"1005590992",
            "underlying_price":"",
            "usd_price":""
        }
    ]
}

User Trade pushes user trade information

Channel Information

Channel	Scope	Arguments	Interval
user_trade	private	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
order_id	string	Order ID
trade_id	string	Trade ID
instrument_id	string	Instrument ID
order_type	string	User Order type
side	string	User Order side
price	string	Trade price
qty	string	Trade quantity
fee	string	Transaction fees
fee_rate	string	Fee rate
sigma	string	Imply volatility
is_taker	boolean	Is taker or not
is_block_trade	boolean	Is block trade or not
index_price	string	Index price
underlying_price	string	Underlying price, option only
usd_price	string	USD price of auto price order
label	string	Order label of related trade
created_at	integer	Timestamp at trade creation (milliseconds since the Unix epoch)

MMP Frozen Event Channel

{
    "type":"subscribe",
    "channels":[
        "mmp_frozen"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"mmp_frozen",
    "timestamp":1643101722258,
    "module":"linear",
    "data":{
        "pair":"BTC-USD",
        "frozen_until_ms":1643101725000
    }
}

MMP Frozen pushes MMP frozen event

frozen_until_ms indicate MMP frozen status.
frozen_until_ms > 0: frozen until this timestamp or a manual reset
frozen_until_ms = 0: frozen until a manual reset

Channel Information

Channel	Scope	Arguments	Interval
mmp_frozen	private	pairs	[`raw`, `100ms`]

for USD-M system, MMP Frozen Event argument is paris

Response

Name	Type	Description
pair	string	Currency pair
frozen_until_ms	integer	MMP frozen until timestamp

Constant definitions

Account Mode

Account mode	Description
classic	Classic mode
um	Unified margin mode
migrating-to-um	Migrating from classic to um (transient state)
migrating-to-classic	Migrating from um to classic (transient state)

Risk mode

Mode	Description
regular	Regular account
portfolio_margin	Determines margin requirements base on future & option portfolio

Instrument Category

Category	Description
option	Options
future	Future (include perpetual)

Option type

Option type	Description
call	Call option
put	Put option

Order side

Order side	Description
buy	Buy
sell	Sell

Order type

To place market order, client input order_type = market
Since market order is translated into special limit order in system, client will see limit(m) for market order in API order query response

OrderType	Description
limit	Limit order
market	Market order
trigger-limit	Trigger limit order
trigger-market	Trigger market order

Order status

Status	Description
pending	Order initial state
open	Order active state
filled	Order fully filled
cancelled	Order is cancelled

ConditionalOrder status

Status	Description
open	Conditional Order is active
triggered	Conditional order is triggered
cancelled	Conditional order is cancelled without being triggered

Order time in force

Status	Description
gtc	Good till cancel
fok	Fill or kill
ioc	Immediate or cancel

Usdx Order auto price type

Option only

Type	Description
base	Place order with base currency price
iv	Place order with imply volatility

Order source

Order source	Description
api	From API
web	From Web GUI
app	From mobile app

UM transaction log type

Um Tx log type	Description
spot-trade-pay	Paying out cash for spot trade
spot-trade-recv	Receiving cash of spot trade
deri-trade	COIN-M trade
deri-delivery	COIN-M delivery
deri-settlement	COIN-M settlement
deri-socialized-fund	COIN-M socialized fund
usdx-trade	USD-M trade
usdx-delivery	USD-M delivery
usdx-settlement	USD-M settlement
usdx-socialized-fund	USD-M socialized fund
pay-accrued-interest	Paying interest
um-pex-trade-pay	Auto sell
um-pex-trade-recv	Auto buy
deposit	Deposit
bad-deposit	Deposit rollback
withdraw	Withdraw
withdraw-revert	Withdraw refund
transfer-in	Fund transfer in
transfer-out	Fund transfer out

Errors

Coin-margined contract error codes