NautilusTrader
Integrations

Nightly docs

These docs track unreleased changes and may change without notice. Their code examples can use APIs that the latest release lacks, so run them with a development wheel or switch to the latest release docs.

Bybit

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.

NautilusTrader provides Bybit integration for live market data and execution. The adapter is implemented in Rust and exposed to Python through the same public configurations, factories, and data types.

Examples

Overview

This guide assumes a trader is setting up for both live market data feeds and trade execution. The Bybit adapter includes multiple components, which can be used together or separately depending on the use case.

  • BybitDataClientConfig and BybitExecutionClientConfig: Live client configuration.
  • BybitDataClientFactory and BybitExecutionClientFactory: Trading node client factories.
  • BybitDataClient: A market data feed manager, built by the data client factory.
  • BybitExecutionClient: An account management and trade execution gateway, built by the execution client factory.
  • BybitHttpClient: Low-level HTTP API connectivity.
  • BybitWebSocketClient: Low-level WebSocket API connectivity for Rust callers.
  • BybitLiquidation: Custom data for public liquidations on linear and inverse contracts, see Liquidations.
  • BybitMarginBorrowResult, BybitMarginRepayResult, BybitMarginStatusResult: Custom data for manual spot margin operations, see Manual margin operations.
  • BYBIT, BYBIT_CLIENT_ID, BYBIT_VENUE: Public identifiers.
  • BybitMarginAction: Names the manual margin query_account actions; params take its spelling as a string.
  • BybitEnvironment, BybitProductType, BybitMarginMode, BybitPositionIdx, BybitPositionMode: Public enums used by the configurations and order params.

Most users configure a live trading node as shown below. They do not need to use the lower-level components directly.

Bybit documentation

Read the Bybit help center with this NautilusTrader integration guide.

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:

Product TypeSupportedNotes
Spot cryptocurrencies✓Native spot markets with margin support.
Linear perpetual contracts✓USDT/USDC margined perpetual swaps.
Linear futures contracts✓Delivery-settled linear futures.
Inverse perpetual contracts✓Coin-margined perpetual swaps.
Inverse futures contracts✓Coin-margined delivery futures.
Option contracts✓European options settled in USDT or USDC.

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.
  • A BTC USDT-settled put option: BTC-27MAR26-70000-P-USDT-OPTION.
  • A ETH USDC-settled call option: ETH-28FEB25-2800-C-OPTION.

Bybit's option symbols include the settlement currency for USDT-settled contracts (e.g. BTC-27MAR26-70000-P-USDT) but omit it for USDC-settled contracts (e.g. ETH-28FEB25-2800-C). The adapter appends -OPTION to whatever symbol the API returns.

Instrument loading

The data and execution clients load all instruments for their configured product_types when they connect. The default is LINEAR. Include each product type required by your subscriptions or orders.

Reconciliation

BybitExecutionClientConfig.load_ids limits reconciliation to the listed instrument IDs. It does not limit instrument loading or order submission. Instrument loading still follows product_types. None or an empty list includes every configured product type. IDs must use the BYBIT venue, an uppercase symbol, and a configured product-type suffix.

Uncached instruments follow the instrument availability rules. Bybit uses the execution client's load_ids for this scope.

  • A closed order or fill with an uncached in-scope instrument fails direct report requests.
  • With reconciliation_lookback_mins, mass status records one cutoff at millisecond precision for order and fill history, marks missing historical instruments or unlinked fills incomplete, and keeps open orders of any age.
  • Lookbacks of 24 hours or longer mark history incomplete because fully canceled, rejected, and deactivated orders have only 24-hour retention. The default venue order-history query covers seven days. With a lookback longer than seven days, the fill query returns only the first seven days after the cutoff, so recent fills can be absent.
  • Bulk option fill queries use Bybit's BTC default. Bounded mass status marks history incomplete whenever OPTION is configured.
  • Order parse and commission construction errors fail the request.

See Reconciliation reports for report collection and order status mapping.

Environments

Bybit provides three trading environments. Configure the appropriate environment with the environment enum on your client configuration.

EnvironmentConfigDescription
MainnetBybitEnvironment.MAINNETProduction trading with real funds.
DemoBybitEnvironment.DEMOPractice trading with simulated funds on mainnet infrastructure.
TestnetBybitEnvironment.TESTNETSeparate test network for development and integration testing.

Mainnet (Production)

The default environment for live trading with real funds.

from nautilus_trader.adapters.bybit import BybitEnvironment
from nautilus_trader.adapters.bybit import BybitExecutionClientConfig

config = BybitExecutionClientConfig(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    environment=BybitEnvironment.MAINNET,
)

Environment variables: BYBIT_API_KEY, BYBIT_API_SECRET

Demo trading

Demo trading uses Bybit's mainnet infrastructure with simulated funds. Create demo API keys from the Bybit demo trading page.

from nautilus_trader.adapters.bybit import BybitEnvironment
from nautilus_trader.adapters.bybit import BybitExecutionClientConfig

config = BybitExecutionClientConfig(
    api_key="YOUR_DEMO_API_KEY",
    api_secret="YOUR_DEMO_API_SECRET",
    environment=BybitEnvironment.DEMO,
)

Environment variables: BYBIT_DEMO_API_KEY, BYBIT_DEMO_API_SECRET

Demo environment limitations:

  • The WebSocket Trade API is not supported for demo trading. NautilusTrader automatically uses the HTTP REST API for order operations in demo mode, including order lists, batch modifies, and batch cancels, which are sent as individual requests.
  • The execution.fast private channel is not supported. Setting use_ws_execution_fast=True in demo mode is rejected; use the standard execution stream.
  • Native TP/SL and option params (order_iv, mmp) on new orders work in demo via the HTTP create-order endpoint.
  • The custom TP/SL trigger prices tp_trigger_price and sl_trigger_price are not supported in demo (orders setting them are denied). The create-order endpoint cannot carry them.
  • Demo private streams use wss://stream-demo.bybit.com, but public market data uses Bybit's mainnet public stream wss://stream.bybit.com.

Testnet

A separate test network for development and integration testing.

