繁體中文
NAV
console python old_python

Group And Resources

Bybit API and WebSocket documentation provides guidance to help you access Bybit's endpoints, their expected outputs, and common errors.

For further assistance or feedback, please join the API Telegram chat! API discussion group on Telegram.

Group And Bybit API Resources

Changelog

2022-04-29

REST API

2022-04-28

REST API

2021

2021-09-03

Websocket API

2021-06-03

REST API

2021-05-20

REST API

2021-05-17

REST API

2021-05-12

REST API

2021-05-12

REST API

2021-05-07

REST API

2021-04-15

REST API

2021-04-14

REST API

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

FAQ

reduce_only and close_on_trigger - what's the difference?

Why aren't all my orders showing on the website?

Calculating order size based on available wallet balance

Can I exchange assets with the API?

Where are Bybit's servers located?

AWS Singapore, Availability Zone ID apse1-az3.

How do I get funds for testnet?

To get testnet funds, please contact the website's customer support using the yellow support button shown in the bottom-right corner.

Why are my Closed PNL prices inaccurate?

Why are values returned to too many decimal places? (float precision issue)

How can I ensure I am using up-to-date data?

What is the difference between turnover and volume?

Authentication

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

Parameters for Authenticated Endpoints

The following parameters must be used for authentication:

We also provide recv_window (unit in millisecond and default value is 5,000) to specify how long an HTTP request is valid. It is also 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 make sure that your timestamp is in sync with our server time. You can use the Server Time endpoint.

Create A Request

An example for adjusting leverage

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

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. Use the HMAC_SHA256 algorithm to sign the query string in step 1, and convert it to a hex string to obtain the sign parameter.

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 sign parameter to the end of the parameters string, and send the HTTP request. Note that the message format for GET and POST requests is different. Please refer to the examples.

Market Data Endpoints

The following market data endpoints do not require authentication.

Order Book

Please see the shared endpoint.

Query Kline

Please see the shared endpoint.

Latest Information for Symbol

Please see the shared endpoint.

Public Trading Records

Please see the shared endpoint.

Query Symbol

Please see the shared endpoint.

Liquidated Orders

Please see the shared endpoint.

Query Mark Price Kline

Please see the shared endpoint.

Query Index Price Kline

Please see the shared endpoint.

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-testnet.bybit.com/futures/private/order/create \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","position_idx":1,"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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.place_active_order(
    position_idx=1,
    symbol="BTCUSDM21",
    side="Buy",
    order_type="Market",
    qty=1,
    time_in_force="GoodTillCancel"
))

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: 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 converted 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: You can set an execution price for your order. The system will fill your order once the last traded price reaches your execution price.

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 price should be 10% higher than the market price and less than 1 million. For the minimum unit of price movement, please refer to the price_filter field in the Query Symbol 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.

HTTP Request

POST /futures/private/order/create

Request Parameters

Parameter Required Type Comment
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
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 Unique user-set order ID. Maximum length of 36 characters
take_profit false number Take profit price, only take effect upon opening the position
stop_loss false number Stop loss price, only take effect upon opening the position
tp_trigger_by false string Take profit trigger price type, default: LastPrice
sl_trigger_by false string Stop loss trigger price type, default: LastPrice

Response Parameters

Parameter Type Comment
user_id number UserID
order_id string Order ID
symbol string Symbol
symbol string Side
symbol string Order type
symbol number Order price
qty number Order quantity in USD
symbol string Time in force
symbol 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 Unique user-set order ID. Maximum length of 36 characters
created_at string Creation time (when the order_status was Created)
updated_at string Update time
take_profit number Take profit price
stop_loss number Stop loss price
tp_trigger_by string Take profit trigger price type, default: LastPrice
sl_trigger_by string Stop loss trigger price type, default: LastPrice

Get Active Order

Request Example

curl "https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.get_active_order(
    symbol="BTCUSDM21"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "data": [
            {
                "user_id": 160861,
                "position_idx": 0,
                "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 Comment
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 Comment
user_id integer UserID
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
symbol string Symbol
symbol string Side
symbol string Order type
price string Order price
qty string Order quantity in USD
symbol string Time in force
symbol string Order status
leaves_qty string Number of unfilled contracts from the order's size
leaves_value string The estimated value corresponding to the number of remaining orders
cum_exec_qty string Cumulative qty of trading
cum_exec_value string Cumulative value of trading
cum_exec_fee string Cumulative trading fees
reject_reason string The reason the order was rejected
order_link_id string Unique user-set order ID. Maximum length of 36 characters
created_at string Creation time (when the order_status was Created)
order_id string Order ID
take_profit number Take profit price
stop_loss number Stop loss price
tp_trigger_by string Take profit trigger price type, default: LastPrice
sl_trigger_by string Stop loss trigger price type, default: LastPrice
cursor string Page turning mark

Cancel Active Order

Request Example

curl https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.cancel_active_order(
    symbol="BTCUSDM21",
    order_id=""
))

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 Comment
symbol true string Symbol
order_id false string Order ID. Required if not passing order_link_id
order_link_id false string Unique user-set order ID. Required if not passing order_id

Response Parameters

Parameter Type Comment
user_id number UserID
order_id string Order ID
symbol string Symbol
symbol string Side
symbol string Order type
symbol number Order price
qty number Order quantity in USD
time_in_force string Time in force
symbol 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 Unique user-set order ID. Maximum length of 36 characters
created_at string Creation time (when the order_status was Created)
updated_at string Update time

Cancel All Active Orders

Request Example

curl https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.cancel_all_active_orders(
    symbol="BTCUSDM21"
))

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

