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.

API Resources and Support Channels

• Help Center - Learn more about exchange mechanisms here!
• pybit - Official Python SDK
• bybit-api - Community NodeJS SDK
• QuickStartWithPostman - Postman API Collection
• API Discussion Group - get English help here!
• API Discussion Group (Chinese) - get Chinese help here!
• Bybit API Announcement - subscribe for changes to the API!
• Bybit Open API Survey - The survey should take no more than 5 minutes to complete.

Changelog

2022-10-12

REST API

• Latest Information for Symbol [update]
  • Deprecated the following fields. Now returns a default value:
    countdown_hour: 0
    predicted_funding_rate: ""
    total_turnover: ""
    total_volume: 0
    price_1h_pcnt: ""
    open_value: ""
• Get Risk Limit [update]
  • Deprecated created_at and updated_at. Now returns an empty string.

2022-09-19

REST API

• API Key Info [new]
  • Add new response field affiliate_id

2022-08-25

WebSocket API

• stop_order [update]
  • Add take_profit and stop_order fields

2022-04-29

REST API

• Place Active Order & Query Symbol [update]
  • Increase maximum trading qty for PostOnly orders. Please refer to post_only_max_trading_qty in Query Symbol endpoint

2022-03-01

REST API

• Query Symbol [update]
  • Add response parameters funding_interval.

2022-02-28

REST API

• Query Trading Fee Rate [new]
• API Key Info [update]
  • Add response parameters vip_level and mkt_maker_level in API Key Info 。

2021

2021-12-28

REST API

• Public Trading Records [update]
  • Remove from field from parameters of Public Trading Records.

2021-09-24

REST API

• Liquidated Orders [abandoned]
  • This endpoint is now offline. Please replace with the liquidation websocket.

2021-09-14

WebSocket API

• liquidation [new]
  • This shift to a websocket helps ensure a fair trading environment by preventing some traders from getting early access to market information. Please ensure you switch to the websocket service before 2021-09-24. Thank you for your continued support!

REST API

• Liquidated Orders [abandoned]
  • Will be fully offline on 2021-09-24. Please replace with the liquidation websocket.

2021-09-03

WebSocket API

• instrumentInfo [update]
  • Deprecate prev_price_24h_e4 in favour of prev_price_24h
  • Deprecate high_price_24h_e4 in favour of high_price_24h
  • Deprecate low_price_24h_e4 in favour of low_price_24h
  • Deprecate prev_price_1h_e4 in favour of prev_price_1h
  • Deprecate mark_price_e4 in favour of mark_price
  • Deprecate index_price_e4 in favour of index_price
  • Deprecate last_price_e4 in favour of last_price

2021-08-23

REST API

• Wallet Fund Records [update]
  • Add additional enums for wallet_fund_type: ReturnServiceCash, Insurance, SubMember Coupon, AccountTransfer, CashBack

2021-07-29

REST API

• Set Leverage [update]
  • Add parameter leverage_only
    Use this parameter to set leverage while in cross margin mode.
    If this field is set to false, when leverage is equal to 0 the position will use cross margin; when leverage is greater than 0 the position will use isolated margin.
    If this field is set to true, you can set leverage in cross margin with leverage. leverage must be greater than 0.
    Use the Cross/Isolated Margin Switch endpoint to switch cross/isolated without modifying the cross level of leverage.
• Cross/Isolated Margin Switch [update]
  • Update buy_leverage and sell_leverage parameters to be always required

2021-06-28

REST API

• Query Symbol [update]
  • Fix values of min_price and tick_size for symbols BCHUSDT and UNIUSDT

2021-06-18

REST API

• Cross/Isolated Margin Switch [update]
  • is_isolated illustrates if position is Isolated Margin or Cross Margin
  • Deprecate to use auto_add_margin to determine if position is Isolated Margin or Cross Margin
  • Not recommend to use Set Leverage endpoint switch Isolated Margin or Cross Margin

2021-06-03

REST API

• Full/Partial Position TP/SL Switch [new]
• Place Conditional Order [update]
  • Support setting take profit and stop loss; Add new request parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
  • Add response parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
• Place Active Order [update]
  • Add new request parameters tp_trigger_by, sl_trigger_by
  • Add response parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
• My Position [update]
  • Add response parameters: tp_sl_mode
• Set Trading-Stop [update]
  • Support creating partial take profit and stop loss orders; Add new request parameters: sl_size, tp_size
• Cancel Conditional Order [update]
  • Support cancelling take profit and stop loss orders
• Replace Conditional Order [update]
  • Support replacing take profit stop loss orders; Add new request parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
• Replace Active Order [update]
  • Support replacing take profit stop loss orders; Add new request parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
• Get Active Order [update]
  • Add response parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
    
• Query Active Order (real-time) [update]
  • Add response parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
    