from nautilus_trader.adapters.bybit import BybitEnvironment
from nautilus_trader.adapters.bybit import BybitExecutionClientConfig

config = BybitExecutionClientConfig(
    api_key="YOUR_TESTNET_API_KEY",
    api_secret="YOUR_TESTNET_API_SECRET",
    environment=BybitEnvironment.TESTNET,
)

Environment variables: BYBIT_TESTNET_API_KEY, BYBIT_TESTNET_API_SECRET

Testnet supports all trading features including the WebSocket Trade API. It uses completely separate infrastructure from mainnet, so market data and liquidity differ significantly from production.

When environment=BybitEnvironment.TESTNET, the adapter resolves Bybit's documented testnet endpoints automatically:

  • REST API: https://api-testnet.bybit.com
  • Public WebSocket: wss://stream-testnet.bybit.com/v5/public/{spot|linear|inverse|option}
  • Private WebSocket: wss://stream-testnet.bybit.com/v5/private
  • Trade WebSocket: wss://stream-testnet.bybit.com/v5/trade

Testnet setup

To set up a Bybit testnet account and credentials:

  1. Open testnet.bybit.com in a desktop browser.

  2. Create a separate testnet account or sign in to your existing testnet account.

  3. Request test coins from Assets -> Assets Overview -> Request Test Coins so the account has balances for testing.

  4. Open API Management at testnet.bybit.com/app/user/api-management.

  5. Click Create New Key.

  6. Select the required permissions for your use case.

  7. Complete the 2FA prompt and copy the API key and secret.

  8. Export the credentials in your shell:

    export BYBIT_TESTNET_API_KEY="YOUR_TESTNET_API_KEY"
    export BYBIT_TESTNET_API_SECRET="YOUR_TESTNET_API_SECRET"

Bybit's current testnet guidance also notes:

  • API keys are created on the website, not in the mobile app.
  • New users may be unable to create API keys for the first 48 hours after registration.
  • Testnet is separate from mainnet. Do not deposit real funds into a testnet account.
  • Bybit currently documents testnet account setup through a desktop browser.

Quotes and order books

For SPOT, LINEAR, and INVERSE products, quote subscriptions use Bybit's depth-1 order book snapshots. This feed provides best bid/ask prices and sizes at a documented 10 ms push frequency. OPTION quotes use the ticker feed. See the Bybit order book specification.

Book delta subscriptions for SPOT, LINEAR, and INVERSE support depths 1, 50, 200, and 1000 and default to 50. OPTION subscriptions support depths 25 and 100 and default to 25.

Quotes and depth-1 book subscriptions share one WebSocket topic. Unsubscribing from one leaves the topic active while the other is still subscribed. A deeper book subscription uses its own topic alongside the depth-1 quote feed, so adding book deltas does not change the quote source. Book deltas only come from the requested depth. Subscribe to one book depth per instrument. Unsubscribe from the existing book before selecting another depth.

Order book recovery

Sequence validation

Each delta must carry the update ID u that follows the book's last accepted frame. Any other delta suppresses book output and requests recovery. So does a delta that reaches a book before its first snapshot. For example, an update sent before a quick resubscribe can reach the new subscription. A request starts recovery only when neither a running recovery nor a snapshot deadline already owns the book.

Every snapshot replaces the book, as the Bybit order book contract requires. The venue sends one after each subscribe and after a service restart, which can reset u to 1, and pushes only snapshots at depth 1. A replacement snapshot can carry an update ID below the book's last delta, since the venue serves it from an earlier state. Deltas then continue from it. A snapshot that arrives while the book's subscription or replacement write is still in flight is discarded.

Snapshot deadlines

Initial and recovery subscriptions wait up to book_snapshot_timeout_secs (default 10 seconds) for a snapshot after the subscription write completes. Books on a reconnected socket wait the same time from the reconnect. A missing snapshot starts or retries recovery.

Set book_snapshot_timeout_secs to 0 to disable snapshot deadlines. A gap still starts recovery, but a recovery attempt whose snapshot never arrives then waits until the 180-second retry budget ends.

A depth-1 book shares its topic with quotes. When quotes already hold the topic, subscribing the book sends nothing, and the next depth-1 snapshot synchronizes it.

Retry limits and reconnects

Recovery unsubscribes and resubscribes the book's topic on the same connection, and the venue answers with a fresh snapshot. Each recovery episode makes up to eight attempts within 180 seconds, with exponential backoff and jitter. It then retries until it accepts a snapshot. The retry interval doubles from one minute to fifteen minutes. Recovery never ends in a failed state. Unsubscribe and shutdown cancel it.

Recovering a depth-1 book also pauses quotes on the shared topic until the replacement snapshot arrives. A venue rejection of a replacement subscription is logged, and the attempt retries once its snapshot deadline passes.

A reconnect resynchronizes every book on the reconnected product type's socket from the snapshot of its replayed subscription. It keeps a running recovery with its remaining budget. A recovery waiting between attempts after its budget retries at once on the new connection.

If the client cannot queue the initial subscription, it logs an error and releases the book instead of recovering it. For example, the subscription can exceed the option connection's topic limit. A queued initial subscription whose write fails starts recovery at once.

See Order book recovery ownership for the shared recovery machinery and adapter responsibilities.

Live recovery validation

The bybit-book-stress harness is a development tool for changes to book synchronization and recovery. It connects to Bybit mainnet public market data and submits no orders. It checks six linear books at the default depth of 50 against:

  • The book stream contract, including rising sequences within each snapshot episode.
  • A reference book of the best 50 levels, rebuilt from the frames the proxy relays.

A separate public connection, outside the proxy, compares that reference book at the same cross sequence (seq). A session fails unless every book has at least one such comparison.

From the repository root, run:

CARGO_BUILD_JOBS=16 bash scripts/strip-adapter-env.bash \
  cargo test -p nautilus-bybit --features examples --test bybit-book-stress -- --timeout 10 --rounds 21