HTTP Request

POST /futures/private/order/cancelAll

Request Parameters

Parameter Required Type Comment
symbol true string Symbol

Response Parameters

Parameter Type Comment
clOrdID string A unique order number of type UUID
user_id number UserID
symbol string Symbol
symbol string Side
symbol string Order type
symbol 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
symbol 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 (when the order_status was Created)
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-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.replace_active_order(
    symbol="BTCUSDM21",
    order_id=""
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": {
        "order_id": "efa44157-c355-4a98-b6d6-1d846a936b93"
    },
    "time_now": "1539778407.210858",
    "rate_limit_status": 99,
    "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 Comment
order_id false string Order ID. Required if not passing order_link_id
order_link_id false string Unique user-set order ID. Required if not passing 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
take_profit false number New take_profit price, also known as stop_px. Do not pass this field if you don't want modify it
stop_loss false number New stop_loss price, also known as stop_px. Do not pass this field if you don't want modify it
tp_trigger_by false string Take profit trigger price type, default: LastPrice
sl_trigger_by false string Stop loss trigger price type, default: LastPrice

Response Parameters

Parameter Type Comment
order_id string Order ID

Query Active Order (real-time)

Request Example

curl "https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.query_active_order(
    symbol="BTCUSDM21",
    order_id=""
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 106958,
        "position_idx":0,
        "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,
            "position_idx":0,
            "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,
            "position_idx":0,
            "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 Comment
symbol true string Symbol
order_id false string Order ID
order_link_id false string Unique user-set order ID. Maximum length of 36 characters

Response Parameters

Parameter Type Comment
user_id number UserID
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
symbol string Symbol
symbol string Side
symbol string Order type
symbol number Order price
qty number Order quantity in USD
symbol string Time in force
symbol 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 Unique user-set order ID. Maximum length of 36 characters
created_at string Creation time (when the order_status was Created)
updated_at string Update time
order_id string Order ID
take_profit number Take profit price
stop_loss number Stop loss price
tp_trigger_by string Take profit trigger price type, default: LastPrice
sl_trigger_by string Stop loss trigger price type, default: LastPrice

Conditional Orders

Place Conditional Order

Request Example

curl https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.place_conditional_order(
    symbol="BTCUSDM21",
    side="Buy",
    order_type="Limit",
    qty=1,
    pric=8100,
    base_price=8300,
    stop_px=8150,
    time_in_force="GoodTillCancel",
    order_link_id="cus_order_id_1"
))```

> t(:codequote_responseExample)

```javascript
{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":{
        "user_id":160880,
        "symbol":"BTCUSDM21",
        "side":"Buy",
        "order_type":"Limit",
        "price":"8100",
        "qty":"1",
        "time_in_force":"GoodTillCancel",
        "remark":"127.0.0.1",
        "leaves_qty":"2",
        "leaves_value":"0",
        "stop_px":"8150",
        "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 price should be 10% higher than the market price and less than 1 million. For the minimum unit of price movement, please refer to the price_filter field in the Query Symbol 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 Comment
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. If you're expecting the price to rise to trigger your conditional order, make sure stop_px > max(market price, base_price) else, stop_px < min(market price, base_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 Unique user-set order ID. Maximum length of 36 characters
take_profit false number Take profit price, only take effect upon opening the position
stop_loss false number Stop loss price, only take effect upon opening the position
tp_trigger_by false string Take profit trigger price type, default: LastPrice
sl_trigger_by false string Stop loss trigger price type, default: LastPrice

Response Parameters

Parameter Type Comment
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. If you're expecting the price to rise to trigger your conditional order, make sure stop_px > max(market price, base_price) else, stop_px < min(market price, base_price)
stop_order_id string Conditional order ID. Once triggered, the conditional order creates an active order with the same ID (order_id)
created_at string Creation time (when the order_status was Created)
order_link_id string Unique user-set order ID. Maximum length of 36 characters
take_profit false number
stop_loss false number
tp_trigger_by string Take profit trigger price type, default: LastPrice
sl_trigger_by string Stop loss trigger price type, default: LastPrice

Get Conditional Order

Request Example

curl "https://api-testnet.bybit.com/futures/private/stop-order/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.FuturesConditional.FuturesConditional_getOrders(symbol="BTCUSDM21",stop_order_status="Untriggered").result())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.get_active_order(
    symbol="BTCUSDM21"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "data": [
            {
                "user_id": 160861,
                "position_idx": 0,
                "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 Comment
symbol true string Symbol
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 Comment
user_id integer UserID
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
order_status string Stop order status
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
stop_order_type string Conditional order type
trigger_by string Trigger price type. Default LastPrice
base_price number Market price at placing order
order_link_id string Unique user-set order ID. Maximum length of 36 characters
created_at string Creation time (when the order_status was Created)
updated_at string Update time
stop_px number Trigger price. If you're expecting the price to rise to trigger your conditional order, make sure stop_px > max(market price, base_price) else, stop_px < min(market price, base_price)
stop_order_id string Conditional order ID. Once triggered, the conditional order creates an active order with the same ID (order_id)
take_profit number Take profit price
stop_loss number Stop loss price
tp_trigger_by string Take profit trigger price type, default: LastPrice
sl_trigger_by string Stop loss trigger price type, default: LastPrice
cursor string Page turning mark

Cancel Conditional Order

Request Example

curl https://api-testnet.bybit.com/futures/private/stop-order/cancel \
-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_cancel(symbol="BTCUSDM21", stop_order_id="").result())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.cancel_conditional_order(
    symbol="BTCUSDM21",
    stop_order_id=""
))

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 Unique user-set order ID. Required if not passing stop_order_id

Response Parameters

Parameter Type Comment
stop_order_id string Conditional order ID. Once triggered, the conditional order creates an active order with the same ID (order_id)

Cancel All Conditional Orders

Request Example

curl https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.cancel_all_conditional_orders(
    symbol="BTCUSDM21"
))

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.

