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

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 is the cheaper long-term option if you already live in this stack.

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.

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.

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

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. Docs and other exchange SDKs live at siebly.io.

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

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.

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.

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.

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:

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):

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.

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.

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.

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. SDK reference: siebly.io/sdk/kraken/javascript.

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.

Yes. @siebly/kraken-api 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.

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.

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.

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.

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.

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.

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

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.*