Bybit

信息

We are currently working on this integration 指南.

Founded in 2018, Bybit is one of the largest cryptocurrency exchanges in terms of daily trading volume, and open interest of crypto assets and crypto derivative products. This integration supports live market 数据 ingest and order 执行 with Bybit.

安装

To install NautilusTrader with Bybit 支持:

pip install --upgrade "nautilus_trader[bybit]"

To build from source with all extras (including Bybit):

uv sync --all-extras

示例

You can find live example scripts here.

概览

This 指南 assumes a trader is setting up for both live market 数据 feeds, and trade 执行. The Bybit adapter includes multiple components, which can be used together or separately depending on the use case.

• BybitHttpClient: Low-level HTTP API connectivity.
• BybitWebSocketClient: Low-level WebSocket API connectivity.
• BybitInstrumentProvider: Instrument parsing and loading functionality.
• BybitDataClient: A market data feed manager.
• BybitExecutionClient: An account management and trade execution gateway.
• BybitLiveDataClientFactory: Factory for Bybit data clients (used by the trading node builder).
• BybitLiveExecClientFactory: Factory for Bybit execution clients (used by the trading node builder).

备注

Most users will simply define a 配置 for a 实时交易 节点 (as below), and won't need to necessarily work with these lower level components directly.

Bybit 文档

Bybit provides extensive documentation for users which can be found in the Bybit help center. It’s recommended you also refer to the Bybit 文档 in conjunction with this NautilusTrader integration 指南.

Products

A product is an umbrella term for a group of related instrument types.

备注

Product is also referred to as category in the Bybit v5 API.

The following product types are supported on Bybit:

• Spot cryptocurrencies
• Perpetual contracts
• Perpetual inverse contracts
• Futures contracts
• Futures inverse contracts
• Option contracts

Symbology

To distinguish between different product types on Bybit, Nautilus uses specific product category suffixes for symbols:

• -SPOT: Spot cryptocurrencies
• -LINEAR: Perpetual and futures contracts
• -INVERSE: Inverse perpetual and inverse futures contracts
• -OPTION: Option contracts

These suffixes must be appended to the Bybit raw symbol string to identify the specific product type for the instrument ID. For example:

• The Ether/Tether spot currency pair is identified with -SPOT, such as ETHUSDT-SPOT.
• The BTCUSDT perpetual futures contract is identified with -LINEAR, such as BTCUSDT-LINEAR.
• The BTCUSD inverse perpetual futures contract is identified with -INVERSE, such as BTCUSD-INVERSE.

Order capability

Bybit offers a flexible combination of trigger types, enabling a broader range of Nautilus 订单. All the order types listed below can be used as either entries or exits, except for trailing stops (which utilize a position-related API).

Order types

Order Type	Spot	Linear	Inverse	Notes
MARKET	✓	✓	✓
LIMIT	✓	✓	✓
STOP_MARKET	✓	✓	✓
STOP_LIMIT	✓	✓	✓
MARKET_IF_TOUCHED	✓	✓	✓
LIMIT_IF_TOUCHED	✓	✓	✓
TRAILING_STOP_MARKET	-	✓	✓	Not supported for Spot.

执行 instructions

Instruction	Spot	Linear	Inverse	Notes
post_only	✓	✓	✓	Only supported on LIMIT 订单.
reduce_only	-	✓	✓	Not supported for Spot products.

Time in force

Time in force	Spot	Linear	Inverse	Notes
GTC	✓	✓	✓	Good Till Canceled.
GTD	-	-	-	Not supported.
FOK	✓	✓	✓	Fill or Kill.
IOC	✓	✓	✓	Immediate or Cancel.

Advanced order features

功能	Spot	Linear	Inverse	Notes
Order Modification	✓	✓	✓	Price and quantity modification.
Bracket/OCO 订单	✓	✓	✓	UI only; API users implement manually.
Iceberg 订单	✓	✓	✓	Max 10 per account, 1 per symbol.

Batch operations

Operation	Spot	Linear	Inverse	Notes
Batch Submit	✓	✓	✓	Submit multiple 订单 in single request.
Batch Modify	✓	✓	✓	Modify multiple 订单 in single request.
Batch Cancel	✓	✓	✓	Cancel multiple 订单 in single request.

Position management