HTTP Request

POST /futures/private/stop-order/cancelAll

Request Parameters

Parameter required type comments
symbol true string Symbol

Response Parameters

Parameter Type Comment
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 (when the order_status was Created)
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-testnet.bybit.com/futures/private/stop-order/replace \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","stop_order_id":"p_r_qty":2,"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())


from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.replace_conditional_order(
    symbol="BTCUSDM21",
    stop_order_id="",
    p_r_qty=2
))

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 Comment
stop_order_id false string Order ID. Required if not passing order_link_id
order_link_id false string Unique user-set 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
take_profit false number New take_profit price, also known as stop_px. Do not pass this field if you don't want modify it
stop_loss false number New stop_loss price, also known as stop_px. Do not pass this field if you don't want modify it
tp_trigger_by false string Take profit trigger price type, default: LastPrice
sl_trigger_by false string Stop loss trigger price type, default: LastPrice

Response Parameters

Parameter Type Comment
stop_order_id string Conditional order ID. Once triggered, the conditional order creates an active order with the same ID (order_id)

Query Conditional Order (real-time)

Request Example

curl "https://api-testnet.bybit.com/futures/private/stop-order?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_query(symbol="BTCUSDM21", stop_order_id="", p_r_trigger_price="16003").result())


from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.query_conditional_order(
    symbol="BTCUSDM21"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 1,
        "position_idx": 0,
        "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,
            "position_idx": 0,
            "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,
            "position_idx": 0,
            "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 10 unfilled orders.

HTTP Request

GET /futures/private/stop-order

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
stop_order_id false string Order ID
order_link_id false string Unique user-set order ID. Maximum length of 36 characters

Response Parameters

Parameter Type Comment
user_id number UserID
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
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 Unique user-set order ID. Maximum length of 36 characters
created_at string Creation time (when the order_status was Created)
updated_at string Update time
order_id string Order ID
base_price string Market price at placing order
stop_px string Trigger price. If you're expecting the price to rise to trigger your conditional order, make sure stop_px > max(market price, base_price) else, stop_px < min(market price, base_price)
trigger_by string Trigger price type. Default LastPrice
take_profit number Take profit price
stop_loss number Stop loss price
tp_trigger_by string Take profit trigger price type, default: LastPrice
sl_trigger_by string Stop loss trigger price type, default: LastPrice

Position

My Position

Request Example

curl "https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.my_position(
    symbol="BTCUSDM21"
))

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"
                "tp_sl_mode": "Full"
            },
            "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"
                "tp_sl_mode": "Full"
            },
            "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 Comment
symbol false string Symbol

Response Parameters

Parameter Type Comment
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 or not auto-margin replenishment is enabled
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 (the distance from the current price)
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
tp_sl_mode string Stop loss and take profit mode

Change Margin

Request Example

curl https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.change_margin(
    symbol="BTCUSDM21",
    margin=10
))

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 Comment
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 Comment
result number User margin

Set Trading-Stop

Request Example

curl https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.set_trading_stop(
    symbol="BTCUSDM21",
    stop_loss=7000
))

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 Comment
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 (Not effective under partial mode)
stop_loss false number Cannot be less than 0, 0 means cancel SL (Not effective under partial mode)
trailing_stop false number Cannot be less than 0, 0 means cancel TS (Not effective under partial mode)
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.
sl_size false number Stop loss quantity (when in partial mode)
tp_size false number Take profit quantity (when in partial mode)

Response Parameters