• Get Conditional Order [update]
  • Add response parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by
    
• Query Conditional Order (real-time) [update]
  • Add response parameters: take_profit, stop_loss, tp_trigger_by, sl_trigger_by

2021-05-11

REST API

• Set Risk Limit [new]
• Get Risk Limit [new]

2021-05-11

REST API

• Set Leverage [update]
  • Add fields buy_leverage,sell_leverage.
  • leverage - Not Recommand
• Position Mode Switch [new]
• Cross/Isolated Margin Switch [new]

2021-04-22

REST API

• LCP Info [update]
  • Deprecated Fields of self_ratio and platform_ratio, it is returned as 0 currently

2021-04-07

REST API

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

2021-04-02

REST API

• Add comment of errcode 10016,10018,30074,30075

2021-03-24

• Get Risk Limit [update]
  • Query risk limit return field added maximum leverage max_leverage

2021-03-22

• Wallet Fund Records [update]
  • Fix the bug that the filtering function doesn't work for parameter start_date and end_date

2021-03-15

REST API

• Prior to December 31, 2020, order price of a market order was returned as the last traded price as of the moment of order placement. On and after December 31, 2020, order price of a market order is returned as a revised limit price. For more information, please refer to description of market order.

2021-03-12

REST API

• Fix value of exec_type,last_liquidity_ind for User Trade Record endpoint

2021-03-11

• Get Active Order [update]
  • Fix sequence of response data
• Get Conditional Order [update]
  • Fix sequence of response data

2021-03-04

• Wallet Fund Records [update]
  • Fix the bug that the filtering function doesn't work for parameter wallet_fund_type

2021-02-02

WebSocket API

• Topic order [update]

  • Add fields reduce_only,close_on_trigger

• Topic stop_order [update]

  • Add field close_on_trigger

2021-01-25

REST API

• Get the Last Funding Rate [update]
  • /v2/private/funding/prev-funding-rate - Not recommended
  • Replaced by: /v2/public/funding/prev-funding-rate

2021-01-12

REST API

• Query Index Price Kline [new]
• Query Premium Index Kline [new]

2020

2020-12-31

REST API

After a service upgrade, a number of v2 endpoints have been added to replace the old routes:

• Set Leverage [new]
  • /user/leverage/save - Not recommended
  • Replaced by: /v2/private/position/leverage/save
• Wallet Fund Records [new]
  • /open-api/wallet/fund/records - Not recommended
  • Replaced by: /v2/private/wallet/fund/records
• Withdraw Records [new]
  • /open-api/wallet/withdraw/list - Not recommended
  • Replaced by: /v2/private/wallet/withdraw/list
• Change Margin [new]
  • /position/change-position-margin - Not recommended
  • Replaced by: /v2/private/position/change-position-margin
• API Key Info [new]
  • /open-api/api-key - Not recommended
  • Replaced by: /v2/private/account/api-key
• Set Trading-Stop [new]
  • /open-api/position/trading-stop - Not recommended
  • Replaced by: /v2/private/position/trading-stop
• Get the Last Funding Rate [new]
  • /open-api/funding/prev-funding-rate - Not recommended
  • Replaced by: /v2/private/funding/prev-funding-rate
• My Last Funding Fee [new]
  • /open-api/funding/prev-funding - Not recommended
  • Replaced by: /v2/private/funding/prev-funding
• Predicted Funding Rate and My Funding Fee [new]
  • /open-api/funding/predicted-funding - Not recommended
  • Replaced by: /v2/private/funding/predicted-funding

2020-12-17

REST API

• Query Conditional Order (real-time) [update]
  • Real-time queries can return multiple unfilled orders
• Query Active Order (real-time) [update]
  • Real-time queries can return multiple unfilled orders

2020-11-20

REST API

• Get Conditional Order [update]
  • Add field trigger_by in response

2020-11-12

REST API

• Get Active Order [update]
  • order_status query orders with specific statuses by passing each order_status split with ','.
• Get Conditional Order [update]
  • stop_order_status query orders with specific statuses by passing each stop_order_status split with ','.

2020-11-10

WebSocket API

The abandoned endpoints will be deprecated on November 30, 2020

• Topic orderBook25 [abandoned]
  • please replace with orderBookL2_25 or orderBookL2_200
• Topic kline [abandoned]
  • please replace with klineV2
• Topic instrument [abandoned]
  • please replace with instrumentInfo

REST API

The following REST API will be upgraded. The abandoned endpoints will be deprecated on December 10, 2020. Effective immediately, the rate limit will be reduced by half before being completely removed from service on December 17, 2020.

• Get Active Order [abandoned]
  • please replace with Get Active Order [new]
• Get Conditional Order [abandoned]
  • please replace with Get Conditional Order [new]
• Place Conditional Order [abandoned]
  • please replace with Place Conditional Order [new]
