Group And Resources

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!

Group And Bybit API Resources

Help Center - learn about exchange mechanisms here!
Bybit API docs - report issues here!
Bybit's api-connectors - find a repo of prebuilt libraries here!
API Discussion Group - get English help here!
Chinese API Discussion Group - get Chinese help here!
API Announcements Channel - subscribe for changes to the API!
IT@bybit.com - official IT support email!

Changelog

2021-04-07

REST API

Fix value of price of Liquidated Orders from liq_price to bust_price, you can find more about liquidation here

2021-04-02

REST API

Add comment of errcode 10016,10018,30074,30075

2021-03-12

REST API

Fix value of exec_type,last_liquidity_ind for User Trade Record endpoint

2021-02-25

REST API

Inverse Futures API released!

Websocket API

Add websocket support to inverse future

2021-03-01

REST API

Change url prefix from future to futures

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:

api_key
timestamp - UTC timestamp in milliseconds
sign - a signature derived from the request's parameters

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=BTCUSDH21&timestamp=1542434791747"

# api_key=B2Rou0PLPpGqcU0Vu2&
# leverage=100&
# symbol=BTCUSDH21&
# 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 /futures/private/order?symbol=BTCUSDH21&api_key=B2Rou0PLPpGqcU0Vu2&timestamp=1542434791000&sign=670e3e4aa32b243f2dedf1dafcec2fd17a440e71b05681550416507de591d908 HTTP/1.1
Host: api-testnet.bybit.com

Message format for POST requests:

POST /futures/private/order/cancel HTTP/1.1
Host: api-testnet.bybit.com
Content-Type: application/json

{
    "api_key": "B2Rou0PLPpGqcU0Vu2",
    "symbol": "BTCUSDH21",
    "order_id": "3bd1844f-f3c0-4e10-8c25-10fea03763f6",
    "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.

Advanced Data

Open Interest

Please see the shared endpoint.

Latest Big Deal

Please see the shared endpoint.

Long-Short Ratio

Please see the shared endpoint.

Account Data Endpoints

The following account data endpoints require authentication.

Active Orders

Place Active Order

Request Example

curl https://api.bybit.com/futures/private/order/create \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","side"="Buy","symbol"="BTCUSDM21","order_type":"Market","qty":10,"time_in_force":"GoodTillCancel","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesOrder.FuturesOrder_new(side="Buy",symbol="BTCUSDM21",order_type="Market",qty=1,time_in_force="GoodTillCancel").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 1,
        "order_id": "335fd977-e5a5-4781-b6d0-c772d5bfb95b",
        "symbol": "BTCUSDM21",
        "side": "Buy",
        "order_type": "Limit",
        "price": 8800,
        "qty": 1,
        "time_in_force": "GoodTillCancel",
        "order_status": "Created",
        "last_exec_time": 0,
        "last_exec_price": 0,
        "leaves_qty": 1,
        "cum_exec_qty": 0,
        "cum_exec_value": 0,
        "cum_exec_fee": 0,
        "reject_reason": "",
        "order_link_id": "",
        "created_at": "2019-11-30T11:03:43.452Z",
        "updated_at": "2019-11-30T11:03:43.455Z"
    },
    "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. To protect market order from excessive slippage, Bybit converts a market order into a limit order with a spread. A market buy order is converted into a limit order at a higher than best ask price; a market sell order is covnerted into a limit order at a lower than best bid price. The converted limit price and executed price are both available in trade history..

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 the 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. All USD markets have a contract size of 1 USD. See more

Order price: If it is a conditional 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. This must modulo by 0.5 (20 and 21.5 are accepted, but 16.1 or 16.15 are not).

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 BTCUSD instrument and 280 active orders on the ETHUSD instrument. And order with parameter reduce_only or closeOnTrigger is unlimited.

HTTP Request

POST /futures/private/order/create

Request Parameters

parameter	required	type	comments
position_idx	true	integer	Position idx, used to identify positions in different position modes: 0-One-Way Mode 1-Buy side of both side mode 2-Sell side of both side mode
side	true	string	Side
symbol	true	string	Symbol
order_type	true	string	Active order type
qty	true	integer	Order quantity in USD
price	false	number	Order price
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
reduce_only	false	bool	What is a reduce-only order? True means your position can only reduce in size if this order is triggered
close_on_trigger	false	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.

Response Parameters

parameter	type	comments
user_id	number	UserID
order_id	string	Your active order ID. The unique order ID returned to you when the corresponding active order was created
symbol	string	Symbol
side	string	Side
order_type	string	Order type
price	number	Order price
qty	number	Order quantity in USD
time_in_force	string	Time in force
order_status	string	Order status
last_exec_time	string	Last execution time
last_exec_price	string	Last execution price
leaves_qty	number	Number of unfilled contracts from the order's size
cum_exec_qty	number	Cumulative qty of trading
cum_exec_value	number	Cumulative value of trading
cum_exec_fee	number	Cumulative trading fees
reject_reason	string	The reason the order was rejected
order_link_id	string	Customised order ID
created_at	string	Creation time
updated_at	string	Update time

Get Active Order

Request Example

curl "https://api.bybit.com/futures/private/order/list?api_key={api_key}&timestamp={timestamp}&sign={sign}&symbol=BTCUSDM21"

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesOrder.FuturesOrder_getOrders(symbol="BTCUSDM21",order_status="New").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "data": [
            {
                "user_id": 160861,
                "order_status": "Cancelled",
                "symbol": "BTCUSDM21",
                "side": "Buy",
                "order_type": "Market",
                "price": "9800",
                "qty": "16737",
                "time_in_force": "ImmediateOrCancel",
                "order_link_id": "",
                "order_id": "fead08d7-47c0-4d6a-b9e7-5c71d5df8ba1",
                "created_at": "2020-07-24T08:22:30Z",
                "updated_at": "2020-07-24T08:22:30Z",
                "leaves_qty": "0",
                "leaves_value": "0",
                "cum_exec_qty": "0",
                "cum_exec_value": "0",
                "cum_exec_fee": "0",
                "reject_reason": "EC_NoImmediateQtyToFill"
            }
        ],
        "cursor": "w01XFyyZc8lhtCLl6NgAaYBRfsN9Qtpp1f2AUy3AS4+fFDzNSlVKa0od8DKCqgAn"
    },
    "time_now": "1604653633.173848",
    "rate_limit_status": 599,
    "rate_limit_reset_ms": 1604653633171,
    "rate_limit": 600
}

Get my active order list.

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

HTTP Request

GET /futures/private/order/list

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
order_status	false	string	Queries orders of all statuses if `order_status` not provided. If you want to query orders with specific statuses, you can pass the order_status split by ',' (eg `Filled,New`).
direction	false	string	Search direction. `prev`: prev page, `next`: next page. Defaults to `next`
limit	false	integer	Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page
cursor	false	string	Page turning mark. Use return `cursor`. Sign using origin data, in request please use urlencode

Response Parameters

parameter	type	comments
data > user_id	integer	UserID
data > symbol	string	Symbol
data > side	string	Side
data > order_type	string	Order type
data > price	string	Order price
data > qty	string	Order quantity in USD
data > time_in_force	string	Time in force
data > order_status	string	Order status
data > leaves_qty	string	Number of unfilled contracts from the order's size
data > leaves_value	string	The estimated value corresponding to the number of remaining orders
data > cum_exec_qty	string	Cumulative qty of trading
data > cum_exec_value	string	Cumulative value of trading
data > cum_exec_fee	string	Cumulative trading fees
data > reject_reason	string	The reason the order was rejected
data > order_link_id	string	Customised order ID
data > created_at	string	Creation time
data > order_id	string	Order ID
cursor	string	Page turning mark

Cancel Active Order

Request Example

curl https://api.bybit.com/futures/private/order/cancel \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","order_id":"","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesOrder.FuturesOrder_cancel(symbol="BTCUSDM21", order_id="").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 1,
        "order_id": "3bd1844f-f3c0-4e10-8c25-10fea03763f6",
        "symbol": "BTCUSDM21",
        "side": "Buy",
        "order_type": "Limit",
        "price": 8800,
        "qty": 1,
        "time_in_force": "GoodTillCancel",
        "order_status": "New",
        "last_exec_time": 0,
        "last_exec_price": 0,
        "leaves_qty": 1,
        "cum_exec_qty": 0,
        "cum_exec_value": 0,
        "cum_exec_fee": 0,
        "reject_reason": "",
        "order_link_id": "",
        "created_at": "2019-11-30T11:17:18.396Z",
        "updated_at": "2019-11-30T11:18:01.811Z"
    },
    "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 /futures/private/order/cancel

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
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

Response Parameters

parameter	type	comments
user_id	number	UserID
order_id	string	Order ID
symbol	string	Symbol
side	string	Side
order_type	string	Order type
price	number	Order price
qty	number	Order quantity in USD
time_in_force	string	Time in force
order_status	string	Order status
last_exec_time	string	Last execution time
last_exec_price	string	Last execution price
leaves_qty	number	Number of unfilled contracts from the order's size
cum_exec_qty	number	Cumulative qty of trading
cum_exec_value	number	Cumulative value of trading
cum_exec_fee	number	Cumulative trading fees
reject_reason	string	The reason the order was rejected
order_link_id	string	Customised order ID
created_at	string	Creation time
updated_at	string	Update time

Cancel All Active Orders

Request Example

curl https://api.bybit.com/futures/private/order/cancelAll \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesOrder.FuturesOrder_cancelAll(symbol="BTCUSDM21").result())

Response Example

