简体中文
NAV Navbar
console

Introduction

Welcome to the official documentation for the Bybit APIs and Websocket! Here you can find details on how to access all of our endpoints, their respective expected outputs, and possible errors you may encounter.

If you encounter an issue you need help with, have a suggestions for us, or just want to have a chat with fellow developers then please head on over to our API Telegram chat!

Bybit API Resources

Changelog

2020-05-21

REST API

2020-05-18

REST API

2020-04-29

REST API

Websocket API

2020-04-27

REST API

2020-04-18

REST API

2020-04-17

REST API

2020-04-14

REST API

2020-04-09

REST API

2020-04-07

REST API

2020-03-31

REST API

Websocket API

2020-03-27

REST API

Websocket API

Authentication

All requests made to private endpoints must be authenticated. Requests made to public endpoints do not require the additional parameters needed for authentication.

Parameters for Authenticated Endpoints

The following parameters must be used for authentication:

Additionally, we offer the recv_window, which indicates for how long an HTTP request is valid. This should be sent in milliseconds. Default value: 5000. It used to prevent replay attacks.

A smaller recv_window is more secure, but your request may fail if the transmission time is greater than your recv_window.

Please ensure that your timestamp is synced with our server time. You can use the Server Time endpoint.

Constructing the Request

An example for adjusting leverage

param_str = "api_key=B2Rou0PLPpGqcU0Vu2&leverage=100&symbol=BTCUSD&timestamp=1542434791747"

# api_key=B2Rou0PLPpGqcU0Vu2&
# leverage=100&
# symbol=BTCUSD&
# timestamp=1542434791747

Note how the parameters are ordered in alphabetical order, with api_key first followed by leverage, then symbol, then timestamp.

1. Concatenate all the public parameters in the query string format. The parameters must be ordered in alphabetical order. This will be used to generate the sign.

2. Sign the parameters string.

Different requests need different message formats. Message format for GET requests:

GET /user/leverage?api_key=B2Rou0PLPpGqcU0Vu2&timestamp=1542434791000&sign=670e3e4aa32b243f2dedf1dafcec2fd17a440e71b05681550416507de591d908 HTTP/1.1
Host: api-testnet.bybit.com

Message format for POST requests:

POST /user/leverage/save HTTP/1.1
Host: api-testnet.bybit.com
Content-Type: application/json

{
    "api_key": "B2Rou0PLPpGqcU0Vu2",
    "leverage": 100,
    "symbol": "BTCUSD",
    "timestamp": 1542434791000,
    "sign": "670e3e4aa32b243f2dedf1dafcec2fd17a440e71b05681550416507de591d908"
}

3. Append the signature at the end of the parameters string, and send the HTTP request. Please note that the format for messages is different depending on whether you are sending a GET or POST request.

Market Data Endpoints

The following market data endpoints do not require authentication.

Orderbook

Please see the shared endpoint.

Query Kline

Curl Example

curl https://api.bybit.com/public/linear/kline?symbol=BTCUSDT&interval=1&limit=2&from=1581231260

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [{
        "id": 3866948,
        "symbol": "BTCUSDT",
        "period": "1",
        "start_at": 1577836800,
        "volume": 1451.59,
        "open": 7700,
        "high": 999999,
        "low": 0.5,
        "close": 6000
    },
    {
        "id": 3866948,
        "symbol": "BTCUSDT",
        "period": "1",
        "start_at": 1577836800, // Abandoned!!
        "volume": 1451.59,
        "open": 7700,           // Abandoned!!
        "high": 999999,
        "low": 0.5,
        "close": 6000,
        "interval": 1,
        "open_time": 1577836800,
        "turnover": 2.4343353100000003,
    }],
    "time_now": "1581928016.558522"
}

Get kline.

For mark price klines, see the Mark Price Kline endpoint.

HTTP Request

GET /public/linear/kline

Request Parameters

parameter required type comments
symbol true string
interval true string Data refresh interval. Enum : 1 3 5 15 30 60 120 240 360 720 "D" "M" "W" "Y"
from true integer From timestamp in seconds
limit false integer Limit for data size, max size is 200. Default as showing 200 pieces of data

Latest Information for Symbol

Please see the shared endpoint.

Public Trading Records

Curl Example

curl https://api.bybit.com/public/linear/recent-trading-records?symbol=BTCUSDT&limit=500

Response Example

{
    "ret_code": 0,                                   // error code 0 means success
    "ret_msg": "OK",                                 // error message
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "id": "18368131384",                            // ID, string type, all ids are in descending order globally
            "symbol": "BTCUSDT",                            // contract type
            "price": 9499.5,                                // execution price
            "qty": 9500,                                    // execution quantity
            "side": "Buy",                                  // side
            "time": "2019-11-19T08:03:04.077Z",             // Abandoned!!
            "trade_time_ms":1587638305175
        }
    ],
    "time_now": "1567109419.049271"
}

Get recent trades. You can find a complete history of trades on Bybit here.

HTTP Request

GET /public/linear/recent-trading-records

Request Parameters

parameter required type comments
symbol true string
limit false int Number of results. Default 500; max 1000

Query Symbol

Please see the shared endpoint.

Liquidated Orders

Please see the shared endpoint.

Get the Last Funding Rate

Curl Example

curl https://api.bybit.com/public/linear/funding/prev-funding-rate?symbol=BTCUSDT

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":{
        "symbol":"BTCUSDT",
        "funding_rate":-0.00005965,
        "funding_rate_timestamp":"2020-04-07T08:00:00.000Z"
    },
    "time_now":"1586251109.454281"
}

The funding rate is generated every 8 hours at 00:00 UTC, 08:00 UTC and 16:00 UTC. For example, if a request is sent at 12:00 UTC, the funding rate generated earlier that day at 08:00 UTC will be sent.

HTTP Request

GET /public/linear/funding/prev-funding-rate

Request Parameters

parameter required type comments
symbol true string

Mark Price Kline

Curl Example

curl https://api.bybit.com/public/linear/mark-price-kline?symbol=BTCUSDT&interval=1&limit=2&from=1581231260

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [{
        "id": 3866948,
        "symbol": "BTCUSDT",
        "period": "1",
        "start_at": 1577836800,
        "volume": 1451.59,
        "open": 7700,
        "high": 999999,
        "low": 0.5,
        "close": 6000
    },
    {
        "id": 3866948,
        "symbol": "BTCUSDT",
        "period": "1",
        "start_at": 1577836800,
        "volume": 1451.59,
        "open": 7700,
        "high": 999999,
        "low": 0.5,
        "close": 6000
    }],
    "time_now": "1581928016.558522"
}

Query mark price kline (like Query Kline but for mark price).

HTTP Request

GET /public/linear/mark-price-kline

Request Parameters

parameter required type comments
symbol true string
interval true string Data refresh interval. Enum : 1 3 5 15 30 60 120 240 360 720 "D" "M" "W" "Y"
from true integer From timestamp in seconds
limit false integer Limit for data size, max size is 200. Default as showing 200 pieces of data

Account Data Endpoints

The following account data endpoints require authentication.

Active Orders