• Cancel Conditional Order [abandoned]
  • please replace with Cancel Conditional Order [new]
• Replace Conditional Order [abandoned]
  • please replace with Replace Conditional Order [new]
• Replace Active Order [abandoned]
  • please replace with Replace Active Order [new]
• User Leverage [abandoned]
  • please replace with My Position
• /open-api/order/create [abandoned]
  • please replace with Place Active Order
• /open-api/order/cancel [abandoned]
  • please replace with Cancel Active Order
• /position/list [abandoned]
  • please replace with My Position

2020-11-02

REST API

• Position [update]
  • Request parameter symbol is optional now; If symbol is not passed, return positions of all symbols

2020-10-26

REST API

• Position [update]
  • Add field is_isolated in response

2020-10-21

REST API

• Get Wallet Balance [update]
  • Fix bug of given_cash and service_cash are always Zero when coin is USDT
• Set Trading-Stop [update]
  • Support setting tp/sl by different trigger price types

2020-10-12

REST API

• Get Conditional Order [bugfix]
  • Fix issue where not returning stop orders of Deactivated status
• Query Active Order (real-time) [bugfix]
  • Fix issue where returning wrong cum_exec_fee for filled orders

2020-09-27

REST API

• Replace Active Order [update]
  • Support replace order by order_link_id
• Replace Conditional Order [update]
  • Support replace order by order_link_id

WebSocket API

• Add new websocket base endpoint [update]

2020-09-15

REST API

• Long-Short Ratio [update]
  • Fix Account Long-short ratio data error
• Place Conditional Order [update]
  
  • Change the return value of the field time_in_force of placing conditional market order from GoodTillCancel to ImmediateOrCancel which is the actual execution strategy

2020-08-19

REST API

• Open Interest [new]
• Latest Big Deal [new]
• Long-Short Ratio [new]

2020-07-07

REST API

• Asset Exchange Records [new]

• Get Wallet Balance [update]
  • Returns all wallet balances if no parameters are passed
• Get User Trade Records [update]
  • Adjust the return quantity from 50 to 200

2020-06-22

REST API

• Closed Profit and Loss [new]
• Query Mark Price Kline [new]

2020-05-21

REST API

• Liquidated Orders [new]

2020-04-29

REST API

• Get User Trade Records [update]
  • Add new request parameter order
• API Key Info [bugfix]
  • Fix bug of always returning Zero for inviter_id under certain conditions

2020-04-27

REST API

• LCP Info [new]
• Latest Information for Symbol [update]
  • Return symbol BTCUSDT by default

2020-04-17

REST API

• Order Book [update]
  • Add new symbol BTCUSDT
• Latest Information for Symbol [update]
  • Add new symbol BTCUSDT
• Get User Trade Records [update]
  • Add new response param trade_time_ms
  • Update support millisecond start_time
  • Abandon response field trade_time

2020-04-14

REST API

• Query Symbol [update]
  • Updated BTCUSDT contract information

2020-03-31

REST API

• Get Wallet Balance [update]
  • Fix incorrect balance of USDT

2020-03-26

REST API

• Set Trading-Stop [update]
  • Add trigger price new_trailing_active for trailing stop order.

2020-03-16

REST API

• Position [update]
  • Add field effective_leverage in response
• Get Wallet Balance [update]
  • Fix value of field equity of USDT

2020-03-09

REST API

• Get User Trade Records [update]
  • Symbol is require
• API Key Info [update]
  • Add inviter_id in response

2020-03-02

WebSocket API

• trade [update]
  • Add new field trade_time_ms

2020-02-26

REST API

• Place Active Order
  • Remove trailing_stop field from parameters of place order endpoint. Currently, this field is useless.

2020-02-10

REST API

• Get Wallet Balance [new]
• Replace Active Order [update]
  • Add order_id in response
• Replace Conditional Order [update]
  • Add stop_order_id in response
  • Add a new request parameter stop_order_id to replace order_id for consistency
• Fix value of rate_limit_reset_ms in V2 private endpoints' response from microseconds to millisecond, be consistent with V1 endpoint [bugfix]

2019

2019-12-27

REST API

• Set Risk Limit [new]
• Get Risk Limit [new]

2019-12-18

REST API

• My Position [new]

WebSocket API

• orderBookL2_200 [new]

2019-12-13

REST API

• Query Conditional Order (real-time) [new]

2019-12-02

REST API

• Place Active Order [new]
• Cancel Active Order [new]
• Cancel All Active Orders [new]
• Cancel All Conditional Orders [new]

2019-11-19

REST API

• Public Trading Records [new]

2019-11-07

REST API

• Set Leverage [update]
• [My position] [update]
• Change Margin [update]
• Set Trading-Stop [update]

2019-11-04

REST API