Parameter Type Comment
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 or not auto-margin replenishment is enabled
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 (the distance from the current price)
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 (when the order_status was Created)
updated_at string Update time
trailing_active string Trailing stop active price
symbol string Stop loss trigger price type

Set Leverage

Request Example

curl https://api-testnet.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", buy_leverage="14",sell_leverage="14").result())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.set_leverage(
    symbol="BTCUSDM21",
    buy_leverage=14,
    sell_leverage=14
))

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

HTTP Request

POST /futures/private/position/leverage/save

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
buy_leverage true number Must be greater than 0 and less than the risk limit leverage.
sell_leverage true number Must be greater than 0 and less than the risk limit leverage.

Response Parameters

Parameter Type Comment
result number User leverage

Position Mode Switch

Request Example

curl https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.position_mode_switch(
    symbol="BTCUSDM21",
    mode=0
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": null,
    "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.

Supports switching between One-Way Mode and Hedge Mode at the coin level.

HTTP Request

POST /futures/private/position/switch-mode

Request Parameters

Parameter Required Type Comment
symbol false string Symbol. Required if not passing coin
coin false string currency alias. Required if not passing symbol
mode true int Position Mode. 0: One-Way Mode; 3: Hedge Mode

Full/Partial Position TP/SL Switch

Request Example

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

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.full_partial_position_tp_sl_switch(
    symbol="BTCUSDM21",
    tp_sl_mode="Partial"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "tp_sl_mode": "Partial"
    },
    "time_now": "1598266294.610276",
    "rate_limit_status": 72,
    "rate_limit_reset_ms": 1598266294607,
    "rate_limit": 75
}

Switch mode between Full or Partial

HTTP Request

POST /futures/private/tpsl/switch-mode

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
tp_sl_mode true string Stop loss and take profit mode

Response Parameters

Parameter Type Comment
tp_sl_mode string Stop loss and take profit mode

Cross/Isolated Margin Switch

Request Example

curl https://api-testnet.bybit.com/futures/private/position/switch-isolated \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21", "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",is_isolated=True, buy_leverage="1", sell_leverage="1").result())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.cross_isolated_margin_switch(
    symbol="BTCUSDM21",
    is_isolated=True,
    buy_leverage=1,
    sell_leverage=1
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "ok",
    "ext_code": "",
    "result": null,
    "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 Comment
symbol true string Symbol
is_isolated true bool Cross/Isolated: true is Isolated; false is Cross
buy_leverage true number Must be greater than 0 and less than the risk limit leverage.
sell_leverage true number Must be greater than 0 and less than the risk limit leverage.

User Trade Records

Request Example

curl "https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.user_trade_records(
    symbol="BTCUSDM21"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "order_id": "Abandoned!!",
        "trade_list": [
            {
                "closed_size": 0,
                "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",
                "exec_type": "Trade",
                "exec_value": "0.00012227",
                "fee_rate": "0.00075",
                "last_liquidity_ind": "RemovedLiquidity",
                "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",
                "side": "Buy",
                "symbol": "BTCUSDM21",
                "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 Comment
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. Maximum of 50 pages
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. Defaults to asc

Response Parameters

Parameter Type Comment
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
exec_value string Transaction value
fee_rate string Maker or taker fee rate
symbol string Exec type
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 Unique user-set order ID. Maximum length of 36 characters
order_price string Order price
order_qty string Order qty
order_type string Exec type
side string Side
symbol string Symbol
user_id number User ID
trade_time_ms number Transaction timestamp

Closed Profit and Loss

Request Example

curl "https://api-testnet.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())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.closed_profit_and_loss(
    symbol="BTCUSDM21"
))

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 Comment
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 (cannot be Funding)
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 Comment
id number PositionID
user_id number UserID
symbol string Symbol
order_id string Order ID of the closing order
side string Side of the closing order
qty number Order quantity in USD
order_price number Order price
order_type string Active order type
exec_type string Exec type
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 The number of fills in a single order
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 (when the order_status was Created)

Risk Limit

Get Risk Limit

Please see the shared endpoint.

Set Risk Limit

Request Example

curl https://api-testnet.bybit.com/futures/private/position/risk-limit \
-H "Content-Type: application/json" \
-d '{"api_key":"{api_key}","symbol":"BTCUSDM21","risk_id":72,"timestamp":{timestamp},"sign":"{sign}"}'

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com",
               api_key="", api_secret="")
print(session.set_risk_limit(
    symbol="BTCUSDM21",
    risk_id=72
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "risk_id": 72
    },
    "time_now": "1620283810.393787",
    "token": null
}

HTTP Request

POST /futures/private/position/risk-limit

Request Parameters

Parameter Required Type Comment
symbol true string Symbol
risk_id true integer Risk ID
position_idx false 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

Response Parameters

Parameter Type Comment
risk_id number Risk ID

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_getTime().result())

from pybit import HTTP
session = HTTP("https://api-testnet.bybit.com")
print(session.server_time())

Response Example

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

Get Bybit server time.

HTTP Request

GET /v2/public/time