Place Active Order

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
        "user_id": 1,
        "symbol": "BTCUSDT",
        "side": "Sell",
        "order_type": "Limit",
        "price": 8083,
        "qty": 10,
        "time_in_force": "GoodTillCancel",
        "order_status": "New",
        "last_exec_price": 8083,    //Last execution price
        "cum_exec_qty": 0,          //Cumulative qty of trading
        "cum_exec_value": 0,        //Cumulative value of trading
        "cum_exec_fee": 0,          //Cumulative trading fees
        "reduce_only": false,       //true means close order, false means open close
        "order_link_id": "",
        "created_time": "2019-10-21T07:28:19.396246Z",
        "updated_time": "2019-10-21T07:28:19.396246Z",
    },
    "time_now": "1575111823.458705",
    "rate_limit_status": 98,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Market price active order: A traditional market price order which will be filled at the best available price. price is not required for this type of order.

Limit price active order: You can set an execution price for your order. Only when the last traded price reaches the order price will the system will fill your order.

Take profit/Stop loss: You may only set a TP/SL conditional order upon opening the position. Once you hold a position, any new active order requests which contain TP/SL data will be accepted but TP/SL data will be ignored. tp_trigger_by/sl_trigger_by default to LastPrice. Passing values to the take_profit or stop_loss parameters in this endpoint will create conditional orders managed by the system, which will be be automatically cancelled if the position is closed.

Order quantity: This parameter indicates the quantity of perpetual contracts you want to buy or sell. This must modulo by 0.5 (20 and 21.5 are accepted, but 16.1 or 16.15 are not).

Order price: If it is a condition order, this parameter is required. When there is no position, the long commission price should be 10% higher than the market price and less than 1 million. If there are positions, they need to be better than strong parity. For the minimum unit of price increase or decrease, please refer to the price_filter field in the Query Symbols endpoint.

Custom order ID: You may customise order IDs for active orders. We will link it to the system order ID, and return the unique system order ID to you after the active order is created successfully. You may use this order ID or your custom order ID to cancel your active order. The customised order ID should be unique, with a maximum length of 36 characters.

Each account can hold up to 500 active orders yet to be filled entirely simultaneously. This is per instrument, so it's possible to have, for example, 300 active orders on the BTCUSDT instrument and 280 active orders on the ETHUSDT instrument. And order with parameter reduce_only or closeOnTrigger is unlimited.

HTTP Request

POST /private/linear/order/create

Request Parameters

parameter required type comments
side true string Side
symbol true string
order_type true string Active order type
qty true number Order quantity in BTC.
price false number Order price. Required if you make limit price order
time_in_force true string Time in force
take_profit false number Take profit price, only take effect upon opening the position
stop_loss false number Stop loss price, only take effect upon opening the position
tp_trigger_by false string Trigger price type. Default LastPrice
sl_trigger_by false string Trigger price type. Default LastPrice
reduce_only true bool What is a reduce-only order? True means your position can only reduce in size if this order is triggered
close_on_trigger true bool What is a close on trigger order? For a closing order. It can only reduce your position, not increase it. If the account has insufficient available balance when the closing order is triggered, then other active orders of similar contracts will be cancelled or reduced. It can be used to ensure your stop loss reduces your position regardless of current available margin.
order_link_id false string Customised order ID, maximum length at 36 characters, and order ID under the same agency has to be unique.

Get Active Order

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
        "current_page": 1,
        "last_page": 6,
        "data": [
            {
                "order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
                "user_id": 1,
                "symbol": "BTCUSDT",
                "side": "Sell",
                "order_type": "Limit",
                "price": 8083,
                "qty": 10,
                "time_in_force": "GoodTillCancel",
                "order_status": "New",
                "last_exec_price": 8083,
                "cum_exec_qty": 0,
                "cum_exec_value": 0,
                "cum_exec_fee": 0,
                "order_link_id": "",
                "reduce_only": false,
                "created_time": "2019-10-21T07:28:19.396246Z",
                "updated_time": "2019-10-21T07:28:19.396246Z",
            }
        ]
    },
    "ext_info": null,
    "time_now": "1577448922.437871",
    "rate_limit_status": 98,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Get my active order list.

Cause order creation/cancellation is asynchronous, sometimes there is a data delay in this endpoint. You can get real-time order info in Query Active Order (real-time) endpoint.

HTTP Request

GET /private/linear/order/list

Request Parameters

parameter required type comments
order_id false string Order ID
order_link_id false string Customised order ID, maximum length at 36 characters, and order ID under the same agency has to be unique.
symbol true string
order false string Sort orders by creation date
page false integer Page. Default getting first page data
limit false integer Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page
order_status false string Query your orders for all statuses if 'order_status' is empty. If you want to query orders with specific statuses, you can pass the order_status split by ','.

Cancel Active Order

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
    },
    "time_now": "1575112681.814760",
    "rate_limit_status": 98,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Either order_id or order_link_id are required for cancelling active orders. order_id - this unique 36 characters order ID was returned to you when the active order was created successfully.

You may cancel active orders that are unfilled or partially filled. Fully filled orders cannot be cancelled.

HTTP Request

POST /private/linear/order/cancel

Request Parameters

parameter required type comments
symbol true string
order_id false string Order ID. Required if not passing order_link_id
order_link_id false string Agency customized order ID. Required if not passing order_id

Cancel All Active Orders

Response Example

{
    "ret_code": 0,      
    "ret_msg": "OK",    
    "ext_code": "",     
    "ext_info": "",
    "result": [
        "89a38056-80f1-45b2-89d3-4d8e3a203a79",  
        "89a38056-80f1-45b2-89d3-4d8e3a203a79",  
    ],
    "time_now": "1575110339.105675",
    "rate_limit_status": 98,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Cancel all active orders that are unfilled or partially filled. Fully filled orders cannot be cancelled.

HTTP Request

POST /private/linear/order/cancel-all

Request Parameters

parameter required type comments
symbol true string

Query Active Order (real-time)

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
        "user_id": 1,
        "symbol": "BTCUSDT",
        "side": "Sell",
        "order_type": "Limit",
        "price": 8083,
        "qty": 10,
        "time_in_force": "GoodTillCancel",
        "order_status": "New",
        "last_exec_price": 8083,
        "cum_exec_qty": 0,
        "cum_exec_value": 0,
        "cum_exec_fee": 0,
        "reduce_only": false,
        "order_link_id": "",
        "created_time": "2019-10-21T07:28:19.396246Z",
        "updated_time": "2019-10-21T07:28:19.396246Z",
    },
    "time_now": "1571651135.291930",
    "rate_limit_status": 99, // The remaining number of accesses in one minute
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Query real-time active order information.

HTTP Request

GET /private/linear/order/search

Request Parameters

parameter required type comments
order_id false string Order ID. Required if not passing order_link_id
order_link_id false string Agency customized order ID. Required if not passing order_id
symbol true string

Conditional Orders