{
    "ret_code": 0,      
    "ret_msg": "OK",    
    "ext_code": "",     
    "ext_info": "",
    "result": [
        {
            "clOrdID": "89a38056-80f1-45b2-89d3-4d8e3a203a79",  
            "user_id": 1,                                  
            "symbol": "BTCUSDM21",                                
            "side": "Buy",                                      
            "order_type": "Limit",                              
            "price": "7693.5",                                  
            "qty": 1,                                           
            "time_in_force": "GoodTillCancel",                  
            "create_type": "CreateByUser",                     
            "cancel_type": "CancelByUser",                      
            "order_status": "",                                 
            "leaves_qty": 1,                                    
            "leaves_value": "0",                                
            "created_at": "2019-11-30T10:38:53.564428Z",        
            "updated_at": "2019-11-30T10:38:59.102589Z",        
            "cross_status": "PendingCancel",  // `PendingCancel` means the matching engine received the cancellation but there is no guarantee that the cancellation will be successful.
            "cross_seq": 387734027                              
        }
    ],
    "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.

This endpoint's rate_limit will decrease by 10 per request

HTTP Request

POST /futures/private/order/cancelAll

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol

Response Parameters

parameter	type	comments
clOrdID	string	A unique order number of type UUID
user_id	number	UserID
symbol	string	Symbol
side	string	Side
order_type	string	Order type
price	number	Order price
qty	number	Order quantity in USD
time_in_force	string	Time in force
create_type	string	Trigger scenario for single action
cancel_type	string	Trigger scenario for cancel operation
order_status	string	Order status
leaves_qty	number	Number of unfilled contracts from the order's size
leaves_value	number	The estimated value corresponding to the number of remaining orders
created_at	string	Creation time
updated_at	string	Update time
cross_status	string	The state of initiating a matchmaking request
cross_seq	number	Cross sequence (internal value)

Replace Active Order

Request Example

curl https://api.bybit.com/futures/private/order/replace \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","order_id":"","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesOrder.FuturesOrder_replace(symbol="BTCUSDM21", order_id="69bd5b88-fa2e-4c33-a489-1860f595191d", p_r_qty="2").result())

Response Example

{
    "ret_code": 0,    //Error code,
    "ret_msg": "ok",  //Error message,
    "ext_code": "",
    "result": {
        "order_id": "efa44157-c355-4a98-b6d6-1d846a936b93"
    },
    "time_now": "1539778407.210858",    // UTC timestamp
    "rate_limit_status": 99, // The remaining number of accesses in one minute
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100             
}

Replace order can modify/amend your active orders.

p_r_qty and p_r_price are the modified price and quantity. If these two fields are not provided, nothing will be modified.

HTTP Request

POST /futures/private/order/replace

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	Symbol.
p_r_qty	false	string	New order quantity. Do not pass this field if you don't want modify it
p_r_price	false	string	New order price. Do not pass this field if you don't want modify it

Response Parameters

parameter	type	comments
order_id	string	Order ID

Query Active Order (real-time)

Request Example

curl "https://api.bybit.com/futures/private/order?api_key={api_key}&symbol=BTCUSDM21&timestamp={timestamp}order_id={order_id}&sign={sign}"

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesOrder.FuturesOrder_query(symbol="BTCUSDM21", order_id="").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 106958,
        "symbol": "BTCUSDM21",
        "side": "Buy",
        "order_type": "Limit",
        "price": "11756.5",
        "qty": 1,
        "time_in_force": "PostOnly",
        "order_status": "Filled",
        "ext_fields": {
            "o_req_num": -68948112492,
            "xreq_type": "x_create"
        },
        "last_exec_time": "1596304897.847944",
        "last_exec_price": "11756.5",
        "leaves_qty": 0,
        "leaves_value": "0",
        "cum_exec_qty": 1,
        "cum_exec_value": "0.00008505",
        "cum_exec_fee": "-0.00000002",
        "reject_reason": "",
        "cancel_type": "",
        "order_link_id": "",
        "created_at": "2020-08-01T18:00:26Z",
        "updated_at": "2020-08-01T18:01:37Z",
        "order_id": "e66b101a-ef3f-4647-83b5-28e0f38dcae0"
    },
    "time_now": "1597171013.867068",
    "rate_limit_status": 599,
    "rate_limit_reset_ms": 1597171013861,
    "rate_limit": 600
}

//When only symbol is passed, the response uses a different structure:

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "user_id": 100228,
            "symbol": "BTCUSDM21",
            "side": "Sell",
            "order_type": "Limit",
            "price": "17740",
            "qty": 10,
            "time_in_force": "GoodTillCancel",
            "order_status": "New",
            "ext_fields": {
                "o_req_num": 434743,
                "xreq_type": "x_create"
            },
            "last_exec_time": "1608193181.827761",
            "leaves_qty": 10,
            "leaves_value": "0.00056369",
            "cum_exec_qty": 0,
            "cum_exec_value": "0.00008505",
            "cum_exec_fee": "-0.00000002",
            "reject_reason": "EC_NoError",
            "cancel_type": "UNKNOWN",
            "order_link_id": "",
            "created_at": "2020-12-17T08:19:41.827637283Z",
            "updated_at": "2020-12-17T08:19:41.827761Z",
            "order_id": "d570d931-771e-4911-a24e-cdeddedb5b0e"
        },
        ...
        {
            "user_id": 100228,
            "symbol": "BTCUSDM21",
            "side": "Sell",
            "order_type": "Limit",
            "price": "17740",
            "qty": 10,
            "time_in_force": "GoodTillCancel",
            "order_status": "New",
            "ext_fields": {
                "o_req_num": 434728,
                "xreq_type": "x_create"
            },
            "last_exec_time": "1608193178.955412",
            "leaves_qty": 10,
            "leaves_value": "0.00056369",
            "cum_exec_qty": 0,
            "cum_exec_value": "0.00008505",
            "cum_exec_fee": "-0.00000002",
            "reject_reason": "EC_NoError",
            "cancel_type": "UNKNOWN",
            "order_link_id": "",
            "created_at": "2020-12-17T08:19:38.955297869Z",
            "updated_at": "2020-12-17T08:19:38.955412Z",
            "order_id": "88b91101-7ac1-40af-90b8-72d53fe23622"
        }
    ],
    "time_now": "1608193190.911073",
    "rate_limit_status": 599,
    "rate_limit_reset_ms": 1608193190909,
    "rate_limit": 600
}

Query real-time active order information. If only order_id or order_link_id are passed, a single order will be returned; otherwise, returns up to 500 unfilled orders.

HTTP Request

GET /futures/private/order

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
order_id	false	string	Order ID
order_link_id	false	string	Order link ID

Response Parameters

parameter	type	comments
user_id	number	UserID
symbol	string	Symbol
side	string	Side
order_type	string	Order type
price	number	Order price
qty	number	Order quantity in USD
time_in_force	string	Time in force
order_status	string	Order status
ext_fields	json	Extension field
leaves_qty	number	Number of unfilled contracts from the order's size
leaves_value	number	The estimated value corresponding to the number of remaining orders
cum_exec_qty	number	Cumulative qty of trading
cum_exec_value	number	Cumulative value of trading
cum_exec_fee	order_link_id	string
reject_reason	string	The reason the order was rejected
cancel_type	string	Trigger scenario for cancel operation
order_link_id	string	Customised order ID
created_at	string	Creation time
updated_at	string	Update time
order_id	string	Order ID

Conditional Orders

Place Conditional Order

Request Example

curl https://api.bybit.com/futures/private/stop-order/create \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","order_type":"Limit","side":"Buy","symbol":"BTCUSDM21","qty":1,"price":8100,"base_price":8300,"stop_px":8150,"time_in_force":"GoodTillCancel","order_link_id":"cus_order_id_1","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesConditional.FuturesConditional_new(order_type="Limit",side="Buy",symbol="BTCUSDM21",qty="1",price="0.2569",base_price="15700",stop_px="0.2119",time_in_force="GoodTillCancel").result())

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":{
        "user_id":160880,
        "symbol":"BTCUSDM21",
        "side":"Buy",
        "order_type":"Limit",
        "price":"9003",
        "qty":"2",
        "time_in_force":"GoodTillCancel",
        "remark":"127.0.0.1",
        "leaves_qty":"2",
        "leaves_value":"0",
        "stop_px":"8232",
        "reject_reason":"EC_NoError",
        "stop_order_id":"eaf205ac-9dcc-44f6-8731-734e2101e61b",
        "created_at":"2020-11-06T07:48:43.940Z",
        "updated_at":"2020-11-06T07:48:43.940Z"
    },
    "time_now":"1604648923.942177"
}

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 stop 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 /futures/private/stop-order/create

Request Parameters

parameter	required	type	comments
position_idx	true	integer	Position idx, used to identify positions in different position modes: 0-One-Way Mode 1-Buy side of both side mode 2-Sell side of both side mode
side	true	string	Side
symbol	true	string	Symbol
order_type	true	string	Conditional order type
qty	true	string	Order quantity in USD
price	false	string	Execution price for conditional order. Required if you make limit price order
base_price	true	string	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	string	Trigger price
time_in_force	true	string	Time in force
trigger_by	false	string	Trigger price type. Default `LastPrice`
close_on_trigger	false	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.

Response Parameters

parameter	type	comments
user_id	integer	UserID
symbol	string	Symbol
side	string	Side
order_type	string	Active order type
price	string	Order price
qty	string	Order quantity in USD
time_in_force	string	Time in force
trigger_by	string	Trigger price type. Default `LastPrice`
base_price	string	Market price at placing order
remark	string	Remark
reject_reason	string	The reason the order was rejected
stop_px	string	Trigger price
stop_order_id	string	Your conditional order ID. The unique order ID returned to you when the corresponding active order was created
created_at	string	Creation time
order_link_id	string	Customised order ID

Get Conditional Order

Request Example

curl "https://api.bybit.com/futures/private/stop-order/list?api_key={api_key}&timestamp={timestamp}&sign={sign}"

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesConditional.FuturesConditional_getOrders(symbol="BTCUSDM21",stop_order_status="Untriggered").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "data": [
            {
                "user_id": 160861,
                "stop_order_status": "Active",
                "symbol": "ETHUSD",
                "side": "Buy",
                "order_type": "Market",
                "stop_order_type": "TakeProfit",
                "price": "220",
                "qty": "120",
                "time_in_force": "ImmediateOrCancel",
                "base_price": "258",
                "order_link_id": "",
                "created_at": "2019-08-02T07:37:24Z",
                "updated_at": "2019-08-02T07:38:40Z",
                "stop_px": "224.3",
                "stop_order_id": "6d0dec74-f516-4d95-81f1-c85e60c9a331"
            }
        ],
        "cursor": "zZtvOJ0gc3UOxZOwotsJSZyMTOgyC9tj1DmFyUU6eNHUL0X4NLwZvo8iqI6ltPIc"
    },
    "time_now": "1604653512.292878",
    "rate_limit_status": 599,
    "rate_limit_reset_ms": 1604653512287,
    "rate_limit": 600
}