Request Parameters

Parameter Required Type Comment

Announcement

Request Example

curl https://api-testnet.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 Comment

API Rate Limits

IP Rate Limit

The IP limits are shared across all endpoints: futures and account asset but SPOT is separate from them. Mainnet and testnet IP limits are separate.

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

Understanding Your Request Rate Limit

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

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

Rate Limits For All Private Endpoints

Limit Path Consume
100/min
/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
/futures/private/stop-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-margin1 / request
/futures/private/position/trading-stop1 / request
/futures/private/position/switch-mode1 / request
/futures/private/position/switch-isolated1 / request
/futures/private/tpsl/switch-mode1 / request
120/min
/futures/private/position/list1 / request

Order Limits

Max. number of unfilled orders supported under each trading pair:

If you have reached the 500 active order limit, creating a new order will be successful, but the oldest existing order will be cancelled. However, if you have reached the 10 conditional order limit, creating a new order will result in an error, maintaining the existing 10 orders.

How to Increase API Limits

Understanding Bybit's Liquidity System

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

The LCP and OFR of different assets are calculated separately.

Order Fill Ratio (OFR) Threshold

If you place more than 2000 orders per day on Bybit, please make sure that your 7-day OFR is above a Minimum OFR threshold. Otherwise, Bybit may reduce the rate limits for your API request.

Minimum OFR Threshold

7-day OFR must be kept above 0.1%.

Order Fill Ratio (OFR)

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


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

Rate Limits for API Requests

The rate limits for your API requests are based on your min. Liquidity Contribution Points (LCP) within 7 days.

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

Explanation
Effective Price Range

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

Bybit calculates the size of your orders that fall within the effective price range / the total size of your orders in the order book per second, and then computes the time-weighted-average of the day.

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

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

POA example

The size of user C's orders that fall within the effective price range is 8,000, while the total size of orders in the order book that fall within the effective price range is 200,000.

Size of user C's orders within effective price range = 8000
Total size of 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. 

# based on: https://github.com/bybit-exchange/pybit/blob/master/pybit/_http_manager.py

import hmac
import json
import time
import websocket

ws_url = "wss://stream.bybit.com/realtime"

api_key = ""
api_secret = ""

# Generate expires.
expires = int((time.time() + 1) * 1000)

# Generate signature.
signature = str(hmac.new(
    bytes(api_secret, "utf-8"),
    bytes(f"GET/realtime{expires}", "utf-8"), digestmod="sha256"
).hexdigest())

param = "api_key={api_key}&expires={expires}&signature={signature}".format(
    api_key=api_key,
    expires=expires,
    signature=signature
)

url = ws_url + "?" + param

ws = websocket.WebSocketApp(
    url=url,
    ...
)

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

ws = websocket.WebSocketApp(
    url=url,
    ...
)

# Authenticate with API.
ws.send(
    json.dumps({
        "op": "auth",
        "args": [api_key, expires, signature]
    })
)

Base endpoints:

Authentication examples are shown in code block.

How to Send Heartbeat Packet

How to Send

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

Response Example

{
    "success": true,
    "ret_msg": "pong",
    "conn_id": "036e5d21-804c-4447-a92d-b65a44d00700"
    "request": {
        "op": "ping",
        "args": null
    }
}

How to Subscribe to Topics

Understanding Websocket Filters

How to subscribe with a filter

// Subscribing to the trade data for 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.

Unsubscribing From Websocket Topics

How to unsubscribe with a filter

// Unsubscribing from the trade data for BTCUSDM21
ws.send('{"op":"unsubscribe","args":["trade.BTCUSDM21"]}')

You can dynamically subscribe and unsubscribe from topics (with or without filters) without websocket disconnection as follows:

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

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

Subscription Response

{
   "success": true,
   "ret_msg": "",
   "conn_id":"e0e10eee-4eff-4d21-881e-a0c55c25e2da"
   "request": {
       "op": "subscribe",
       "args": [
           "kline.BTCUSDH21.1m"
       ]
   }
}

Each subscription will have a response. You can determine whether the subscription is successful based on the 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)

from pybit import WebSocket
subs = [
    "orderBookL2_25.BTCUSDH21"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs
)
while True:
    data = ws.fetch(subs[0])
    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.

Push frequency: 20ms

Response Parameters

Parameter Type Comment
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"]}');

from pybit import WebSocket
subs = [
    "orderBook_200.100ms.BTCUSDH21"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs
)
while True:
    data = ws.fetch(subs[0])
    if data:
        print(data)

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.

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.

Push frequency: 100ms

Response Parameters

Parameter Type Comment
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)

from pybit import WebSocket
subs = [
    """{
        "topic": "trade",
        "event": "sub",
        "symbol": "BTCUSDT",
        "params": {
            "binary": false
        }
    }"""
]
ws = WebSocket(
    "wss://stream.bybit.com/spot/quote/ws/v1",
    subscriptions=subs
)
while True:
    data = ws.fetch(subs[0])
    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,
            "symbol": "BTCUSDH21",
            "side": "Sell",
            "size": 328,
            "price": 8098,
            "tick_direction": "MinusTick",
            "trade_id": "00c706e1-ba52-5bb0-98d0-bf694bdc69f7",
            "cross_seq": 1052816407
        }
    ]
}