--scenario selects the run:

  • churn (default): checks recovery without reconnects, then rotates update ID gaps, dropped and delayed snapshots, reconnects cut before their snapshots, unsubscribe during recovery, a restart during recovery, and a 40-second traffic freeze.
  • initial: drops each book's first snapshot, once per round in a fresh session.
  • turnover: unsubscribes and resubscribes books during recovery.
  • boundaries: probes replacement cuts, retry exhaustion into the retry ceiling, and shutdown during a reconnect. With a nonzero timeout, it also rejects a replacement and a replayed subscription.

--timeout sets the snapshot timeout in seconds, where 0 disables snapshot deadlines. --rounds sets the number of rounds (21 by default) for churn, initial, and turnover. boundaries runs its sequence once.

The harness requires the mainnet linear WebSocket stream and the public instruments-info REST API. See Stress harnesses for the shared flags and output format.

Orders capability

Bybit offers a flexible combination of trigger types, enabling a broader range of Nautilus orders. All the order types listed below can be used as either entries or exits.

Order types

Order TypeSpotLinearInverseOptionNotes
MARKET✓✓✓✓Quote quantity: Spot only.
LIMIT✓✓✓✓
STOP_MARKET✓✓✓-Not supported for Options.
STOP_LIMIT✓✓✓-Not supported for Options.
MARKET_IF_TOUCHED✓✓✓-Not supported for Options.
LIMIT_IF_TOUCHED✓✓✓-Not supported for Options.
TRAILING_STOP_MARKET----See Trailing stops.

At submission, the adapter denies an unsupported order type locally with an UNSUPPORTED_ORDER_TYPE reason. It does not send the order to the venue.

Execution instructions

InstructionSpotLinearInverseOptionNotes
post_only✓✓✓✓Limit order types only; sent as Bybit's PostOnly time in force.
reduce_only-✓✓✓Not supported for Spot.

Time in force

Time in forceSpotLinearInverseOptionNotes
GTC✓✓✓✓Good Till Canceled.
GTD----No native expiry; sent as GTC.
FOK✓✓✓✓Fill or Kill.
IOC✓✓✓✓Immediate or Cancel.

Other time in force values (DAY, AT_THE_OPEN, and AT_THE_CLOSE) produce OrderDenied with an UNSUPPORTED_TIME_IN_FORCE reason before HTTP or WebSocket submission. This also applies to market and post-only orders. An unsupported TIF in an order list denies every leg before submission.

Advanced order features

FeatureSpotLinearInverseOptionNotes
Order Modification✓✓✓✓Price and quantity modification.
Bracket/OCO Orders----See Contingent orders.
Iceberg Orders----Not implemented.

Conditional orders also support trigger-price amendments.

Batch operations

OperationSpotLinearInverseOptionNotes
Batch Submit✓✓✓✓Submit multiple orders in single request.
Batch Modify✓✓✓✓Modify multiple orders in single request.
Batch Cancel✓✓✓✓Cancel multiple orders in single request.

Batch submit, batch modify, and batch cancel use the trade WebSocket on mainnet and testnet. In demo mode the adapter falls back to individual HTTP requests, because the demo environment has no trade WebSocket.

Bybit accepts at most 10 Spot orders, 20 Linear or Inverse orders, or 5 Option orders in one batch request. Linear, Inverse, and Spot batches consume UID quota per order, while an Option batch consumes one request. The adapter splits Spot, Linear, and Inverse batches into groups of 10 by default so one request cannot exceed the standard rolling UID allowance. It splits Option batches into groups of five. The HTTP batch-cancel method accepts up to 20 Option operations in one call.

Cancel-all orders

For venue-wide cancel-all (strategy_only=False) without an order_side filter, the adapter updates cached orders only after the venue confirms cancellation. Fills use the execution stream and reconciliation. The cancel request, history lookup, and confirmation queries share one http_timeout_secs deadline. The adapter waits retry_delay_initial_ms (at least 1 ms) between polling rounds. If a request fails or the deadline expires, unconfirmed orders stay open locally until a later order update or reconciliation confirms closure. With an order_side filter, the adapter uses batch cancel for matching orders instead. See Cancel-all routing for command routing.

Reconciliation reports

With LiveNode, open-order and targeted order checks collect order reports on a runtime worker. The node accepts the reports before finalization updates order identities on the core thread. Expired or canceled collections retain the identities needed for pending cancel and amend rejections. Startup mass status and direct asynchronous report methods still collect and finalize in one call.

HTTP order reports keep a venue rejectReason on cancel_reason, except EC_NoError. When a rejected order has an empty rejectReason, the reason is venue omitted rejectReason rather than UNKNOWN. Bybit reports a post-only order that would take liquidity as Cancelled with EC_PostOnlyWillTakeLiquidity; reconciliation emits OrderRejected with due_post_only=true.

Position management

FeatureSpotLinearInverseOptionNotes
Query positions-✓✓✓Real-time position updates.
Position mode-✓✓-One-Way only for Options.
Leverage control-✓✓-Not applicable for Options.
Margin mode-✓✓✓ISOLATED_MARGIN, REGULAR_MARGIN, or PORTFOLIO_MARGIN.

Set margin_mode on the execution client config to apply a BybitMarginMode to the account when the client connects.

Hedge mode (BothSides)

Bybit only accepts Both Sides mode on USDT linear perpetuals. Configure the position mode at Bybit. Then pass position_idx through the order params. Use 1 for the long side or 2 for the short side. Use 0 or omit the parameter for one-way mode.

Bybit documents these values in the V5 switch position mode and place order APIs.

Orders and reports with positionIdx=0 (one-way / Merged Single mode) carry no venue position ID. For hedge-mode indexes 1 and 2, the adapter maps reports to venue position IDs ending in -LONG and -SHORT. If Bybit execution messages omit positionIdx, fills carry the same ID.

In hedge mode, positionIdx identifies the affected position, not the trade direction. Thus, a reduce-only sell resolves to the long index. A reduce-only buy resolves to the short index.

To override, pass position_idx via params:

params = {"position_idx": 1}  # 0 one-way, 1 long, 2 short

Risk events

FeatureSpotLinearInverseOptionNotes
Liquidation handling-✓✓✓Takeover fills flagged as exchange-generated.
ADL handling-✓✓✓Auto-deleveraging fills flagged and logged.
ADL rank warnings-✓✓✓Position reports logged when adlRankIndicator >= 4.