Place Conditional Order

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
       "stop_order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
       "user_id": 1,
       "symbol": "BTCUSDT",
       "side": "Sell",
       "order_type": "Limit",
       "price": 8083,
       "qty": 10,
       "time_in_force": "GoodTillCancel",
       "order_status": "New",
       "trigger_price": 8003,
       "order_link_id": "",
       "created_at": "2019-10-21T07:28:19.396246Z",
       "updated_at": "2019-10-21T07:28:19.396246Z",
    },
    "ext_info": null,
    "time_now": "1577450904.327654",
    "rate_limit_status": 99,
    "rate_limit_reset_ms": 1577450904335,
    "rate_limit": "100"
}

Market price conditional order: A traditional market price order, will be filled at the best available price. price is not required for this type of order.

Limit price conditional order: You can set an execution price for your order. Only when the last traded price reaches the order price will the system will fill your order.

Take profit/Stop loss: You may only set a take-profit/stop-loss conditional order upon opening the position. Once you hold a position, the take profit and stop loss information you sent when placing an order will no longer be valid.

Order quantity: This parameter indicates the quantity of perpetual contracts you want to buy or sell, currently Bybit only support order quantity in an integer.

Order price: If it is a condition order, this parameter is required. When there is no position, the long commission price should be 10% higher than the market price and less than 1 million. If there are positions, they need to be better than strong parity. For the minimum unit of price increase or decrease, please refer to the price_filter field in the Query Symbols endpoint.

Conditional order trigger price: You may set a trigger price for your conditional order. conditional order will not enter the order book until the last price hits the trigger price. When last price hits trigger price: 1) your limit conditional order will enter order book, and wait to be executed; 2) your market conditional order will be executed immediately at the best available market price.

Customize conditional order ID: You may customize order IDs for active orders. We will link it to the system order ID , and return the unique system order ID to you after the active order is created successfully. You may use this order ID to cancel your active order. The customized order ID is asked to be unique, with a maximum length of 36 characters.

HTTP Request

POST /private/linear/stop-order/create

Request Parameters

parameter required type comments
side true string Side
symbol true string
order_type true string Conditional order type
qty true number Order quantity in BTC.
price false number Execution price for conditional order. Required if you make limit price order
base_price true number It will be used to compare with the value of stop_px, to decide whether your conditional order will be triggered by crossing trigger price from upper side or lower side. Mainly used to identify the expected direction of the current conditional order.
stop_px true number Trigger price
time_in_force true string Time in force
trigger_by false string Trigger price type. Default LastPrice
close_on_trigger true bool What is a close on trigger order? For a closing order. It can only reduce your position, not increase it. If the account has insufficient available balance when the closing order is triggered, then other active orders of similar contracts will be cancelled or reduced. It can be used to ensure your stop loss reduces your position regardless of current available margin.
order_link_id false string Customised order ID, maximum length at 36 characters, and order ID under the same agency has to be unique.
reduce_only true bool What is a reduce-only order? True means your position can only reduce in size if this order is triggered

Get Conditional Order

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
        "current_page": 1,
        "last_page": 1,
        "data": [
            {
                 "stop_order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
                 "user_id": 1,
                 "symbol": "BTCUSDT",
                 "side": "Sell",
                 "order_type": "Limit",
                 "price": 8083,
                 "qty": 10,
                 "time_in_force": "GoodTillCancel",
                 "order_status": "New",
                 "trigger_price": 8003,
                 "order_link_id": "",
                 "created_at": "2019-10-21T07:28:19.396246Z",
                 "updated_at": "2019-10-21T07:28:19.396246Z",
            },
            {
                 "stop_order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
                 "user_id": 1,
                 "symbol": "BTCUSDT",
                 "side": "Sell",
                 "order_type": "Limit",
                 "price": 8083,
                 "qty": 10,
                 "time_in_force": "GoodTillCancel",
                 "order_status": "New",
                 "trigger_price": 8003,
                 "order_link_id": "",
                 "created_at": "2019-10-21T07:28:19.396246Z",
                 "updated_at": "2019-10-21T07:28:19.396246Z",
            }
        ]
    },
    "ext_info": null,
    "time_now": "1577451658.755468",
    "rate_limit_status": 599,
    "rate_limit_reset_ms": 1577451658762,
    "rate_limit": 600
}

Get my conditional order list.

Cause order creation/cancellation is asynchronous, sometimes there is a data delay in this endpoint. You can get real-time order info in Query Conditional Order (real-time) endpoint.

HTTP Request

GET /private/linear/stop-order/list

Request Parameters

parameter required type comments
stop_order_id false string Your conditional order ID. The unique order ID returned to you when the corresponding active order was created
order_link_id false string Customised order ID, maximum length at 36 characters, and order ID under the same agency has to be unique.
symbol true string
stop_order_status false string stop order status
order false string Sort orders by creation date
page false integer Page. Default getting first page data
limit false integer Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page

Cancel Conditional Order

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
         "stop_order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
    },
    "ext_info": null,
    "time_now": "1577452218.567120",
    "rate_limit_status": 97,
    "rate_limit_reset_ms": 1577452218573,
    "rate_limit": "100"
}

You may cancel all untriggered conditional orders. Essentially, after a conditional order is triggered, it will become an active order. So, when a conditional order is triggered, cancellation has to be done through the active order endpoint for any unfilled or partially filled active order. As always, orders that have been fully filled cannot be cancelled.

HTTP Request

POST /private/linear/stop-order/cancel

Request Parameters

parameter required type comments
symbol true string
stop_order_id false string Order ID. Required if not passing order_link_id
order_link_id false string Agency customized order ID. Required if not passing stop_order_id

Cancel All Conditional Orders

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        "89a38056-80f1-45b2-89d3-4d8e3a203a79",  
        "89a38056-80f1-45b2-89d3-4d8e3a203a79",
    ],
    "time_now": "1577454993.799912",
    "rate_limit_status": 90,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Cancel all untriggered conditional orders.

HTTP Request

POST /private/linear/stop-order/cancel-all

Request Parameters

parameter required type comments
symbol true string

Query Conditional Order (real-time)

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "stop_order_id":"bd1844f-f3c0-4e10-8c25-10fea03763f6",
        "user_id": 1,
        "symbol": "BTCUSDT",
        "side": "Sell",
        "order_type": "Limit",
        "price": 8083,
        "qty": 10,
        "time_in_force": "GoodTillCancel",
        "order_status": "New",
        "trigger_price": 8003,
        "order_link_id": "",
        "created_at": "2019-10-21T07:28:19.396246Z",
        "updated_at": "2019-10-21T07:28:19.396246Z",
    },
    "time_now": "1577476584.386958",
    "rate_limit_status": 99,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Query real-time stop order information.

HTTP Request

GET /private/linear/stop-order/search

Request Parameters

parameter required type comments
symbol true string
stop_order_id false string Order ID. Required if not passing order_link_id
order_link_id false string Agency customized order ID. Required if not passing order_id

Position