Get my conditional order list.

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

HTTP Request

GET /futures/private/stop-order/list

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
stop_order_status	false	string	Queries orders of `Untriggered`,`Active`,`Deactivated` statuses if `stop_order_status` not provided. If you want to query orders with specific statuses, you can pass the stop_order_status split by ',' (eg `Untriggered,Active`)
direction	false	string	Search direction. `prev`: prev page, `next`: next page. Defaults to `next`
limit	false	integer	Limit for data size per page, max size is 50. Default as showing 20 pieces of data per page
cursor	false	string	Page turning mark. Use return `cursor`. Sign using origin data, in request please use urlencode

Response Parameters

parameter	type	comments
data > user_id	integer	UserID
data > stop_order_status	string	Stop order status
data > symbol	string	Symbol
data > side	string	Side
data > order_type	string	Active order type
data > price	number	Order price
data > qty	number	Order quantity in USD
data > time_in_force	string	Time in force
data > stop_order_type	string	Conditional order type
data > trigger_by	string	Trigger price type. Default `LastPrice`
data > base_price	number	Market price at placing order
data > order_link_id	string	Customised order ID
data > created_at	string	Creation time
data > updated_at	string	Update time
data > stop_px	number	Trigger price
data > stop_order_id	string	Your conditional order ID. The unique order ID returned to you when the corresponding active order was created
cursor	string	Page turning mark

Cancel Conditional Order

Request Example

curl https://api.bybit.com/futures/private/stop-order/cancel \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","stop_order_id":"xxx","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesConditional.FuturesConditional_cancel(symbol="BTCUSDM21", stop_order_id="").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
        "stop_order_id": "c1025629-e85b-4c26-b4f3-76e86ad9f8cb"
    },
    "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 or take profit/stop loss order. 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 /futures/private/stop-order/cancel

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
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

Response Parameters

parameter	type	comments
stop_order_id	string	Your conditional order ID. The unique order ID returned to you when the corresponding active order was created

Cancel All Conditional Orders

Request Example

curl https://api.bybit.com/futures/private/stop-order/cancelAll \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesConditional.FuturesConditional_cancelAll(symbol="BTCUSDM21").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "clOrdID": "dea89649-9492-459d-a8c4-c298b87b3d26",
            "user_id": 1,
            "symbol": "BTCUSDM21",
            "side": "Sell",
            "order_type": "Limit",
            "price": "999999",
            "qty": 1,
            "time_in_force": "PostOnly",
            "create_type": "CreateByUser",
            "cancel_type": "CancelByUser",
            "order_status": "",
            "leaves_qty": 1,
            "leaves_value": "0",
            "created_at": "2019-12-17T12:13:20Z",
            "updated_at": "2019-12-27T13:56:33.793799Z",
            "cross_status": "Deactivated",
            "cross_seq": -1,
            "stop_order_type": "Stop",
            "trigger_by": "LastPrice",
            "base_price": "6910.5",
            "expected_direction": "Rising"
        },
        {
            "clOrdID": "a85cd1c0-a9a4-49d3-a1bd-bab5ebe946d5",
            "user_id": 1,
            "symbol": "BTCUSDM21",
            "side": "Buy",
            "order_type": "Limit",
            "price": "8000",
            "qty": 1,
            "time_in_force": "GoodTillCancel",
            "create_type": "CreateByStopOrder",
            "cancel_type": "CancelByUser",
            "order_status": "",
            "leaves_qty": 1,
            "leaves_value": "0",
            "created_at": "2019-12-27T12:48:24.339323Z",
            "updated_at": "2019-12-27T13:56:33.793802Z",
            "cross_status": "Deactivated",
            "cross_seq": -1,
            "stop_order_type": "Stop",
            "trigger_by": "LastPrice",
            "base_price": "7000",
            "expected_direction": "Rising"
        }
    ],
    "time_now": "1577454993.799912",
    "rate_limit_status": 90,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

Cancel all untriggered conditional orders.

This endpoint's rate_limit will decrease by 10 per request

HTTP Request

POST /futures/private/stop-order/cancelAll

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol

Response Parameters

parameter	type	comments
clOrdID	string	A unique order number of type UUID
user_id	number	UserID
symbol	string	Symbol
side	string	Side
order_type	string	Active order type
price	number	Order price
qty	number	Order quantity in USD
time_in_force	string	Time in force
create_type	string	Trigger scenario for single action
cancel_type	string	Trigger scenario for cancel operation
order_status	string	Order status
leaves_qty	number	Number of unfilled contracts from the order's size
leaves_value	number	The estimated value corresponding to the number of remaining orders
created_at	string	Creation time
updated_at	string	Update time
cross_status	string	The state of initiating a matchmaking request
cross_seq	number	Cross sequence (internal value)
stop_order_type	string	Conditional order type
trigger_by	string	Trigger price type. Default `LastPrice`
base_price	number	Market price at placing order
expected_direction	string	Expected direction

Replace Conditional Order

Request Example

curl https://api.bybit.com/futures/private/stop-order/replace \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","stop_order_id":"","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesConditional.FuturesConditional_replace(symbol="BTCUSDM21", stop_order_id="69bd5b88-fa2e-4c33-a489-1860f595191d",p_r_qty="2").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
        "stop_order_id": "378a1bbc-a93a-4e75-87f4-502ea754ba36"
    },
    "ext_info": null,
    "time_now": "1577475760.604942",
    "rate_limit_status": 96,
    "rate_limit_reset_ms": 1577475760612,
    "rate_limit": "100"
}

Replace conditional order can modify/amend your conditional orders.

order_id and symbol are required for identifying a conditional order.

p_r_qty, p_r_price and p_r_trigger_price can be set for your conditional order. If these fields are not provided, nothing will be modified.

HTTP Request

POST /futures/private/stop-order/replace

Request Parameters

parameter	required	type	comments
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
symbol	true	string	Symbol.
p_r_qty	false	integer	New order quantity. Do not pass this field if you don't want modify it
p_r_price	false	string	New order price. Do not pass this field if you don't want modify it
p_r_trigger_price	false	string	New conditional order's trigger price or TP/SL order price, also known as stop_px. Do not pass this field if you don't want modify it

Response Parameters

parameter	type	comments
stop_order_id	string	Your conditional order ID. The unique order ID returned to you when the corresponding active order was created

Query Conditional Order (real-time)

Request Example

curl "https://api.bybit.com/futures/private/stop-order?api_key={api_key}&symbol=BTCUSDM21&timestamp={timestamp}order_id={order_id}&sign={sign}"

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesConditional.FuturesConditional_query(symbol="BTCUSDM21", stop_order_id="", p_r_trigger_price="16003").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 1,
        "symbol": "BTCUSDM21",
        "side": "Buy",
        "order_type": "Limit",
        "price": "8000",
        "qty": 1,
        "time_in_force": "GoodTillCancel",
        "order_status": "Untriggered",
        "ext_fields": {},
        "leaves_qty": 1,
        "leaves_value": "0.00013333",
        "cum_exec_qty": 0,
        "cum_exec_value": null,
        "cum_exec_fee": null,
        "reject_reason": "",
        "order_link_id": "",
        "created_at": "2019-12-27T19:56:24.052194Z",
        "updated_at": "2019-12-27T19:56:24.052194Z",
        "order_id": "378a1bbc-a93a-4e75-87f4-502ea754ba36"
    },
    "time_now": "1577476584.386958",
    "rate_limit_status": 99,
    "rate_limit_reset_ms": 1580885703683,
    "rate_limit": 100
}

//When only symbol is passed, the response uses a different structure:

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "user_id": 100328,
            "symbol": "EOSUSD",
            "side": "Sell",
            "order_type": "Limit",
            "price": "2.7",
            "qty": 1,
            "stop_px": "2.0000",
            "base_price": "2.7000",
            "time_in_force": "GoodTillCancel",
            "order_status": "Untriggered",
            "ext_fields": {},
            "leaves_qty": 1,
            "leaves_value": "0.37037037",
            "cum_exec_qty": 0,
            "cum_exec_value": null,
            "cum_exec_fee": null,
            "reject_reason": "EC_NoError",
            "cancel_type": "UNKNOWN",
            "order_link_id": "",
            "created_at": "2020-12-17T08:21:15.246331281Z",
            "updated_at": "2020-12-17T08:21:15.246331281Z",
            "order_id": "a0dee45e-ae2a-4eb4-8205-9739075a7a81",
            "trigger_by": "MarkPrice"
        },
        ...
        {
            "user_id": 100328,
            "symbol": "EOSUSD",
            "side": "Sell",
            "order_type": "Limit",
            "price": "2.6",
            "qty": 1,
            "stop_px": "2.0000",
            "base_price": "2.7000",
            "time_in_force": "GoodTillCancel",
            "order_status": "Untriggered",
            "ext_fields": {},
            "leaves_qty": 1,
            "leaves_value": "0.38461538",
            "cum_exec_qty": 0,
            "cum_exec_value": null,
            "cum_exec_fee": null,
            "reject_reason": "EC_NoError",
            "cancel_type": "UNKNOWN",
            "order_link_id": "",
            "created_at": "2020-12-17T08:21:10.924193413Z",
            "updated_at": "2020-12-17T08:21:10.924193413Z",
            "order_id": "51d048ba-a71f-40ef-b4c4-897e94590b80",
            "trigger_by": "MarkPrice"
        }
    ],
    "time_now": "1608193281.690286",
    "rate_limit_status": 599,
    "rate_limit_reset_ms": 1608193281687,
    "rate_limit": 600
}

Query real-time stop order information. When passing the parameter order_id or order_link_id, a single order data will be returned; otherwise, returns up to 50 unfilled orders.

HTTP Request

GET /futures/private/stop-order

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
stop_order_id	false	string	Order ID
order_link_id	false	string	Order link ID

Response Parameters

parameter	type	comments
user_id	number	UserID
symbol	string	Symbol
side	string	Side
order_type	string	Active order type
price	number	Order price
qty	number	Order quantity in USD
time_in_force	string	Time in force
order_status	string	Order status
ext_fields	json	Extension field
leaves_qty	number	Number of unfilled contracts from the order's size
leaves_value	number	The estimated value corresponding to the number of remaining orders
cum_exec_qty	number	Cumulative qty of trading
cum_exec_value	number	Cumulative value of trading
cum_exec_fee	number	Cumulative trading fees
reject_reason	string	The reason the order was rejected
order_link_id	string	Customised order ID
created_at	string	Creation time
updated_at	string	Update time
order_id	string	Order ID
base_price	string	Market price at placing order
stop_px	string	Trigger price
trigger_by	string	Trigger price type. Default `LastPrice`