Bybit emits venue-initiated fills with execType set to:

  • AdlTrade: Auto-deleveraging execution. An opposing profitable position was selected to close the undercollateralised counterparty after the insurance fund could not cover the loss.
  • BustTrade: Liquidation takeover. The liquidation engine seized the position after margin was exhausted.
  • Delivery: USDC futures delivery.
  • Settle: Inverse futures settlement.
  • ForwardSplitSettle: Forward stock split fractional share settlement.
  • ReverseSplitSettle: Reverse stock split fractional share settlement.
  • Dividend: Dividend distribution.

The venue previously issued CorporateAction for stock splits and reverse splits. The adapter still accepts it in execution history recorded before its replacement by the settle and dividend types above.

The adapter flags each as exchange-generated and logs a warning containing the execution ID, symbol, side, quantity, and price. Fills flow through the normal FillReport path. Because these orders carry an empty orderLinkId, the execution engine treats them as external. It assigns them through the instrument's active external order claim, configured initially with external_order_instrument_ids. Without a claim, it assigns them to the EXTERNAL strategy.

Execution types the adapter does not recognize are handled as UNKNOWN rather than rejected, so future venue additions still flow through the fill path instead of being dropped.

Funding settlements use execType=Funding, but they are balance adjustments rather than fills. The adapter ignores them in historical fill reports and standard private execution messages. Thus, it emits neither a FillReport nor an OrderFilled event. It does not change local position quantity. During reconciliation, funding records do not count toward the requested fill-report limit.

Bybit also publishes an ADL ranking on position updates via the adlRankIndicator field. The range is 0 (flat / no position) to 5 (next to deleverage). The adapter logs a warning whenever an open position carries a rank of 4 or higher so you can react before the venue force-closes.

Upstream references:

Order querying

FeatureSpotLinearInverseOptionNotes
Query open orders✓✓✓✓List all active orders.
Query order history✓✓✓✓Historical order data.
Order status updates✓✓✓✓Real-time order state changes.
Trade history✓✓✓✓Execution and fill reports.

Contingent orders

FeatureSpotLinearInverseOptionNotes
Order lists✓✓✓✓WebSocket batch; individual HTTP requests in demo.
OCO orders----No native linkage; manage sibling orders.
Bracket orders----No native entry-fill sequencing.
Conditional orders✓✓✓-Stop and limit-if-touched orders.

An order list is validated locally as a unit before any leg is sent. When one leg fails validation, that leg is denied with its specific reason. The remaining legs are denied with ORDER_LIST_DENIED. Thus, a partially submitted list cannot result from a local validation failure. Venue submission is not atomic: Bybit can accept some legs and reject others.

Bracket submission limits

For non-emulated bracket order lists sent to the Bybit adapter, the entry, take-profit (TP), and stop-loss (SL) legs submit without waiting for entry fills. The adapter does not defer exit submission or provide native OCO linkage for these legs.

Bybit rejects reduce-only limit orders when no position exists. In demo trading, an ETHUSDT-LINEAR bracket with a resting limit entry can have its entry and conditional reduce-only stop-market SL accepted while the non-conditional reduce-only limit TP is rejected with current position is zero, cannot fix reduce-only order qty. The accepted legs can leave the position without a TP order. With StrategyConfig.manage_contingent_orders enabled, the TP rejection can also cancel its open SL sibling, leaving no exit orders.

Wait for confirmed entry fills before submitting separate reduce-only exits, and size them to the filled position. Handle OrderRejected for each leg, and manage sibling cancellation and quantity updates in your strategy. See Strategy-managed contingencies for automatic management of open sibling orders. To use native TP/SL, pass order parameters to submit_order for a single entry order. Order-list params apply to every leg.

Order parameters

Individual orders can be customized using the params dictionary when submitting orders:

ParameterTypeDescription
is_leverageboolSpot only. Enables margin trading (borrowing). Default: False.
take_profitstr or floatTP trigger price. Attaches a native TP to the order.
stop_lossstr or floatSL trigger price. Attaches a native SL to the order.
tp_trigger_bystrTP trigger type: "LastPrice", "IndexPrice", or "MarkPrice".
sl_trigger_bystrSL trigger type: "LastPrice", "IndexPrice", or "MarkPrice".
tp_order_typestrTP execution type: "Market" or "Limit".
sl_order_typestrSL execution type: "Market" or "Limit".
tp_limit_pricestr or floatLimit price for TP when tp_order_type is "Limit".
sl_limit_pricestr or floatLimit price for SL when sl_order_type is "Limit".
tp_trigger_pricestr or floatExplicit TP trigger price sent alongside take_profit.
sl_trigger_pricestr or floatExplicit SL trigger price sent alongside stop_loss.
tpsl_modestrTP/SL mode: "Full" or "Partial".
close_on_triggerboolClose the position when TP/SL triggers.
position_idxintHedge-mode position index. See Hedge mode.
bbo_side_typestrLinear/inverse BBO side: "Queue" or "Counterparty".
bbo_levelstr or intLinear/inverse BBO book level: "1" through "5".
smp_typestrSelf-match prevention. See SMP.

Parameters left unset are omitted from the request, so Bybit's own defaults apply.

Bybit's close_on_trigger parameter is not the generic close_position whole-position exit contract used by the risk engine. The adapter sends the order quantity, and it ignores an unknown close_position parameter. Do not add BYBIT to full_position_exit_venues based on close_on_trigger. Leave the venue unlisted so ordinary quantity and notional checks apply.

The adapter validates these params before emitting OrderSubmitted and denies the order with a VALIDATION_FAILED reason when a rule is broken:

  • Every TP override field (tp_trigger_by, tp_order_type, tp_limit_price, tp_trigger_price) requires take_profit, and every SL override field likewise requires stop_loss.
  • tp_order_type="Limit" requires tp_limit_price, and tp_limit_price requires tp_order_type="Limit". The same pairing applies to sl_order_type and sl_limit_price.
  • bbo_side_type and bbo_level must be provided together.
  • smp_type must be "None", "CancelMaker", "CancelTaker", or "CancelBoth", matched case-insensitively.