My Position

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
       {
               "user_id":100004,
               "symbol":"BTCUSDT",
               "side":"Buy",
               "size":0,
               "position_value":0,      //Current position value
               "entry_price":0,         //Average opening price
               "liq_price":1,           //Liquidation price
               "bust_price":100,        //Bust price
               "leverage":0,
               "position_margin":0,     //Position margin
               "occ_closing_fee":0,     //Pre-occupancy closing fee
               "realised_pnl":0,        //Today's realised Profit and Loss
               "cum_realised_pnl":0,    //Cumulative realised Profit and Loss
               "free_qty": 30,          //Can be to closing Qty
           },
           {
               "user_id":100004,
               "symbol":"BTCUSDT",
               "side":"Buy",
               "size":0,
               "position_value":0,
               "entry_price":0,
               "liq_price":1,
               "bust_price":100,
               "leverage":0,
               "position_margin":0,
               "occ_closing_fee":0,
               "realised_pnl":0,
               "cum_realised_pnl":0,
               "free_qty": 30,
           }
    ],
    "time_now": "1577480599.097287",
    "rate_limit_status": 119,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 120
}

Get my position list.

HTTP Request

GET /private/linear/position/list

Request Parameters

parameter required type comments
symbol true string

Set Auto Add Margin

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": null,
    "time_now": "1586780385.549188",
    "rate_limit_status": 74,
    "rate_limit_reset_ms": 1586780385547,
    "rate_limit": 75
}

Set auto add margin, or Auto-Margin Replenishment.

HTTP Request

POST /private/linear/position/set-auto-add-margin

Request Parameters

parameter required type comments
symbol true string
side true string Side
auto_add_margin true bool Auto add margin button

Set Leverage

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": null,
    "time_now": "1585881527.650138",
    "rate_limit_status": 74,
    "rate_limit_reset_ms": 1585881527648,
    "rate_limit": 75
}

Set Leverage

HTTP Request

POST /private/linear/position/set-leverage

Request Parameters

parameter required type comments
symbol true string
buy_leverage true number Must be greater than 0 and less than the risk limit leverage.
sell_leverage true number Must be greater than 0 and less than the risk limit leverage.

Cross/Isolated Margin Switch

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": null,
    "time_now": "1585881597.006026",
    "rate_limit_status": 74,
    "rate_limit_reset_ms": 1585881597004,
    "rate_limit": 75
}

Switch Cross/Isolated; must be leverage value when switching from Cross to Isolated

HTTP Request

POST /private/linear/position/switch-isolated

Request Parameters

parameter required type comments
symbol true string
is_isolated true bool Cross/Isolated: true is Isolated; false is Cross
buy_leverage true number Must be greater than 0 and less than the risk limit leverage.
sell_leverage true number Must be greater than 0 and less than the risk limit leverage.

Set Trading-Stop

Response Example

{
  "ret_code": 0,
  "ret_msg": "OK",
  "ext_code": "",
  "ext_info": "",
  "result": null,
  "time_now": "1586780408.193508",
  "rate_limit_status": 73,
  "rate_limit_reset_ms": 1586780408191,
  "rate_limit": 75
}

Set take profit, stop loss, and trailing stop for your open position.

HTTP Request

POST /private/linear/position/trading-stop

Request Parameters

parameter required type comments
symbol true string
side true string Side
take_profit false number Cannot be less than 0, 0 means cancel TP
stop_loss false number Cannot be less than 0, 0 means cancel SL
trailing_stop false number Cannot be less than 0, 0 means cancel TS
tp_trigger_by false string Trigger price type. Default LastPrice
sl_trigger_by false string Trigger price type. Default LastPrice

Add/Reduce Margin

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "PositionListResult": {
            "user_id": 160815,
            "symbol": "BTCUSDT",
            "side": "Buy",
            "size": 3.14,
            "position_value": 18843.14,
            "entry_price": 6001,
            "liq_price": 5428,
            "bust_price": 5398,
            "leverage": 10,
            "position_margin": 1907.0331195,
            "occ_closing_fee": 12.71229,
            "realised_pnl": 3052.20905294,
            "cum_realised_pnl": 75628.40815795,
            "free_qty": 0
        },
        "wallet_balance": 68738.01696765,
        "available_balance": 66830.98384815
    },
     "time_now": "1577480599.097287",
     "rate_limit_status": 119,
     "rate_limit_reset_ms": 1580885703683,
     "rate_limit": 120
}

Add Margin

HTTP Request

POST /private/linear/position/add-margin

Request Parameters

parameter required type comments
symbol true string
side true string Side
margin true number Add/Remove how much margin: Increase 10; decrease -10, supports 4 decimal places

User Trade Records

Response Example

{
    "ret_code": 0,
        "ret_msg": "OK",
        "ext_code": "",
        "ext_info": "",
        "result": {
            "current_page": 1,
            "data": [
                {
                    "order_id": "7369b2f4-52f1-4698-abf7-368e4ba9aefa",
                    "order_link_id": "",
                    "side": "Buy",  //Side Enum
                    "symbol": "BTCUSDT", //Symbol Enum
                    "exec_id": "9b8216fa-98d7-55c0-b5fa-279db5727996",
                    "price": 5894,//Abandoned!!
                    "order_price": 5894,
                    "order_qty": 0.001,
                    "order_type": "Limit", //Order Type Enum
                    "fee_rate": 0.00075,
                    "exec_price": 5894,
                    "exec_type": "Trade", //Exec Type Enum
                    "exec_qty": 0.001,
                    "exec_fee": 0.0044205,
                    "exec_value": 5.894,
                    "leaves_qty": 0,
                    "closed_size": 0, // The corresponding closing size of the closing order
                    "last_liquidity_ind": "RemovedLiquidity",  //Liquidity Enum
                    "trade_time": 1585547384,//Abandoned!!
                    "trade_time_ms": 1585547384847
                }
            ]
        },
        "time_now": "1577480599.097287",
        "rate_limit_status": 119,
        "rate_limit_reset_ms": 1580885703683,
        "rate_limit": 120
    }

}

Get user's trading records. The results are ordered in descending order (the first item is the latest).

HTTP Request

GET /private/linear/trade/execution/list

Request Parameters

parameter required type comments
symbol true string
start_time false int Start timestamp point for result, in millisecond
end_time false int End timestamp point for result, in millisecond
exec_type false string Execution type
page false integer Page. Default getting first page data
limit false integer Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page.

Closed Profit and Loss

Response Example

{
     "ret_code": 0,
     "ret_msg": "OK",
     "ext_code": "",
     "ext_info": "",
     "result": {
         "current_page": 1,
         "data": [
             {
                 "id": 1710,
                 "user_id": 160815,
                 "symbol": "BTCUSDT",
                 "order_id": "e6a11e08-6dd0-404e-bea7-dc22b7ab0228",
                 "side": "Buy",
                 "qty": 0.5,
                 "order_price": 999999,
                 "order_type": "Market",
                 "exec_type": "Trade",
                 "closed_size": 0.5,        //Closing size
                 "cum_entry_value": 3000,   //Closing position value
                 "avg_entry_price": 6000,   //Average entry price
                 "cum_exit_value": 3000.5,  //Cumulative trading value of closing orders
                 "avg_exit_price": 6001,    //Average exit price
                 "closed_pnl": -5.000375,   //Closed Profit and Loss
                 "fill_count": 1,           //Number of transactions
                 "leverage": 100,
                 "created_at": 1577480599
             }
         ]
     },
     "time_now": "1577480599.097287",
     "rate_limit_status": 119,
     "rate_limit_reset_ms": 1580885703683,
     "rate_limit": 120

}