Position

My Position

Request Example

curl "https://api.bybit.com/futures/private/position/list?api_key={api_key}&symbol=BTCUSDM21&timestamp={timestamp}&sign={sign}"

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesPositions.FuturesPositions_myPosition(symbol="BTCUSDM21").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "data": {
                "id": 0,
                "position_idx": 1,
                "mode": 3,
                "user_id": 103669,
                "risk_id": 61,
                "symbol": "BTCUSDM21",
                "side": "Buy",
                "size": 200000,
                "position_value": "3.62934747",
                "entry_price": "55106.32466392",
                "is_isolated": true,
                "auto_add_margin": 0,
                "leverage": "10",
                "effective_leverage": "0",
                "position_margin": "0.36592896",
                "liq_price": "50325.5",
                "bust_price": "50097",
                "occ_closing_fee": "0.0029942",
                "occ_funding_fee": "0",
                "take_profit": "0",
                "stop_loss": "0",
                "trailing_stop": "0",
                "position_status": "Normal",
                "deleverage_indicator": 4,
                "oc_calc_data": "{\"blq\":0,\"slq\":0,\"bmp\":0,\"smp\":0,\"fq\":-200000,\"bv2c\":0.101575,\"sv2c\":0.101425}",
                "order_margin": "0",
                "wallet_balance": "9.95270565",
                "realised_pnl": "-0.00272207",
                "unrealised_pnl": 0,
                "cum_realised_pnl": "-0.00272207",
                "cross_seq": 2392689554,
                "position_seq": 0,
                "created_at": "2021-03-11T08:11:17.747178448Z",
                "updated_at": "2021-03-11T08:24:18.923067183Z"
            },
            "is_valid": true
        },
        {
            "data": {
                "id": 0,
                "position_idx": 0,
                "mode": 0,
                "user_id": 103669,
                "risk_id": 71,
                "symbol": "BTCUSDM21",
                "side": "Buy",
                "size": 2,
                "position_value": "0.00003644",
                "entry_price": "54884.74204171",
                "is_isolated": false,
                "auto_add_margin": 1,
                "leverage": "100",
                "effective_leverage": "0",
                "position_margin": "0.0000004",
                "liq_price": "0.5",
                "bust_price": "0.5",
                "occ_closing_fee": "0.003",
                "occ_funding_fee": "0",
                "take_profit": "0",
                "stop_loss": "0",
                "trailing_stop": "0",
                "position_status": "Normal",
                "deleverage_indicator": 3,
                "oc_calc_data": "{\"blq\":0,\"slq\":0,\"bmp\":0,\"smp\":0,\"fq\":-2,\"bv2c\":0.0115075,\"sv2c\":0.0114925}",
                "order_margin": "0",
                "wallet_balance": "9.95270565",
                "realised_pnl": "0",
                "unrealised_pnl": 0,
                "cum_realised_pnl": "-0.00000002",
                "cross_seq": 2360303954,
                "position_seq": 0,
                "created_at": "2021-02-24T05:56:07.964274148Z",
                "updated_at": "2021-03-11T08:52:06.772110817Z"
            },
            "is_valid": true
        }
    ],
    "time_now": "1615452727.664848",
    "rate_limit_status": 119,
    "rate_limit_reset_ms": 1615452727660,
    "rate_limit": 120
}

Get my position list.

HTTP Request

GET /futures/private/position/list

Request Parameters

parameter	required	type	comments
symbol	false	string	Symbol

Response Parameters

parameter	type	comments
id	number	PositionID
position_idx	integer	Position idx, used to identify positions in different position modes: 0-One-Way Mode 1-Buy side of both side mode 2-Sell side of both side mode
mode	number	Position mode
user_id	number	UserID
risk_id	number	Risk ID
symbol	string	Symbol
side	string	Side
size	number	Position qty
position_value	string	Position value
entry_price	string	Average entry price
is_isolated	bool	`true` means isolated margin mode; `false` means cross margin mode
auto_add_margin	number	Whether to add margin automatically
leverage	string	In Isolated Margin mode, the value is set by user. In Cross Margin mode, the value is the max leverage at current risk level
effective_leverage	string	Effective leverage
position_margin	string	Position margin
liq_price	string	Liquidation price
bust_price	string	Bankruptcy price
occ_closing_fee	string	Position closing fee occupied (your opening fee + expected maximum closing fee)
occ_funding_fee	string	Pre-occupied funding fee: calculated from position qty and current funding fee
take_profit	string	Take profit price
stop_loss	string	Stop loss price
trailing_stop	string	Trailing stop
position_status	string	Position status: `Normal`, `Liq`, `Adl`
deleverage_indicator	number	Deleverage indicator level (1,2,3,4,5)
oc_calc_data	string	Pre-occupied calculate parameters. `blq`: total number of the long side unsettled orders; `bmp`: the lowest price of the long side; `slq`: total number of the short side unsettled orders; `smp`: the lowest price of the short side
order_margin	string	Pre-occupied order margin
wallet_balance	string	Wallet balance
realised_pnl	string	Today's realised pnl
unrealised_pnl	number	unrealised pnl
cum_realised_pnl	string	Accumulated realised pnl (all-time total)
cross_seq	number	Cross sequence (internal value)
position_seq	number	Position sequence
created_at	string	The account creation time
updated_at	string	Update time

Change Margin

Request Example

curl https://api.bybit.com/futures/private/position/change-position-margin \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21",margin:"10","timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesPositions.FuturesPositions_changeMargin(symbol="BTCUSDM21", margin="10").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": 9.996e-05,
    "ext_info": null,
    "time_now": "1577480720.003444",
    "rate_limit_status": 74,
    "rate_limit_reset_ms": 1577480720011,
    "rate_limit": 75
}

Update margin.

HTTP Request

POST /futures/private/position/change-position-margin

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
position_idx	true	integer	Position idx, used to identify positions in different position modes: 0-One-Way Mode 1-Buy side of both side mode 2-Sell side of both side mode
margin	true	string	margin

Response Parameters

parameter	type	comments
result	number	User margin

Set Trading-Stop

Request Example

curl https://api.bybit.com/futures/private/position/trading-stop \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","stop_loss":7000,"timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesPositions.FuturesPositions_tradingStop(symbol="BTCUSDM21",take_profit="0", stop_loss="9110", trailing_stop="0", new_trailing_active="0").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
        "id": 27913,
        "user_id": 1,
        "symbol": "BTCUSDM21",
        "side": "Buy",
        "size": 5,
        "position_value": 0.0006947,
        "entry_price": 7197.35137469,
        "risk_id": 1,
        "auto_add_margin": 0,
        "leverage": 6.95,
        "position_margin": 9.996e-05,
        "liq_price": 6320,
        "bust_price": 6292.5,
        "occ_closing_fee": 6e-07,
        "occ_funding_fee": 0,
        "take_profit": 0,
        "stop_loss": 7000,
        "trailing_stop": 0,
        "position_status": "Normal",
        "deleverage_indicator": 5,
        "oc_calc_data": "{\"blq\":2,\"blv\":\"0.0002941\",\"slq\":0,\"bmp\":6800.408,\"smp\":0,\"fq\":-5,\"fc\":-0.00004279,\"bv2c\":0.14549282,\"sv2c\":0.14527699}",
        "order_margin": 4.279e-05,
        "wallet_balance": 0.03000227,
        "realised_pnl": -1.26e-06,
        "cum_realised_pnl": -1.306e-05,
        "cum_commission": 0,
        "cross_seq": 444081383,
        "position_seq": 287176872,
        "created_at": "2019-10-19T17:04:55.000Z",
        "updated_at": "2019-12-27T21:17:27.000Z",
        "ext_fields": {
            "trailing_active":"9000",
            "sl_trigger_by": "LastPrice",
            "v": 221,
            "mm": 0
        }
    },
    "ext_info": null,
    "time_now": "1577481447.436689",
    "rate_limit_status": 73,
    "rate_limit_reset_ms": 1577481447443,
    "rate_limit": 75
}

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

HTTP Request

POST /futures/private/position/trading-stop

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
position_idx	true	integer	Position idx, used to identify positions in different position modes: 0-One-Way Mode 1-Buy side of both side mode 2-Sell side of both side mode
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	take profit trigger price type, default: `LastPrice`
sl_trigger_by	false	string	take profit trigger price type, default: `LastPrice`
new_trailing_active	false	number	Trailing stop trigger price. Trailing stops are triggered only when the price reaches the specified price. Trailing stops are triggered immediately by default.

Response Parameters

parameter	type	comments
id	number	PositionID
user_id	number	UserID
symbol	string	Symbol
side	string	Side
size	number	Position qty
position_value	string	Position value
entry_price	string	Average entry price
risk_id	number	Risk ID
auto_add_margin	number	Whether to add margin automatically
leverage	string	In Isolated Margin mode, the value is set by user. In Cross Margin mode, the value is the max leverage at current risk level
position_margin	string	Position margin
liq_price	string	Liquidation price
bust_price	string	Bankruptcy price
occ_closing_fee	string	Position closing fee occupied (your opening fee + expected maximum closing fee)
occ_funding_fee	string	Pre-occupied funding fee: calculated from position qty and current funding fee
take_profit	string	Take profit price
stop_loss	string	Stop loss price
trailing_stop	string	Trailing stop
position_status	string	Position status: `Normal`, `Liq`, `Adl`
deleverage_indicator	number	Deleverage indicator level (1,2,3,4,5)
oc_calc_data	string	Pre-occupied calculate parameters. `blq`: total number of the long side unsettled orders; `bmp`: the lowest price of the long side; `slq`: total number of the short side unsettled orders; `smp`: the lowest price of the short side
order_margin	string	Pre-occupied order margin
wallet_balance	string	Wallet balance
realised_pnl	string	Today's realised pnl
cum_realised_pnl	string	Accumulated realised pnl (all-time total)
cum_commission	number	Accumulated commission
cross_seq	number	Cross sequence (internal value)
position_seq	number	Position sequence
created_at	string	Creation time
updated_at	string	Update time
ext_fields>trailing_active	string	Trailing stop active price
ext_fields>sl_trigger_by	string	Stoploss trigger price type