• Announcement [new]
• Cancel order [update]
  • Support cancel order by order_link_id
• Cancel Conditional Order [update]
  • Support cancel conditional order by order_link_id
• API Key Info [update]
  • Add extra info
  • Update ips field to return content
• Update REST API rate limit [update]
  • The rate limit is accurate to milliseconds
  • Refine the rate limit of the endpoints
  • Add new response fields: rate_limit_reset_ms, rate_limit

WebSocket API

• klineV2 [new]
• stop_order [new]

2019-10-22

REST API

• Query Active Order (real-time) [new]

WebSocket API

• position [update]
  • Add extra info, eg. wallet_balance
• trade [update]
  • Fix issue of sometimes push same trade multi times
  • Support pushing multi trades in single message

FAQ

reduce_only and close_on_trigger - what's the difference?

• To close your position, submit an order and specify reduce_only to true. close_on_trigger is not strictly applicable here, but you can also set it to true if it's required.
• reduce_only is the one that really matters for closing position, and we will improve the interface in the future.
• Be careful when you specify close_on_trigger to true as it could cause conflict when reduce_only is false.

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

• Users who have bots which place large numbers of laddered orders will be restricted by the frontend interface, which only shows a maximum of 50 orders on-screen.
• Don't worry, your orders are still in the system and can be queried by the API, but the frontend cannot show more than 50.

Calculating order size based on available wallet balance

• price * available_balance * leverage * perc * (1 - (0.0006 * 2))
• Unfortunately this is not a perfectly accurate formula; the real calculation is complex and may be published in the docs at a later date.
• price - last price (or your entry price) - can be found with the Latest Symbol Info endpoint.
• available_balance - can be found with the My Position endpoint.
• leverage - up to the respective maximum leverage for the market and your risk limit (eg 2, 10, 50).
• perc - 0.1 for 10%, 0.25 for 25%, etc.
• 1 - (0.0006 * 2) - used to calculate the maximum order cost (always assumes entry & exit orders use taker fee regardless actual fee).

Can I exchange assets with the API?

• There is no endpoint to exchange assets. This can only be done on the website.
• However, it is possible to access your Asset Exchange Records 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?

• The entry_price and exit_price returned by Closed PNL endpoints are not the actual execution prices of the orders.
• It is based on the total costs of the order
  • (whether or not the position was only opened/closed by one order executed at one price - it is more complicated if multiple orders opened/closed a position.)
• For instance, the entry_price and exit_price reported by this endpoint are influenced by the fee paid/received on the orders.

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

• For example, you received 11.969999 but you expected 11.97.
• Some values are returned to too many decimal places, or a fraction too high or low, due to a float precision problem.
• For now, we recommend rounding the received value to the correct decimal place. This can be done with reference to the Query Symbol endpoint.
• This issue will be has been fixed in the latest major version of the API: v3. You can see the documentation for the v3 websocket here.

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

• It is possible, although unlikely, that the REST API or (even less likely) the websocket could return/push old data.
• For the greatest level of data resilience, we recommend clients to:
  • firstly, rely on the websocket, which will not only ensure you get the latest data as fast as possible, but will also ensure you get complete data
  • secondly, query the REST API to fill in any discrepencies in data - or between websocket disconnections.
• The best practice is to save all of this data locally in your own database or cache.
• This frees up your rate limits for other requests and also ensures a level of redundancy against the exchange in case of data delays.

What is the difference between turnover and volume?

• Turnover: is in the opposite currency to the quantity's currency
• Volume: is in the same currency as the quantity's currency

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:

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

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=XXXXXXXXXX&leverage=100&symbol=BTCUSD&timestamp=1542434791747"

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

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

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

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

2. 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 /v2/private/order?symbol=BTCUSD&api_key=XXXXXXXXXX&timestamp=1542434791000&sign=670e3e4aa32b243f2dedf1dafcec2fd17a440e71b05681550416507de591d908 HTTP/1.1
Host: api-testnet.bybit.com

Message format for POST requests:

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

{
    "api_key": "XXXXXXXXXX",
    "symbol": "BTCUSD",
    "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

Request Example

curl https://api-testnet.bybit.com/v2/public/orderBook/L2?symbol=BTCUSD

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session.orderbook(symbol="BTCUSD"))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "symbol": "BTCUSD",
            "price": "9487",
            "size": 336241,
            "side": "Buy"
        },
        {
            "symbol": "BTCUSD",
            "price": "9487.5",
            "size": 522147,
            "side": "Sell"
        }
    ],
    "time_now": "1567108756.834357"
}

Get the orderbook. Each side has a depth of 25.

HTTP Request

GET /v2/public/orderBook/L2

Request Parameters

Response Parameters

Query Kline

Request Example

