Introduction
Overview
The V5 API brings uniformity and efficiency to Bybit's product lines, unifying Spot, Derivatives, and Options in one set of specifications.
Current API Coverage
If your account is still a Unified Margin Account, you cannot trade spot through the V5 API. We strongly recommend upgrading to the Unified Trading Account.
| OpenAPI Version | Account Type | Linear | Inverse | Spot | Options | |||
|---|---|---|---|---|---|---|---|---|
| USDT Perpetual | USDC Perpetual | USDC Futures | Perpetual | Futures | ||||
| V5 | Unified trading account | ✓ | ✓ | ✓ | see note | ✓ | ✓ | |
| Classic account | ✓ | ✓ | ✓ | ✓ | ||||
| V3 | Classic account | ✓ | ✓ | ✓ | ✓ | |||
Note: the Unified account supports inverse trading. However, the margin used is from the inverse derivatives wallet instead of the unified wallet.
Key Upgrades
Product Lines Alignment
Previously, Spot V1/V3, Futures V2 and USDC Options V1 each had their own set of APIs which only covered a portion of Bybit's products. V5 unifies the APIs of various trading products into one, providing users the capability to trade Spot, Derivatives and Options contracts with a single API by distinguishing transactions through different order parameters. Consequently, there is no need to switch between multiple interfaces when building different products – regardless of tasks such as order management or querying wallet data – as the same API can be used to request and return results.
The global dictionary in V5 is uniquely defined to avoid scenarios where different terms are used for the same purposes, or where a single term has multiple references. This simplifies the troubleshooting process for users.
For example, when creating an order with POST V5/order/create, users can specify category=spot/linear/option to create
multiple orders across different products.
Ease of Upgrade
API V5 is built upon V3, so minimal changes are required to upgrade. If you are already connected via Contract V3 or Unified V3, simply change the URL to the corresponding one of V5 and adjust some interface fields. Please refer to the interface mapping list below for more details about specific interfaces.
Enhance Capital Efficiency
V5 provides users the ability to upgrade accounts to a unified account, allowing for sharing and cross-utilization of funds across Spot, USDT Perpetual, USDC Perpetual and Options contracts. Users are also able to offset profit and losses across different positions, thus further enhancing capital efficiency.
Unified Account Borrowing
API V5 supports borrowing across a unified account mode. Users can pledge multiple assets as collateral to obtain margin for trading across different products.
For example: Trader Alice opens a USDT-settled BTCUSDT contract position while holding only BTC assets. If a floating loss is incurred, a debt will be recorded and interest will be charged hourly.
Paradigm Block Trading
Unified accounts now support block trading via Paradigm. Users can utilize funds across different products.
Portfolio Margin Mode
Unified Accounts now support combined margin between USDT Perpetual, USDC Perpetual, USDC Futures and Options contracts
API Interface Naming Standard
API V5 offers clearer path definitions for improved clarity and reduced ambiguity. The new version divides the API path into market data, order management, position management, account management, asset management, and more modules.
{host}/{version}/{product}/{module}
Example: api.bybit.com/v5/market/recent-trade
| Address Segment | Description |
|---|---|
| v5/market/ | Candlestick, orderbook, ticker, platform transaction data, underlying financial rules, risk control rules |
| v5/order/ | Order management |
| v5/position/ | Position management |
| v5/account/ | Single account operations only – unified funding account, rates, etc. |
| v5/asset/ | Operations across multiple accounts – asset management, fund management, etc. |
| v5/spot-lever-token/ | Obtain quotes from Leveraged Tokens on Spot, and to exercise purchase and redeem functions |
| v5/spot-margin-trade/ | Manage Margin Trading on Spot |
API Rate Limit Adjustment
The rate limit has been adjusted in V5 to allocate a per-second rate limit quota for each User ID across products, to ensure smooth transactions and improve user experience.
- V2 Rate Limit: “User ID + Symbol + API Endpoint” limits the frequency of API requests by a fixed number of counts per minute
- V3 Rate Limit: “User ID + API Endpoint” limits the frequency of API requests by a fixed number of counts per second
- V5 Rate Limit: “User ID + API Endpoint” limits the frequency of API requests by a fixed number of counts per second
For example:
- In V2 Futures,
- Trader Bob sets the order frequency of BTCUSDT at 400/m, ETHUSDT at 200/m, and other symbols at 100/m
- If he places 200 order requests for BTCUSDT, his remaining limit in that one minute is 200 order requests for BTCUSDT, 200 for ETHUSDT and 100 for other symbols
- If 100 ETHUSDT order requests are sent in at the same time, the remaining credit in that one minute is 200 order requests for BTCUSDT, 100 for ETHUSDT, and 100 for other symbols
- In V3/V5,
- The default limit is 10/s for all users
- Trader Charlie increases his order frequency to 100/s (representing a maximum of 100 requests across all interfaces for a single UID)
- He places 50 order requests for BTCUSDT in one second, which leaves a remaining limit of 50 order requests in that second
- The frequency limit then resets to 100/s during the next second
Query-based APIs CANNOT increase in frequency and are limited to 10 requests per second (WebSocket is recommended for data reception).
No Change in Latency
Implemented since Jan 1, 2023, API V5 currently supports unified account trading with the same latencies as unified margin trading. The upcoming implementation for non-unified account trading will feature the same latency as API V3.
Single Placement Interface
With V2, submission of normal and conditional orders required two different APIs. API V3 and V5 merge orders via different submission parameters on one single placement interface. This eliminates the need for users to request multiple orders using different interfaces.
Addition of Real-Time Order Query
With V5, users can request the last 500 orders in real-time, as compared to API V3 which only supports real-time queries of unfilled orders.
The status of recently filled orders can also be queried in real-time, reducing the delay compared to querying through order or history interfaces.
Cancellation of Orders by Settlement Currency
Users can cancel all Derivatives orders settled by the same currency with settleCoin.
Addition of Historical Funding Rate Query
While API V2 only supports the query of funding rates from the previous cycle, API V3 and V5 support the query of funding rate changes, which allows users to conduct historical funding backtests.
Addition of Insurance Fund Interface
This interface addition allows for queries of the insurance pool, which users can use to check for any insurance fund updates on the Bybit platform.
Additional WebSocket Data
More WebSocket data has been added to provide a range of orderbook data at different frequencies and depths. Push frequency has no change, but depth has been increased from 25 to 50. Please refer to the WebSocket interface description for more details.
The updated orderbook now checks for data continuity to ensure that local orderbook data is correct. A Seq (sequence)
field has also been added to help determine the sequence of pulled data, so users can respond efficiently to market changes.
| Product | Depth 1 | Depth 25 | Depth 50 | Depth 100 | Depth 200 | Depth 500 |
|---|---|---|---|---|---|---|
| Spot | 10ms | - | 20ms | - | - | - |
| Derivatives | 10ms | - | 20ms | - | 100ms | 100ms |
| Option | - | 20ms | - | 100ms | - | - |
Increase in Post Only Orders
Under Derivatives, the submission of Post Only orders allows users to place more orderQty for each symbol – typically up to five times the usual orderQty. Users can use the instrument-info endpoint to obtain the maximum number of orders that can be traded for each symbol.
Uniform and Precise Data
Previous APIs returned data as E2 and E8. API V3 and V5 return data as actual values, eliminating the need for users to implement conversion logic.
Readability Improvements to API Documentation
The API documentation has been revised and proofread to improve clarity and reduce confusion. Any parts of the previous documentation that were not clear have been revised to provide better explanations.
V5 and V3 Interface Mapping List
| Module | V5 Endpoint | V3 Endpoint |
|---|---|---|
| Market | /v5/market/kline | /derivatives/v3/public/kline |
| /spot/v3/public/quote/kline | ||
| /v5/market/mark-price-kline | /derivatives/v3/public/mark-price-kline | |
| /v5/market/index-price-kline | /derivatives/v3/public/index-price-kline | |
| /v5/market/premium-index-price-kline | /derivatives/v3/public/premium-index-price-kline | |
| /v5/market/orderbook | /derivatives/v3/public/order-book/L2 | |
| /spot/v3/public/quote/depth | ||
| /v5/market/tickers | /derivatives/v3/public/tickers | |
| /spot/v3/public/quote/ticker/24hr | ||
| /spot/v3/public/quote/ticker/price | ||
| /spot/v3/public/quote/ticker/bookTicker | ||
| /v5/market/funding/history | /derivatives/v3/public/funding/history-funding-rate | |
| /v5/market/recent-trade | /derivatives/v3/public/recent-trade | |
| /spot/v3/public/quote/trades | ||
| /v5/market/open-interest | /derivatives/v3/public/open-interest | |
| /v5/market/historical-volatility | /derivatives/v3/public/historical-volatility | |
| /v5/market/insurance | /derivatives/v3/public/insurance | |
| /v5/market/instruments-info | /derivatives/v3/public/instruments-info | |
| /spot/v3/public/infos | ||
| /spot/v3/public/symbols | ||
| /v5/market/risk-limit | /derivatives/v3/public/risk-limit/list | |
| /v5/market/delivery-price | /derivatives/v3/public/delivery-price | |
| Order | /v5/order/create | /unified/v3/private/order/create |
| /contract/v3/private/order/create | ||
| /v5/order/amend | /unified/v3/private/order/replace | |
| /contract/v3/private/order/replace | ||
| /v5/order/cancel | /unified/v3/private/order/cancel | |
| /contract/v3/private/order/cancel | ||
| /v5/order/realtime | /unified/v3/private/order/unfilled-orders | |
| /contract/v3/private/order/unfilled-orders | ||
| /v5/order/cancel-all | /unified/v3/private/order/cancel-all | |
| /contract/v3/private/order/cancel-all | ||
| /v5/order/history | /unified/v3/private/order/list | |
| /contract/v3/private/order/list | ||
| /v5/order/create-batch | /unified/v3/private/order/create-batch | |
| /v5/order/amend-batch | /unified/v3/private/order/replace-batch | |
| /v5/order/cancel-batch | /unified/v3/private/order/cancel-batch | |
| /v5/order/spot-borrow-check | None | |
| Position | /v5/position/list | /unified/v3/private/position/list |
| /contract/v3/private/position/list | ||
| /v5/position/set-leverage | /unified/v3/private/position/set-leverage | |
| /contract/v3/private/position/set-leverage | ||
| /v5/position/set-risk-limit | /unified/v3/private/position/set-risk-limit | |
| /contract/v3/private/position/set-risk-limit | ||
| /v5/position/trading-stop | /unified/v3/private/position/trading-stop | |
| /contract/v3/private/position/trading-stop | ||
| /v5/position/switch-isolated | /contract/v3/private/position/switch-isolated | |
| /v5/position/switch-mode | /contract/v3/private/position/switch-mode | |
| /v5/position/set-auto-add-margin | /contract/v3/private/position/set-auto-add-margin | |
| /v5/position/closed-pnl | /contract/v3/position/closed-pnl | |
| /v5/execution/list | /unified/v3/private/execution/list | |
| /contract/v3/private/execution/list | ||
| Account | /v5/account/wallet-balance | /unified/v3/private/account/wallet/balance |
| /contract/v3/private/account/wallet/balance | ||
| /v5/account/upgrade-to-uta | /unified/v3/private/account/upgrade-unified-account | |
| /v5/account/borrow-history | /unified/v3/private/account/borrow-history | |
| /v5/account/collateral-info | /unified/v3/private/account/borrow-rate | |
| /v5/asset/coin-greeks | None | |
| /v5/account/info | None | |
| /v5/account/transaction-log | /unified/v3/private/account/transaction-log | |
| /v5/account/set-margin-mode | /contract/v3/private/account/setMarginMode | |
| Spot Leverage Token | /v5/spot-lever-token/info | /spot/v3/public/infos |
| /v5/spot-lever-token/reference | /spot/v3/private/order/reference | |
| /v5/spot-lever-token/purchase | /spot/v3/private/order/purchase | |
| /v5/spot-lever-token/redeem | /spot/v3/private/order/redeem | |
| /v5/spot-lever-token/order-record | /spot/v3/private/order/record | |
| Spot Margin Trade | /v5/spot-margin-trade/switch-mode | /spot/v3/private/cross-margin-switch |
| /v5/spot-margin-trade/set-leverage | None | |
| /v5/spot-margin-trade/set-pledge-token | None | |
| Asset | /v5/asset/delivery-record | /unified/v3/private/delivery-record |
| /v5/asset/settlement-record | /unified/v3/private/settlement-record | |
| /v5/asset/transfer/inter-transfer | /asset/v3/private/transfer/inter-transfer | |
| v5/asset/transfer/query-inter-transfer-list | /asset/v3/private/transfer/inter-transfer/list/query | |
| v5/asset/transfer/save-transfer-sub-member | /asset/v3/private/transfer/transfer-sub-member-save | |
| /v5/asset/transfer/universal-transfer | /asset/v3/private/transfer/universal-transfer | |
| /v5/asset/transfer/query-universal-transfer-list | /asset/v3/private/transfer/universal-transfer/list/query | |
| /v5/asset/transfer/query-transfer-coin-list | /asset/v3/private/transfer/transfer-coin/list/query | |
| /v5/asset/transfer/query-sub-member-list | /asset/v3/private/transfer/sub-member/list/quer | |
| /v5/asset/transfer/query-account-coin-balance | /asset/v3/private/transfer/account-coin/balance/query | |
| /v5/asset/transfer/query-asset-info | /asset/v3/private/transfer/asset-info/query | |
| /v5/asset/deposit/query-allowed-list | /asset/v3/public/deposit/allowed-deposit-list/query | |
| /v5/asset/deposit/query-record | /asset/v3/private/deposit/record/query | |
| /v5/asset/deposit/query-sub-member-record | /asset/v3/private/deposit/sub-member-record/query | |
| /v5/asset/withdraw/query-record | /asset/v3/private/withdraw/record/query | |
| /v5/asset/coin/query-info | /asset/v3/private/coin-info/query | |
| /v5/asset/withdraw/create | /asset/v3/private/withdraw/create | |
| /v5/asset/withdraw/cancel | /asset/v3/private/withdraw/cancel | |
| /v5/asset/deposit/query-address | /asset/v3/private/deposit/address/query | |
| /v5/asset/deposit/query-sub-member-address | /asset/v3/private/deposit/sub-member-address/query | |
| /v5/asset/exchange/order-record | /asset/v2/private/exchange/query-exchange-order | |
| WebSocket Public | wss://stream.bybit.com/v5/public/spot | wss://stream.bybit.com/spot/public/v3 |
| wss://stream.bybit.com/v5/public/linear | wss://stream.bybit.com/contract/usdt/public/v3 | |
| wss://stream.bybit.com/contract/usdc/public/v3 | ||
| wss://stream.bybit.com/v5/public/inverse | wss://stream.bybit.com/contract/inverse/public/v3 | |
| wss://stream.bybit.com/v5/public/option | wss://stream.bybit.com/option/usdc/public/v3 | |
| WebSocket Private | wss://stream.bybit.com/v5/private | wss://stream.bybit.com/spot/private/v3 |
| wss://stream.bybit.com/unified/private/v3 | ||
| wss://stream.bybit.com/contract/private/v3 |