Get user's closed profit and loss records. The results are ordered in descending order (the first item is the latest).

HTTP Request

GET /private/linear/trade/closed-pnl/list

Request Parameters

parameter required type comments
symbol true string
start_time false int Start timestamp point for result, in second
end_time false int End timestamp point for result, in second
exec_type false string Execution type
page false integer Page. Default getting first page data
limit false integer Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page.

Risk Limit

Get Risk Limit

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "id": 1,
            "symbol": "BTCUSDT",
            "limit": 1000000,
            "maintain_margin": 0.005,
            "starting_margin": 0.01,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "25",
                "50",
                "100"
            ],
            "is_lowest_risk": 1,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 2,
            "symbol": "BTCUSDT",
            "limit": 1500000,
            "maintain_margin": 0.01,
            "starting_margin": 0.015,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "25",
                "50",
                "66"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 3,
            "symbol": "BTCUSDT",
            "limit": 2000000,
            "maintain_margin": 0.015,
            "starting_margin": 0.02,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "25",
                "33",
                "50"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 4,
            "symbol": "BTCUSDT",
            "limit": 2500000,
            "maintain_margin": 0.02,
            "starting_margin": 0.025,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "25",
                "33",
                "40"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 5,
            "symbol": "BTCUSDT",
            "limit": 3000000,
            "maintain_margin": 0.025,
            "starting_margin": 0.03,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "15",
                "25",
                "33"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 6,
            "symbol": "BTCUSDT",
            "limit": 3500000,
            "maintain_margin": 0.03,
            "starting_margin": 0.035,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "15",
                "20",
                "28"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 7,
            "symbol": "BTCUSDT",
            "limit": 4000000,
            "maintain_margin": 0.035,
            "starting_margin": 0.04,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "15",
                "20",
                "25"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 8,
            "symbol": "BTCUSDT",
            "limit": 4500000,
            "maintain_margin": 0.04,
            "starting_margin": 0.045,
            "section": [
                "1",
                "2",
                "3",
                "5",
                "10",
                "15",
                "20",
                "22"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 9,
            "symbol": "BTCUSDT",
            "limit": 5000000,
            "maintain_margin": 0.045,
            "starting_margin": 0.05,
            "section": [
                "1",
                "2",
                "3",
                "4",
                "5",
                "10",
                "15",
                "20"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:28.000Z",
            "updated_at": "2020-01-06T09:45:28.000Z"
        },
        {
            "id": 10,
            "symbol": "BTCUSDT",
            "limit": 5500000,
            "maintain_margin": 0.05,
            "starting_margin": 0.055,
            "section": [
                "1",
                "2",
                "3",
                "4",
                "5",
                "10",
                "15",
                "18"
            ],
            "is_lowest_risk": 0,
            "created_at": "2020-01-06T09:45:29.000Z",
            "updated_at": "2020-01-06T09:45:29.000Z"
        }
    ],
    "time_now": "1586780586.850288"
}

Get risk limit.

HTTP Request

GET /public/linear/risk-limit

Request Parameters

parameter required type comments

Funding

My Last Funding Fee

Curl Example

curl https://api.bybit.com/private/linear/funding/prev-funding?symbol=BTCUSDT

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "symbol": "BTCUSDT",
        "side": "Buy",
        "size": 3.13,
        "funding_rate": 0.0001,
        "exec_fee": 1.868923,
        "exec_time": "2020-04-13T08:00:00.000Z"
    },
    "time_now": "1586780352.867171",
    "rate_limit_status": 119,
    "rate_limit_reset_ms": 1586780352864,
    "rate_limit": 120
}

Get recent trades. You can find a complete history of trades on Bybit here.

HTTP Request

GET /private/linear/funding/prev-funding

Request Parameters

parameter required type comments
symbol true string

Predicted Funding Rate and My Funding Fee

Curl Example

curl https://api.bybit.com/private/linear/funding/predicted-funding?symbol=BTCUSDT

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "predicted_funding_rate": -0.00375,
        "predicted_funding_fee": 0.13081256
    },
    "time_now": "1587035697.424492",
    "rate_limit_status": 119,
    "rate_limit_reset_ms": 1587035697422,
    "rate_limit": 120
}

Get predicted funding rate and my funding fee.

HTTP Request

GET /private/linear/funding/predicted-funding

Request Parameters

parameter required type comments
symbol true string

API Key Info

Please see the shared endpoint.

Wallet Data Endpoints

The following wallet data endpoints require authentication.

Get Wallet Balance

Please see the shared endpoint.

Wallet Fund Records

Please see the shared endpoint.

Withdraw Records

Please see the shared endpoint.

API Data Endpoints

The following API data endpoints do not require authentication.

Server Time

Curl Example

curl https://api-testnet.bybit.com/v2/public/time

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {},
    "time_now": "1577444332.192859"
}

Get Bybit server time.

HTTP Request

GET /v2/public/time

Request Parameters

parameter required type comments

Announcement

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "id": 2,
            "title": "2019-12-02 RELEASE",
            "link": "https://github.com/bybit-exchange/bybit-official-api-docs/blob/master/en/CHANGELOG.md",
            "summary": "<p>New `cancel all` endpoint is here now!</p><p>Additionally, we strongly recommend that you use the new released place and cancel active V2 endpoints, which are more stable and efficient.The old ones are deprecated (although still working for the time be",
            "created_at": "2019-12-02T11:33:42Z"
        }
    ],
    "time_now": "1577444818.227082"
}

Get Bybit OpenAPI announcements in the last 30 days by reverse order.

HTTP Request

GET /v2/public/announcement

Request Parameters

parameter required type comments

API Rate Limits

IP Rate Limit

Bybit has different IP frequency limits for GET and POST method:

Understanding Your Request Rate Limit

Bybit makes frequency limits based on the rolling time window per minute and UID, and each symbol is independent. Every request to the API returns the fields shown in the code panel:

"rate_limit_status": 119,
"rate_limit_reset_ms": 1572114055663,
"rate_limit": 120

Rate Limits For All Private Endpoints

limit path consume
100/min /private/linear/order/create 1 / request
/private/linear/order/cancel 1 / request
/private/linear/order/cancel-all 10 / request
/private/linear/stop-order/create 1 / request
/private/linear/stop-order/cancel 1 / request
/private/linear/stop-order/cancel-all 10 / request
75/min /private/linear/position/set-leverage 1 / request
/private/linear/position/switch-isolated 1 / request
/private/linear/position/set-auto-add-margin 1 / request
/private/linear/position/trading-stop 1 / request
/private/linear/position/add-margin 1 / request
120/min /private/linear/position/list 1 / request
/private/linear/trade/closed-pnl/list 1 / request
/private/linear/trade/execution/list 1 / request
600/min /private/linear/order/list 1 / request
/private/linear/order/search 1 / request
/private/linear/stop-order/list 1 / request
/private/linear/stop-order/search 1 / request
120/min /private/linear/funding/prev-funding 1 / request
/private/linear/funding/predicted-funding 1 / request

