---
title: "Kraken Futures API TypeScript SDK"
description: "Build production-ready integrations with the Kraken Futures API TypeScript SDK. This guide covers awaitable WebSockets, auto-reconnect, and type-safe requests."
canonical: "https://siebly.io/blog/kraken-futures-api-typescript-sdk-a-guide-to-production-ready-integration"
---

# Kraken Futures API TypeScript SDK: A Guide to Production-Ready Integration

Build production-ready integrations with the Kraken Futures API TypeScript SDK. This guide covers awaitable WebSockets, auto-reconnect, and type-safe requests.

## Technical Disclaimer

These articles are software engineering references for exchange API integrations. They are not financial, investment, legal, tax, compliance, or trading advice. Use public data, demo, testnet, or paper workflows first. Keep API credentials out of frontend code and disable withdrawal permissions for automation keys.

## Overview {#overview}

Kraken Spot and Kraken Futures are not the same API. Spot signs with `API-Key` / `API-Sign` and a nonce. Futures signs with `APIKey` / `Authent`. Response shapes differ. Private Futures WebSockets use a challenge-response flow that Spot does not. If you wire that by hand, you spend more time on signing and reconnects than on the trading system itself.

The Kraken Futures API TypeScript SDK lives in [@siebly/kraken-api](https://www.npmjs.com/package/@siebly/kraken-api). It covers Spot, Derivatives (Futures), Institutional, and Partner REST clients, plus a unified `WebsocketClient`. It signs requests, types payloads, and keeps sockets alive. It does not throttle you. Siebly SDKs never auto-rate-limit. You still own request pacing against Kraken's cost budgets.

This guide walks through a working Futures setup in Node.js: REST market data and orders, demo/testnet, and WebSocket streams with the reconnect and heartbeat behavior the SDK already provides.

## Key Takeaways {#key-takeaways}

- Use [@siebly/kraken-api](/sdk/kraken/javascript) and the `DerivativesClient` for Kraken Futures REST. Do not invent a `DerivativesRestClient`. That class does not exist.
- Place Futures orders over REST. Kraken's Derivatives WebSocket is streaming only. Order entry is REST (or FIX). The SDK's awaitable `WebsocketAPIClient` is Spot-only.
- `WebsocketClient` already reconnects, resubscribes, and sends heartbeats. Listen to `reconnected` / `exception`. You do not need to rebuild that loop.
- Pace REST yourself. `/derivatives` allows 500 cost units every 10 seconds. `/history` is a separate 100-token pool that refills every 10 minutes. Public REST calls have no cost. Over-limit responses return `error: "apiLimitExceeded"`.
- Keep keys in env vars, disable withdrawals on automation keys, and start on Kraken's Futures demo with `testnet: true`.



## The Complexity of Raw Kraken Futures API Integration {#the-complexity-of-raw-kraken-futures-api-integration}

A custom Futures client is not "Spot with a different base URL". Futures uses HMAC over SHA-256 then HMAC-SHA512, then puts the result in the `Authent` header with `APIKey`. The signed payload is query string + body + endpoint path (with `/derivatives` stripped). Spot uses a nonce plus `API-Key` / `API-Sign`. Mix those schemes and every private call fails.

Raw sockets add another split. Private Futures feeds need a challenge, a signed challenge, and those values on every private subscribe. Kraken's own docs say Derivatives WebSocket is observation only. You still send, edit, and cancel orders on REST. For [algorithmic trading](https://en.wikipedia.org/wiki/Algorithmic_trading) that split is the actual architecture, not a temporary workaround.

The SDK hides the signing and the challenge flow. It does not hide Kraken's rate budgets. You still count cost locally.

### Fragmented API Standards {#fragmented-api-standards}

Spot tickers, books, and orders do not look like Futures tickers, books, and orders. Symbols differ too: Spot uses `BTC/USD` or `XBTUSD`, Futures perpetuals look like `PF_ETHUSD` or `PI_XBTUSD`. DIY mappers rot as Kraken changes fields. A maintained package such as [@siebly/kraken-api](/sdk/kraken/javascript) is the cheaper long-term option if you already live in this stack.

### The TypeScript Advantage {#the-typescript-advantage}

Typed request objects catch missing `symbol`, `side`, or `orderType` before the request leaves your process.

- Compile-time checks on nested order params.
- IntelliSense for REST methods and WebSocket topics.
- Typed success and error shapes instead of untyped JSON blobs.

JavaScript still works. Types ship with the package. You do not have to write TypeScript to install it.

## Implementing the Siebly Kraken SDK in Node.js {#implementing-the-siebly-kraken-sdk-in-nodejs}

Install the published package:

```bash title="Imported example"
npm install --save @siebly/kraken-api
```

Use a current Node.js LTS. The Kraken SDK does not pin a Node 26 runtime. Put keys in environment variables. Enable only what you need. Turn withdrawal off for bot keys. [FINRA's notes on supervision of automated systems](https://www.finra.org/rules-guidance/key-topics/algorithmic-trading) are a useful checklist even if you are not a US broker-dealer: least privilege, hard size caps, and a human kill switch.

### Authentication and Request Signing {#authentication-and-request-signing}

For Futures REST the SDK builds `Authent` and sends `APIKey`. Internally that is SHA-256 over the concatenated query, body, and path, then HMAC-SHA512 with your secret (base64). Spot REST still uses a nonce and `API-Sign`. You do not pick the algorithm per call. You pick the client:

- `SpotClient` for spot
- `DerivativesClient` for futures
- `InstitutionalClient` for institutional
- `PartnerClient` for partner / embed

Nonce management is a Spot problem. Futures signing in this SDK does not send a nonce header. "Invalid nonce" and clock-skew auth failures are not the Futures REST failure mode you should design around first. Rate limits and connectivity are.

### Working with Type-Safe Requests {#working-with-type-safe-requests}

Construct a `DerivativesClient`. Public calls need no keys. Private calls need `apiKey` and `apiSecret`.

```js title="Imported example"
import { DerivativesClient } from "@siebly/kraken-api";

const publicClient = new DerivativesClient();

const client = new DerivativesClient({
  apiKey: process.env.API_FUTURES_KEY,
  apiSecret: process.env.API_FUTURES_SECRET,
});

const ticker = await publicClient.getTicker({
  symbol: "PF_ETHUSD",
});
console.log("Ticker:", ticker);

const orderBook = await publicClient.getOrderbook({
  symbol: "PF_ETHUSD",
});
console.log("Order book:", orderBook);

const accounts = await client.getAccounts();
console.log("Accounts:", accounts);
```

`getTickers()` returns every contract. `getTicker({ symbol })` returns one. `getOrderbook` is the method name (not `getOrderBook`). Account balances come from `getAccounts()`, not `getAccountsDetails`.

For a longer walkthrough, see the [Siebly Kraken SDK tutorial](/sdk/kraken/javascript/tutorial). Docs and other exchange SDKs live at [siebly.io](/).

## Placing Futures Orders and Streaming Market Data {#placing-futures-orders-and-streaming-market-data}

Kraken Futures order entry is REST. The Derivatives WebSocket does not place orders. If a guide tells you to `await` a Futures order on `WebsocketAPIClient`, that guide is wrong. `WebsocketAPIClient` currently wraps Spot WS API methods such as `submitSpotOrder`.

### REST order placement {#rest-order-placement}

Use `DerivativesClient.submitOrder`. Limit orders use `orderType: 'lmt'`. Market orders use `'mkt'`. Post-only uses `'post'`. Generate client ids with `generateNewOrderID()`.

```js title="Imported example"
import { DerivativesClient } from "@siebly/kraken-api";

const client = new DerivativesClient({
  apiKey: process.env.API_FUTURES_KEY,
  apiSecret: process.env.API_FUTURES_SECRET,
});

const limitOrder = await client.submitOrder({
  orderType: "lmt",
  symbol: "PF_ETHUSD",
  side: "buy",
  size: 0.01,
  limitPrice: 1000,
  cliOrdId: client.generateNewOrderID(),
});
console.log("Limit order:", JSON.stringify(limitOrder, null, 2));

const marketOrder = await client.submitOrder({
  orderType: "mkt",
  symbol: "PF_ETHUSD",
  side: "sell",
  size: 0.01,
});
console.log("Market order:", JSON.stringify(marketOrder, null, 2));

await client.editOrder({
  orderId: "a04d0f84-36d4-4499-8382-96fcfc3ce7aa",
  limitPrice: 1100,
});

await client.cancelOrder({
  order_id: "a04d0f84-36d4-4499-8382-96fcfc3ce7aa",
});
```

Note the param names: edit uses `orderId`, cancel uses `order_id`. That is Kraken's API, not a typo in the sample.

For a dead-man's switch, call `cancelAllOrdersAfter` on a timer. The SDK comments recommend roughly every 15 to 20 seconds with a 60 second timeout so a brief disconnect does not leave orders working forever.

Treat this as an integration example, not a live order. Use demo keys first.

### Demo / testnet {#demo-testnet}

As of November 2025, only Derivatives supports Kraken's demo environment. Pass `testnet: true`. Do not hand-edit the base URL unless you have a reason. Liquidity there is not live liquidity. It is for API wiring, not strategy research.

```js title="Imported example"
const demoClient = new DerivativesClient({
  apiKey: process.env.API_FUTURES_TESTNET_KEY,
  apiSecret: process.env.API_FUTURES_TESTNET_SECRET,
  testnet: true,
});

const wallets = await demoClient.getAccounts();
const positions = await demoClient.getOpenPositions();
```

The same flag works on `WebsocketClient`.

### Public and private WebSocket streams {#public-and-private-websocket-streams}

`WebsocketClient` is the stream client for Spot and Futures. Pass a `WsKey` such as `derivativesPublicV1` or `derivativesPrivateV1` so the SDK picks `wss://futures.kraken.com/ws/v1` (or the demo host when `testnet: true`).

It already:

- connects and reconnects
- resubscribes after reconnect
- authenticates private Futures topics (challenge, cache, signed challenge)
- heartbeats (default ping every 10 seconds, pong timeout 5 seconds)

You subscribe. You handle `message`. You do not reimplement the socket state machine.

Public book / ticker / trades:

```js title="Imported example"
import { WebsocketClient, WS_KEY_MAP } from "@siebly/kraken-api";

const wsClient = new WebsocketClient();

wsClient.on("open", (data) => {
  console.log("connected", data?.wsKey);
});

wsClient.on("message", (data) => {
  console.log("data", JSON.stringify(data));
});

wsClient.on("reconnected", (data) => {
  console.log("reconnected", data?.wsKey);
});

wsClient.on("exception", (data) => {
  console.error("ws error", data);
});

wsClient.subscribe(
  {
topic: "ticker",
payload: {
product_ids: ["PI_XBTUSD", "PI_ETHUSD"],
},
  },
  WS_KEY_MAP.derivativesPublicV1,
);

wsClient.subscribe(
  {
topic: "book",
payload: {
product_ids: ["PI_XBTUSD"],
},
  },
  WS_KEY_MAP.derivativesPublicV1,
);

wsClient.subscribe(
  {
topic: "trade",
payload: {
product_ids: ["PI_XBTUSD", "PI_ETHUSD"],
},
  },
  WS_KEY_MAP.derivativesPublicV1,
);
```

Private account streams (SDK fills in `api_key`, `original_challenge`, and `signed_challenge`):

```js title="Imported example"
import { WebsocketClient, WS_KEY_MAP } from "@siebly/kraken-api";

const wsClient = new WebsocketClient({
  apiKey: process.env.API_FUTURES_KEY,
  apiSecret: process.env.API_FUTURES_SECRET,
});

wsClient.on("authenticated", (data) => {
  console.log("authenticated", data);
});

wsClient.on("message", (data) => {
  console.log("private data", JSON.stringify(data));
});

wsClient.subscribe("open_orders", WS_KEY_MAP.derivativesPrivateV1);
wsClient.subscribe("open_orders_verbose", WS_KEY_MAP.derivativesPrivateV1);
wsClient.subscribe(
  {
topic: "fills",
payload: {
product_ids: ["PF_XBTUSD"],
},
  },
  WS_KEY_MAP.derivativesPrivateV1,
);
wsClient.subscribe("balances", WS_KEY_MAP.derivativesPrivateV1);
wsClient.subscribe("open_positions", WS_KEY_MAP.derivativesPrivateV1);
wsClient.subscribe("account_log", WS_KEY_MAP.derivativesPrivateV1);
wsClient.subscribe("notifications_auth", WS_KEY_MAP.derivativesPrivateV1);
```

Use fills and open-order events as the live order state. REST is for sending the order and for periodic reconcile, not as your only fill source.

If you also trade Spot and want awaitable WS orders, that is `WebsocketAPIClient.submitSpotOrder`. It is a different product surface. Do not point it at Futures.

```js title="Imported example"
import { WebsocketAPIClient } from "@siebly/kraken-api";

const spotWs = new WebsocketAPIClient({
  apiKey: process.env.API_SPOT_KEY,
  apiSecret: process.env.API_SPOT_SECRET,
});

const orderResponse = await spotWs.submitSpotOrder({
  order_type: "limit",
  side: "buy",
  limit_price: 26500.4,
  order_qty: 1.2,
  symbol: "BTC/USD",
});
```

For market-data pipeline patterns beyond the socket itself, see [historical and live data pipeline](/ai/historical-live-data-pipeline).



## Reliability Best Practices for Production Systems {#reliability-best-practices-for-production-systems}

Production is less about "remember to ping" and more about what you do when Kraken is slow, your process restarts, or you blow the cost budget.

The SDK's WebSocket layer already pings, detects dead sockets, reconnects after `reconnectTimeout` (default 500 ms), and resubscribes stored topics. Hook `reconnecting`, `reconnected`, `close`, and `exception`. After a long outage, reconcile open orders and positions with REST (`getOpenOrders`, `getOpenPositions`, `getFills`) because you may have missed events while disconnected.

Do not assume you must write your own ping/pong loop. You can change `pingInterval` and `pongTimeout` if you want. Kraken asks for a ping at least every 60 seconds. The SDK default of 10 seconds already satisfies that.

Hard-code order size caps and max exposure in your own code. The SDK will happily send whatever you pass.

### Handling Rate Limits and Throttling {#handling-rate-limits-and-throttling}

Siebly SDKs do not throttle. Kraken Futures REST uses request cost, not a simple "N calls per second" cap.

- Public REST endpoints have no cost.
- Private `/derivatives` calls share a budget of 500 every 10 seconds. `sendorder` / `editorder` / `cancelorder` cost 10 each. `accounts` and `openpositions` cost 2. `cancelallorders` costs 25. `batchorder` costs 9 plus batch size.
- `/history` (order events, executions, account log) is a separate pool of 100 tokens, refilling 100 every 10 minutes.
- Exceeding the budget returns JSON `{ "result": "error", "error": "apiLimitExceeded" }`. That is the signal, not a Binance-style remaining-weight header.

Track cost in your process. Back off when you see `apiLimitExceeded`. Do not mix history traffic into the same burst as order entry.

WebSocket limits are separate: 100 connections, and 100 requests per connection per second (subscribe / unsubscribe / challenge, not REST token costs). You do not debit the 500 REST budget per ticker tick.

### State Management and Error Handling {#state-management-and-error-handling}

Keep a local order/position cache. Update it from `fills` and `open_orders`. Confirm with REST after reconnects and on startup. Handle insufficient margin and maintenance windows as hard failures for that order, not as retries-without-limit.

`cancelAllOrdersAfter` is the exchange-side safety net if your process dies.

More architecture notes: [algorithmic trading system architecture](/blog). SDK reference: [siebly.io/sdk/kraken/javascript](/sdk/kraken/javascript).

## Scaling Kraken Integrations with Siebly AI Tooling {#scaling-kraken-integrations-with-siebly-ai-tooling}

Typed clients are easier for both humans and coding agents because method names and param objects are stable. That is the real "AI" benefit: `llms.txt` ships in the package, and [Siebly AI](/ai) has prompt/skills material for these SDKs. It does not replace your rate limiter or your risk caps.

When you migrate off a handwritten signer, keep a local cost tracker in the plan. The HMAC work goes away. The 500-per-10-seconds budget does not.

### AI-Optimized Developer Workflows {#ai-optimized-developer-workflows}

Use the bundled `llms.txt` if an agent is writing calls against this package. It matches the real method names (`DerivativesClient`, `getOrderbook`, `submitOrder`, `WebsocketClient`). That avoids the usual hallucinated class names.

### Next Steps for Systematic Traders {#next-steps-for-systematic-traders}

## Architecting Stable Kraken Futures Integrations {#architecting-stable-kraken-futures-integrations}

A production Futures stack on this SDK is straightforward:

1. `DerivativesClient` for send / edit / cancel and for snapshots.
2. `WebsocketClient` on `derivativesPublicV1` and `derivativesPrivateV1` for books, trades, fills, and positions.
3. Your own cost accounting against Kraken's tables.
4. Demo first (`testnet: true`), live keys with no withdraw permission.

You still own risk limits and reconnect reconcile. You do not own HMAC, challenge tokens, or the heartbeat loop.

[Start building with the Siebly Kraken SDK](/sdk/kraken/javascript).

## Frequently Asked Questions {#frequently-asked-questions}

### Does the Siebly Kraken SDK support both Spot and Futures markets? {#does-the-siebly-kraken-sdk-support-both-spot-and-futures-markets}

Yes. [@siebly/kraken-api](/sdk/kraken/javascript) exports `SpotClient`, `DerivativesClient`, `InstitutionalClient`, and `PartnerClient`, plus one `WebsocketClient` for stream subscriptions. Auth details still differ under the hood. You pick the client for the product. You do not get one identical header scheme across Spot and Futures.

### How does the SDK handle Kraken API request signing? {#how-does-the-sdk-handle-kraken-api-request-signing}

Spot REST: nonce in the body, SHA-256, HMAC-SHA512, headers `API-Key` and `API-Sign`.

Futures REST: SHA-256 over query + body + path, HMAC-SHA512, headers `APIKey` and `Authent`.

Private Futures WebSockets: the SDK requests a challenge, signs it, and attaches `original_challenge` / `signed_challenge` on private subscribe. You do not do that by hand.

### Can I use the Kraken Futures API TypeScript SDK with a testnet account? {#can-i-use-the-kraken-futures-api-typescript-sdk-with-a-testnet-account}

Yes, for Derivatives. Pass `testnet: true` on `DerivativesClient` or `WebsocketClient`. Kraken calls it Demo. Spot does not have the same testnet switch in this SDK as of November 2025.

### What are the benefits of using awaitable WebSockets for order placement? {#what-are-the-benefits-of-using-awaitable-websockets-for-order-placement}

That pattern exists for Spot, via `WebsocketAPIClient` (`submitSpotOrder`, `amendSpotOrder`, `cancelSpotOrder`, …). You `await` the WS API reply like a REST call, on a persistent socket.

It does not exist for Kraken Futures in this SDK, and Kraken's Derivatives WebSocket is not an order-entry API. For Futures, `await client.submitOrder(...)` on `DerivativesClient`.

### Does the SDK automatically handle API rate limits? {#does-the-sdk-automatically-handle-api-rate-limits}

No. You implement pacing. Futures `/derivatives` is 500 cost per 10 seconds. `/history` is 100 per 10 minutes. Public REST is free. Watch for `apiLimitExceeded`. Do not expect the SDK to sleep for you.

### How do I manage WebSocket reconnections in Node.js with this library? {#how-do-i-manage-websocket-reconnections-in-node-js-with-this-library}

Subscribe once. The client stores topics and resubscribes after reconnect. Listen to `reconnecting` and `reconnected`. After a drop, snapshot orders and positions over REST so you are not blind during the gap. You can tune `pingInterval`, `pongTimeout`, and `reconnectTimeout`. You should not write a second reconnect state machine on top unless you have a specific reason.

### Is TypeScript required to use the Siebly Kraken SDK? {#is-typescript-required-to-use-the-siebly-kraken-sdk}

No. It is a JavaScript package with TypeScript types. Types help in the editor. They are not a runtime requirement.

### What security measures should I take when handling API keys in Node.js? {#what-security-measures-should-i-take-when-handling-api-keys-in-node-js}

Least-privilege Futures keys, withdrawals disabled, keys only in env or a secret manager, never in the browser or git. IP-restrict if Kraken lets you. Rotate. Keep automation on a sub-account with a balance you can afford to lose.

Disclaimer

*Technical and legal disclaimer: Siebly.io provides software development tools, SDKs, documentation, and educational engineering content for crypto exchange API integrations. This content is for software engineering education only and is not financial, investment, legal, tax, accounting, compliance, or trading advice.

Nothing in this article is a recommendation, invitation, or inducement to buy, sell, hold, trade, long, short, or allocate to any cryptoasset, exchange product, strategy, bot, or automated workflow. Examples, code patterns, simulations, backtests, and architecture diagrams are illustrative only and must not be treated as trading signals, investment recommendations, or evidence of future performance.

Cryptoasset markets are high risk and volatile. If you choose to build or operate exchange-connected software, you are responsible for your own legal, regulatory, tax, security, exchange-account, API-key, and risk-management obligations. Use public data, testnet, demo, dry-run, or paper-trading workflows before any live execution. Keep API keys server-side, use least-privilege permissions, and never enable withdrawals for automation keys unless you fully understand and accept the risks.

Siebly.io is not an exchange, custodian, investment adviser, trading-signal provider, or managed trading service. Official exchange documentation remains the source of truth for exchange-specific rules, API behavior, and terms of use. Use of Siebly.io content and software is also subject to the Siebly.io terms and conditions.*

## Related articles

- [Building a Reliable Kraken API Client in TypeScript: A 2026 Engineering Guide](/blog/building-a-reliable-kraken-api-client-in-typescript-a-2026-engineering-guide)
- [Gate.io Futures API TypeScript SDK: A Production Integration Guide](/blog/gateio-futures-api-typescript-sdk-a-production-integration-guide)
- [Kraken API Integration in JavaScript: A Production-Ready Engineering Guide](/blog/kraken-api-integration-in-javascript-a-production-ready-engineering-guide)


## Related Siebly Resources

- [Binance JavaScript SDK](/sdk/binance/javascript)
- [Kraken JavaScript SDK](/sdk/kraken/javascript)
- [Siebly SDK directory](/sdk)
- [Siebly AI Prompt Framework & Skills](/ai)
- [Exchange State Management](/ai/exchange-state)