Set Leverage

Request Example

curl https://api.bybit.com/futures/private/position/leverage/save \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","buy_leverage":14,"sell_leverage":14,"timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesPositions.FuturesPositions_saveLeverage(symbol="BTCUSDM21",position_idx=1, buy_leverage="14",sell_leverage="14").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": 2,
    "ext_info": null,
    "time_now": "1577477968.175013",
    "rate_limit_status": 74,
    "rate_limit_reset_ms": 1577477968183,
    "rate_limit": 75
}

Set Leverage

Set leverage to 0 if you want to trade in Cross Margin mode. Note that your position mode will be changed to Isolated Margin mode if you change your leverage from 0 to any other value.

HTTP Request

POST /futures/private/position/leverage/save

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
position_idx	true	integer	Position idx, used to identify positions in different position modes: 0-One-Way Mode 1-Buy side of both side mode 2-Sell side of both side mode
buy_leverage	true	number	translation missing: en.futures_row_comment_leverage
sell_leverage	true	number	translation missing: en.futures_row_comment_leverage

Response Parameters

parameter	type	comments
result	number	User leverage

Position Mode Switch

Request Example

curl https://api.bybit.com/futures/private/position/switch-mode \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","mode":0,"timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesPositions.FuturesPositions_switchPositionMode(symbol="BTCUSDM21",mode=0).result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": 2,
    "ext_info": null,
    "time_now": "1577477968.175013",
    "rate_limit_status": 74,
    "rate_limit_reset_ms": 1577477968183,
    "rate_limit": 75
}

If you are in One-Way Mode, you can only open one position on Buy or Sell side;
If you are in Hedge Mode, you can open both Buy and Sell side positions simultaneously.

HTTP Request

POST /futures/private/position/switch-mode

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
mode	true	int	Position Mode. `0`: One-Way Mode; `3`: Hedge Mode

Response Parameters

parameter	type	comments
result	number	Position Mode. `0`: One-Way Mode; `3`: Hedge Mode

Cross/Isolated Margin Switch

Request Example

curl https://api.bybit.com/futures/private/position/switch-isolated \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21", "position_idx":1, "is_isolated":true,"buy_leverage":10,"sell_leverage":20, "timestamp":{timestamp},"sign":"{sign}"}'

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesPositions.FuturesPositions_switchIsolated(symbol="BTCUSDM21",position_idx=1,is_isolated=True, buy_leverage="1", sell_leverage="1").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": 2,
    "ext_info": null,
    "time_now": "1577477968.175013",
    "rate_limit_status": 74,
    "rate_limit_reset_ms": 1577477968183,
    "rate_limit": 75
}

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

HTTP Request

POST /futures/private/position/switch-isolated

Request Parameters

parameter	required	type	comments
symbol	true	string	Symbol
position_idx	true	integer	Position idx, used to identify positions in different position modes: 0-One-Way Mode 1-Buy side of both side mode 2-Sell side of both side mode
is_isolated	true	bool	Cross/Isolated: true is Isolated; false is Cross
buy_leverage	true	number	translation missing: en.futures_row_comment_leverage
sell_leverage	true	number	translation missing: en.futures_row_comment_leverage

Response Parameters

parameter	type	comments
result	number

User Trade Records

Request Example

curl "https://api.bybit.com/futures/private/execution/list?api_key={api_key}&symbol=BTCUSDM21&timestamp={timestamp}&sign={sign}"

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesExecution.FuturesExecution_getTrades(symbol="BTCUSDM21").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "order_id": "Abandoned!!", // Abandoned!!
        "trade_list": [
            {
                "closed_size": 0, // The corresponding closing size of the closing order
                "cross_seq": 277136382,
                "exec_fee": "0.0000001",
                "exec_id": "256e5ef8-abfe-5772-971b-f944e15e0d68",
                "exec_price": "8178.5",
                "exec_qty": 1,
                "exec_time": "1571676941.70682",    //Abandoned!!
                "exec_type": "Trade", //Exec Type Enum
                "exec_value": "0.00012227",
                "fee_rate": "0.00075",
                "last_liquidity_ind": "RemovedLiquidity", //Liquidity Enum, only valid while exec_type is Trade、AdlTrade、BustTrade
                "leaves_qty": 0,
                "nth_fill": 2,
                "order_id": "7ad50cb1-9ad0-4f74-804b-d82a516e1029",
                "order_link_id": "",
                "order_price": "8178",
                "order_qty": 1,
                "order_type": "Market", //Order Type Enum
                "side": "Buy", //Side Enum
                "symbol": "BTCUSDM21", //Symbol Enum
                "user_id": 1,
                "trade_time_ms": 1577480599000
            }
        ]
    },
    "time_now": "1577483699.281488",
    "rate_limit_status": 118,
    "rate_limit_reset_ms": 1577483699244737,
    "rate_limit": 120
}

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

HTTP Request

GET /futures/private/execution/list

Request Parameters

parameter	required	type	comments
order_id	false	string	OrderID. If not provided, will return user's trading records
symbol	true	string	Contract type. Required
start_time	false	int	Start timestamp point for result, in milliseconds
page	false	integer	Page. By default, gets first page of data
limit	false	integer	Limit for data size per page, max size is 200. Default as showing 50 pieces of data per page
order	false	string	Sort orders by creation date

Response Parameters

parameter	type	comments
closed_size	number	The corresponding closing size of the closing order
cross_seq	number	Cross sequence (internal value)
exec_fee	string	Transaction fee
exec_id	string	Transaction ID
exec_price	number	Transaction price
exec_qty	number	Transaction qty
exec_type	string	Exec Type Enum
exec_value	string	Transaction value
fee_rate	string	Maker or taker fee rate
last_liquidity_ind	string	Liquidity Enum, only valid while `exec_type` is `Trade、AdlTrade、BustTrade`
leaves_qty	number	Number of unfilled contracts from the order's size
nth_fill	number	The sequence of the transaction in this cross sequence data package
order_id	string	Order ID
order_link_id	string	Order link ID
order_price	string	Order price
order_qty	string	Order qty
order_type	string	Order Type Enum
side	string	Side
symbol	string	Symbol Enum
user_id	number	User ID
trade_time_ms	number	Transaction timestamp

Closed Profit and Loss

Request Example

curl "https://api.bybit.com/futures/private/trade/closed-pnl/list?api_key={api_key}&symbol=BTCUSDM21&timestamp={timestamp}&sign={sign}"

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.FuturesPositions.FuturesPositions_closePnlRecords(symbol="BTCUSDM21").result())

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "current_page": 1,
        "data": [
            {
                "id": 9982,
                "user_id": 160320,
                "symbol": "BTCUSDM21",
                "order_id": "e976ac13-10e7-4883-a7ba-13b0e93659f1",
                "side": "Sell",
                "qty": 226,
                "order_price": 1600,
                "order_type": "Limit",
                "exec_type": "Trade",
                "closed_size": 113,
                "cum_entry_value": 0.07062500000000001,
                "avg_entry_price": 1600,
                "cum_exit_value": 0.066198,
                "avg_exit_price": 1707,
                "closed_pnl": 0.0043950000000000005,
                "fill_count": 1,
                "leverage": 100,
                "created_at": 1591155741
            }
        ]
    },
    "time_now": "1591173153.876047",
    "rate_limit_status": 119,
    "rate_limit_reset_ms": 1591173153852,
    "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 /futures/private/trade/closed-pnl/list

Request Parameters

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

Response Parameters

parameter	type	comments
id	number	PositionID
user_id	number	UserID
symbol	string	Symbol
order_id	string	Order ID
side	string	Side
qty	number	Order quantity in USD
order_price	number	Order price
order_type	string	Active order type
exec_type	string	Exec Type Enum
closed_size	number	The corresponding closing size of the closing order
cum_entry_value	number	Closed position value
avg_entry_price	number	Average entry price
cum_exit_value	number	Cumulative trading value of position closing orders
avg_exit_price	number	Average exit price
closed_pnl	number	Closed Profit and Loss
fill_count	number	Number of transactions
leverage	number	In Isolated Margin mode, the value is set by user. In Cross Margin mode, the value is the max leverage at current risk level
created_at	number	Creation time

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.

Asset Exchange Records

Please see the shared endpoint.

API Data Endpoints

The following API data endpoints do not require authentication.

Server Time

Request Example

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

import bybit
client = bybit.bybit(test=True, api_key="api_key", api_secret="api_secret")
print(client.Common.Common_get().result())

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

Request Example

curl https://api.bybit.com/v2/public/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 in 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:

GETmethod:
- 70 requests per second
- 50 requests per second continuously for 2 minutes
POSTmethod:
- 50 requests per second
- 20 requests per second continuously for 2 minutes

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_limit_status - your remaining requests for current endpoint
rate_limit - your current limit for current endpoint
rate_limit_reset_ms - the timestamp indicating when your request limit resets if you have exceeded your rate_limit. Otherwise, this is just the current timestamp.

Rate Limits For All Private Endpoints

limit	path	consume
100/min
	futures/private/order/cancel	1 / request
	futures/private/stop-order/create	1 / request
	futures/private/stop-order/cancel	1 / request
	futures/private/order/replace	1 / request
	futures/private/stop-order/replace	1 / request
	futures/private/order/create	1 / request
	futures/private/order/cancel	1 / request
	futures/private/order/cancelAll	10 / request
	futures/private/stop-order/cancelAll	10 / request
600/min	futures/private/order/list	1 / request
	futures/private/stop-order/list	1 / request
	futures/private/order	1 / request
120/min	futures/private/execution/list	1 / request
75/min	futures/private/position/leverage/save	1 / request
	futures/private/position/change-position-margin	1 / request
	futures/private/position/trading-stop	1 / request
	futures/private/position/switch-mode	1 / request
	futures/private/position/switch-isolated	1 / request
120/min

	futures/private/position/list	1 / request
	v2/private/wallet/balance	1 / request
120/min
	v2/private/wallet/fund/records	1 / request
	v2/private/wallet/withdraw/list	1 / request