Push frequency: 100ms

Response Parameters

Parameter Type Comment
timestamp string UTC time
trade_time_ms number Millisecond timestamp
symbol string Symbol
side string Direction of taker
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)

from pybit import WebSocket
subs = [
    "insurance"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs
)
while True:
    data = ws.fetch(subs[0])
    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.

Push frequency: 20:00 UTC / day

Response Parameters

Parameter Type Comment
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)

from pybit import WebSocket
subs = [
    "instrument_info.100ms.BTCUSDH21"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs
)
while True:
    data = ws.fetch(subs[0])
    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",
        "coin":"BTC",
        "quote_symbol":"BTCUSD",
        "mode":"MergedSingle",
        "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":"500340000",
        "last_price_e4":500340000,
        "last_tick_direction":"MinusTick",
        "bid1_price":"400025000",
        "bid1_price_e4":400025000,
        "ask1_price":"475450000",
        "ask1_price_e4":475450000,
        "prev_price_24h":"467820000",
        "prev_price_24h_e4":467820000,
        "price_24h_pcnt_e6":90205,
        "high_price_24h":"573420000",
        "high_price_24h_e4":573420000,
        "low_price_24h":"510020000",
        "low_price_24h_e4":510020000,
        "prev_price_1h":"543920000",
        "prev_price_1h_e4":543920000,
        "price_1h_pcnt_e6":-62325,
        "mark_price":"507019537",
        "mark_price_e4":507019537,
        "index_price":"579821900",
        "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":"0",
        "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,
                "prev_price_24h": 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.

Push frequency: 100ms

Response Parameters

Parameter Type Comment
symbol string Symbol
last_price_e4 integer (Deprecated) Latest transaction price 10^4
tick_direction string Direction of price change
prev_price_24h_e4 integer (Deprecated) 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 (Deprecated) The highest price in the last 24 hours * 10^4
low_price_24h_e4 integer (Deprecated) Lowest price in the last 24 hours * 10^4
prev_price_1h_e4 integer (Deprecated) 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 (Deprecated) Mark price * 10^4
index_price_e4 integer (Deprecated) Index_price * 10^4
last_price integer Latest transaction price
prev_price_24h integer Price of 24 hours ago
high_price_24h integer The highest price in the last 24 hours
low_price_24h integer Lowest price in the last 24 hours
prev_price_1h integer Hourly market price an hour ago
mark_price integer Mark price
index_price integer Index_price
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 (when the order_status was Created)
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"]}')

from pybit import WebSocket
subs = [
    "klineV2.1.BTCUSDH21"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs
)
while True:
    data = ws.fetch(subs[0])
    if data:
        print(data)

Response Example - format of all responses

{
    "topic": "klineV2.1.BTCUSDH21",
    "data": [{
        "start": 1572425640,
        "end": 1572425700,
        "open": 9200,
        "close": 9202.5,
        "high": 9202.5,
        "low": 9196,
        "volume": 81790,
        "turnover": 8.889247899999999,
        "confirm": False,
        "cross_seq": 297503466,                 
        "timestamp": 1572425676958323
    }],
    "timestamp_e6": 1572425677047994
}

Currently supported intervals:

Push frequency: 1-60s

Response Parameters

Parameter Type Comment
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 Turnover
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)

from pybit import WebSocket
subs = [
    "position"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs,
    api_key="", api_secret=""
)
while True:
    data = ws.fetch(subs[0])
    if data:
        print(data)

Response Example - format of all responses

{
   "topic": "position",
   "action": "update",
   "data": [
       {
           "user_id":  1,
           "symbol": "BTCUSDH21",
           "position_idx":1,
           "size": 11,
           "side": "Sell",
           "mode": 0,
           "isolated":true,
           "position_value": "0.00159252",
           "entry_price": "6907.291588174717",
           "liq_price": "7100.234",
           "bust_price": "7088.1234",
           "leverage": "1",
           "order_margin":  "1",
           "position_margin":  "1",
           "available_balance":  "2",
           "take_profit": "0",
           "tp_trigger_by":  "LastPrice",
           "stop_loss": "0",
           "sl_trigger_by":  "",
           "realised_pnl":  "0.10",
           "trailing_stop": "0",
           "trailing_active": "0",
           "wallet_balance":  "4.12",
           "risk_id":  1,                       
           "occ_closing_fee":  "0.1",
           "occ_funding_fee":  "0.1",
           "auto_add_margin": 0,
           "cum_realised_pnl":  "0.12",
           "position_status": "Normal",

           "position_seq": 14
       }
   ]
}

Get my position list.

Response Parameters

Parameter Type Comment
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 (the distance from the current price)
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 or not auto-margin replenishment is enabled
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)