When take_profit or stop_loss is set without tpsl_mode, the adapter sends Full. For Linear and Inverse, Full covers the entire position and supports only market TP/SL. Set tpsl_mode="Partial" to size native TP/SL to the entry's filled quantity and support limit TP/SL. See Bybit's create-order parameters. When a TP or SL price is set without its own tp_trigger_by or sl_trigger_by, the adapter derives the trigger type from the order's trigger type.

On demo, native TP/SL params route through the HTTP create-order endpoint, with one exception. The endpoint cannot carry the custom trigger prices tp_trigger_price and sl_trigger_price. Thus, the adapter denies orders that set either price. The is_leverage param applies to Spot products only. See Bybit's isLeverage documentation.

When bbo_side_type and bbo_level are set, Nautilus sends Bybit's bboSideType and bboLevel fields and omits the order price from the API request. BBO orders are supported for linear and inverse limit, stop-limit, and limit-if-touched orders.

Self-match prevention

Self-match prevention (SMP) tells Bybit what to do when one of your orders would trade against another of your own orders. Bybit accepts four values on an order, shown below in their canonical wire spellings. The adapter matches them case-insensitively and always sends the canonical spelling.

ValueBehavior
NoneNo self-match prevention.
CancelMakerCancel the resting maker order.
CancelTakerCancel the incoming taker order.
CancelBothCancel both orders.

Set smp_type on the execution client config to send that value on every order the client submits:

from nautilus_trader.adapters.bybit import BybitExecutionClientConfig

config = BybitExecutionClientConfig(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    smp_type="CancelMaker",
)

Pass smp_type through the order params to override the configured default for a single order:

params = {"smp_type": "CancelBoth"}

The adapter denies an order whose smp_type is not one of the four values above, and it rejects a client config carrying any other value. With neither the config nor the param set, the adapter omits smpType, so Bybit's own default applies. Bybit overrides the setting in some regions. Derivatives accounts in Kazakhstan have SMP force-enabled and cannot opt out. For spot accounts in Turkey, Kazakhstan, and Georgia, Bybit uses CancelMaker when smpType is omitted, None, or invalid.

Bybit documents the values and the regional rules in the V5 SMP guide.

Example: Order with native TP/SL

order = strategy.order_factory.limit(
    instrument_id=InstrumentId.from_str("BTCUSDT-LINEAR.BYBIT"),
    order_side=OrderSide.BUY,
    quantity=Quantity.from_str("0.01"),
    price=Price.from_str("60000.0"),
)
strategy.submit_order(
    order,
    params={
        "take_profit": "65000.0",
        "stop_loss": "58000.0",
        "tp_trigger_by": "LastPrice",
        "sl_trigger_by": "LastPrice",
    },
)

Example: BBO order

order = strategy.order_factory.limit(
    instrument_id=InstrumentId.from_str("BTCUSDT-LINEAR.BYBIT"),
    order_side=OrderSide.BUY,
    quantity=Quantity.from_str("0.01"),
    price=Price.from_str("60000.0"),
    params={"bbo_side_type": "Queue", "bbo_level": 1},
)
strategy.submit_order(order)

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 orders use your available balance and do not 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 Python execution tester.

Spot trading limitations

The following limitations apply to Spot products, as positions are not tracked on the venue side:

  • reduce_only orders are not supported.
  • Trailing stop orders are not supported.

Options trading

Bybit lists European-style options on crypto and US equity underlyings, such as BTC, ETH, SOL, and NVDA, settled in USDT or USDC. The adapter uses the CryptoOption instrument type and the -OPTION symbol suffix. See the symbology section for the full symbol format.

Option instruments carry exercise_style EUROPEAN and settlement_type CASH. Bybit definitions have neither field; the values follow the Bybit options specification.

With OPTION in product_types, the adapter loads options for every listed base coin, including BTC, ETH, and SOL, on mainnet, testnet, and demo. Instrument refreshes and status updates cover the same base coins.

Options data

The adapter supports real-time options market data through the WebSocket ticker channel:

Data typeDescription
Quotes (bid/ask)Top-of-book prices and sizes for each option contract.
GreeksDelta, gamma, vega, theta, plus bid/ask/mark IV. Bybit publishes no rho.
Mark priceExchange mark price for each option contract.
Index priceUnderlying index price.
Underlying reference pricePer-expiry venue reference used for ATM determination.
Open interestPer-contract open interest.
Order book deltasL2 MBP updates from the option orderbook stream.

Subscribe to per-instrument Greeks or aggregate them into option chain snapshots with ATM-relative strike filtering. See the options concept guide for subscription patterns and the options data tutorial for a step-by-step walkthrough. NautilusTrader builds the option chain view locally from Bybit's per-contract option market data.

Bar (kline) data is not available for options. Bybit does not provide kline streams for this product type.

Options order parameters

In addition to the standard order parameters, option orders accept:

ParameterTypeDescription
order_ivstr or floatPlace or amend the order by implied volatility instead of price.
mmpboolEnable Market Maker Protection for the order.

These parameters are passed through params on SubmitOrder. On mainnet they flow through the WebSocket trade channel. On demo they route through the HTTP create-order endpoint. Amending an existing order by order_iv is not supported in demo mode.

Options trading limitations

  • Amending an order by implied volatility (order_iv) and other WS-trade-only features are not supported in demo mode.
  • Leverage is not configurable. Option buyers pay premium. Sellers post margin.
  • Position mode is one-way only. Hedge mode is not supported.
  • Conditional order types (STOP_MARKET, STOP_LIMIT, MARKET_IF_TOUCHED, LIMIT_IF_TOUCHED) are not supported.
  • Trading stops (TP/SL on positions) are not supported.
  • Funding rates do not apply to options.
  • Options require a Unified Trading Account (UTA).

Trailing stops

The adapter does not submit Nautilus TRAILING_STOP_MARKET orders to Bybit. Submitting one denies the order locally with an UNSUPPORTED_ORDER_TYPE reason.