curl https://api-testnet.bybit.com/v2/public/kline/list?symbol=BTCUSD&interval=1&limit=2&from=1581231260

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.query_kline(
    symbol="BTCUSD",
    interval="D",
    from_time="1653408000"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [{
        "symbol": "BTCUSD",
        "interval": "1",
        "open_time": 1581231300,
        "open": "10112.5",
        "high": "10112.5",
        "low": "10112",
        "close": "10112",
        "volume": "75981",
        "turnover": "7.51394369"
    }, {
        "symbol": "BTCUSD",
        "interval": "1",
        "open_time": 1581231360,
        "open": "10112",
        "high": "10112.5",
        "low": "10112",
        "close": "10112",
        "volume": "24616",
        "turnover": "2.4343353100000003"
    }],
    "time_now": "1581928016.558522"
}

Get kline.

HTTP Request

GET /v2/public/kline/list

Request Parameters

Response Parameters

Latest Information for Symbol

Request Example

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

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.latest_information_for_symbol(
    symbol="BTCUSD"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "result": [
        {
            "symbol": "BTCUSD",
            "bid_price": "19244.5",
            "ask_price": "19245",
            "last_price": "19244.50",
            "last_tick_direction": "MinusTick",
            "prev_price_24h": "18780.50",
            "price_24h_pcnt": "0.024706",
            "high_price_24h": "19582.00",
            "low_price_24h": "18492.50",
            "prev_price_1h": "19217.00",
            "mark_price": "19242.60",
            "index_price": "19229.37",
            "open_interest": 4.13999123e+08,
            "countdown_hour": 0,
            "turnover_24h": "1977.97821021",
            "volume_24h": 3.7810482e+07,
            "funding_rate": "0.0001",
            "predicted_funding_rate": "",
            "next_funding_time": "2022-09-08T16:00:00Z",
            "predicted_delivery_price": "",
            "total_turnover": "",
            "total_volume": 0,
            "delivery_fee_rate": "",
            "delivery_time": "",
            "price_1h_pcnt": "",
            "open_value": ""
        }
    ],
    "ext_code": "",
    "ext_info": "",
    "time_now": "1662629551.232415"
}

Get the latest information for symbol.

HTTP Request

GET /v2/public/tickers

Request Parameters

Response Parameters

Public Trading Records

Request Example

curl https://api-testnet.bybit.com/v2/public/trading-records?symbol=BTCUSD

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.public_trading_records(
    symbol="BTCUSD"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "id": 7724919,
            "symbol": "BTCUSD",
            "price": 9499.5,
            "qty": 9500,
            "side": "Buy",
            "time": "2019-11-19T08:03:04.077Z"
        }
    ],
    "time_now": "1567109419.049271"
}

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

HTTP Request

GET /v2/public/trading-records

Request Parameters

Response Parameters

Query Symbol

Request Example

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

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session.query_symbol())

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":[
        {
            "name":"BTCUSD",
            "alias":"BTCUSD",
            "status":"Trading",
            "base_currency":"BTC",
            "quote_currency":"USD",
            "price_scale":2,
            "taker_fee":"0.00075",
            "maker_fee":"-0.00025",
            "funding_interval":480,
            "leverage_filter":{
                "min_leverage":1,
                "max_leverage":100,
                "leverage_step":"0.01"
            },
            "price_filter":{
                "min_price":"0.5",
                "max_price":"999999.5",
                "tick_size":"0.5"
            },
            "lot_size_filter":{
                "max_trading_qty":1000000,
                "min_trading_qty":1,
                "qty_step":1,
                "post_only_max_trading_qty":"5000000"
            }
        },
        {
            "name":"EOSUSD",
            "alias":"EOSUSD",
            "status":"Trading",
            "base_currency":"EOS",
            "quote_currency":"USD",
            "price_scale":3,
            "taker_fee":"0.00075",
            "maker_fee":"-0.00025",
            "funding_interval":480,
            "leverage_filter":{
                "min_leverage":1,
                "max_leverage":50,
                "leverage_step":"0.01"
            },
            "price_filter":{
                "min_price":"0.001",
                "max_price":"1999.999",
                "tick_size":"0.001"
            },
            "lot_size_filter":{
                "max_trading_qty":1000000,
                "min_trading_qty":1,
                "qty_step":1,
                "post_only_max_trading_qty":"5000000"
            }
        },
        {
            "name":"BTCUSDT",
            "alias":"BTCUSDT",
            "status":"Trading",
            "base_currency":"BTC",
            "quote_currency":"USDT",
            "price_scale":2,
            "taker_fee":"0.00075",
            "maker_fee":"-0.00025",
            "funding_interval":480,
            "leverage_filter":{
                "min_leverage":1,
                "max_leverage":100,
                "leverage_step":"0.01"
            },
            "price_filter":{
                "min_price":"0.5",
                "max_price":"999999.5",
                "tick_size":"0.5"
            },
            "lot_size_filter":{
                "max_trading_qty":100,
                "min_trading_qty":0.001,
                "qty_step":0.001,
                "post_only_max_trading_qty":"500"
            }
        },
        {
            "name":"BTCUSDM22",
            "alias":"BTCUSD0624",
            "status":"Trading",
            "base_currency":"BTC",
            "quote_currency":"USD",
            "price_scale":2,
            "taker_fee":"0.00075",
            "maker_fee":"-0.00025",
            "funding_interval":480,
            "leverage_filter":{
                "min_leverage":1,
                "max_leverage":100,
                "leverage_step":"0.01"
            },
            "price_filter":{
                "min_price":"0.5",
                "max_price":"999999.5",
                "tick_size":"0.5"
            },
            "lot_size_filter":{
                "max_trading_qty":1000000,
                "min_trading_qty":1,
                "qty_step":1,
                "post_only_max_trading_qty":"5000000"
            }
        }
    ],
    "time_now":"1615801223.589808"
}

