How to use the Bybit API for contract trading?

Bybit API enables automated contract trading with secure authentication, real-time data via WebSocket, and full order management for USDT and inverse contracts.

Aug 11, 2025 at 01:01 pm

Understanding the Bybit API for Contract Trading

The Bybit API is a powerful tool that allows traders to automate their contract trading strategies on the Bybit exchange. By leveraging the API, users can programmatically place orders, manage positions, retrieve market data, and monitor account status. To begin, it's essential to understand that Bybit supports RESTful API and WebSocket API for real-time interaction. The API endpoints for contract trading are specifically tailored for USDT Perpetual, Inverse Perpetual, and Futures contracts. Before any integration, ensure you are accessing the correct API documentation based on the contract type you intend to trade.

To get started, navigate to your Bybit account settings and generate API keys. During this process, you must define permissions such as "Order," "Asset," and "Read-Only." For contract trading, both "Order" and "Position" permissions are required. Never expose your secret key in client-side code or public repositories. Always use HTTPS when making API calls to ensure secure communication.

Setting Up Your API Credentials

To use the Bybit API effectively, you must first create and configure your API keys. Log in to your Bybit account and go to the API Management section under your profile. Click on Create API, then assign a name to your key for easy identification. When setting permissions:

• Enable Trade permission to allow order placement and cancellation
• Enable Position permission to access open positions and leverage settings
• Restrict Withdrawal unless absolutely necessary to reduce security risks

After creation, you will receive three critical components: API Key, Secret Key, and User ID. Store these securely. You can also set IP restrictions to limit API access to specific IP addresses, enhancing security. If your IP changes, you must update the whitelist accordingly. Note that Bybit uses HMAC-SHA256 for authentication, so your requests must include a properly signed message.

Authenticating API Requests

Every private API request to Bybit must be authenticated using your API Key and Secret Key. The authentication process involves generating a signature using HMAC-SHA256 hashing. The string to be signed typically includes the HTTP method, request path, query parameters, and timestamp. The timestamp must be within 5 seconds of the server time to prevent replay attacks.

Here’s how to construct the signature:

• Concatenate the request method (e.g., POST), the request path (e.g., /v5/order/create), and the query string (if any)
• Use your Secret Key to hash the concatenated string using HMAC-SHA256
• Encode the result in hexadecimal format
• Include the signature in the request header as X-BAPI-SIGN

Additional headers required include X-BAPI-API-KEY, X-BAPI-TIMESTAMP, and X-BAPI-RECV-WINDOW (optional, default 5000ms). Incorrect timestamp or signature will result in authentication failure. Always verify your system clock is synchronized with NTP servers.

Placing and Managing Contract Orders

To place a contract order via the Bybit API, use the /v5/order/create endpoint. You must include essential parameters such as symbol, side (Buy or Sell), orderType (Limit, Market, etc.), qty, and price (for limit orders). For USDT-margined contracts, the symbol format is BTCUSDT. For inverse contracts, it’s BTCUSD.

Key parameters to consider:

• timeInForce: Options include GoodTillCancel, ImmediateOrCancel, FillOrKill
• reduceOnly: Set to true to ensure the order reduces position size only
• closeOnTrigger: Useful for stop-loss or take-profit orders
• positionIdx: Required for hedge mode; 0 for one-way, 1 for long, 2 for short

To cancel an order, use the /v5/order/cancel endpoint with the orderId or orderLinkId. To retrieve active orders, use /v5/order/realtime. For position management, the /v5/position/list endpoint returns current positions, including size, entry price, and leverage. Adjust leverage using /v5/position/set-leverage.

Retrieving Market and Account Data

Real-time market data is crucial for informed trading decisions. Bybit provides several public endpoints for this purpose. Use /v5/market/tickers to get the latest prices, funding rates, and 24-hour volume for all contracts. For order book data, use /v5/market/orderbook with the symbol and depth parameters (e.g., 1, 5, 50 levels). To fetch historical candlestick data, use /v5/market/kline with category, symbol, interval, and start/end time.

For account-related data, the /v5/account/wallet-balance endpoint returns your wallet balance across all coins. Use /v5/account/info to get overall account details, including total equity and available balance. To monitor recent order fills, use /v5/order/execution-list. This returns executed trades with price, qty, fee, and execTime.

Implementing WebSocket for Real-Time Updates

For low-latency trading, use Bybit’s WebSocket API instead of polling REST endpoints. Connect to wss://stream.bybit.com/v5/public/linear for USDT contracts or wss://stream.bybit.com/v5/public/inverse for inverse contracts. To subscribe to real-time data, send a JSON message with the op field set to "subscribe" and the args array containing topics like orderBookL2_25.BTCUSDT, tickers.BTCUSDT, or candle.1.BTCUSDT.

For private data such as order updates and position changes, authenticate the WebSocket connection. Send an authentication request with your API Key, timestamp, and signature. Once authenticated, subscribe to order, position, and execution topics to receive live updates. WebSocket messages are compressed using zlib, so decompress them before parsing.

Frequently Asked Questions

What is the rate limit for Bybit API?

Bybit enforces rate limits to prevent abuse. For REST API, the limit is typically 60 requests per second per API key. Exceeding this results in HTTP 429 errors. WebSocket connections allow higher throughput but are also subject to limits based on subscription count and message frequency.

How do I handle API errors like “Invalid signature”?

Ensure your Secret Key is correct and not trimmed. Verify that the signature string includes the exact method, path, and parameters. Check that the timestamp is in milliseconds and within 5 seconds of Bybit’s server time. Use https://api.bybit.com/v5/market/time to fetch the current server time.

Can I use the Bybit API for grid trading or DCA bots?

Yes, the API supports automated strategies. Use /v5/order/create in a loop with varying prices and quantities. Implement logic to cancel stale orders and adjust positions based on market conditions. Ensure your bot handles funding rate payments and liquidation risks.

Is testnet available for API contract trading?

Yes, Bybit offers a testnet environment at https://api-testnet.bybit.com. Use it to simulate trades without risking real funds. Generate separate API keys for testnet. All endpoints mirror the live environment, allowing full strategy testing.