Order Limits

The number of orders per instrument that can be held entirely simultaneously:

How to Raise Your API Limit

Understanding Bybit's Liquidity System

Bybit uses an Order Fill Ratio (OFR) and Liquidity Contribution Points (LCP) to measure customers' contribution to our executable liquidity.

The LCP and OFR of different symbols are calculated separately.

Order Fill Ratio (OFR) Threshold

If you place more than 2000 orders per day on Bybit, please maintain your 7-day OFR above a Minimum OFR threshold, or Bybit may reduce your API request frequency limit.

Order Fill Ratio (OFR)

Order Fill Ratio Example
User A:
Orders Filled = 2
Orders Submitted to Bybit = 8
QFR = 2/8 = 25%

User B:
Orders Filled = 1
Orders Submitted to Bybit = 1
QFR = 1/1 = 100%

Minimum OFR Threshold

7-day OFR must be kept above 0.1%.

API Request Frequency Limits

Your API request frequency limit is based on your min Liquidity Contribution Points (LCP) of 7 days.

LCP Order Frequency Limit
20-100 800 times per minute
10-20 600 times per minute
5-10 400 times per minute
2-5 200 times per minute
<2 100 times per minute
Liquidity Contribution Points (LCP)

Explanation
Effective Price Range

Effective Price Range Example
BTC best bid = 10000
BTC best ask = 10001
Effective Price Range: [(10000 + 10001) / 2 - 3* 0.5, (10000 + 10001) / 2 + 3* 0.5] = [9999,10002]

POU

Bybit calculates your amount of orders within effective price range / amount of all your orders in orderbook, and then performs a 1-Day Time-Weighted-Average over the series of seconds rates.

amount of User C's orders within effective price range = 8000
amount of all User C's orders = 2000 + 8000 = 10000
POU = 8000 / 10000 = 0.8

POA

Bybit calculates your amount of orders within effective price range / amount of all orders within effective price range in orderbook, and then performs a 1-Day Time-Weighted-Average over the series of seconds rates.

POA example

User C only has 8000 contracts within effective price range, while Bybit have 200000 contracts within effective price range in orderbook.

amount of User C's orders within effective price range = 8000
amount of all orders within effective price range = 200000
POA = 8000 / 200000 = 0.04

WebSocket Data

Authentication

Authentication methods:

First method: Apply for authentication when establishing a connection.

var api_key = "";
var secret = "";
// A UNIX timestamp after which the request become invalid. This is to prevent replay attacks.
// unit:millisecond
var expires = time.now()+1000;

// Signature
var signature = hex(HMAC_SHA256(secret, 'GET/realtime' + expires));

// Parameters string
var param = "api_key={api_key}&expires={expires}&signature={signature}";

// Establishing connection
var ws = new WebSocket("wsurl?param");

Second method: Apply for authentication after establishing a connection through auth request.

var ws = new WebSocket("wsurl")
// Signature is the same for both methods of authentication
ws.send('{"op":"auth","args":["{api_key}","{expires}","{signature}"]}');

Base endpoints:

There are two methods of authentication, as shown in the code panel to the right.

How to Send the Heartbeat Packet

How to Send

ws.send('{"op":"ping"}');

Response Example

{
    "success": true, // Whether ping is successful
    "ret_msg": "pong",
    "conn_id": "036e5d21-804c-4447-a92d-b65a44d00700",// current connection id
    "request": {
        "op": "ping",
        "args": null
    }
}

How to Subscribe to Topics

Understanding Websocket Filters

How to subscribe with a filter

// Subscribing to the trade data for ETHBTC
ws.send('{"op":"subscribe","args":["trade.ETHBTC"]}')

How to subscribe with multiple filters

// Example: Subscribing to the trade data for BTCUSD and XRPUSD
ws.send('{"op":"subscribe","args":["trade.BTCUSD|XRPUSD"]}')

How to subscribe without filters

// Example: Subscribing to the trade data for all symbols
ws.send('{"op": "subscribe", "args": ["trade.*"]}')

After establishing the connection, one can subscribe to a new topic by sending a JSON request. The specific formats are as follows:

ws.send('{"op": "subscribe", "args": ["topic.filter"]}');

The topic indicates the data you would like to receive whilst the filter parses for the specific data you desire - for example, the symbol. The topic is mandatory but the filter is optional.

To subscribe to more than one topic, simply list multiple topics out, like so:

ws.send('{"op": "subscribe", "args": ["topic.filter", "topic.filter"]}');

It is possible to use multiple filters for the same topic by splitting them with a pipe (|) - of course, these filters must all be applicable to the selected topic.

Finally, to subscribe to the topic without filters please use the * wildcard.

Intervals

Some topics are pushed at intervals. If the args contain a millisecond param, such as 100ms, this topic is pushed at intervals. Otherwise, it is pushed constantly.

Understanding the Subscription Response

Subscription Response

{
   "success": true, // Whether subscription is successful
   "ret_msg": "",   // Successful subscription: "", otherwise it shows error message
   "conn_id":"e0e10eee-4eff-4d21-881e-a0c55c25e2da",// current connection id
   "request": {     // Request to your subscription
       "op": "subscribe",
       "args": [
           "kline.BTCUSD.1m"
       ]
   }
}

Every subscription will have a response.

Public Topics

orderBookL2_25

How to Subscribe

ws.send('{"op": "subscribe", "args": ["orderBookL2_25.BTCUSDT"]}');

Snapshot Response Example - format of the first response

{
     "topic": "orderBookL2_25.BTCUSDT",
     "type": "snapshot",
     "data": [
        {
            "price": "2999.00",
            "symbol": "BTCUSDT",
            "id": 29990000,
            "side": "Buy",
            "size": 9
        },
        {
            "price": "3001.00",
            "symbol": "BTCUSDT",
            "id": 30010000,
            "side": "Sell",
            "size": 10
        }
     ],
     "cross_seq": 11518,
     "timestamp_e6": 1555647164875373
}

Delta Response Example - format of the responses following the snapshot response

{
     "topic": "orderBookL2_25.BTCUSDT",
     "type": "delta",
     "data": {
          "delete": [
             {
                   "price": "3001.00",
                   "symbol": "BTCUSDT",
                   "id": 30010000,
                   "side": "Sell"
             }
          ],
          "update": [
             {
                   "price": "2999.00",
                   "symbol": "BTCUSDT",
                   "id": 29990000,
                   "side": "Buy",
                   "size": 8
             }
          ],
          "insert": [
             {
                   "price": "2998.00",
                   "symbol": "BTCUSDT",
                   "id": 29980000,
                   "side": "Buy",
                   "size": 8
             }
          ],
          "transactTimeE6": 0
     },
     "cross_seq": 11519,
     "timestamp_e6": 1555647221331673
}

Fetches the orderbook with a depth of 25 orders per side.

After the subscription response, the first response will be the snapshot response. This shows the entire orderbook. The data is ordered by price, starting with the lowest buys and ending with the highest sells.