功能	Spot	Linear	Inverse	Notes
Query 头寸	-	✓	✓	实时 position updates.
Position mode	-	✓	✓	One-Way vs Hedge mode.
Leverage control	-	✓	✓	Dynamic leverage adjustment per symbol.
Margin mode	-	✓	✓	Cross vs Isolated margin.

Order querying

功能	Spot	Linear	Inverse	Notes
Query open 订单	✓	✓	✓	List all active 订单.
Query order history	✓	✓	✓	Historical order 数据.
Order status updates	✓	✓	✓	实时 order state changes.
Trade history	✓	✓	✓	执行 and fill 报告.

Contingent 订单

功能	Spot	Linear	Inverse	Notes
Order lists	-	-	-	Not supported.
OCO 订单	✓	✓	✓	UI only; API users implement manually.
Bracket 订单	✓	✓	✓	UI only; API users implement manually.
Conditional 订单	✓	✓	✓	Stop and limit-if-touched 订单.

配置 options

The following 执行 客户端 配置 options affect order behavior:

Option	Default	Description
use_gtd	False	GTD is not supported; 订单 are remapped to GTC for local management.
use_ws_trade_api	False	If True, uses WebSocket for order requests instead of HTTP.
use_http_batch_api	False	If True, uses HTTP batch API when WebSocket trading is enabled.
futures_leverages	None	Dict to set leverage for futures symbols.
position_mode	None	Dict to set position mode for USDT perpetual and inverse futures.
margin_mode	None	Sets margin mode for the account.

Order parameters

Individual 订单 can be customized using the params dictionary when submitting 订单:

Parameter	Type	Description
is_leverage	bool	For SPOT products only. If True, enables margin trading (borrowing) for the order. Default: False. See Bybit's isLeverage documentation.

Example: SPOT margin trading

# Submit a SPOT order with margin enabled
order = strategy.order_factory.market(
    instrument_id=InstrumentId.from_str("BTCUSDT-SPOT.BYBIT"),
    order_side=OrderSide.BUY,
    quantity=Quantity.from_str("0.1"),
    params={"is_leverage": True}  # Enable margin for this order
)
strategy.submit_order(order)

备注

Without is_leverage=True in the params, SPOT 订单 will only use your available balance and won't borrow funds, even if you have auto-borrow enabled on your Bybit account.

For a complete example of using order parameters including is_leverage, see the bybit_exec_tester.py example.

Product-specific limitations

The following limitations apply to SPOT products, as 头寸 are not tracked on the venue side:

• reduce_only 订单 are not supported.
• Trailing stop 订单 are not supported.

Trailing stops

Trailing stops on Bybit do not have a 客户端 order ID on the venue side (though there is a venue_order_id). This is because trailing stops are associated with a netted position for an instrument. Consider the following points when using trailing stops on Bybit:

• reduce_only instruction is available
• When the position associated with a trailing stop is closed, the trailing stop is automatically "deactivated" (closed) on the venue side.
• You cannot query trailing stop 订单 that are not already open (the venue_order_id is unknown until then).
• You can manually adjust the trigger price in the 图形界面, which will 更新 the Nautilus order.

配置

The product types for each 客户端 must be specified in the configurations.

数据 clients

If no product types are specified then all product types will be loaded and available.

执行 clients

The adapter automatically determines the account type based on configured product types:

• SPOT only: Uses CASH account type with borrowing support enabled
• Derivatives or mixed products: Uses MARGIN account type (UTA - Unified Trading Account)

This allows you to trade SPOT alongside derivatives in a single Unified Trading Account, which is the standard account type for most Bybit users.

信息

Unified Trading Accounts (UTA) and SPOT margin trading

Most Bybit users now have Unified Trading Accounts (UTA) as Bybit steers new users to this account type. Classic accounts are considered legacy.

For SPOT margin trading on UTA accounts:

• Borrowing is NOT automatically enabled - it requires explicit API 配置
• To use SPOT margin via API, you must submit orders with is_leverage=True in the parameters (see Bybit docs)
• If auto-borrow/auto-repay is enabled on your Bybit account, the venue will automatically borrow/repay funds for those margin 订单
• Without auto-borrow enabled, you'll need to manually manage borrowing through Bybit's 接口

Important: The Nautilus Bybit adapter defaults to is_leverage=False for SPOT orders, meaning they won't use margin unless you explicitly enable it.

Fee currency logic

Understanding how Bybit determines the currency for trading fees is important for accurate accounting and position tracking. The fee currency rules vary between SPOT and derivatives products.

SPOT trading fees