Get symbol info.

HTTP Request

GET /v2/public/symbols

Request Parameters

Response Parameters

Query Mark Price Kline

Request Example

curl "https://api-testnet.bybit.com/v2/public/mark-price-kline?symbol=BTCUSD&interval=1&limit=2&from=1581231260"

print(session_unauth.query_mark_price_kline(
    symbol="BTCUSD",
    interval="D",
    from_time=1653408000
))

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":[
        {
            "id":2,
            "symbol":"BTCUSD",
            "period":"1",
            "start_at":1582231260,
            "open":100,
            "high":120,
            "low":88,
            "close":115
        }
    ],
    "time_now":"1591263582.601795"
}

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

HTTP Request

GET /v2/public/mark-price-kline

Request Parameters

Response Parameters

Query Index Price Kline

Request Example

curl "https://api-testnet.bybit.com/v2/public/index-price-kline?symbol=BTCUSD&interval=1&limit=2&from=1581231260"

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.query_index_price_kline(
    symbol="BTCUSD",
    interval="D",
    from_time=1653408000
))

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":[
        {
            "symbol":"BTCUSD",
            "period":"1",
            "open_time":1582231260,
            "open":"10106.09",
            "high":"10108.75",
            "low":"10104.66",
            "close":"10108.73"
        }
    ],
    "time_now":"1591263582.601795"
}

Index price kline. Tracks BTC spot prices, with a frequency of every second (learn more here).

HTTP Request

GET /v2/public/index-price-kline

Request Parameters

Response Parameters

Query Premium Index Kline

Request Example

curl "https://api-testnet.bybit.com/v2/public/premium-index-kline?symbol=BTCUSD&interval=1&limit=2&from=1581231260"

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.query_premium_index_kline(
    symbol="BTCUSD",
    interval="D",
    from_time=1653408000
))

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":[
        {
            "symbol":"BTCUSD",
            "period":"1",
            "open_time":1582231260,
            "open":"0.000588",
            "high":"0.000618",
            "low":"0.000588",
            "close":"0.000618"
        }
  ],
    "time_now":"1591263582.601795"
}

Premium index kline. Tracks the premium / discount of BTC perpetual contracts relative to the mark price per minute (learn more here).

HTTP Request

GET /v2/public/premium-index-kline

Request Parameters

Response Parameters

Advanced Data

Open Interest

Request Example

curl https://api-testnet.bybit.com/v2/public/open-interest?symbol=BTCUSD&period=5min

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.open_interest(
    symbol="BTCUSD",
    period="30min"
))

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":[
        {
            "open_interest":371491978,
            "timestamp":1597658100,
            "symbol":"BTCUSD"
        },
        {
            "open_interest":370696076,
            "timestamp":1597657800,
            "symbol":"BTCUSD"
        }
    ],
    "time_now":"1597658304.938839"
}

Gets the total amount of unsettled contracts. In other words, the total number of contracts held in open positions.

HTTP Request

GET /v2/public/open-interest

Request Parameters

Response Parameters

Latest Big Deal

Request Example

curl https://api-testnet.bybit.com/v2/public/big-deal?symbol=BTCUSD

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.latest_big_deal(
    symbol="BTCUSD",
    limit=10
))

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":[
        {
            "symbol":"BTCUSD",
            "side":"Sell",
            "timestamp":1597623362,
            "value":1242368
        },
        {
            "symbol":"BTCUSD",
            "side":"Buy",
            "timestamp":1597623363,
            "value":1242368
        }
    ],
    "time_now":"1597658434.219859"
}

Obtain filled orders worth more than 500,000 USD within the last 24h.

This endpoint may return orders which are over the maximum order qty for the symbol you call. For instance, the maximum order qty for BTCUSD is 1 million contracts, but in the event of the liquidation of a position larger than 1 million this endpoint returns this "impossible" order size.