Following this, all responses are in the delta format, which represents updates to the orderbook relative to the last response.

orderBookL2_200

How to Subscribe

ws.send('{"op": "subscribe", "args": ["orderBook_200.100ms.BTCUSDT"]}');

Snapshot Response Example - format of the first response

{
     "topic": "orderBook_200.100ms.BTCUSDT",
     "type": "snapshot",
     "data": [
        {
            "price": "2999.00",
            "symbol": "BTCUSDT",
            "id": 29990000,
            "side": "Buy",
            "size": 9
        },
        {
            "price": "3001.00",
            "symbol": "BTCUSDT",
            "id": 30010000,
            "side": "Sell",
            "size": 10
        }
     ],
     "cross_seq": 11518,
     "timestamp_e6": 1555647164875373
}

Delta Response Example - format of the responses following the snapshot response

{
     "topic": "orderBook_200.100ms.BTCUSDT",
     "type": "delta",
     "data": {
          "delete": [
             {
                   "price": "3001.00",
                   "symbol": "BTCUSDT",
                   "id": 30010000,
                   "side": "Sell"
             }
          ],
          "update": [
             {
                   "price": "2999.00",
                   "symbol": "BTCUSDT",
                   "id": 29990000,
                   "side": "Buy",
                   "size": 8
             }
          ],
          "insert": [
             {
                   "price": "2998.00",
                   "symbol": "BTCUSDT",
                   "id": 29980000,
                   "side": "Buy",
                   "size": 8
             }
          ],
          "transactTimeE6": 0
     },
     "cross_seq": 11519,
     "timestamp_e6": 1555647221331673
}

Fetches the orderbook with a depth of 200 orders per side.

After the subscription response, the first response will be the snapshot response. This shows the entire orderbook. The data is ordered by price, starting with the lowest buys and ending with the highest sells.

Following this, all responses are in the delta format, which represents updates to the orderbook relative to the last response.

instrument_info

How to Subscribe

ws.send('{"op": "subscribe", "args": ["instrument_info.100ms.BTCUSDT"]}')

Snapshot Response Example - format of the first response

{
    "topic": "instrument_info.100ms.BTCUSDT",
    "type": "snapshot",
    "data": {
        "id": 1,
        "symbol": "BTCUSDT",                           //instrument name
        "last_price_e4": 81165000,                    //the latest price
        "last_tick_direction": "ZeroPlusTick",        //the direction of last tick:PlusTick,ZeroPlusTick,MinusTick,ZeroMinusTick
        "prev_price_24h_e4": 81585000,                //the price of prev 24h
        "price_24h_pcnt_e6": -5148,                   //the current last price percentage change from prev 24h price
        "high_price_24h_e4": 82900000,                //the highest price of prev 24h
        "low_price_24h_e4": 79655000,                 //the lowest price of prev 24h
        "prev_price_1h_e4": 81395000,                 //the price of prev 1h
        "price_1h_pcnt_e6": -2825,                    //the current last price percentage change from prev 1h price
        "mark_price_e4": 81178500,                    //mark price
        "index_price_e4": 81172800,                   //index price
        "open_interest": 154418471,                   //open interest quantity - Attention, the update is not immediate - slowest update is 1 minute
        "open_value_e8": 1997561103030,               //open value quantity - Attention, the update is not immediate - the slowest update is 1 minute
        "total_turnover_e8": 2029370141961401,        //total turnover
        "turnover_24h_e8": 9072939873591,             //24h turnover
        "total_volume": 175654418740,                 //total volume
        "volume_24h": 735865248,                      //24h volume
        "funding_rate_e6": 100,                       //funding rate
        "predicted_funding_rate_e6": 100,             //predicted funding rate
        "cross_seq": 1053192577,                      //sequence
        "created_at": "2018-11-14T16:33:26Z",         
        "updated_at": "2020-01-12T18:25:16Z",         
        "next_funding_time": "2020-01-13T00:00:00Z",  //next funding time
                                                      //the rest time to settle funding fee
        "countdown_hour": 6                           //the remaining time to settle the funding fee
    },
    "cross_seq": 1053192634,
    "timestamp_e6": 1578853524091081                  //the timestamp when this information was produced
}

Delta Response Example - format of the responses following the snapshot response

{
    "topic": "instrument_info.100ms.BTCUSDT",
    "type": "delta",
    "data": {
        "delete": [],
        "update": [
            {
                "id": 1,
                "symbol": "BTCUSDT",
                "prev_price_24h_e4": 81565000,
                "price_24h_pcnt_e6": -4904,
                "open_value_e8": 2000479681106,
                "total_turnover_e8": 2029370495672976,
                "turnover_24h_e8": 9066215468687,
                "volume_24h": 735316391,
                "cross_seq": 1053192657,
                "created_at": "2018-11-14T16:33:26Z",
                "updated_at": "2020-01-12T18:25:25Z"
            }
        ],
        "insert": []
    },
    "cross_seq": 1053192657,
    "timestamp_e6": 1578853525691123
}

Get latest information for symbol.

trade

How to Subscribe

ws.send('{"op": "subscribe", "args": ["trade.BTCUSDT"]}')

Response Example - format of all responses

{
    "topic": "trade.BTCUSDT",
    "data": [
        {
            "symbol": "BTCUSDT",
            "tick_direction": "PlusTick",
            "price": 8098,
            "size": 328,
            "timestamp":"2020-03-30T02:21:06.000Z",
            "trade_time_ms":"1585534866418",
            "side":"Sell",
            "trade_id":"01e79e28-d1f4-59ac-b079-ca909606d91a"
        }
    ]
}

Get real-time trading information.

kline

How to Subscribe

ws.send('{"op":"subscribe","args":["candle.1.BTCUSDT"]}')

Response Example - format of all responses

{
    "topic":"candle.1.BTCUSDT",
    "data":[
        {
            "start":1588071660,
            "end":1588071720,
            "open":7744.5,
            "close":7745,
            "high":7745,
            "low":7744,
            "volume":"33.051",
            "turnover":"255979.995",
            "confirm":true,
            "cross_seq":71947372,
            "timestamp":1588071717325846
        }
    ],
    "timestamp_e6":1588071721163975
}

Currently supported intervals:

Private Topics

position

How to Subscribe

ws.send('{"op": "subscribe", "args": ["position"]}')

Response Example - format of all responses

{
   "topic": "position",
   "action": "update",
   "data": [
       {
           "user_id":  1,
           "symbol": "BTCUSD",
           "size": 11, 
           "side": "Sell",
           "position_value": "0.00159252",
           "entry_price": "6907.291588174717",
           "liq_price": "7100.234",
           "bust_price": "7088.1234",
           "leverage": "1",
           "order_margin":  "1",
           "position_margin":  "1", 
           "occ_closing_fee":  "0.1", 
           "take_profit":  "0.1",
           "tp_trigger_by": 0,
           "stop_loss":  "0.12",
           "sl_trigger_by": "Normal", 
           "realised_pnl": "Normal", 
           "cum_realised_pnl": "Normal",
           "position_seq": 14
       }
   ]
}

execution

How to Subscribe

ws.send('{"op": "subscribe", "args": ["execution"]}')