from pybit import WebSocket
subs = [
    "execution"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs,
    api_key="", api_secret=""
)
while True:
    data = ws.fetch(subs[0])
    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"
        }
    ]
}

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

Response Parameters

Parameter Type Comment
symbol string Symbol
side string Side
order_id string Order ID
exec_id string Transaction ID
order_link_id string Unique user-set order ID. Maximum length of 36 characters
price string Transaction price
order_qty number Order qty
exec_type string Execution type (cannot be Funding)
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)

from pybit import WebSocket
subs = [
    "order"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs,
    api_key="", api_secret=""
)
while True:
    data = ws.fetch(subs[0])
    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 Comment
order_id string Order ID
order_link_id string Unique user-set order ID. Maximum length of 36 characters
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 Timestamp (when the order_status was New)
take_profit string Take profit price
stop_loss string Stop loss price
trailing_stop string Trailing stop (the distance from the current price)
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"]}')

from pybit import WebSocket
subs = [
    "stop_order"
]
ws = WebSocket(
    "wss://stream-testnet.bybit.com/realtime",
    subscriptions=subs,
    api_key="", api_secret=""
)
while True:
    data = ws.fetch(subs[0])
    if data:
        print(data)

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_type": "Stop",
            "trigger_by": "LastPrice",
            "trigger_price": "8584.5",
            "close_on_trigger": false,
            "timestamp": "2020-01-14T14:11:22.062Z"
        }
    ]
}

Response Parameters

Parameter Type Comment
order_id string Order ID
order_link_id string Unique user-set order ID. Maximum length of 36 characters
user_id number UserID
symbol string Symbol
order_type string Order type
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_by 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.

Historical funding rates are not available through the API. However, you can obtain a CSV of this data by using the "Export" button here.

Enums Definitions

The following lists enumerator names for the request and response parameters of each endpoint.

Side (side)

Symbol (symbol)

You can get all symbols with the Query Symbol endpoint.

Currency (currency/coin)

Contract Type(contract_type)

Contract Status(status)

Wallet fund type (wallet_fund_type / type)

Withdraw status (status)

Order type (order_type)

Quantity (qty)

Price (price)

Time in force (time_in_force)

Trigger price type (trigger_by)

Order (order)

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

Order status (order_status/stop_order_status)

Only for conditional orders:

Cancel type (cancel_type)

Create type (create_type)

Exec type (exec_type)

Liquidity type (last_liquidity_ind)

Tick direction type (tick_direction)

It indicates price fluctuation relative to the last trade.

TP/SL mode (tp_sl_mode)

Take profit/stop loss mode

Kline interval (interval)

Stop order type (stop_order_type)

Errors

The Bybit API uses the following HTTP codes and error codes:

HTTP Code Meaning
200 Request is valid -- Your request is valid
403 Access denied -- You request too many times
404 Request path not found

10000

An unknown error occurred while processing the request.

10001

Params Error

10002

Request not authorized - an API key is required and should be included in all requests.

10003

Too many requests - please use WebSocket for live updates. Current limit is %s requests per minute.

10004

Invalid sign

10005