Bybit models trailing stops as an attribute of a netted position rather than as an order. Thus, a trailing stop has no venue-side client order ID. It cannot be queried until it is already open. Attach a trailing stop through the Bybit interface if you need one, and manage the resulting position exit outside Nautilus.

Spot margin borrowing and repayment

NautilusTrader can automatically repay spot margin borrows after BUY orders fill, and strategies can drive borrowing, repayment, and borrow queries manually.

Background

When trading Spot with margin enabled (is_leverage=True), Bybit automatically borrows coins when you execute short positions. However, after you close the short position (BUY order fills), the borrowed coins are NOT automatically repaid - they continue accruing hourly interest charges until manually repaid. This can result in significant interest costs if left unattended.

The execution client can automatically repay spot margin borrows after BUY orders fully fill on Spot instruments. This feature is disabled by default, so set auto_repay_spot_borrows=True to opt in.

How it works:

  1. When a Spot BUY order fully fills on the standard execution channel, the execution client attempts to repay the base coin borrow.
  2. The repayment is capped at the lesser of the outstanding borrow and the base quantity acquired across the order's executions.
  3. The execution client uses Bybit's converting repay endpoint to cover base-denominated trading fees. For MNT, which Bybit excludes from converting repayment, it uses no-convert repay and subtracts MNT-denominated fees from the amount.
  4. A failed request or FA result status is logged without crashing the execution client. A P result status is logged as processing, not complete.
  5. The execution client defers queued repayments during Bybit's UTC blackout window.

Example:

from nautilus_trader.adapters.bybit import BybitExecutionClientConfig

config = BybitExecutionClientConfig(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    product_types=[BybitProductType.SPOT],
    auto_repay_spot_borrows=True,  # Opt in; default is False
)

UTC blackout window

Bybit blocks both repayment endpoints from 4 minutes through 5 minutes 30 seconds past every UTC hour for interest calculation. Auto-repayment keeps the request queued and attempts it at 5 minutes 31 seconds past the hour.

Auto-repayment configuration

OptionTypeDefaultDescription
auto_repay_spot_borrowsboolFalseIf True, automatically repay Spot margin borrows after BUY orders fully fill. Repayment is deferred during the blackout.

Auto-repayment notes

  • Auto-repayment only triggers on Spot BUY orders, not derivatives.
  • Repayment uses converting repayment except for MNT, which uses no-convert repayment.
  • Bybit documents the endpoint restrictions and result statuses in Manual Repay and Manual Repay Without Asset Conversion.
  • Manual borrowing is still required before opening short positions unless auto-borrow is enabled on your Bybit account. See Manual margin operations.

Manual margin operations

Strategies control spot margin borrowing directly through query_account params. An unknown or missing action refreshes the account state instead of performing a margin operation, and an unknown value also logs a warning.

ParamTypeDescription
actionstrborrow, repay, or get_borrow_amount (case-insensitive).
coinstrRequired. Without it the client logs an error and publishes no result.
amountstr or numberRequired for borrow and must be positive. Omit on repay to repay everything.

An amount that is present but null, zero, negative, or not a string or number publishes a failed result rather than repaying everything. Unlike v1, the params must use plain strings or numbers: json.dumps raises TypeError on Decimal values and enum objects. An omitted amount asks the venue to repay the whole outstanding borrow, bounded by the available coin balance, so query the remaining borrow with get_borrow_amount before treating the liability as cleared.

account_id = self.portfolio.account(BYBIT_VENUE).id

# Borrow the base coin before opening a short
self.query_account(
    account_id=account_id,
    params={"action": "borrow", "coin": "ETH", "amount": 0.5},
)

# Repay a specific amount, or omit "amount" to repay the whole outstanding borrow
self.query_account(
    account_id=account_id,
    params={"action": "repay", "coin": "ETH", "amount": 0.05},
)

# Query the current borrowed amount
self.query_account(
    account_id=account_id,
    params={"action": "get_borrow_amount", "coin": "ETH"},
)

Each action that names a coin publishes custom data:

ActionPublished typeNotes
borrowBybitMarginBorrowResultsuccess and message; a missing or invalid amount publishes this.
repayBybitMarginRepayResultresult_status is the venue P or SU on success, FAIL otherwise.
get_borrow_amountBybitMarginStatusResultborrow_amount; a failed query publishes nothing.

Manual repayment differs from auto-repayment:

  • REPAY uses Bybit's no-convert repay endpoint, so an explicit amount that exceeds the available coin balance fails rather than spending other assets. Repaying immediately after a Spot BUY fill can therefore fall short by the base-coin trading fee; use auto_repay_spot_borrows to cover that shortfall by conversion.
  • A REPAY is checked immediately before the request and, inside the hourly blackout window, is not sent: the client publishes a failed result whose message names the retry time. A request admitted just before the window opens can still reach the venue and fail with the venue's error. Borrow and borrow-amount queries are not blocked.
  • A manual repay can race the auto-repay queue on the same coin; the losing side fails with the venue's error and publishes or logs it.

Subscribe with each type's name and unwrap the CustomData in on_data:

from nautilus_trader.adapters.bybit import BybitMarginBorrowResult
from nautilus_trader.adapters.bybit import BybitMarginRepayResult
from nautilus_trader.adapters.bybit import BybitMarginStatusResult
from nautilus_trader.model import CustomData
from nautilus_trader.model import DataType


class MyStrategy(Strategy):
    def on_start(self):
        self.subscribe_data(DataType(BybitMarginBorrowResult.__name__))
        self.subscribe_data(DataType(BybitMarginRepayResult.__name__))
        self.subscribe_data(DataType(BybitMarginStatusResult.__name__))

    def on_data(self, data: CustomData) -> None:
        result = data.data
        if isinstance(result, BybitMarginRepayResult) and not result.success:
            self.log.error(f"Repay failed: {result.message}")

Funding rates

The adapter receives funding rate data from the Linear Ticker WebSocket stream. Bybit provides the fundingIntervalHour field in ticker updates, which the adapter uses to populate the interval field on FundingRateUpdate.

The adapter caches the last known fundingIntervalHour per symbol so that partial ticker updates (which may omit the field) still carry the correct interval.

