Kraken futures API Python example

The Kraken Futures API lets traders automate futures trading via REST calls, requiring HMAC-signed requests, valid symbols like `pi_xbtusd`, and separate API keys from Kraken’s Futures tab.

Jul 26, 2025 at 07:29 pm

What is Kraken Futures API?

The Kraken Futures API is a REST-based interface that allows traders and developers to programmatically interact with Kraken’s futures trading platform. This includes placing orders, retrieving market data, checking account balances, and managing positions. It is ideal for algorithmic traders or those building automated trading bots. To use it in Python, you must first obtain an API key and secret from your Kraken Futures account dashboard. These credentials must be securely stored—preferably in environment variables—to avoid exposing them in code.

How to Install Required Python Libraries

Before writing any code, ensure you have the necessary libraries installed. The most critical ones are requests for HTTP communication and python-dotenv if you plan to use environment variables for API credentials. Run the following commands in your terminal:

• pip install requests
• pip install python-dotenv
  

  Once installed, you can import them in your script like this:

  import os
  import requests
  import time
  import hashlib
  import hmac
  from dotenv import load_dotenv

  Make sure to call load_dotenv() at the top of your script if you're using a .env file to store your credentials.

  Setting Up Authentication Headers

  
  Kraken Futures API uses HMAC-SHA256 for signing requests. You must generate a signature for each private endpoint call. The process involves:
• Creating a nonce (a unique timestamp in seconds)
• Concatenating the request path, nonce, and body
• Using your API secret to hash the message

• Adding headers like APIKey and Authent (the signature)
  

  Here’s how to structure the authentication:

  def get_kraken_signature(urlpath, data, secret):
    postdata = data
    encoded = (str(data['nonce']) + postdata).encode()
    message = urlpath.encode() + hashlib.sha256(encoded).digest()
    mac = hmac.new(base64.b64decode(secret), message, hashlib.sha512)
    sigdigest = base64.b64encode(mac.digest())
    return sigdigest.decode()

  This function returns the Authent header value, which is required for private API calls like placing orders or fetching your balance.

  Placing a Futures Order via API

  
  To place a futures order, you must send a POST request to the /derivatives/api/v3/sendorder endpoint. Here’s a complete example:

  url = "https://futures.kraken.com/derivatives/api/v3/sendorder"
  headers = {
    "User-Agent": "Python API Client",
    "APIKey": os.getenv("KRAKEN_API_KEY"),
  }
  data = {
  "orderType": "lmt",
  "size": 1,
  "symbol": "pi_xbtusd",
  "side": "buy",
  "limitPrice": "69000.0",
  "cliOrdId": f"myorder{int(time.time())}",
  "nonce": str(int(time.time() * 1000)),
  }
  signature = get_kraken_signature("/sendorder", data, os.getenv("KRAKEN_API_SECRET"))
  headers["Authent"] = signature
  response = requests.post(url, headers=headers, data=data)
  The **`cliOrdId`** ensures each order is unique. The **`symbol`** must match Kraken’s futures contract naming convention (e.g., `pi_xbtusd` for perpetual Bitcoin/USD).
  
  <h3>Fetching Open Positions and Account Info</h3>
  To retrieve your current open positions, send a GET request to `/derivatives/api/v3/openpositions`. No body is needed, but you still need authentication:
  url = "https://futures.kraken.com/derivatives/api/v3/openpositions"
  headers = {
   "APIKey": os.getenv("KRAKEN_API_KEY"),
   "User-Agent": "Python API Client",
  }
  nonce = str(int(time.time() * 1000))
  data = {"nonce": nonce}
  signature = get_kraken_signature("/openpositions", data, os.getenv("KRAKEN_API_SECRET"))
  headers["Authent"] = signature

response = requests.get(url, headers=headers)
positions = response.json()

The positions variable will contain a list of active positions, including entry price, size, and unrealized P&L.

Common Errors and How to Fix Them

• Invalid signature: Double-check the concatenation logic in your signature function. Ensure the nonce is a string and matches the one in the data payload.
• Insufficient margin: Kraken may reject orders if your account lacks margin. Check your balance first using /accountsummary.
• Invalid symbol: Use /instruments to fetch a list of valid futures contracts. Do not assume naming patterns.
• Rate limiting: Kraken enforces rate limits. If you get a 429 error, add a delay between requests using time.sleep(1).
  

  Frequently Asked Questions

  How do I find the correct futures symbol for BTC/USD?
  
  Use the /instruments endpoint: GET https://futures.kraken.com/derivatives/api/v3/instruments. Look for symbols ending in usd—the most common is pi_xbtusd for the perpetual futures contract.

  Can I use the same API key for spot and futures trading?
  
  No. Kraken Futures requires a separate API key generated from the Futures tab in your Kraken account. Using a spot key will return an authentication error.

  Why does my order get rejected even with correct parameters?
  
  Check if your order size is below the minimum (e.g., 0.001 BTC for BTC/USD). Also verify that limitPrice is within the allowed deviation from the mark price—Kraken may reject orders too far from the current market.

  Is it safe to store API keys in environment variables?
  
  Yes, as long as your .env file is not committed to public repositories. Always add .env to your .gitignore file and never print or log your API keys in code.