HTTP Request

GET /v2/public/big-deal

Request Parameters

Response Parameters

Long-Short Ratio

Request Example

curl https://api-testnet.bybit.com/v2/public/account-ratio?symbol=BTCUSD&period=5min

from pybit import inverse_perpetual
session_unauth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com"
)
print(session_unauth.long_short_ratio(
    symbol="BTCUSD",
    limit=2,
    period="5min"
))

Response Example

{
    "ret_code":0,
    "ret_msg":"OK",
    "ext_code":"",
    "ext_info":"",
    "result":[
        {
            "symbol":"BTCUSD",
            "buy_ratio":0.6538,
            "sell_ratio":0.3462,
            "timestamp":1597659000
        },
        {
            "symbol":"BTCUSD",
            "buy_ratio":0.6533,
            "sell_ratio":0.3467,
            "timestamp":1597658700
        }
    ],
    "time_now":"1597659230.743313"
}

Gets the Bybit user accounts' long-short ratio.

HTTP Request

GET /v2/public/account-ratio

Request Parameters

Response Parameters

Account Data Endpoints

The following account data endpoints require authentication.

Active Orders

Place Active Order

Request Example

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

from pybit import inverse_perpetual
session_auth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com",
    api_key="your api key",
    api_secret="your api secret"
)
print(session_auth.place_active_order(
    symbol="BTCUSD",
    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": 533285,
        "order_id": "a1904030-f99c-4e35-9217-111591f08493",
        "symbol": "BTCUSD",
        "side": "Buy",
        "order_type": "Limit",
        "price": 20010,
        "qty": 200,
        "time_in_force": "GoodTillCancel",
        "order_status": "Created",
        "last_exec_time": 0,
        "last_exec_price": 0,
        "leaves_qty": 200,
        "cum_exec_qty": 0,
        "cum_exec_value": 0,
        "cum_exec_fee": 0,
        "reject_reason": "EC_NoError",
        "order_link_id": "",
        "created_at": "2022-06-20T06:56:22.070Z",
        "updated_at": "2022-06-20T06:56:22.070Z",
        "take_profit": "22000.00",
        "stop_loss": "19000.00",
        "tp_trigger_by": "MarkPrice",
        "sl_trigger_by": "MarkPrice"
    },
    "time_now": "1655708182.071362",
    "rate_limit_status": 99,
    "rate_limit_reset_ms": 1655708182068,
    "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. For the minimum unit of qty increase or decrease, please refer to the lot_size_filter field in the Query Symbol endpoint. Note: The allowed max trade quantity of PostOnly is 5 times bigger than normal orders.

Order price: If it is a conditional order, this parameter is required. When there is no position, the price should be higher than 10% of 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 /v2/private/order/create

Request Parameters

Response Parameters

Get Active Order

Request Example

curl "https://api-testnet.bybit.com/v2/private/order/list?api_key={api_key}&timestamp={timestamp}&sign={sign}&symbol=BTCUSD"

from pybit import inverse_perpetual
session_auth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com",
    api_key="your api key",
    api_secret="your api secret"
)
print(session_auth.get_active_order(
    symbol="BTCUSD",
    order_status="New"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "data": [
            {
                "user_id": 533285,
                "position_idx": 0,
                "order_status": "New",
                "symbol": "BTCUSD",
                "side": "Buy",
                "order_type": "Limit",
                "price": "20010",
                "qty": "200",
                "time_in_force": "GoodTillCancel",
                "order_link_id": "",
                "order_id": "a1904030-f99c-4e35-9217-111591f08493",
                "created_at": "2022-06-20T06:56:22.070Z",
                "updated_at": "2022-06-20T06:56:22.075Z",
                "leaves_qty": "200",
                "leaves_value": "0.009995",
                "cum_exec_qty": "0",
                "cum_exec_value": "0",
                "cum_exec_fee": "0",
                "reject_reason": "EC_NoError",
                "take_profit": "22000.0000",
                "stop_loss": "19000.0000",
                "tp_trigger_by": "MarkPrice",
                "sl_trigger_by": "MarkPrice"
            }
        ],
        "cursor": "/oIljKFOerbXfuWAmnc33qCc1649q+xLuuagMYyoYh6pV+BShVJ8ph439Xw8ywSp"
    },
    "time_now": "1655708401.042813",
    "rate_limit_status": 599,
    "rate_limit_reset_ms": 1655708401039,
    "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 /v2/private/order/list

Request Parameters

Response Parameters

Cancel Active Order

Request Example

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

from pybit import inverse_perpetual
session_auth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com",
    api_key="your api key",
    api_secret="your api secret"
)
print(session_auth.cancel_active_order(
    symbol="BTCUSD",
    order_id="3bd1844f-f3c0-4e10-8c25-10fea03763f6"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 533285,
        "order_id": "bab79185-7759-48f3-a5f4-206808b6f1ec",
        "symbol": "BTCUSD",
        "side": "Buy",
        "order_type": "Limit",
        "price": 19500,
        "qty": 100,
        "time_in_force": "GoodTillCancel",
        "order_status": "New",
        "last_exec_time": 1655711524.37661,
        "last_exec_price": 0,
        "leaves_qty": 100,
        "cum_exec_qty": 0,
        "cum_exec_value": 0,
        "cum_exec_fee": 0,
        "reject_reason": "EC_NoError",
        "order_link_id": "IPBTC00001",
        "created_at": "2022-06-20T07:52:04.376Z",
        "updated_at": "2022-06-20T07:54:35.339Z",
        "take_profit": "",
        "stop_loss": "",
        "tp_trigger_by": "",
        "sl_trigger_by": ""
    },
    "time_now": "1655711675.340162",
    "rate_limit_status": 99,
    "rate_limit_reset_ms": 1655711675338,
    "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 /v2/private/order/cancel

Request Parameters

Response Parameters

Cancel All Active Orders

Request Example

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

from pybit import inverse_perpetual
session_auth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com",
    api_key="your api key",
    api_secret="your api secret"
)
print(session_auth.cancel_all_active_orders(
    symbol="BTCUSD"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": [
        {
            "clOrdID": "89f67ac2-8f51-4463-b5c1-75d0d8aca185",
            "order_link_id": "IPBTC00003",
            "user_id": 533285,
            "symbol": "BTCUSD",
            "side": "Buy",
            "order_type": "Limit",
            "price": "17000",
            "qty": 100,
            "time_in_force": "GoodTillCancel",
            "create_type": "CreateByUser",
            "cancel_type": "CancelByUser",
            "order_status": "",
            "leaves_qty": 100,
            "leaves_value": "0",
            "created_at": "2022-06-21T02:05:30.430491295Z",
            "updated_at": "2022-06-21T04:34:46.3745089Z",
            "cross_status": "PendingCancel",
            "cross_seq": 5208583955
        }
    ],
    "time_now": "1655786086.374891",
    "rate_limit_status": 80,
    "rate_limit_reset_ms": 1655786086373,
    "rate_limit": 100
}

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

