How can I get historical contract data from the Kraken API?

Fetch Kraken Futures historical OHLC data via `futures-api.kraken.com/api/history/candles` using symbol, interval, and Unix timestamps; authenticate with API key and HMAC-SHA256 signature if rate-limited.

Aug 08, 2025 at 02:49 pm

Understanding Kraken API and Historical Contract Data

The Kraken API is a powerful interface that enables developers and traders to interact with Kraken’s cryptocurrency exchange services programmatically. When referring to historical contract data, it's important to clarify that Kraken primarily supports spot trading and futures contracts through its Kraken Futures platform (formerly known as Cryptowatch Derivatives). The standard Kraken REST API (api.kraken.com) does not provide historical data for futures or perpetual contracts directly. Instead, historical contract data is accessible via the Kraken Futures API, hosted at futures-api.kraken.com.

To retrieve historical data, you must identify the correct endpoint based on the type of contract and time frame needed. The Kraken Futures API offers endpoints such as /api/history/candles to fetch OHLC (Open, High, Low, Close) data for specific futures contracts. Each endpoint requires parameters like symbol, interval, and from/until timestamps to define the data range.

Setting Up API Access Credentials

Before making any requests, you must set up authenticated access to the Kraken Futures API. This involves creating an API key and secret:

• Log in to your Kraken account and navigate to the Funding section.
• Select API and choose Kraken Futures.
• Click Create API Key.
• Assign permissions—ensure Read access is enabled for market data.
• Generate the key and securely store both the API key and secret key.

These credentials are required to sign requests using HMAC-SHA256. Unlike spot trading, Kraken Futures uses a separate authentication mechanism. Every request must include headers such as APIKey and Authent, where Authent is the computed signature based on the request method, path, body, and timestamp.

Constructing the API Request for Historical Data

To retrieve historical contract data, use the candles history endpoint:

GET https://futures-api.kraken.com/api/history/candles

Required query parameters include:

• symbol: The contract symbol, such as PI_XBTUSD for the Bitcoin perpetual inverse contract.
• interval: The candlestick interval. Valid values include 1m, 5m, 15m, 1h, 4h, 1d.
• from: Start time in Unix timestamp (seconds).
• until: End time in Unix timestamp (seconds).

For example, to fetch 1-hour candles for the Bitcoin perpetual contract from January 1, 2024, to January 2, 2024:

https://futures-api.kraken.com/api/history/candles?symbol=PI_XBTUSD&interval=1h&from=1704067200&until=1704153600

This request does not require authentication if only public market data is accessed. However, if rate-limited, consider using authenticated requests.

Handling Authentication for Rate-Limited Requests

If you exceed the unauthenticated request limit, switch to signed requests. The process involves:

• Creating a request payload with method, path, body, and ISO 8601 timestamp.
• Concatenating the timestamp, method, path, and body (if present) into a signing string.
• Using HMAC-SHA256 with your secret key to generate a signature.
• Including the signature in the Authent header and your key in APIKey.

Example steps in Python:

• Set the request method: GET
• Define the path: /api/history/candles?symbol=PI_XBTUSD&interval=1h&from=1704067200&until=1704153600
• Generate the ISO timestamp: 2024-01-01T00:00:00Z
• Build the signing message: 2024-01-01T00:00:00ZGET/api/history/candles?symbol=PI_XBTUSD&interval=1h&from=1704067200&until=1704153600
• Compute HMAC-SHA256 of the message using your secret key
• Encode the result in base64
• Set headers:
  • APIKey: YOUR_PUBLIC_KEY
  • Authent: BASE64_SIGNATURE
  • Nonce: 2024-01-01T00:00:00Z

Send the request using a library like requests.

Processing and Storing the Response Data

The API returns a JSON response containing an array of candle objects. Each candle includes:

• timestamp: Unix time of the candle start.
• open: Opening price.
• high: Highest price.
• low: Lowest price.
• close: Closing price.
• volume: Traded volume.

Example response:

{
  "result": "success",
  "candles": [
{
  "timestamp": 1704067200,
  "open": "42000.00",
  "high": "42500.00",
  "low": "41800.00",
  "close": "42300.00",
  "volume": "120.5"
}
]
}

Parse the JSON and extract the candles array. You can store this data in CSV, a database, or a DataFrame for analysis. Ensure timestamps are converted to local time or UTC as needed. Handle pagination if the time range is large—Kraken may limit results per request, requiring multiple calls with adjusted from and until values.

Common Errors and Troubleshooting

• Invalid symbol: Double-check the contract symbol. Use GET /api/instruments to list all available contracts.
• Rate limiting: Unauthenticated requests are limited. Use authentication or add delays between calls.
• Invalid timestamp format: Ensure Unix timestamps are in seconds, not milliseconds.
• Signature mismatch: Verify the signing string includes the exact path and query parameters, and that the secret key is correct.
• Empty response: Confirm the time range includes active trading periods.

Use tools like Postman or Python scripts to test requests incrementally. Enable logging to capture request headers and responses for debugging.

Frequently Asked Questions

How do I find the correct symbol for a Kraken Futures contract?

Use the instruments endpoint: GET https://futures-api.kraken.com/api/instruments. This returns all active contracts with their symbols, such as PI_XBTUSD for Bitcoin perpetuals or FI_ETHUSD for Ether futures.

Can I retrieve tick-level historical data instead of candles?

The Kraken Futures API does not provide tick-level data through public endpoints. The /api/history/candles endpoint only supports aggregated OHLC data at specified intervals. For granular data, consider WebSocket feeds or third-party data providers.

Is there a limit on how much historical data I can fetch at once?

Yes, the API may limit the number of candles returned per request. If your time range is large, split it into smaller intervals—such as one day at a time—and make multiple requests. Check the response for completeness and adjust the from and until parameters accordingly.

Do I need to be a verified Kraken user to access historical contract data?

For unauthenticated public data requests, basic account access suffices. However, to increase rate limits and ensure stable access, a verified account with API credentials is recommended. Full trading permissions are not required for data retrieval.