API Reference

NAV Navbar
json

USDT-M Futures Changelogs

version time content
V0.1.2
2022 JUN 2
* Add Kline resolutions(minutes): 360, 720
V0.1.1
2022 APR 22
* Add 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)

API hosts (testnet)

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.

API summary

Path Method Description Scope Rate Limit Type Permission
/linear/v1/orders POST Place new order private trade USDT-M futures trade
/linear/v1/cancel_orders POST Cancel order private trade USDT-M futures trade
/linear/v1/close_positions POST Close positions private trade USDT-M futures trade
/linear/v1/amend_orders POST Amend order private trade USDT-M futures trade
/linear/v1/batchorders POST Place multiple orders private trade USDT-M futures trade
/linear/v1/amend_batchorders POST Amend multiple orders private trade USDT-M futures 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/settlements GET Query user settlements private others read
/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 /
/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"

Response

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

Get server timestamp

Query Parameters

None

Response

Name Type Description
data string Server timestamp

Get system version

GET /linear/v1/system/version

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

Response

{
  "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"

Response


{
    "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"

Response

{
    "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"

Response

{
  "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 "" Category
active boolean false true Set true to query active instruments

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 tickers

GET /linear/v1/tickers

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

Response


{
  "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": "34980.27000000",
    "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 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"

Response

{
  "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"

Response

{
  "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
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
offset int false 1 Page index, first page = 1
limit int false 100 Page size

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"

Response

{
  "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 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"

Response


{
  "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

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=USDT&instrument_id=BTC-USDT-PERPETUAL"

Response


{
  "code": 0,
  "message": "",
  "data": [
    {
      "instrument_id": "BTC-USDT-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 false "option" 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"

Response


{
  "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"

Response


{
    "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"

Response

{
  "code": 0,
  "message": "",
  "data": {
    "total_usdx_volume24_hours": "1605299277.97876500",
    "details": [
      {
        "margin_currency": "USDT",
        "volume_in_usd": "1605299277.97876500"
      }
    ]
  }
}

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_volume24_hours string Total volume
details array Volume details

details

Name Type Description
margin_currency string Margin Currency
volume_in_usd string 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"

Response


{
    "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",
        "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"
    }
}


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

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

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

None

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
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
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 Account 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

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" 


Response

{
    "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
    }
}

USDT-M Futures 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 "" 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 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" 

Response

{
    "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" 

Response

{
    "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
category string false "" Category
instrument_id string false "" Instrument ID

Response

Name Type Desc
instrument_id string Instrument ID
qty string Signed position size
qty_base string Signed position size in 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
liq_price string Reserved field
leverage string Position leverage (Future only)

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" 


Response

{
    "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
currency string true "" Margin Currency
category string false "" Category
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

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"}' 


Response

{
    "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.


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

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 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"}' 


Response

{
    "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)
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

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 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", "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}' 



Response

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

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

Post json body

Parameter Type Required Default Description
currency string true "" Margin currency
order_id string false "" Order ID
order_id_list string false "" Order id list in csv format, e.g: 1,2,3
category string false "" Category
instrument_id string false "" Instrument ID
label string false "" Order label

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", "price": "49000", "timestamp": 1590760362688, "signature": "a74dda0f2bdaf1e1587a5e7577a281497cb66607166bd3b7e0cc4c805c750bf1"}' 



Response

{
    "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 is 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
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 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", "price": "50000", "qty": "1.3"}, {"order_id": "invalid-order-id", "price": "50000", "qty": "0.2"}], "timestamp": 1597313835731, "signature": "c8b5fddd5f2cfa1517854dc54c51e7c3b79af91f0927ea1389ba43dbeee45652"}' 


Response

{
    "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 is 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)
Parameter Type Required Default Description
currency string true "" Margin currency
order_id string true "" Order 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 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"}' 




Response



{
    "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 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" 

Response

{
    "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
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 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 USDT-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" 


Response



{
    "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
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
offset int false 1 Page index, first page = 1
limit int false 100 Page size

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 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 USDT-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" 


Response


{
    "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
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" 

Response

{
    "code": 0,
    "message": "",
    "data": {
        "buy_margin": "70.93672651",
        "sell_margin": "100.13000000",
        "min_sell": "34890.97000000",
        "max_buy": "35953.65000000",
        "usdt_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
usdt_index_price string USDT 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" 


Response

{
    "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
instrument_id string false "" Instrument ID
status string false "" Conditional Order status
start_time integer false Start timestamp
end_time integer false End timestamp
offset int false 1 Page index, first page = 1
limit int false 100 Page size

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

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 USDT-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

Request

{
    "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"
}

Response (success)

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

Response (failure)

{
    "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:

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

Request

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

Response

{
    "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

Depth Channel

Request

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

Response (snapshot)

{
    "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""
            ]
        ]
    }
}

Response (update)

{
    "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

Request

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

Response

{
    "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

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

Request

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

Response

{
    "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

Request

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

Response

{
    "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

Request

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

Response

{
    "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

Request

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

Response

{
    "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

Request

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

Response

{
    "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

Request

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

Response

{
    "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

Request

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

Response

{
    "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

Request

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

Response

{
    "channel":"um_account",
    "timestamp":1632439007081,
    "module":"um",
    "data": {
        "user_id": 1,
        "created_at": 1632642549581,
        "usdt_total_collateral": "200.00000000",
        "usdt_total_margin_balance": "190.00000000",
        "usdt_total_available": "80.00000000",
        "usdt_total_initial_margin": "90.00000000",
        "usdt_total_maintenance_margin": "120.00000000",
        "usdt_total_initial_margin_ratio": "0.60000000",
        "usdt_total_maintenance_margin_ratio": "0.60000000",
        "usdt_total_liability": "8060000.00000000",
        "usdt_total_unsettled_amount": "322143.95604395",
        "spot_orders_hc_loss": "30.00000000",
        "details": [
            {
                "currency": "BTC",
                "equity": "100.00000000",
                "liability": "0.00000000",
                "usdt_index_price": "40000.00000000",
                "cash_balance": "100.00000000",
                "margin_balance": "100.00000000",
                "available_balance": "50.00000000",
                "initial_margin": "20.00000000",
                "spot_margin": "30.00000000",
                "maintenance_margin": "80.00000000",
                "potential_liability": "0.00000000",
                "interest": "1.00000000",
                "interest_rate": "0.01000000",
                "pnl": "0.11538462",
                "total_delta": "0.38461538",
                "session_rpl": "10.00000000",
                "session_upl": "0.11538462",
                "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.11538462",
                "future_session_rpl": "10.00000000",
                "future_session_upl": "0.11538462",
                "future_session_funding": "10.00000000",
                "future_delta": "0.38461538",
                "future_available_balance": "0.00200000",
                "option_available_balance": "0.00200000",
                "unsettled_amount": "9.11538462"
            },
            {
                "currency": "USDT",
                "equity": "-8000000.00000000",
                "liability": "8000000.00000000",
                "usdt_index_price": "1.00000000",
                "cash_balance": "-8000000.00000000",
                "margin_balance": "-8000000.00000000",
                "available_balance": "0.00000000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "8000000.00000000",
                "interest": "300.00000000",
                "interest_rate": "0.00500000",
                "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": "0.00000000",
                "option_available_balance": "0.00000000",
                "unsettled_amount": "-300.00000000"
            }
        ]
    }
}

UM mode: subscribe um_accountchannnel to get UM account information.

Channel Information

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

Response

Name Type Description
user_id int User Id
created_at int Timestamp (query time)
usdt_total_collateral string USDT Total Collateral
usdt_total_margin_balance string USDT Total Margin Balance
usdt_total_available string USDT Total Available
usdt_total_initial_margin string USDT Total Initial Margin
usdt_total_maintenance_margin string USDT Total Maintenance Margin
usdt_total_initial_margin_ratio string USDT Total Initial Margin Ratio, may returns "infinity"
usdt_total_maintenance_margin_ratio string USDT Total Maintenance Margin Ratio, may returns "infinity"
usdt_total_liability string USDT total liability
usdt_total_unsettled_amount string USDT total unsettled amount
spot_orders_hc_loss string Total spot order haircut loss
details array of Detail Details, array of currency level detail
Name Type Description
currency string Currency
equity string Equity
liability string Liability
usdt_index_price string USDT 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 Account 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

Request

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

Response

{
    "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

Request

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

Response

{
    "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 Auto price type, option only
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

Request

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

Response

{
    "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)

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

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

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 Derivative trade
deri-delivery Derivative delivery
deri-settlement Derivative settlement
deri-socialized-fund Derivative 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