How to access historical trading data for Bybit contracts?

Understanding Historical Trading Data on Bybit

Historical trading data for Bybit contracts refers to past records of executed trades, including information such as price, quantity, timestamp, side (buy/sell), and contract type. This data is essential for traders who engage in technical analysis, backtesting strategies, or auditing their trading performance. Bybit provides access to this data through multiple methods, including its official API and web interface. The data typically covers perpetual contracts and futures contracts across various cryptocurrencies like BTCUSD, ETHUSD, and others.

It is important to distinguish between public trade history and personal trade history. Public data reflects all trades executed on the order book and is available to any user. Personal trade history includes only the trades executed by your account and requires authentication to access. Both types of data are structured in JSON format when retrieved via API, making them suitable for integration into analytical tools.

Accessing Public Trade History via Bybit API

To retrieve public historical trade data for Bybit contracts, use the official Bybit REST API endpoint:

• API Endpoint: https://api.bybit.com/v5/market/recent-trade

This endpoint returns the most recent trades for a specified symbol. To access deeper historical records, you must paginate using the cursor parameter returned in each response. Here’s how to make the request:

• Use an HTTP GET request with required parameters:
  • category: Set to linear for USDT contracts or inverse for inverse contracts
  • symbol: Specify the contract, e.g., BTCUSDT
  • limit: Number of records per request (maximum 1000)
  • cursor: Use the cursor from the previous response to fetch the next batch

Example request in Python:

import requests





url = 'https://api.bybit.com/v5/market/recent-trade'params = {





'category': 'linear',
'symbol': 'BTCUSDT',
'limit': 100
}
 
response = requests.get(url, params=params)data = response.json()

The returned JSON includes fields like price, size, side, time, and symbol. To retrieve older data, extract the cursor from the next_page_cursor field and include it in the next request.

Retrieving Personal Trade History Using API Authentication

To access your personal contract trade history, authentication is required. You must generate an API key with 'Order' and 'Read' permissions from your Bybit account settings. The relevant endpoint is:

• API Endpoint: https://api.bybit.com/v5/order/execution-list

This endpoint returns filled contract orders associated with your account. Required parameters include:

• category: linear or inverse
• symbol: e.g., BTCUSDT
• start_time and end_time: Unix timestamps to define the time range
• limit: Max 50 records per request
• api_key, timestamp, and sign: Authentication headers

Steps to generate the request:

• Generate a timestamp in milliseconds
• Create a signature using HMAC SHA256 with your API secret
• Include headers: X-BAPI-API-KEY, X-BAPI-TIMESTAMP, X-BAPI-SIGN

Example Python code for signing:

import hmacimport time





api_key = 'your_api_key'api_secret = 'your_api_secret'timestamp = str(int(time.time() * 1000))





param_str = f'category=linear&symbol=BTCUSDT&limit=50&start_time=1700000000000&end_time=1701000000000'signature = hmac.new(api_secret.encode(), param_str.encode(), digestmod='sha256').hexdigest()





headers = {





'X-BAPI-API-KEY': api_key,
'X-BAPI-TIMESTAMP': timestamp,
'X-BAPI-SIGN': signature
}
 
response = requests.get(url, params=params, headers=headers)

Each record includes exec_price, exec_qty, side, fee, and order_id.

Using Bybit Web Interface for Trade History

For users who prefer not to use APIs, Bybit offers a web-based interface to view personal contract trade history. Log in to your Bybit account and navigate to:

• Derivatives → Order → Trade History

Here, you can:

• Select Linear Contracts or Inverse Contracts
• Choose a specific symbol from the dropdown
• Filter by date range
• Export up to 100 records at a time in CSV format

The displayed columns include Symbol, Side, Quantity, Price, Fee, Closed PnL, and Time. Note that the web interface does not allow bulk export of all historical data in one click. You must manually paginate through dates and download multiple CSV files if needed.

Processing and Storing Historical Data

Once retrieved, historical trade data should be stored for analysis. Recommended formats include CSV, Parquet, or database tables. For continuous data collection, set up a cron job or script that periodically calls the API and appends new records.

Key considerations:

• Rate limits: Bybit allows 60 requests per minute for public endpoints and 120 for private
• Data deduplication: Use exec_id or trade_time as unique identifiers
• Timezone handling: All timestamps are in UTC
• Data retention: Bybit retains personal trade history for up to 6 months on the web interface, but API access may allow retrieval of older data depending on account activity

Store data in structured directories:

/trade_data/  /public/





btcusdt_20231201.csv
/private/
 
my_trades_20231201.csv
Use pandas in Python to merge and analyze:
 
import pandas as pd
df = pd.read_csv('btcusdt_20231201.csv')df['time'] = pd.to_datetime(df['time'], unit='ms')

Frequently Asked Questions

How far back does Bybit’s contract trade history go?Bybit’s public API typically retains recent trade data for up to 7 days in the recent-trade endpoint. For older public data, third-party aggregators or custom data collection scripts are needed. Personal trade history via the private API can go back several months, depending on account creation date and Bybit’s internal retention policy.

Can I get tick-level historical data for backtesting?Yes, the /v5/market/recent-trade endpoint provides tick-level data including price and volume per trade. To build a complete tick history, you must continuously poll the API or use WebSocket streams (publicTrade topic) to capture real-time trades and store them.

Why am I getting an “Invalid signature” error when accessing private data?This error occurs when the HMAC signature does not match. Ensure the parameter string is correctly sorted alphabetically, the timestamp is in milliseconds, and the API secret is correctly entered. Also verify that the HTTP method (GET/POST) matches the expected format for the endpoint.

Is historical data available for expired futures contracts?Yes, historical trade data for expired futures contracts can be accessed via the API by specifying the correct symbol name used during the contract’s active period. For example, BTCUSD231229 for the December 2023 BTC inverse futures. The same API endpoints apply, with category=inverse and the appropriate symbol.