Response Example - format of all responses

{
    "topic": "execution",
    "data": [
        {
            "symbol": "BTCUSD",
            "side": "Buy",
            "order_id": "xxxxxxxx-xxxx-xxxx-9a8f-4a973eb5c418",
            "exec_id": "xxxxxxxx-xxxx-xxxx-8b66-c3d2fcd352f6",
            "order_link_id": "",
            "price": "8300",
            "order_qty": 1,
            "exec_type": "Trade",
            "exec_qty": 1,
            "exec_fee": "0.00000009",
            "trade_time": "2020-01-14T14:07:23.629Z" // trade time
        }
    ]
}

order

How to Subscribe

ws.send('{"op": "subscribe", "args": ["order"]}')

Response Example - format of all responses

{
    "topic": "order",
    "data": [
        {
            "order_id": "xxxxxxxx-xxxx-xxxx-9a8f-4a973eb5c418",
            "order_link_id": "",
            "symbol": "BTCUSD",
            "side": "Sell",
            "order_type": "Market",
            "price": "8579.5",
            "qty": 1,
            "time_in_force": "ImmediateOrCancel",
            "order_status": "Filled",
            "last_exec_price": 0,
            "cum_exec_qty": 1,
            "cum_exec_value": "0.00011655",
            "cum_exec_fee": "0.00000009",
            "create_time": "2020-01-14T14:09:31.778Z",
            "update_time": "2020-01-14T14:09:31.778Z"
        }
    ]
}

stop_order

How to Subscribe

ws.send('{"op": "subscribe", "args": ["stop_order"]}')

Response Example - format of all responses

{
    "topic": "stop_order",
    "data": [
        {
            "stop_order_id": "xxxxxxxx-xxxx-xxxx-98fb-335aaa6c613b",
            "order_link_id": "",
            "user_id": 1,
            "symbol": "BTCUSD",
            "side": "Buy",
            "order_type": "Limit",
            "price": "8584.5",
            "qty": 1,
            "time_in_force": "ImmediateOrCancel",
            "order_status": "Untriggered", //Stop Order Status
            "stop_order_type": "Stop",
            "trigger_by": "LastPrice",
            "trigger_price": "8584.5",
            "create_time": "2020-01-14T14:11:22.062Z",
            "update_time": "2020-01-14T14:11:22.062Z"
        }
    ]
}

wallet

How to Subscribe

ws.send('{"op": "subscribe", "args": ["wallet"]}')

Response Example - format of all responses

{
    "topic": "wallet",
    "data": [
        {
            "wallet_balance":429.80713,
            "available_balance":429.67322
        }
    ]
}

Errors

The Bybit API uses the following HTTP Codes and Error Codes:

HTTP Code Meaning
200 Request valid -- Your request is valid
403 Forbidden -- You request too many times
404 Request path not found
Error Code Meaning
10001 parameter error
10002 request expired, check your timestamp and recv_window
10001 parameter error
10002 request expired, check your timestamp and recv_window
10003 Invalid apikey
10004 invalid sign
10005 permission denied for current apikey
10006 too many requests
10007 api_key not found in your request parameters
10010 request ip mismatch
10017 request path not found or request method is invalid
33004 apikey already expired
130001 Not get position
130002 wallet is nil
130003 the pz status is not normal
130004 Order number is out of permissible range
130005 Order price is out of permissible range
130006 order qty is out of permissible range
130007 Order price is out of permissible range
130008 order_type invalid
130009 The number of contracts below min limit allowed
130010 order not exists or Too late to operate
130011 Operation not allowed as position is undergoing liquidation
130012 Operation not allowed as position is undergoing ADL
130013 stop_order trail value invalid
130014 stop_order trigger price invalid
130015 stop_order expected_direction or base_price invalid
130016 invalid stop_order_type, cannot replace price
130017 invalid stop_order_type, cannot replace qty
130018 invalid trail_value
130019 invalid stop_order_type, cannot replace trigger_price
130020 invalid stop_order_type, cannot replace trail_value
130021 order cost not available
130024 cannot set tp_sl_ts for zero position
130025 below < 10% of base price
130026 the price is too high
130027 the price set for Buy position should be higher than base_price
130028 the price set for Sell position should be between base_price and liq_price
130029 the price set for Buy position should be between liq_price and base_price
130030 the price set for Sell position should be lower than base_price
130032 invalid order_status, cannot cancel or execute trigger
130033 number of condition order >= 10
130034 stop_order cannot replace
130035 Too freq to cancel, Try it later
130037 Order already cancelled
130040 position will be liq
130041 AvailableBalanceE8 less than 0
130049 available balance not enough
130050 Any adjustments made will trigger liq
130051 cannot set leverage ,due to risk limit,
130052 cannot set leverage , below the lower limit
130056 the position is in cross_margin
130057 the position size is 0
130058 can not set margin less than minPositionCost
130059 can not set pz open limit more than symbol limit
130060 autoAddMargin not changed
130061 not change fee,invalid req
130062 can not set pz open limit less than current buy pz value
130063 can not set pz open limit less than current sell pz value
130064 just support usdt
130074 expect Rising, trigger_price <= current
130075 expect Falling, trigger_price >= current
130076 replace params invalid
130077 the deposit req has handled
130078 the withdraw req has handled
130079 the rotate req has handled
130101 unknown request for create order
130102 unknown request for cancel order
130103 unknown request for cancelAll
130104 unknown request for LiqExecuteReq, req param not match liqExecuteReq
130105 unknown request for pre create order
130106 unknown req for query order
130107 unmatch request for triggeredToActiveImpl
130108 unknown request for addMargin
130109 unknown request for calculatePositionPnl
130110 unknown request for qryAssetImpl
130111 unknown request for query_position_list
130112 unknown request for setAutoAddMargin
130113 unknown request for setFeeRate
130114 unknown request for setLeverage
130115 unknown request for setMargin
130116 unknown request for setOpenLimit
130117 unknown request for setTpSlTs
130118 unknown request for settleFundingFeeReq
130119 unknown request for setPositionMode
130120 unknown request for walletDeposit
130121 unknown request for walletWithDraw
130122 unknown request for rotateRealisedPnl
130123 unknown request for AdlExecute
130124 unknown request for AdlCleanReq
130125 No change made for TP/SL price
130126 No orders
130023 Will be triggered Liq after order is completed
130127 Take Profit, Stop Loss and Trailing Stop Loss are not modified

ENUMs Definitions

This is a list of valid options (and rules) for the different parameters when sending a request to the API.

Side (side)

Symbol (symbol)

Currency (currency/coin)

Wallet fund type (wallet_fund_type)

Withdraw status (status)

Order type (order_type)

Quantity (qty)

Price (price)

Time in force (time_in_force)

Trigger price type (trigger_by)

Order (order)

This is for sorting orders/trades in a specified direction.

Order status (order_status)

Filter fetched orders by their order statuses. To filter by multiple statuses, separate with a comma like so: Filled,New

Cancel type (cancel_type)

Create type (create_type)

Exec type (exec_type)

Liquidity type (last_liquidity_ind)