Bybit

tradectl trades Bybit Linear perpetuals (USDT/USDC-settled) and Inverse perpetuals (coin-margined) via the Bybit V5 API.

Bybit's TradFi Perpetuals — the stock and commodity USDT perps (AAPLUSDT, NVDAUSDT, SPYUSDT, XAUUSDT, CLUSDT, …) — are ordinary linear symbols and need no special configuration. Bybit CFD is a separate MT5 platform with no Bybit API and is not supported.

Requirements

• A Unified Trading Account (UTA). Classic accounts use a different wallet and position model; the bot refuses to start on one rather than trade against a shape it does not model. Upgrade in Bybit's UI, or use a UTA subaccount.

Supported

• Real-time top-of-book and public trade WebSocket streams
• Kline streams and historical kline fetch
• Market and limit orders
• TP (limit) and SL (stop-market) exits, as standalone conditional orders
• Per-symbol leverage configuration
• Hedge mode (positionIdx) as well as one-way
• Per-fill commission and per-symbol fee rates in realized PnL
• User-data WebSocket for order updates, executions and wallet

Not supported yet

	Why
Spot	Deferred. Spot conditional orders and the min-notional-dust rule differ enough from futures to need their own phase.
L2 depth subscriptions	Bybit publishes orderbook.{50,200}; the bot subscribes only to orderbook.1 (top of book) today. get_depth returns None rather than an empty book, so a caller can tell the difference.
Per-symbol margin mode	Under UTA, margin mode is an account-level setting with different semantics from the per-symbol isolated/cross this config field describes. Setting it returns an error rather than silently doing nothing — configure it in Bybit's UI for the whole account.
WebSocket order entry	Order entry is REST. One order path is easier to keep correct; latency work comes later.

API key setup

1. Log in to Bybit
2. API → Create New Key → System-generated API Keys
3. Permissions: Contract – Trade
4. IP restriction — strongly recommended
5. Do not enable withdrawals

Configuration

{
  "api": { "provider": "Bybit", "key": "...", "secret": "..." },
  "strats": [{
    "name": "btc-linear",
    "type": "shot",
    "marketType": "LINEAR",
    "isEmulator": false,
    "pairs": ["BTCUSDT", "ETHUSDT"],
    "leverage": 10
  }]
}

marketType: LINEAR or INVERSE.

Hedge mode

api.hedgeMode is true, false, or omitted. Omitted means adopt whatever the account is already in — the bot detects the mode and never switches it behind your back. Set explicitly, it switches at startup and re-reads to verify; Bybit refuses the switch while any position or order is open, and the error says so.

Environments

api.env selects which Bybit to talk to:

Value	Market data	Fills
live (default)	real	real
demo	real	simulated
testnet	testnet	testnet

Prefer demo over testnet for rehearsal: testnet's order books are effectively empty, so a strategy tested there has been tested against nothing.

{ "api": { "provider": "Bybit", "env": "demo", "key": "...", "secret": "..." } }

Watchdog

The watchdog guards Bybit accounts. Use bybit-linear or bybit-inverse as the account's market.

Rate limits

Bybit's limits are per-UID, per-endpoint-group, and every response reports that group's remaining budget. The bot reads those headers and gates entries before the budget runs out; exits are never refused. A separate per-IP edge limit (~600 requests / 5 s) surfaces as HTTP 403 and pauses until it clears.