Bybit API tutorial: How to connect and start automated trading?

Understanding Bybit API Authentication

1. Bybit requires API keys generated from the user’s account dashboard under the API Management section. These keys consist of an API Key and a Secret Key, both essential for signing requests.

2. The Secret Key must never be exposed in client-side code or public repositories. It is used to generate HMAC-SHA256 signatures for each request to verify identity and prevent tampering.

3. Users must assign precise permissions during key creation—such as “Order”, “Wallet”, or “Contract” access—and restrict IP addresses if operating in production environments.

4. Time synchronization is mandatory. Requests rejected with error code 10004 indicate timestamp mismatch; systems must maintain clock drift under 30 seconds relative to Bybit’s server time.

5. All endpoints require the X-BAPI-API-KEY header containing the public key and X-BAPI-SIGN header holding the base64-encoded signature derived from concatenated parameters and secret.

Setting Up REST API Integration

1. Developers commonly use Python with the requests library to construct authenticated GET/POST calls. A typical example includes fetching wallet balance via the /v5/account/wallet-balance endpoint.

2. Query parameters must be sorted alphabetically before hashing when building the signature string. Nonce values must increase monotonically across successive requests to avoid replay attacks.

3. Rate limits vary per endpoint: public endpoints allow up to 60 requests per minute while private ones are capped at 120 per minute unless upgraded through Bybit’s institutional tier.

4. Error handling must parse JSON responses for status codes like 10001 (invalid API key), 10002 (invalid signature), or 110001 (insufficient margin) to trigger appropriate fallback logic.

5. Session reuse improves performance—persistent connections via urllib3’s PoolManager reduce TCP handshake overhead during high-frequency order submissions.

WebSocket Real-Time Data Streaming

1. Bybit supports WebSocket v5 for real-time market data, trade execution updates, and position changes. Connections initiate with a single authentication frame using the same API Key and signature method as REST.

2. Subscribing to topics like orderbook.1.BTCUSDT or trade.BTCUSDT requires sending a JSON payload with op: 'subscribe' and args: ['topic.name'].

3. Heartbeat pings must be sent every 20 seconds to maintain connection stability. Failure to respond within timeout window triggers forced disconnection and reconnection sequence.

4. Message compression is disabled by default but can be enabled via permessage-deflate extension negotiation during WebSocket handshake for bandwidth-sensitive deployments.

5. Order book snapshots arrive as full depth snapshots first, followed by delta updates. Clients must apply these deltas correctly to avoid state desynchronization and mispricing.

Building a Basic Automated Trading Bot

1. A minimal working bot begins with initializing credentials, establishing WebSocket connection for price feed, and setting up REST session for order placement.

2. Strategy logic—such as detecting moving average crossovers—runs on tick-level OHLCV data reconstructed from WebSocket trade streams or fetched via REST /v5/market/kline.

3. Order execution uses POST /v5/order/create with strict validation on side (Buy/Sell), orderType (Market/Limit), and qty fields. Invalid quantity formats return error 30089.

4. Risk controls include checking available margin before submission, verifying open order count limits, and enforcing maximum position size based on equity percentage.

5. Logging must capture raw request/response payloads, timestamps, and execution latency metrics to aid debugging latency spikes or unexpected fills.

Frequently Asked Questions

Q: Can I use the same API key for both testnet and mainnet?A: No. Testnet and mainnet require separate API key generation. Keys created on one environment do not function on the other.

Q: What happens if my bot sends duplicate order IDs?A: Bybit rejects duplicate clOrdID values within a 24-hour window with error code 110012, preventing accidental double-submission.

Q: Is there a way to retrieve historical trade history older than 7 days?A: REST /v5/execution/list only returns records from the past week. For extended archives, users must enable trade logging on their own infrastructure during live operation.

Q: Do spot and derivatives APIs share the same authentication flow?A: Yes. Both use identical HMAC-SHA256 signing logic and header structure, though endpoint paths and required parameters differ significantly between product types.