For SPOT trading, the fee currency depends on the order side and whether the fee is a rebate (negative fee for maker 订单):

Normal fees (positive)

• BUY orders: Fee is charged in the base currency (e.g., BTC for BTCUSDT)
• SELL orders: Fee is charged in the quote currency (e.g., USDT for BTCUSDT)

Maker rebates (negative fees)

When maker fees are negative (rebates), the currency logic is inverted:

• BUY orders with maker rebate: Rebate is paid in the quote currency (e.g., USDT for BTCUSDT)
• SELL orders with maker rebate: Rebate is paid in the base currency (e.g., BTC for BTCUSDT)

备注

Taker 订单 never have inverted logic, even if the maker fee rate is negative. Taker fees always follow the normal fee currency rules.

Example: BTCUSDT SPOT

• Buy 1 BTC as taker (0.1% fee): Pay 0.001 BTC in fees
• Sell 1 BTC as taker (0.1% fee): Pay equivalent USDT in fees
• Buy 1 BTC as maker (-0.01% rebate): Receive USDT rebate (inverted)
• Sell 1 BTC as maker (-0.01% rebate): Receive BTC rebate (inverted)

Derivatives trading fees

For all derivatives products (LINEAR, INVERSE, OPTION), fees are always charged in the settlement currency:

Product Type	Settlement Currency	Fee Currency
LINEAR	USDT (typically)	USDT
INVERSE	Base coin (e.g., BTC for BTCUSD)	Base coin
OPTION	USDC (legacy) or USDT (post Feb 2025)	USDC/USDT

Fee calculation

When the WebSocket 执行 message doesn't provide the exact fee amount (execFee), the adapter calculates fees as follows:

SPOT products

• BUY orders: fee = base_quantity × fee_rate
• SELL orders: fee = notional_value × fee_rate (where notional_value = quantity × price)

Derivatives

• All derivatives: fee = notional_value × fee_rate

Official 文档

For complete details on Bybit's fee structure and currency rules, refer to:

• Bybit WebSocket Private Execution
• Bybit Spot Fee Currency Instruction

The most common use case is to configure a live TradingNode to include Bybit 数据 and 执行 clients. To achieve this, add a Bybit section to your 客户端 配置(s):

from nautilus_trader.adapters.bybit import BYBIT
from nautilus_trader.adapters.bybit import BybitProductType
from nautilus_trader.live.node import TradingNode

config = TradingNodeConfig(
    ...,  # Omitted
    data_clients={
        BYBIT: {
            "api_key": "YOUR_BYBIT_API_KEY",
            "api_secret": "YOUR_BYBIT_API_SECRET",
            "base_url_http": None,  # Override with custom endpoint
            "product_types": [BybitProductType.LINEAR]
            "testnet": False,
        },
    },
    exec_clients={
        BYBIT: {
            "api_key": "YOUR_BYBIT_API_KEY",
            "api_secret": "YOUR_BYBIT_API_SECRET",
            "base_url_http": None,  # Override with custom endpoint
            "product_types": [BybitProductType.LINEAR]
            "testnet": False,
        },
    },
)

Then, create a TradingNode and add the 客户端 factories:

from nautilus_trader.adapters.bybit import BYBIT
from nautilus_trader.adapters.bybit import BybitLiveDataClientFactory
from nautilus_trader.adapters.bybit import BybitLiveExecClientFactory
from nautilus_trader.live.node import TradingNode

# Instantiate the live trading node with a configuration
node = TradingNode(config=config)

# Register the client factories with the node
node.add_data_client_factory(BYBIT, BybitLiveDataClientFactory)
node.add_exec_client_factory(BYBIT, BybitLiveExecClientFactory)

# Finally build the node
node.build()

API credentials

There are two options for supplying your credentials to the Bybit clients. Either pass the corresponding api_key and api_secret values to the 配置 objects, or set the following 环境 variables:

For Bybit live clients, you can set:

• BYBIT_API_KEY
• BYBIT_API_SECRET

For Bybit demo clients, you can set:

• BYBIT_DEMO_API_KEY
• BYBIT_DEMO_API_SECRET

For Bybit testnet clients, you can set:

• BYBIT_TESTNET_API_KEY
• BYBIT_TESTNET_API_SECRET

提示

We recommend using 环境 variables to manage your credentials.

When starting the trading 节点, you'll receive immediate confirmation of whether your credentials are valid and have trading permissions.