For historical funding rate requests, the adapter computes the interval from consecutive funding timestamps. The oldest record in a response has no earlier timestamp to pair with, so its interval is unset.

Bybit specific data

Liquidations

The adapter emits BybitLiquidation custom data from Bybit's public all liquidation WebSocket stream (allLiquidation.{symbol}). Bybit publishes this stream for linear and inverse contracts only, so the adapter rejects Spot and Option subscriptions. Bybit pushes updates every 500 ms, and one update can carry several liquidations. The adapter emits one BybitLiquidation for each of them.

FieldTypeDescription
instrument_idInstrumentIdInstrument of the liquidated position.
position_sidePositionSideSide of the liquidated position, LONG for Bybit Buy.
bankruptcy_pricePriceBankruptcy price of the liquidated position.
quantityQuantityExecuted liquidation size.
ts_eventintUNIX timestamp in nanoseconds when Bybit updated the liquidation.
ts_initintUNIX timestamp in nanoseconds when the object was built.

position_side is the side of the liquidated position, not the liquidation order. Bybit reports Buy for a liquidated long position and Sell for a liquidated short position. bankruptcy_price is the price at which the position's margin is exhausted, not the price at which the liquidation executed.

Subscribe from an actor or strategy with DataType(BybitLiquidation.__name__). The instrument_id metadata key is required:

from nautilus_trader.adapters.bybit import BybitLiquidation
from nautilus_trader.model import ClientId
from nautilus_trader.model import CustomData
from nautilus_trader.model import DataType

self.subscribe_data(
    data_type=DataType(
        BybitLiquidation.__name__,
        metadata={"instrument_id": "BTCUSDT-LINEAR.BYBIT"},
    ),
    client_id=ClientId("BYBIT"),
)


def on_data(self, data: CustomData) -> None:
    liquidation = data.data
    if isinstance(liquidation, BybitLiquidation):
        self.log.info(
            f"{liquidation.instrument_id} {liquidation.position_side} liquidated: "
            f"{liquidation.quantity} @ {liquidation.bankruptcy_price}",
        )

Each emitted CustomData carries the DataType the subscription used, so events reach the subscribing actor's on_data. The adapter holds one data type per instrument and rejects a subscription to the same instrument with a different data type until the first is unsubscribed.

BybitLiquidation supports Arrow/Parquet catalog persistence under data/custom/BybitLiquidation/{identifier}. Rust builds need the nautilus-bybit arrow feature flag for this persistence.

The feed contains the liquidation events Bybit publishes. Treat it as a venue-reported signal, not as independently audited, exchange-wide ground truth of every liquidation.

Rate limiting

The adapter queues requests against exact rolling windows before it creates an authentication timestamp or signature. HTTP clients and the trade WebSocket share UID state for the same API key and environment. Data and execution clients also share IP state when they use the same origin and proxy.

ScopeBybit limitAdapter behavior
HTTP IP600 requests per 5 secondsShared by origin and proxy
HTTP and trade WebSocket UIDVaries by endpoint and productShared by API key and environment
Trade WebSocket IP3,000 requests per secondShared by WebSocket origin and proxy
WebSocket connection attempts500 attempts per 5 minutes per domainShared across initial connects and reconnects
Option subscriptions2,000 arguments per connectionRejected before subscription state changes

The UID limiter includes the documented lower-rate account and user routes, 50-request read routes, product-specific order routes, cancel-all limits, and weighted batch operations. HTTP and trade WebSocket responses update the configured UID limit from X-Bapi-Limit, track X-Bapi-Limit-Status, and honor a future X-Bapi-Limit-Reset-Timestamp when the remaining count reaches zero.

The execution client's recv_window_ms applies to signed REST requests and trade WebSocket order commands. A queued WebSocket order gets its timestamp and receive-window header only after all applicable quotas allow the send. A reconnect retry rebuilds the command with a fresh header and uses a connection-bound write, so the transport cannot replay a stale order payload.

Bybit returns retCode 10006 ("Too many visits") when the API rate limit is exceeded. Exceeding the IP ceiling of 600 requests per 5 seconds returns HTTP 403 and bans the IP for at least 10 minutes. A matching 403 discards the affected pooled HTTP session and starts a shared 10-minute cooldown. Other 403 responses do not activate the cooldown.

Coordination is process-local. Another process or host using the same API key or public IP can consume venue quota that this adapter cannot reserve in advance. Response headers reduce this gap for UID limits, but separate processes still require operational coordination.

The following outcomes do not prove whether Bybit accepted the command. The adapter emits no OrderRejected, OrderModifyRejected, or OrderCancelRejected. The order stays in flight until a later order update or reconciliation resolves it:

  • HTTP or WebSocket retCode 10006 ("Too many visits") or 10429 ("System level frequency protection") on submit, modify, or cancel
  • Transport timeouts
  • Service restarts
  • Duplicate request identifiers

For more details on rate limiting, see the official documentation: https://bybit-exchange.github.io/docs/v5/rate-limit.

Account types

The execution client factory determines the account type and OMS type from the configured product types:

  • Spot only: CASH account type with a HEDGING OMS type.
  • Derivatives or mixed products: MARGIN account type (UTA - Unified Trading Account) with a NETTING OMS type.

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 configuration
  • 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 orders
  • Without auto-borrow enabled, you'll need to manually manage borrowing through Bybit's interface

Important: The Nautilus Bybit adapter defaults to is_leverage=False for Spot orders, so they do not 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.

For standard execution messages and REST execution reports, the adapter takes the commission amount and currency directly from the venue's execFee and feeCurrency fields. The fast-execution path described below derives commission instead.

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 orders):

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 orders 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 TypeSettlement CurrencyFee Currency
LINEARUSDT (typically)USDT
INVERSEBase coin (e.g., BTC for BTCUSD)Base coin
OPTIONUSDT or USDCSettle coin

Fast execution commission derivation

