Kraken futures API tutorial

Understanding Kraken Futures and the API Ecosystem

The Kraken futures API is a powerful tool designed for traders and developers seeking automated access to Kraken’s derivatives market. Unlike spot trading, futures allow users to speculate on price movements of cryptocurrencies using leverage. The Kraken Futures API provides endpoints for placing orders, retrieving market data, managing positions, and monitoring account status programmatically. This API operates over HTTPS and WebSocket protocols, enabling both REST-based requests and real-time streaming of data.

To interact with the API, you must first understand its two primary environments: the production environment at futures.kraken.com and the sandbox testing environment at demo-futures.kraken.com. The sandbox allows developers to test strategies without risking real funds. All endpoints require authentication using an API key and secret, which are generated through your Kraken Futures account dashboard.

Each request to the private endpoints must include three headers:

• APIKey: Your public API key
• Authentification: A SHA256 HMAC signature generated from your secret key
• Nonce: A unique, incrementing number or timestamp

These security measures ensure that only authorized users can perform actions such as placing orders or withdrawing funds.

Setting Up Your Kraken Futures API Credentials

Before making any API calls, you must generate valid credentials within your Kraken Futures account. Navigate to the API management section in your Kraken Futures dashboard. Ensure you're logged into the correct environment—either live or demo—based on your development needs.

• Click on 'Generate New Key'
• Assign a descriptive name to your API key for easier identification
• Select the appropriate permissions: Order placement, Reading balance, and Viewing positions
• Enable IP whitelisting if required for additional security
• Confirm the generation process

Upon completion, you will receive two critical components: the API key (a long alphanumeric string) and the private secret. Store these securely. The secret will not be shown again after closing the dialog. Losing it means you’ll need to revoke and regenerate the key.

For testing purposes, use the sandbox environment to avoid unintended trades on live markets. When switching between environments, update your base URL accordingly:

• Sandbox: https://demo-futures.kraken.com
• Live: https://futures.kraken.com

Authentication Mechanism for Private Endpoints

Accessing private endpoints like /orders, /positions, or /account requires proper authentication. The core of this process lies in generating a valid HMAC-SHA256 signature. This signature is derived from your private secret and includes the request path, nonce, and body (if applicable).

Here's how to construct the authentication header step-by-step:

• Concatenate the current Unix timestamp (as nonce), the request path (e.g., /api/v3/leads/status), and the request body (if POST/PUT) into a single string
• Use your private secret to compute the HMAC-SHA256 hash of this concatenated string
• Encode the resulting hash in Base64 format
• Include this encoded value in the Authentification header

Python example:

import hmacimport hashlibimport time





nonce = str(int(time.time() * 1000))path = '/api/v3/orders'body = '{'orderType':'lmt','symbol':'pi_xbtusd','side':'buy','size':1000,'limitPrice':30000}'





message = nonce + path + bodysignature = hmac.new(





b'your_private_secret_here',
msg=message.encode(),
digestmod=hashlib.sha256
).digest()
 
auth_header = base64.b64encode(signature).decode()

This signature, along with the APIKey and Nonce, must be included in every private request.

Placing a Futures Order via API

Once authenticated, you can begin interacting with trading endpoints. To place a new order, send a POST request to /api/v3/sendorder. The payload must include essential parameters such as symbol, side, size, and order type.

Required fields in the JSON body:

• orderType: Can be lmt (limit), mkt (market), or post (post-only limit)
• symbol: For example, pi_xbtusd for the perpetual Bitcoin/USD contract
• side: Either buy or sell
• size: Number of contracts (minimum 1 for most pairs)
• limitPrice: Required for limit orders

Example request using curl:

curl -X POST https://futures.kraken.com/api/v3/sendorder \-H 'APIKey: your_api_key_here' \-H 'Nonce: 1234567890' \-H 'Authentification: generated_signature_here' \-d '{'orderType':'lmt','symbol':'pi_xbtusd','side':'buy','size':100,'limitPrice':35000}'

After submission, the API returns a response containing the orderId, status, and other metadata. You can use this ID to cancel or query the order later.

Retrieving Market Data and Account Information

Public endpoints do not require authentication and are ideal for fetching real-time market conditions. Useful endpoints include:

• GET /api/v3/tickers: Returns latest prices, funding rates, and open interest for all symbols
• GET /api/v3/orderbook?symbol=pi_xbtusd: Fetches full Level 2 order book
• GET /api/v3/history?symbol=pi_xbtusd&lastTime=...: Retrieves recent trade history

For account-specific data, use private endpoints:

• GET /api/v3/accounts: Shows margin balances, equity, and PNL across all ledgers
• GET /api/v3/positions: Lists all active positions with entry price, size, and liquidation levels
• GET /api/v3/orders: Retrieves open orders; add ?order_status=closed to see filled/cancelled ones

All responses are in JSON format, making them easy to parse in code. Polling intervals should respect rate limits—typically 10 requests per second for public endpoints and 5 for private ones.

Handling Errors and Debugging API Calls

Even with correct syntax, API requests may fail due to invalid parameters, insufficient margin, or connectivity issues. Common HTTP status codes include:

• 400 Bad Request: Malformed JSON or missing required fields
• 401 Unauthorized: Invalid API key or failed signature verification
• 403 Forbidden: IP not whitelisted or insufficient permissions
• 429 Too Many Requests: Rate limit exceeded

Error responses contain a code and error message. For instance, 'error': 'Invalid signature' indicates a mismatch in HMAC computation. Double-check the concatenation logic and encoding steps.

Enable logging of raw requests and responses during development. Tools like Postman or curl with -v flag help inspect headers and payloads. Validate timestamps—they must be within a small window (usually ±60 seconds) of Kraken’s server time, retrievable via GET /api/v3/time.

---

Frequently Asked Questions

How do I find the correct symbol for a futures contract?Symbols follow a specific naming convention. Perpetuals start with pi_, followed by the base and quote currency (e.g., pi_ethusd). Quarterly futures use f_ prefix and include expiry date (e.g., f_xbtusd_240628). Check /api/v3/instruments for a complete list.

Can I use the same API key for both spot and futures trading?No. Kraken spot and futures platforms operate on separate systems. You must generate distinct API keys from the Kraken Futures dashboard, not the main Kraken.com interface.

What is the minimum order size on Kraken Futures?Most perpetual contracts have a minimum order size of 1 contract. One contract typically equals $1 of the underlying asset. For pi_xbtusd, 1 contract = $1 worth of Bitcoin. Always verify via /api/v3/instruments.

Is WebSocket support available for Kraken Futures?Yes. Connect to wss://futures.kraken.com/ws/v1 for live updates on order books, trades, and your private order events. Authentication involves sending a token obtained from the /api/v3/auth/token endpoint.