HTTP Request

POST /v2/private/order/cancelAll

Request Parameters

Response Parameters

Replace Active Order

Request Example

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

from pybit import inverse_perpetual
session_auth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com",
    api_key="your api key",
    api_secret="your api secret"
)
print(session_auth.replace_active_order(
    symbol="BTCUSD",
    order_id="efa44157-c355-4a98-b6d6-1d846a936b93"
))

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.

HTTP Request

POST /v2/private/order/replace

Request Parameters

Response Parameters

Query Active Order (real-time)

Request Example

curl "https://api-testnet.bybit.com/v2/private/order?api_key={api_key}&symbol=BTCUSD&timestamp={timestamp}order_id={order_id}&sign={sign}"

from pybit import inverse_perpetual
session_auth = inverse_perpetual.HTTP(
    endpoint="https://api-testnet.bybit.com",
    api_key="your api key",
    api_secret="your api secret"
)
print(session.query_active_order(
    symbol="BTCUSD",
    order_id="e66b101a-ef3f-4647-83b5-28e0f38dcae0"
))

Response Example

{
    "ret_code": 0,
    "ret_msg": "OK",
    "ext_code": "",
    "ext_info": "",
    "result": {
        "user_id": 533285,
        "position_idx": 0,
        "symbol": "BTCUSD",
        "side": "Buy",
        "order_type": "Limit",
        "price": "20000",
        "qty": 200,
        "time_in_force": "GoodTillCancel",
        "order_status": "New",
        "ext_fields": {
            "o_req_num": 1240101436
        },
        "last_exec_time": "1655716503.5852108",
        "leaves_qty": 200,
        "leaves_value": "0.01",
        "cum_exec_qty": 0,
        "cum_exec_value": null,
        "cum_exec_fee": null,
        "reject_reason": "EC_NoError",
        "cancel_type": "UNKNOWN",
        "order_link_id": "IPBTC000002",
        "created_at": "2022-06-20T09:15:03.585128212Z",
        "updated_at": "2022-06-20T09:15:03.590398174Z",
        "order_id": "2b1d811c-8ff0-4ef0-92ed-b4ed5fd6de34",
        "take_profit": "23000.00",
        "stop_loss": "18000.00",
        "tp_trigger_by": "MarkPrice",
        "sl_trigger_by": "MarkPrice"
    },
    "time_now": "1655718311.123686",
    "rate_limit_status": 597,
    "rate_limit_reset_ms": 1655718311122,
    "rate_limit": 600
}