How to use the Bybit API?

Understanding the Bybit API and Its Use Cases

The Bybit API is a powerful interface that allows traders and developers to interact with Bybit’s trading platform programmatically. It enables automation of trading strategies, real-time market data retrieval, order placement, position management, and account balance monitoring. The API supports both RESTful and WebSocket protocols, offering flexibility for different use cases. REST APIs are ideal for one-time requests such as placing an order or checking balance, while WebSocket is best suited for continuous data streaming like live price updates or order book changes. Before using the API, users must generate API keys from their Bybit account, which serve as authentication credentials.

Generating Your Bybit API Key

To begin using the Bybit API, you must first create an API key. This process is done directly within your Bybit account dashboard. Navigate to the API Management section under your profile settings. Click on Create API, where you will be prompted to enter a name for your API key and set up IP restrictions. IP whitelisting enhances security by limiting API access to specified IP addresses. After entering the required details, Bybit will generate a pair of credentials: an API Key and a Secret Key. These must be stored securely, as the Secret Key will not be shown again after the initial creation. Never share these keys or expose them in client-side code.

Configuring API Authentication for Requests

All private endpoints in the Bybit API require authentication using the API Key and Secret Key. Authentication is implemented via HMAC SHA256 signatures. Each request must include specific headers:

• X-BAPI-API-KEY: Your API key
• X-BAPI-SIGN: The generated signature
• X-BAPI-TIMESTAMP: The current timestamp in milliseconds
• X-BAPI-RECV-WINDOW: Optional, defines the time window for request validity (default is 5000ms)

To generate the X-BAPI-SIGN, concatenate the request parameters in a specific order (timestamp + api_key + recv_window + query_string) and hash them using HMAC SHA256 with your Secret Key. Most programming languages provide built-in libraries for this. For example, in Python, use the hmac and hashlib modules. Ensure timestamps are synchronized with Bybit’s server time to avoid signature errors.

Placing Orders Using the REST API

To place a trade via the Bybit API, send a POST request to the appropriate endpoint, such as /v5/order/create. Required parameters include:

• symbol: The trading pair, e.g., BTCUSDT
• side: Either Buy or Sell
• orderType: Such as Limit, Market, or Stop
• qty: The quantity to trade
• price: Required for limit orders
• timeInForce: Specifies execution instructions, e.g., GTC (Good Till Cancel)

Before sending the request, ensure all parameters are correctly formatted and included in the signature calculation. A successful response will return a JSON object containing the orderId, orderLinkId, and status. Always validate the response code and message to confirm execution. Use the orderLinkId to track your order in subsequent queries.

Streaming Real-Time Data with WebSocket

For applications requiring live updates—such as algorithmic trading bots or market monitoring dashboards—Bybit’s WebSocket API is essential. Connect to the WebSocket endpoint: wss://stream.bybit.com/v5/public/linear for USDT perpetual contracts. After establishing the connection, subscribe to topics using the subscribe message format. Examples include:

• orderBookL2_25.BTCUSDT: Top 25 order book levels
• tickers.BTCUSDT: Real-time ticker data
• candle.1.BTCUSDT: 1-minute candlestick data
• publicTrade.BTCUSDT: Recent trades

Each message received will contain a topic field and a data payload. Parse the JSON response accordingly. For private data like positions or balance updates, establish a separate WebSocket connection to the private endpoint and include authentication headers similar to REST.

Managing Positions and Risk via API

The Bybit API allows full control over open positions. To retrieve current positions, send a GET request to /v5/position/list. The response includes size, entryPrice, unrealizedPnL, and leverage. To modify a position, such as adjusting stop-loss or take-profit levels, use the /v5/position/trading-stop endpoint. Required parameters:

• symbol
• stopLoss: Stop-loss price
• takeProfit: Take-profit price

Ensure these values are within allowable price ranges and account leverage settings. For closing a position, place an opposing market order with the same quantity. For example, if you hold a Buy position of 1 BTC, send a Sell market order for 1 BTC. Confirm closure by checking the updated position size in the next position query.

Frequently Asked Questions

How do I reset my Bybit API secret key?Bybit does not allow resetting the secret key directly. You must delete the existing API key and create a new one. Navigate to API Management, locate the key, click Delete, confirm the action, then generate a new key pair. Update your application with the new credentials immediately.

Can I use the Bybit API without IP restrictions?Yes, but it is highly discouraged. Leaving IP restrictions disabled exposes your API key to potential misuse. If you must disable it, ensure your application uses additional security layers such as encrypted storage and minimal permission scopes.

What rate limits apply to the Bybit API?Bybit enforces rate limits to prevent abuse. The REST API allows up to 60 requests per second per IP. WebSocket connections support up to 24 subscriptions per connection. Exceeding limits results in a 429 error. Distribute requests across multiple IPs or use batching where possible.

Why am I getting a “Invalid signature” error?This typically occurs due to incorrect parameter ordering, timestamp mismatch, or wrong hashing method. Verify that the timestamp matches the X-BAPI-TIMESTAMP header, parameters are sorted lexicographically, and HMAC SHA256 is used with the correct Secret Key. Test with a simple endpoint like /v5/user/query-api to isolate the issue.