How to Fetch Historical Mark Price Candles on OKX Using CCXT in Python

Overview

When working with cryptocurrency market data, accessing accurate historical price information is essential for traders and analysts. This guide explains how to retrieve historical mark price candles from OKX using Python and the CCXT library.

Understanding Mark Price vs. History Mark Price

Before diving into the implementation, it's important to understand the distinction between:

• Mark Price Candles: Current mark price data
• History Mark Price Candles: Historical mark price data

The OKX API provides separate endpoints for these two types of data, which leads to different implementation approaches.

Current Implementation Using CCXT

The standard CCXT method fetch_mark_ohlcv() accesses the mark-price-candles endpoint:

import ccxt.pro
import time

exchange = ccxt.pro.okx()
since = int(time.time() - 300000) * 1000
await exchange.fetch_mark_ohlcv('ETH/USDT', '1m', since=since, limit=100)

👉 Learn more about CCXT integration with OKX

Accessing Historical Data

To retrieve historical mark price candles, you have two options:

Option 1: Using CCXT's Public API Methods

exchange = ccxt.okx()
response = exchange.public_get_market_history_mark_price_candles({
    'instId': 'ETH-USDT',
    'bar': '1m',
    'limit': 100,
    'before': '1670157530999',
    'after': '1670163530999'
})

Option 2: Direct API Request

You can make a direct request to OKX's API endpoint:

GET https://www.okx.com/join/BLOCKSTARapi/v5/market/history-mark-price-candles

With parameters:

• instId: Instrument ID (e.g., ETH-USDT)
• bar: Timeframe (e.g., 1m, 5m, 1H)
• limit: Number of candles to retrieve
• before/after: Timestamp range

Best Practices for Historical Data Retrieval

1. Timeframe Selection: Choose appropriate candle intervals based on your analysis needs
2. Rate Limiting: Be mindful of API rate limits when making frequent requests
3. Error Handling: Implement proper error handling for API responses
4. Data Storage: Consider caching historical data to reduce API calls

👉 OKX API documentation for historical data

FAQ Section

What's the difference between mark price and index price?

Mark price is used for liquidation purposes and incorporates both index price and a premium/discount factor.

How far back can I retrieve historical mark price data?

OKX typically provides historical data for several months, though exact availability may vary by instrument.

Can I get historical mark price data for all trading pairs?

Most major trading pairs support historical mark price data, but check the API documentation for specific availability.

What timeframes are available for historical mark price candles?

Common timeframes include 1m, 5m, 15m, 1H, 4H, 1D, and 1W.

How do I handle pagination when retrieving large amounts of historical data?

Use the 'before' and 'after' parameters to specify time ranges and implement a pagination logic in your code.

Is there a rate limit for historical mark price data requests?

Yes, OKX implements rate limits on all API endpoints. Check their documentation for current limits.

Conclusion

While CCXT's standard fetch_mark_ohlcv() method provides current mark price data, accessing historical mark price candles requires using either CCXT's public API methods or making direct requests to OKX's specialized endpoint.

For developers building trading systems or analytical tools, understanding these distinctions and implementation methods is crucial for accurate historical data retrieval.