With use_ws_execution_fast=True, the adapter subscribes to execution.fast instead of the standard execution channel. The fast channel omits execFee, feeCurrency, feeRate, and execution type. Before connecting the private stream, the adapter requests account maker and taker rates from Bybit's /v5/account/fee-rate endpoint and derives fast-fill commissions from the cached rates:

  • Spot uses base quantity times the fee rate for base-denominated fees and quote notional times the fee rate for quote-denominated fees. Maker rebates use the opposite fee currency and a negative commission amount.
  • Linear and inverse derivatives use instrument notional times the fee rate, denominated in settlement currency. No currency conversion is applied when quote and settlement currencies differ. A charged Linear fee rounds up at the settlement currency precision, as Bybit's execFee does.
  • The adapter rejects use_ws_execution_fast=True with the OPTION product type. The fast payload lacks the underlying/index price and cap inputs required by Bybit's Option fee formula.

If the fee-rate request fails and no previous rates are cached, the connection fails. On a later connect, a failed refresh retains the previous rates.

The adapter never substitutes zero commission. When it cannot derive a commission, because the instrument has no cached rate or the calculation fails, it logs an error and emits no fill from the stream. Only execution reconciliation can then record the fill, and it does not always do so:

  • With open_check_interval_secs set, the open-order check can infer the fill from the order status report while the order is still open in the system. The inferred fill has a generated trade ID and no commission.
  • Without periodic checks, the fill stays unrecorded until the next reconciliation.
  • A fill skipped before the order is canceled, or during shutdown, can stay unrecorded: the order closes or the session ends before a check covers it.

The adapter refreshes these rates each time the execution client connects, not when an individual WebSocket automatically reconnects. Fast fills with an empty orderLinkId are correlated by venue order ID and deferred until the corresponding order update when necessary.

Fast-execution-derived commission is not authoritative from the venue. Cached rates can be stale, and the formula excludes special fee schedules such as RPI, extraFees, product-specific fee caps, and rounding rules not verified against the venue. Use the standard execution channel or REST execution reports when authoritative execFee accounting is required.

The fast channel delivers only ordinary Trade executions. It does not provide other execution types such as ADL or liquidation fills, and it does not trigger auto_repay_spot_borrows. Use the standard channel for these behaviors.

Official documentation

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

Configuration

The product types for each client must be specified in the configurations.

Data client configuration options

OptionDefaultDescription
product_types[LINEAR]Sequence of BybitProductType values to enable.
environmentMAINNETBybit environment enum. Use BybitEnvironment.MAINNET, BybitEnvironment.DEMO, or BybitEnvironment.TESTNET.
api_keyNoneAPI key; loaded from the matching environment variable when omitted.
api_secretNoneAPI secret; loaded from the matching environment variable when omitted.
base_url_httpNoneOverride for the REST base URL.
base_url_ws_publicNoneOverride for the public WebSocket URL.
base_url_ws_privateNoneOverride for the private WebSocket URL.
proxy_urlNoneOptional proxy URL for HTTP and WebSocket transports.
http_timeout_secs60Timeout (seconds) for REST requests.
max_retries3Maximum retry attempts for REST reads.
retry_delay_initial_ms1,000Initial retry delay for REST reads (milliseconds).
retry_delay_max_ms10,000Maximum retry delay for REST reads (milliseconds).
heartbeat_interval_secs20Heartbeat interval (seconds) for WebSocket clients.
recv_window_ms5,000Receive window (milliseconds) for signed REST requests.
update_instruments_interval_mins60Interval (minutes) between instrument catalog refreshes.
instrument_status_poll_secs60Interval (seconds) between instrument and status polls; 0 disables polling.
book_snapshot_timeout_secs10Initial, reconnect, and recovery snapshot wait; 0 disables it.
transport_backendSockudoWebSocket transport backend.
bars_timestamp_on_closeTrueTimestamp bars on the interval close; False timestamps them on the interval open.

Execution client configuration options

OptionDefaultDescription
product_types[LINEAR]Sequence of BybitProductType values to enable.
environmentMAINNETBybit environment enum. Use BybitEnvironment.MAINNET, BybitEnvironment.DEMO, or BybitEnvironment.TESTNET.
api_keyNoneAPI key; loaded from the matching environment variable when omitted.
api_secretNoneAPI secret; loaded from the matching environment variable when omitted.
base_url_httpNoneOverride for the REST base URL.
base_url_ws_privateNoneOverride for the private WebSocket base URL.
base_url_ws_tradeNoneOverride for the trade WebSocket base URL.
proxy_urlNoneOptional proxy URL for HTTP and WebSocket transports.
http_timeout_secs60REST request timeout and total cancel-all confirmation deadline (seconds).
max_retries3Maximum retry attempts for REST reads.
retry_delay_initial_ms1,000Initial REST read retry delay and cancel-all polling interval (milliseconds).
retry_delay_max_ms10,000Maximum REST read retry delay (milliseconds).
heartbeat_interval_secs20Heartbeat interval (seconds) for WebSocket clients.
auth_timeout_secsNoneOptional WebSocket authentication timeout (seconds).
recv_window_ms5,000Receive window (milliseconds) for signed REST and trade WebSocket requests.
account_idNoneOptional account ID associated with this client.
use_spot_position_reportsFalseReport Spot wallet balances as positions for scoped requests; bulk reports omit Spot (no pair attribution).
auto_repay_spot_borrowsFalseAutomatically repay tracked Spot margin borrows after BUY orders fully fill on the standard execution channel.
use_ws_execution_fastFalseUse execution.fast instead of execution; derives non-authoritative commissions. Rejected in demo mode and with OPTION.
margin_modeNoneUnified margin mode setting for the account.
smp_typeNoneSelf-match prevention sent on every order. See SMP.
transport_backendSockudoWebSocket transport backend.
load_idsNoneInstrument IDs included in reconciliation. See Reconciliation.

The compiled default is Sockudo when the transport-sockudo Cargo feature is enabled and Tungstenite otherwise.

Use BybitDataClientConfig with BybitDataClientFactory and BybitExecutionClientConfig with BybitExecutionClientFactory. The current Python examples show the complete LiveNode.builder(...) configuration for data and execution clients.

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 configuration objects, or set the following environment 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 environment variables to manage your credentials.

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

Contributing

For additional features or to contribute to the Bybit adapter, please see our contributing guide.

On this page