Permission denied for current apikey. API key was created without the correct permissions (e.g. doesn´t have Order permission, or it's set to read-only)

10006

System not responding. Request status unknown. Too many visits. Please contact live support.

10007

Response timeout from backend server. Delivery and request status unknown.

10010

Request IP mismatch.

10016

Service not available.

10017

Request path not found or request method is invalid

10018

Exceeded IP rate limit.

10020

Request not supported.

10021

Timestamp for the request is outside of the recvWindow. The timestamp of this request is 1000 milliseconds ahead of the server time. Please check local time and server time.

10022

Invalid request signature.

11000

Parameter characters not supported.

11001

Too many parameters sent for this endpoint.

11002

Required parameter not sent. Parameter was empty/null or format was incorrect.

11003

Unknown parameter sent.

11004

Not all parameters sent were read.

11005

Empty parameter.

11006

Parameter was sent when no longer required.

11011

Order price exceeded upper limit.

11012

Trading pair does not exist.

11014

TimeInForce parameter sent when not required.

11015

Invalid timeInForce.

11016

Invalid orderType.

11017

Invalid direction.

11018

User-generated order ID was empty.

11019

User-generated order ID was empty.

11020

Invalid interval.

11021

Invalid symbol.

11025

listenKey does not exist.

11027

Query intervals too large.

11028

Invalid parameter combination.

11030

Invalid parameter sent.

11030

Invalid parameter sent.

11031

Insufficient balance.

11032

Order price exceeded upper limit.

11033

Order price exceeded lower limit.

11034

Order price has too many decimals.

11035

Order quantity exceeded upper limit.

11036

Order quantity exceeded lower limit.

11037

Order quantity has too many decimals.

11038

Order price exceeded limits.

11039

Order has been filled.

11040

Order value exceeded lower limit.

20001

Order does not exist.

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

New order rejected.

20011

Cancelation rejected.

20012

qty must be greater than zero and less than 1 million

20013

Order does not exist.

20014

Invalid API key format.

20015

Invalid API key or IP.

20016

Trading window not open yet for current pair.

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 not unique.

30003

qty must be higher than the minimum allowed.

30004

qty must be higher than the minimum allowed. The number of contracts exceeds maximum limit allowed. Order qty should be less than 1 million per order.

30005

Order price is out of permissible range.

30006

No last_price.

30007

Order price is out of permissible range.

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 be greater than size.

30015

Invalid closing order, side should be the opposite.

30016

TP and SL must be cancelled before closing the 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 is 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 stop order found.

30035

Too fast to cancel, try it later.

30036

The expected position value after order execution exceeds the current risk limit

30037

Order already cancelled

30038

No mark_price.

30039

Applied leverage has exceeded the permitted range.

30040

Any adjustments made will trigger immediate liquidation.

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

30045

Operation not allowed as position is not in normal status.

30046

There are multiple untriggered stop orders.

30047

Inconsistent p:o.

30048

Applied leverage has exceeded the permitted range.

30049

Insufficient available balance.

30050

Any adjustments made will trigger immediate liquidation!

30051

Due to risk limit, cannot adjust leverage.

30052

Leverage cannot be less than 1x.

30053

max_affordable_position_margin <= 0, position:%s

30054

fixed_new_position_margin is invalid.

30055

Available Balance is not enough to add margin.

30056

The position is in cross_margin.

30057

Requested quantity of contracts exceeds risk limit, please adjust your risk limit level before trying again.

30063

Reduce-only rule not satisfied

30066

Set auto add margin fail.

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

30076

Replace params invalid. Order not modified.

30077

Submission of order will result in the breach of user's limit according to open interest.

30078

Contracts not in trading status

30079

The position is about to trigger a liquidation

30080

Price cannot be lower than current Buy liq_price

30081

Price cannot be greater than current sell liq_price

30082

Position exists No switching of position mode allowed

30083

No change in position pattern

30084

No changes to the full position-by-position model

30085

Margin unchanged

30086

translation missing: en.err_3086

30087

Symbol does not support two-way open positions

30088

Symbol does not exist

30089

Duplicate order number

30090

Risk limit info does not exist

30091

Illegal orders (meaning that the order os|cs is not legal in various scenarios)

30092

No position is not allowed to set margin

30093

No net position

30094

Withdrawal of an order before a liquidation is not concluded

30095

Full positions are not allowed to modify leverage

31003

User account banned

32006

The available balance is not sufficient to cover the handling fee.

32008

Insufficient available margin.

32009

Any adjustments made will trigger immediate liquidation.

32010

Risk limit cannot be adjusted due to insufficient available margin.

32011

Risk limit cannot be adjusted as the current/expected position value held exceeds the revised risk limit.

33004

apikey already expired

34010

Wallet Balance is less than zero.

34015

Cannot set new leverage as it is equal to the previous leverage.

34017

Current leverage is less than 1X

34018

Cannot set leverage lower than 1X

34019

Cannot set leverage greater than maxLeverage.

34020

Cannot set leverage which is same to the previous leverage.

34021

Cannot cancel occ_calc_data, the data is wrong.

34022

Cannot set leverage which will cause available balance less than 0.

34023

The request was canceled because the origin request has been handled.

34024

The request does not include add margin data.

34025

Increase in leverage has failed.

34026

The new limit is equal to the old limit (no change).

34027

Cannot adjust leverage.

32009

Any adjustments made will trigger immediate liquidation.

34028

ReCalc Funding Fee Failed.

34030

positionInfo not sync with current exec_rpt.

34033

Realized PNL already rotated.

34032

PositionSeq not match on Withdraw.

34035

Add margin not modified.

34036

Set leverage not modified.

34037

Set custom fee rate not modified.

34038

Update deleverage indicator not modified.

34039

Update position status not modified.

34040

Set TP/SL/TS not modified.

35014

Over order limit.

37001

Both side positions tp_sl_mode is equal.

37002

Same tp_sl_mode.

37003

This position has at least one stop-link order and cannot switch between stop-loss and take-profit modes.

37004

This position has at least one stop-loss link order and cannot switch between stop-loss and take-profit modes

37005

This position has at least one trailing stop or trailing stop link order and cannot be switched to take profit and stop loss mode

37006

Conditional or limit orders carry a take profit and stop loss parameter

37007

Insufficient number of positions left to set Stop Loss and Take Profit

37008

Active orders are not allowed to modify the price and quantity when they also modify the trigger price

37009

Activity orders are not allowed to modify the stop-loss and take-profit settings if the order is partially filled

37010

In Full Take Profit Stop Loss mode, it is not allowed to modify the Stop Profit Stop Loss size

37011

In partial SL mode, SL is set to more than 20. Set SL/TP exceeds the limit oldTpNum+oldStNum+newNum=(2 the num is tp+sl)

37012

Stop loss price needs to be greater than base price.

37013

Stop loss price needs to be less than base price.

38101

Replacement of order will result in the breach of user's limit according to open interest.

console python old_python