600/min
600/min	v2/private/account/api-key	1 / request

Order Limits

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

Active orders: 500
Conditional orders: 10

How to Raise Your API Limit

Please read Understanding Bybit's Liquidity System to understand how our system automatically allocates rate limits for users placing over 2000 orders per day.
Please send your application email to api@bybit.com. We will reply in 1-4 working days. And the email must include below information:

Your name and your company details
Your Bybit UIDs or registered Emails, and the symbol which you are trading
General description of your trading strategy and why requires higher rate limit
Screenshot of previous monthly trading volume (maker/taker) with other platforms
Optional: your order history in CSV files

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 (OFR): Orders Filled to Orders Submitted to Bybit to Bybit.
Orders Submitted to Bybit: any order sent to Bybit.
Orders Filled: any order that has been filled for any amount.
OFR = (number of orders filled / number of orders submitted to Bybit)

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)

Liquidity Contribution Points (LCP) = POU * POA * 100

Explanation

Effective Price Range

effective price range: 6 tick sizes range around middle of best bid price and best ask price.
Min effective price: (best bid price + best ask price) / 2 - (3 * tick_size)
Max effective price: (best bid price + best ask price) / 2 + (3 * tick_size)

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

POU: the proportion of your orders within effective price range to all your orders in orderbook.

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

POA: the proportion of your orders within effective price range to all orders within effective price range in orderbook.

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:

Testnet: wss://stream-testnet.bybit.com/realtime

Mainnet (both endpoints are available):
- wss://stream.bybit.com/realtime
- wss://stream.bytick.com/realtime

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

Due to unstable networks or program errors, we strongly advise you to send the ping heartbeat packet to maintain websocket connections. We recommend every 30 seconds to 1 minute.

Understanding Websocket Filters

How to subscribe with a filter

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

How to subscribe with multiple filters

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

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.BTCUSDH21.1m"
       ]
   }
}

Every subscription will have a response.

Public Topics

orderBookL2_25

How to Subscribe

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

from BybitWebsocket import BybitWebsocket
ws = BybitWebsocket(wsURL="wss://stream-testnet.bybit.com/realtime",
                    api_key=None, api_secret=None)
ws.subscribe_orderBookL2(symbol="BTCUSDH21")
while True:
    data = ws.get_data("orderBookL2_25.BTCUSDH21")
    if data:
        print(data)

Snapshot Response Example - format of the first response

{
     "topic": "orderBookL2_25.BTCUSDH21",
     "type": "snapshot",
     "data": [
        {
            "price": "2999.00",
            "symbol": "BTCUSDH21",
            "id": 29990000,
            "side": "Buy",
            "size": 9
        },
        {
            "price": "3001.00",
            "symbol": "BTCUSDH21",
            "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.BTCUSDH21",
     "type": "delta",
     "data": {
          "delete": [
             {
                   "price": "3001.00",
                   "symbol": "BTCUSDH21",
                   "id": 30010000,
                   "side": "Sell"
             }
          ],
          "update": [
             {
                   "price": "2999.00",
                   "symbol": "BTCUSDH21",
                   "id": 29990000,
                   "side": "Buy",
                   "size": 8
             }
          ],
          "insert": [
             {
                   "price": "2998.00",
                   "symbol": "BTCUSDH21",
                   "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.

Response Parameters

parameter	type	comments
price	string	Order price
symbol	string	Symbol
side	string	Side
size	number	Position qty

orderBookL2_200

How to Subscribe

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

Snapshot Response Example - format of the first response

{
     "topic": "orderBook_200.100ms.BTCUSDH21",
     "type": "snapshot",
     "data": [
        {
            "price": "2999.00",
            "symbol": "BTCUSDH21",
            "id": 29990000,
            "side": "Buy",
            "size": 9
        },
        {
            "price": "3001.00",
            "symbol": "BTCUSDH21",
            "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.BTCUSDH21",
     "type": "delta",
     "data": {
          "delete": [
             {
                   "price": "3001.00",
                   "symbol": "BTCUSDH21",
                   "id": 30010000,
                   "side": "Sell"
             }
          ],
          "update": [
             {
                   "price": "2999.00",
                   "symbol": "BTCUSDH21",
                   "id": 29990000,
                   "side": "Buy",
                   "size": 8
             }
          ],
          "insert": [
             {
                   "price": "2998.00",
                   "symbol": "BTCUSDH21",
                   "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.

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

Response Parameters

parameter	type	comments
price	string	Order price
symbol	string	Symbol
side	string	Side
size	number	Position qty

trade

How to Subscribe

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

from BybitWebsocket import BybitWebsocket
ws = BybitWebsocket(wsURL="wss://stream-testnet.bybit.com/realtime",
                    api_key=None, api_secret=None)
ws.subscribe_trade()
while True:
    data = ws.get_data("trade.BTCUSDH21")
    if data:
        print(data)

Response Example - format of all responses

{
    "topic": "trade.BTCUSDH21",
    "data": [
        {
            "timestamp": "2020-01-12T16:59:59.000Z",
            "trade_time_ms": 1582793344685, // trade time in millisecond
            "symbol": "BTCUSDH21",
            "side": "Sell",
            "size": 328,
            "price": 8098,
            "tick_direction": "MinusTick",
            "trade_id": "00c706e1-ba52-5bb0-98d0-bf694bdc69f7",
            "cross_seq": 1052816407
        }
    ]
}

Get real-time trading information.

Response Parameters

parameter	type	comments
time	string	UTC time
trade_time_ms	number	Millisecond timestamp
symbol	string	Symbol
side	string	Side
size	number	Position qty
price	number	Order price
tick_direction	string	Direction of price change
trade_id	string	Trade ID
cross_seq	number	Cross sequence (internal value)

insurance

How to Subscribe

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

from BybitWebsocket import BybitWebsocket
ws = BybitWebsocket(wsURL="wss://stream-testnet.bybit.com/realtime",
                    api_key=None, api_secret=None)
ws.subscribe_insurance()
while True:
    data = ws.get_data("insurance.BTC")
    if data:
        print(data)

Response Example - format of all responses

{
    "topic": "insurance.BTC",
    "data": [
        {
            "currency": "BTC",
            "timestamp": "2020-01-11T20:00:00Z",
            "wallet_balance": 98786916569
        }
    ]
}

Get the daily insurance fund update.

The wallet_balance is in Satoshis, with one Satoshi being 100 millionth (100000000) of one Bitcoin.

Response Parameters

parameter	type	comments
currency	string	Currency type
timestamp	string	UTC time
wallet_balance	number	Wallet balance

instrument_info

How to Subscribe

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

from BybitWebsocket import BybitWebsocket
ws = BybitWebsocket(wsURL="wss://stream-testnet.bybit.com/realtime",
                    api_key=None, api_secret=None)
ws.subscribe_instrument_info(symbol="BTCUSDH21")
while True:
    data = ws.get_data("instrument_info.100ms.BTCUSDH21")
    if data:
        print(data)

Snapshot Response Example - format of the first response

{
    "topic":"instrument_info.100ms.BTCUSDH21",
    "type":"snapshot",
    "data":{
        "id":8,
        "symbol":"BTCUSDM21",
        "symbol_name":"BTCUSD0625",
        "symbol_year":2021,
        "contract_type":"InverseFutures",  // Contract Type Enum             
        "coin":"BTC",
        "quote_symbol":"BTCUSD",
        "mode":"MergedSingle", // Supported position mode: MergedSingle - Single side position mode  BothSide - Both side mode
        "is_up_borrowable":0,
        "import_time_e9":0,
        "start_trading_time_e9":1602732600000000000,
        "time_to_settle":1038939,
        "settle_time_e9":1616833800000000000,
        "settle_fee_rate_e8":0,
        "contract_status":"Trading",
        "system_subsidy_e8":0,
        "last_price_e4":500340000,
        "last_tick_direction":"MinusTick",
        "bid1_price_e4":400025000,
        "ask1_price_e4":475450000,
        "prev_price_24h_e4":467820000,
        "price_24h_pcnt_e6":90205,
        "high_price_24h_e4":573420000,
        "low_price_24h_e4":510020000,
        "prev_price_1h_e4":543920000,
        "price_1h_pcnt_e6":-62325,
        "mark_price_e4":507019537,
        "index_price_e4":579821900,
        "open_interest":0,
        "open_value_e8":0,
        "total_turnover_e8":874161217,
        "turnover_24h_e8":6781366,
        "total_volume":426476,
        "volume_24h":3613,
        "fair_basis_e8":-793519000000,
        "fair_basis_rate_e8":-13685564,
        "basis_in_year_e8":-412313782,
        "expect_price_e4":0,
        "cross_seq":8761176,
        "created_at_e9":0,
        "updated_at_e9":1615541855287480000
    },
    "cross_seq":9267002,
    "timestamp_e6":1615794861826248
}

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

{
    "topic": "instrument_info.100ms.BTCUSDH21",
    "type": "delta",
    "data": {
        "delete": [],
        "update": [
            {
                "id": 1,
                "symbol": "BTCUSDH21",
                "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.

This topic only utilises the update field. Both the delete and insert fields are null. If a key is not found in the update field, its value has not changed.

Some values use scientific notation. This is indicated by that value's key, which will be appended with, for example, e6. If the key is last_price_e4 and the value is 81585000, then to find the true value we can do 81585000 / 10^4, which equals 8158.5.

Response Parameters

parameter	type	comments
symbol	string	Symbol
last_price_e4	integer	Latest transaction price 10^4
last_tick_direction	string	Tick Direction
prev_price_24h_e4	integer	Price of 24 hours ago * 10^4
price_24h_pcnt_e6	integer	Percentage change of market price relative to 24h * 10^4
high_price_24h_e4	integer	The highest price in the last 24 hours * 10^4
low_price_24h_e4	integer	Lowest price in the last 24 hours * 10^4
prev_price_1h_e4	integer	Hourly market price an hour ago * 10^4
price_1h_pcnt_e6	integer	Percentage change of market price relative to 1 hour ago * 10^6
mark_price_e4	integer	Mark price * 10^4
index_price_e4	integer	Index_price * 10^4
open_interest	integer	Open interest. The update is not immediate - slowest update is 1 minute
open_value_e8	integer	Open position value * 10^8. The update is not immediate - slowest update is 1 minute
total_turnover_e8	integer	Total turnover * 10^8
turnover_24h_e8	integer	Turnover for 24H * 10^8
total_volume	integer	Total volume
volume_24h	integer	Trading volume in the last 24 hours
predicted_funding_rate_e6	integer	Predicted funding rate *10^6
cross_seq	integer	Cross sequence (internal value)
created_at	string	Creation time
updated_at	string	Update time
next_funding_time	string	Next settlement time of capital cost
countdown_hour	integer	Countdown of settlement capital cost

klineV2

How to Subscribe

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

Response Example - format of all responses

{
    "topic": "klineV2.1.BTCUSDH21",                //topic name
    "data": [{
        "start": 1572425640,                    //start time of the candle
        "end": 1572425700,                      //end time of the candle
        "open": 9200,                           //open price
        "close": 9202.5,                        //close price
        "high": 9202.5,                         //max price
        "low": 9196,                            //min price
        "volume": 81790,                        //volume
        "turnover": 8.889247899999999,          //turnover
        "confirm": False,                       //snapshot flag
        "cross_seq": 297503466,                 
        "timestamp": 1572425676958323           //cross time
    }],
    "timestamp_e6": 1572425677047994            //server time
}

Currently supported intervals:

1 3 5 15 30
60 120 240 360
D
W
M

If confirm is True, the data is the final tick for the interval. Otherwise, it is a snapshot.

Response Parameters

parameter	type	comments
start	integer	Start timestamp point for result, in seconds
end	integer	End timestamp point for result, in seconds
open	number	Starting price
close	number	Closing price
high	number	Maximum price
low	number	Minimum price
volume	number	Trading volume
turnover	number	Transaction amount
confirm	bool	Is confirm
cross_seq	integer	Cross sequence (internal value)
timestamp	integer	End timestamp point for result, in seconds

Private Topics

position

How to Subscribe

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

from BybitWebsocket import BybitWebsocket
ws = BybitWebsocket(wsURL="wss://stream-testnet.bybit.com/realtime",
                    api_key=api_key, api_secret=api_secret)
ws.subscribe_position()
while True:
    data = ws.get_data("position")
    if data:
        print(data)

Response Example - format of all responses

{
   "topic": "position",
   "action": "update",
   "data": [
       {
           "user_id":  1,                            // user ID
           "symbol": "BTCUSDH21",                       // the contract for this position
           "position_idx":1,
           "size": 11,                               // the current position amount
           "side": "Sell",                           // side
           "mode": 0,                                // 0- merged single mode 3- both side mode
           "isolated":true,
           "position_value": "0.00159252",           // positional value
           "entry_price": "6907.291588174717",       // entry price
           "liq_price": "7100.234",                  // liquidation price
           "bust_price": "7088.1234",                // bankruptcy price
           "leverage": "1",                           // leverage
           "order_margin":  "1",                      // order margin
           "position_margin":  "1",                   // position margin
           "available_balance":  "2",                 // available balance
           "take_profit": "0",                        // take profit price           
           "tp_trigger_by":  "LastPrice",             // take profit trigger price, eg: LastPrice, IndexPrice. Conditional order only
           "stop_loss": "0",                          // stop loss price
           "sl_trigger_by":  "",                     // stop loss trigger price, eg: LastPrice, IndexPrice. Conditional order only
           "realised_pnl":  "0.10",               // realised PNL
           "trailing_stop": "0",                  // trailing stop points
           "trailing_active": "0",                // trailing stop trigger price
           "wallet_balance":  "4.12",             // wallet balance
           "risk_id":  1,                       
           "occ_closing_fee":  "0.1",             // position closing
           "occ_funding_fee":  "0.1",             // funding fee
           "auto_add_margin": 0,                  // auto margin replenishment switch
           "cum_realised_pnl":  "0.12",           // Total realized profit and loss
           "position_status": "Normal",           // status of position (Normal: normal Liq: in the process of liquidation Adl: in the process of Auto-Deleveraging)
                        // Auto margin replenishment enabled (0: no 1: yes)
           "position_seq": 14                     // position version number
       }
   ]
}

Get my position list.

Response Parameters

parameter	type	comments
user_id	number	UserID
symbol	string	Symbol
side	string	Side
size	number	Position qty
position_value	string	Position value
entry_price	string	Average entry price
liq_price	string	Liquidation price
bust_price	string	Bankruptcy price
leverage	string	In Isolated Margin mode, the value is set by user. In Cross Margin mode, the value is the max leverage at current risk level
order_margin	string	Pre-occupied order margin
position_margin	string	Position margin
available_balance	string	Available balance = wallet balance - used margin
take_profit	string	Take profit price
tp_trigger_by	string	take profit trigger price type, default: `LastPrice`
stop_loss	string	Stop loss price
sl_trigger_by	string	stop loss trigger price type, default: `LastPrice`
realised_pnl	string	Today's realised pnl
trailing_stop	string	Trailing stop
trailing_active	string	Trailing stop active price
wallet_balance	string	Wallet balance
risk_id	number	Risk ID
occ_closing_fee	string	Position closing fee occupied (your opening fee + expected maximum closing fee)
occ_funding_fee	string	Pre-occupied funding fee: calculated from position qty and current funding fee
auto_add_margin	number	Whether to add margin automatically
cum_realised_pnl	string	Accumulated realised pnl (all-time total)
position_status	string	Position status: `Normal`, `Liq`, `Adl`
position_seq	number	Position sequence

execution

How to Subscribe

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

from BybitWebsocket import BybitWebsocket
ws = BybitWebsocket(wsURL="wss://stream-testnet.bybit.com/realtime",
                    api_key=api_key, api_secret=api_secret)
ws.subscribe_execution()
while True:
    data = ws.get_data("execution")
    if data:
        print(data)

Response Example - format of all responses

{
    "topic": "execution",
    "data": [
        {
            "symbol": "BTCUSDH21",
            "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",
            "leaves_qty": 0,
            "is_maker": false,
            "trade_time": "2020-01-14T14:07:23.629Z" // trade time
        }
    ]
}

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

Response Parameters

parameter	type	comments
symbol	string	Symbol
side	string	Side
order_id	string	Order ID
exec_id	string	Transaction ID
order_link_id	string	Order link ID
price	string	Transaction price
order_qty	number	Order qty
exec_type	string	Exec Type Enum
exec_qty	number	Transaction qty
exec_fee	string	Transaction fee
leaves_qty	number	Number of unfilled contracts from the order's size
is_maker	bool	Is maker
trade_time	string	Transaction timestamp

order

How to Subscribe

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

from BybitWebsocket import BybitWebsocket
ws = BybitWebsocket(wsURL="wss://stream-testnet.bybit.com/realtime",
                    api_key=api_key, api_secret=api_secret)
ws.subscribe_order()
while True:
    data = ws.get_data("order")
    if data:
        print(data)

Response Example - format of all responses

{
    "topic": "order",
    "data": [
        {
            "order_id": "xxxxxxxx-xxxx-xxxx-9a8f-4a973eb5c418",
            "order_link_id": "",
            "symbol": "BTCUSDH21",
            "side": "Sell",
            "order_type": "Market",
            "price": "8579.5",
            "qty": 1,
            "time_in_force": "ImmediateOrCancel",
            "create_type": "CreateByClosing",
            "cancel_type": "",
            "order_status": "Filled",
            "leaves_qty": 0,
            "cum_exec_qty": 1,
            "cum_exec_value": "0.00011655",
            "cum_exec_fee": "0.00000009",
            "timestamp": "2020-01-14T14:09:31.778Z",
            "take_profit": "0",
            "stop_loss": "0",
            "trailing_stop": "0",
            "trailing_active": "0",
            "last_exec_price": "8580",
            "reduce_only": false,
            "close_on_trigger": false
        }
    ]
}

Response Parameters

parameter	type	comments
order_id	string	Order ID
order_link_id	string	Order link ID
symbol	string	Symbol
side	string	Side
order_type	string	Conditional order type
price	string	Order price
qty	number	Transaction qty
time_in_force	string	Time in force
create_type	string	Trigger scenario for single action
cancel_type	string	Trigger scenario for cancel operation
order_status	string	Order status
leaves_qty	number	Number of unfilled contracts from the order's size
cum_exec_qty	number	Cumulative qty of trading
cum_exec_value	string	Cumulative value of trading
cum_exec_fee	string	Cumulative trading fees
timestamp	string	Commission time
take_profit	string	Take profit price
stop_loss	string	Stop loss price
trailing_stop	string	Trailing stop
trailing_active	string	Trailing stop active price
last_exec_price	string	Last execution price
reduce_only	bool	What is a reduce-only order? True means your position can only reduce in size if this order is triggered
close_on_trigger	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.

stop_order

How to Subscribe

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

Response Example - format of all responses

{
    "topic": "stop_order",
    "data": [
        {
            "order_id": "xxxxxxxx-xxxx-xxxx-98fb-335aaa6c613b",
            "order_link_id": "",
            "user_id": 1,
            "symbol": "BTCUSDH21",
            "side": "Buy",
            "order_type": "Limit",
            "price": "8584.5",
            "qty": 1,
            "time_in_force": "ImmediateOrCancel",
            "create_type": "CreateByStopOrder",
            "cancel_type": "",
            "order_status": "Untriggered", //Stop Order Status
            "stop_order_type": "Stop",
            "trigger_by": "LastPrice",
            "trigger_price": "8584.5", //If stop_order_type is TrailingProfit, this field is the trailing stop active price.
            "close_on_trigger": false,
            "timestamp": "2020-01-14T14:11:22.062Z"
        }
    ]
}

Response Parameters

parameter	type	comments
order_id	string	Order ID
order_link_id	string	Order link ID
user_id	number	UserID
symbol	string	Symbol Enum
order_type	string	Order Type Enum
side	string	Side
price	string	Order price
qty	number	Order quantity in USD
time_in_force	string	Time in force
create_type	string	Trigger scenario for single action
cancel_type	string	Trigger scenario for cancel operation
order_status	string	Order status
stop_order_type	string	Conditional order type
trigger_by	string	Trigger price type. Default `LastPrice`
trigger_price	string	If `stop_order_type` is `TrailingProfit`, this field is the trailing stop active price.
close_on_trigger	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.
timestamp	string	UTC time

Archive Data

Historical Market Data

You can get Bybit's historical market data here.

ENUMs Definitions

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

Side (`side`)

Buy
Sell

Symbol (`symbol`)

BTCUSDH21 // H: First quarter; 21: 2021
BTCUSDM21 // M: Second quarter; 21: 2021
BTCUSDU21 // U: Third quarter; 21: 2021
BTCUSDZ21 // Z: Fourth quarter; 21: 2021

You can find trading symbols by Query Symbol endpoint

Currency (`currency`/`coin`)

BTC
ETH
EOS
XRP
USDT

Contract Type(`contract_type`)

InversePerpetual
LinearPerpetual
InverseFutures

Contract Status(`status`)

Trading
Settling
Closed

Wallet fund type (`wallet_fund_type`)

Deposit
Withdraw
RealisedPNL
Commission
Refund
Prize
ExchangeOrderWithdraw
ExchangeOrderDeposit

Withdraw status (`status`)

ToBeConfirmed
UnderReview
Pending - Pending transfer
Success
CancelByUser
Reject
Expire

Order type (`order_type`)

Limit
Market

Quantity (`qty`)

Maximum quantity of 1 million (1000000)
Must be an integer - no decimals, only a whole number of USD contracts
- 40 - allowed
- 30.5 - illegal

Price (`price`)

Active order
- Must be an increment of that market's tick_size
  - Current symbol information (like tick sizes) can be found with the Query Symbol endpoint.
  - Use modulo (%) to calculate whether or not a price will be accepted, like so:
```
IF price % tick_size = 0
    // send request
ELSE
    // do not send request as the price will not be accepted by the system
```
- Must be less than 1 million (1000000)
- If the user has no open position then the price must be greater than 10% of the market price
  - For example, if the current market price (last price) is 10314, then the absolute minimum the price may be is 1031.5. It may not be 1031 or below.
  - In pseudocode (assuming the price is an increment of 0.5):
```
IF price > (last_price * 0.1)
    // send request
ELSE
    // do not send request as the price will not be accepted by the system
```
- If the user holds a position, the order price must be better than the liquidation price.
  - For example, if the liquidation price of an open long position is 5176.5 then the price may be a minimum of 5177. In the case of a short position the price must be less than the liquidation price.
Conditional order
- Must be equal to order greater than 1

Time in force (`time_in_force`)

GoodTillCancel
ImmediateOrCancel
FillOrKill
PostOnly

Trigger price type (`trigger_by`)

LastPrice
IndexPrice
MarkPrice

Order (`order`)

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

desc
asc

Order status (`order_status`)

Created - order accepted by the system but not yet put through matching engine
Rejected
New - order has placed successfully
PartiallyFilled
Filled
Cancelled
PendingCancel - the matching engine has received the cancellation but there is no guarantee that it will be successful

Stop order status (`stop_order_status`)

Active - order is triggered and placed successfully
Untriggered - order waits to be triggered
Triggered - order is triggered
Cancelled - order is cancelled
Rejected - order is triggered but failed to be placed (for example, due to insufficient margin)
Deactivated - order was cancelled by user before triggering

Cancel type (`cancel_type`)

CancelByUser
CancelByReduceOnly
CancelByPrepareLiq,CancelAllBeforeLiq - Cancelled by force liquidation
CancelByPrepareAdl,CancelAllBeforeAdl - Cancelled by ADL
CancelByAdmin
CancelByTpSlTsClear - This is a cancelled TP/SL/TS order
CancelByPzSideCh - This order is cancelled after TP/SL/TS

Create type (`create_type`)

CreateByUser
CreateByClosing
CreateByAdminClosing
CreateByStopOrder
CreateByTakeProfit
CreateByStopLoss
CreateByTrailingStop
CreateByLiq - Created by partial liquidation
CreateByAdl_PassThrough - Created by ADL
CreateByTakeOver_PassThrough - Created by liquidation takeover

Exec type (`exec_type`)

Trade
AdlTrade
Funding
BustTrade

Liquidity type (`last_liquidity_ind`)

AddedLiquidity - Maker liquidity
RemovedLiquidity - Taker liquidity

Tick direction type (`tick_direction`)

It indicates the fluctuation of price, which is up or down relative to the last transaction

PlusTick - Rise in price
ZeroPlusTick - Rise in price compared to last trade of different price
MinusTick - Drop in price
ZeroMinusTick - Drop in price compared to last trade of different price

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`
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
10016	unexpect error or timeout
10017	request path not found or request method is invalid
10018	exceed ip rate limit
20001	Order not exists
20003	missing parameter `side`
20004	invalid parameter `side`
20005	missing parameter `symbol`
20006	invalid parameter `symbol`
20007	missing parameter `order_type`
20008	invalid parameter `order_type`
20009	missing parameter `qty`
20010	qty must be greater than 0
20011	qty must be an integer
20012	qty must be greater than zero and less than 1 million
20013	missing parameter `price`
20014	price must be greater than 0
20015	missing parameter `time_in_force`
20016	invalid value for parameter `time_in_force`
20017	missing parameter `order_id`
20018	invalid date format
20019	missing parameter `stop_px`
20020	missing parameter `base_price`
20021	missing parameter `stop_order_id`
20022	missing parameter `leverage`
20023	leverage must be a number
20031	leverage must be greater than zero
20070	missing parameter `margin`
20071	margin must be greater than zero
20084	order_id or order_link_id is required
30001	order_link_id is repeated
30003	qty must be more than the minimum allowed
30004	qty must be less than the maximum allowed
30005	price exceeds maximum allowed
30007	price exceeds minimum allowed
30008	invalid order_type
30009	no position found
30010	insufficient wallet balance
30011	operation not allowed as position is undergoing liquidation
30012	operation not allowed as position is undergoing ADL
30013	position is in liq or adl status
30014	invalid closing order, qty should not greater than size
30015	invalid closing order, side should be opposite
30016	TS and SL must be cancelled first while closing position
30017	estimated fill price cannot be lower than current Buy liq_price
30018	estimated fill price cannot be higher than current Sell liq_price
30019	cannot attach TP/SL params for non-zero position when placing non-opening position order
30020	position already has TP/SL params
30021	cannot afford estimated position_margin
30022	estimated buy liq_price cannot be higher than current mark_price
30023	estimated sell liq_price cannot be lower than current mark_price
30024	cannot set TP/SL/TS for zero-position
30025	trigger price should bigger than 10% of last price
30026	price too high
30027	price set for Take profit should be higher than Last Traded Price
30028	price set for Stop loss should be between Liquidation price and Last Traded Price
30029	price set for Stop loss should be between Last Traded Price and Liquidation price
30030	price set for Take profit should be lower than Last Traded Price
30031	insufficient available balance for order cost
30032	order has been filled or cancelled
30033	The number of stop orders exceeds maximum limit allowed
30034	no order found
30035	too fast to cancel
30036	the expected position value after order execution exceeds the current risk limit
30037	order already cancelled
30041	no position found
30042	insufficient wallet balance
30043	operation not allowed as position is undergoing liquidation
30044	operation not allowed as position is undergoing AD
30045	operation not allowed as position is not normal status
30049	insufficient available balance
30050	any adjustments made will trigger immediate liquidation
30051	due to risk limit, cannot adjust leverage
30052	leverage can not less than 1
30054	position margin is invalid
30057	requested quantity of contracts exceeds risk limit
30063	reduce-only rule not satisfied
30067	insufficient available balance
30068	exit value must be positive
30074	can't create the stop order, because you expect the order will be triggered when the `LastPrice`(or `IndexPrice`、 `MarkPrice`, determined by `trigger_by`) is raising to `stop_px`, but the `LastPrice`(or `IndexPrice`、 `MarkPrice`) is already equal to or greater than `stop_px`, please adjust `base_price` or `stop_px`
30075	can't create the stop order, because you expect the order will be triggered when the `LastPrice`(or `IndexPrice`、 `MarkPrice`, determined by `trigger_by`) is falling to `stop_px`, but the `LastPrice`(or `IndexPrice`、 `MarkPrice`) is already equal to or less than `stop_px`, please adjust `base_price` or `stop_px`
33004	apikey already expired
34026	the limit is no change

Group And Resources

Group And Bybit API Resources

Changelog

2021-04-07

REST API

2021-04-02

REST API

2021-03-12

REST API

2021-02-25

REST API

Websocket API

2021-03-01

REST API

Authentication

Parameters for Authenticated Endpoints

Constructing the Request

Market Data Endpoints

Orderbook

Query Kline

Latest Information for Symbol

Public Trading Records

Query Symbol

Liquidated Orders

Query Mark Price Kline

Query Index Price Kline

Advanced Data

Open Interest

Latest Big Deal

Long-Short Ratio

Account Data Endpoints

Active Orders

Place Active Order

Get Active Order

Cancel Active Order

Cancel All Active Orders

Replace Active Order

Query Active Order (real-time)

Conditional Orders

Place Conditional Order

Get Conditional Order

Cancel Conditional Order

Cancel All Conditional Orders

Replace Conditional Order

Query Conditional Order (real-time)

Position

My Position

Change Margin

Set Trading-Stop

Set Leverage

Position Mode Switch

Cross/Isolated Margin Switch

User Trade Records

Closed Profit and Loss

API Key Info

Wallet Data Endpoints

Get Wallet Balance

Wallet Fund Records

Withdraw Records

Asset Exchange Records

API Data Endpoints

Server Time

Announcement

API Rate Limits

IP Rate Limit

Understanding Your Request Rate Limit

Rate Limits For All Private Endpoints

Order Limits

How to Raise Your API Limit

Understanding Bybit's Liquidity System

Order Fill Ratio (OFR) Threshold

Order Fill Ratio (OFR)

Order Fill Ratio Example

Minimum OFR Threshold

API Request Frequency Limits

Liquidity Contribution Points (LCP)

Explanation

Effective Price Range

Effective Price Range Example

POU

Side (`side`)

Symbol (`symbol`)

Currency (`currency`/`coin`)

Contract Type(`contract_type`)

Contract Status(`status`)

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

Order status (`order_status`)

Stop order status (`stop_order_status`)

Cancel type (`cancel_type`)

Create type (`create_type`)

Exec type (`exec_type`)

Liquidity type (`last_liquidity_ind`)

Tick direction type (`tick_direction`)