Kraken TypeScript SDK

TypeScript SDK Usage

Use typed requests, responses, and event flows in stricter TypeScript services and shared libraries.

In TypeScript, use the package types to check request shapes, response fields, WebSocket payloads, and refactors around exchange-specific code.

What This SDK Covers

• Complete Kraken REST API integrations for exchange-specific workflows.
• Robust Kraken WebSocket support for market and account stream handling.
• TypeScript-friendly usage patterns for production integration work.
• Adaptable TypeScript examples & guides under /examples for implementation reference.
• Type-rich examples that emphasize request and response shapes, editor hints, and safer refactors.
• Implementation patterns for larger TypeScript services, shared libraries, and stricter TypeScript application code.

Install Package

npm install @siebly/kraken-api
# or
pnpm install @siebly/kraken-api
yarn add @siebly/kraken-api

Quickstart REST API Walkthrough

Quickstart REST API Example

/* eslint-disable @typescript-eslint/no-unused-vars */
// This example shows how to call Kraken API endpoint with either node.js,
// javascript (js) or typescript (ts) with the npm module "@siebly/kraken-api" for Kraken exchange
// for ORDER MANAGEMENT

import { DerivativesClient } from '@siebly/kraken-api';

// initialise the client
/**
 *
 * Kraken Futures API uses API Key and API Secret
 *
 * Example:
 * {
 *   apiKey: 'your-api-key',
 *   apiSecret: 'your-api-secret',
 * }
 */
const client = new DerivativesClient({
  apiKey: process.env.API_FUTURES_KEY || 'insertApiKeyHere',
  apiSecret: process.env.API_FUTURES_SECRET || 'insertApiSecretHere',
});
async function editOrder() {
  try {
    // Edit an existing order
    const editResult = await client.editOrder({
      orderId: 'a04d0f84-36d4-4499-8382-96fcfc3ce7aa', // Or use cliOrdId instead
      limitPrice: 1100, // New limit price
      // or add some other parameters you want to edit
    });
    console.log('Edit Order Result: ', JSON.stringify(editResult, null, 2));

    // Response includes:
    // - status: edited, invalidSize, invalidPrice, etc.
    // - orderEvents: Array of order events
  } catch (e) {
    console.error('Edit order error: ', e);
  }
}

async function cancelOrder() {
  try {
    // Cancel a single order
    const cancelResult = await client.cancelOrder({
      order_id: 'a04d0f84-36d4-4499-8382-96fcfc3ce7aa', // Or use cliOrdId
    });
    console.log('Cancel Order Result: ', JSON.stringify(cancelResult, null, 2));

    // Response status:
    // - cancelled: Successfully cancelled
    // - filled: Order was already filled
    // - notFound: Order not found
  } catch (e) {
    console.error('Cancel order error: ', e);
  }
}

async function cancelAllOrders() {
  try {
    // Cancel all open orders
    const cancelAllResult = await client.cancelAllOrders();
    console.log(
      'Cancel All Orders Result: ',
      JSON.stringify(cancelAllResult, null, 2),
    );

    // Response includes:
    // - status: cancelled or noOrdersToCancel
    // - cancelledOrders: Array of cancelled order IDs
  } catch (e) {
    console.error('Cancel all orders error: ', e);
  }
}

async function cancelAllOrdersBySymbol() {
  try {
    // Cancel all orders for specific symbol
    const cancelBySymbol = await client.cancelAllOrders({
      symbol: 'PF_ETHUSD',
    });
    console.log(
      'Cancel Orders by Symbol Result: ',
      JSON.stringify(cancelBySymbol, null, 2),
    );
  } catch (e) {
    console.error('Cancel orders by symbol error: ', e);
  }
}

async function batchOrderManagement() {
  try {
    // Send, edit, and cancel orders in a single batch request
    const batchResult = await client.batchOrderManagement({
      json: {
        batchOrder: [
          // Edit existing order
          {
            order: 'edit',
            order_id: 'a04d1143-757a-4dba-a0a7-687303b9c62d',
            limitPrice: 900,
          },
          // Cancel existing order
          {
            order: 'cancel',
            order_id: 'a04d116e-fb9c-4bcf-9eaf-ea90254439b3',
          },
        ],
      },
    });
    console.log('Batch Order Result: ', JSON.stringify(batchResult, null, 2));

    // Response includes batchStatus array with results for each order
    // - status: placed, edited, cancelled, or rejection reason
    // - order_tag: Maps back to your request
  } catch (e) {
    console.error('Batch order management error: ', e);
  }
}

// Uncomment the function you want to test:

// editOrder();
// cancelOrder();
// cancelAllOrders();
// cancelAllOrdersBySymbol();
// batchOrderManagement();

Quickstart WebSocket Walkthrough

Quickstart WebSocket Example

// eslint-disable-next-line @typescript-eslint/no-unused-vars
import {
  DefaultLogger,
  LogParams,
  WebsocketClient,
  WS_KEY_MAP,
  WSTopicRequest,
} from '@siebly/kraken-api';
import { WSDerivativesTopic } from '@siebly/kraken-api';

const customLogger: DefaultLogger = {
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  trace: (...params: LogParams): void => {
    // console.log(new Date(), '--> trace', ...params);
  },
  info: (...params: LogParams): void => {
    console.log(new Date(), '--> info', ...params);
  },
  error: (...params: LogParams): void => {
    console.error(new Date(), '--> error', ...params);
  },
};

async function start() {
  const account = {
    key: process.env.API_FUTURES_KEY || 'keyHere',
    secret: process.env.API_FUTURES_SECRET || 'secretHere',
  };

  /**
   * The WebsocketClient is the core class to manage WebSocket subscriptions. Give it the topics you want to subscribe to, and it will handle the rest:
   * - Connection management (connect, disconnect, reconnect)
   * - Authentication for private topics
   * - Subscription management (subscribe, unsubscribe, resubscribe on reconnect)
   * - Message handling (dispatch messages to appropriate handlers)
   *
   * All you need to do is provide the topics you want to subscribe to when calling `subscribe()`, and the client will take care of the rest.
   *
   * Here we create a WebsocketClient instance with API key/secret for private topic subscriptions.
   *
   * In terms of product groups such as Spot, Derivatives, etc., the WebsocketClient understand the product group from the WsKey you provide when subscribing. For example, using `WS_KEY_MAP.spotPrivateV2` indicates that the subscription is for Spot private topics, as shown below.
   *
   * Refer to WS_KEY_MAP in the source code for all available WsKey options.
   */
  const client = new WebsocketClient(
    {
      apiKey: account.key,
      apiSecret: account.secret,
    },
    customLogger,
  );

  client.on('open', (data) => {
    console.log(new Date(), 'connected ', data?.wsKey);
  });

  // Data received
  client.on('message', (data) => {
    console.info(new Date(), 'data received: ', JSON.stringify(data));
  });

  // Something happened, attempting to reconnect
  client.on('reconnecting', (data) => {
    console.log(new Date(), 'reconnect: ', data?.wsKey);
  });

  // Reconnect successful
  client.on('reconnected', (data) => {
    console.log(new Date(), 'reconnected: ', data?.wsKey);
  });

  // Connection closed. If unexpected, expect reconnect -> reconnected.
  client.on('close', (data) => {
    console.error(new Date(), 'close: ', data);
  });

  // Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
  client.on('response', (data) => {
    console.info(new Date(), 'server reply: ', JSON.stringify(data), '\n');
  });

  client.on('exception', (data) => {
    console.error(new Date(), 'exception: ', data);
  });

  client.on('authenticated', (data) => {
    console.error(new Date(), 'authenticated: ', data);
  });

  /**
   * The below examples demonstrate how you can subscribe to private topics.
   *
   * Note: while the documentation specifies "api_key", "original_challenge" and "signed_challenge" as required parameters, but don't worry about that. The SDK will automatically:
   * - Fetch the challenge using your API key,
   * - Cache the challenge
   * - Include the key, original challenge and signed challenge parameters for you when subscribing to private topics on the derivativesPrivateV1 WebSocket connection.
   *
   * You do NOT need to manually fetch or provide the "original_challenge" and "signed_challenge" tokens when subscribing to private topics.
   *
   * Do note that all of these include the "derivativesPrivateV1" WsKey reference. This tells the WebsocketClient to use the private "wss://futures.kraken.com/ws/v1" endpoint for these private subscription requests. It will also automatically authenticate the connection when it is established.
   */

  try {
    /**
     * All of the following parameters require API keys for Derivatives APIs.
     *
     * Note: your "WsTopicRequest" does not need to include "api_key", "original_challenge" and "signed_challenge". See above for details, or below for examples.
     */

    // Open orders: https://docs.kraken.com/api/docs/futures-api/websocket/open_orders
    const openOrdersTopicRequest: WSTopicRequest<WSDerivativesTopic> = {
      topic: 'open_orders',
    };
    client.subscribe(openOrdersTopicRequest, WS_KEY_MAP.derivativesPrivateV1);

    // Note: if there are no parameters needed, you can also just request the topic by name
    // This is the same as openOrdersTopicRequest, since openOrdersTopicRequest contains no parameters
    // client.subscribe('open_orders', WS_KEY_MAP.derivativesPrivateV1);

    // Open orders (verbose): https://docs.kraken.com/api/docs/futures-api/websocket/open_orders
    client.subscribe('open_orders_verbose', WS_KEY_MAP.derivativesPrivateV1);

    // Fills: https://docs.kraken.com/api/docs/futures-api/websocket/fills
    const accountFillsTopicRequest: WSTopicRequest<WSDerivativesTopic> = {
      topic: 'fills',
      // Optionally, the product_ids field can be used to subscribe only to specific product.
      // payload: {
      //   product_ids: ['PF_XBTUSD'],
      // },
    };
    client.subscribe(accountFillsTopicRequest, WS_KEY_MAP.derivativesPrivateV1);

    // Balances: https://docs.kraken.com/api/docs/futures-api/websocket/balances
    client.subscribe('balances', WS_KEY_MAP.derivativesPrivateV1);

    // Open Position: https://docs.kraken.com/api/docs/futures-api/websocket/open_position
    client.subscribe('open_positions', WS_KEY_MAP.derivativesPrivateV1);

    // Account Log: https://docs.kraken.com/api/docs/futures-api/websocket/account_log
    client.subscribe('account_log', WS_KEY_MAP.derivativesPrivateV1);

    // Notification: https://docs.kraken.com/api/docs/futures-api/websocket/notifications
    client.subscribe('notifications_auth', WS_KEY_MAP.derivativesPrivateV1);
  } catch (e) {
    console.error('Req error: ', e);
  }
}

start();

Quickstart WebSocket API Walkthrough

Quickstart WebSocket API Example

// eslint-disable-next-line @typescript-eslint/no-unused-vars
import {
  DefaultLogger,
  LogParams,
  WebsocketAPIClient,
} from '@siebly/kraken-api';

const customLogger: DefaultLogger = {
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  trace: (...params: LogParams): void => {
    // console.log('trace', ...params);
  },
  info: (...params: LogParams): void => {
    console.log('info', ...params);
  },
  error: (...params: LogParams): void => {
    console.error('error', ...params);
  },
};

async function start() {
  const account = {
    key: process.env.API_SPOT_KEY || 'keyHere',
    secret: process.env.API_SPOT_SECRET || 'secretHere',
  };

  /**
   * The WebsocketClient is the core class to manage WebSocket subscriptions. Give it the topics you want to subscribe to, and it will handle the rest:
   * - Connection management (connect, disconnect, reconnect)
   * - Authentication for private topics
   * - Subscription management (subscribe, unsubscribe, resubscribe on reconnect)
   * - Message handling (dispatch messages to appropriate handlers)
   *
   * All you need to do is provide the topics you want to subscribe to when calling `subscribe()`, and the client will take care of the rest.
   *
   * Here we create a WebsocketClient instance with API key/secret for private topic subscriptions.
   *
   * In terms of product groups such as Spot, Derivatives, etc., the WebsocketClient understand the product group from the WsKey you provide when subscribing. For example, using `WS_KEY_MAP.spotPrivateV2` indicates that the subscription is for Spot private topics, as shown below.
   *
   * Refer to WS_KEY_MAP in the source code for all available WsKey options.
   */
  const client = new WebsocketAPIClient(
    {
      apiKey: account.key,
      apiSecret: account.secret,
    },
    customLogger,
  );

  /**
   * The below examples demonstrate how you can subscribe to private topics.
   *
   * Note: while the documentation specifies "token" as a required parameter, the SDK will automatically:
   * - fetch the token using your API key/secret,
   * - manage token caching/refreshing,
   * - include the token in the request for you.
   *
   * So you do NOT need to manually fetch or provide the token when subscribing to private topics.
   *
   * Do note that all of these include the "spotPrivateV2" WsKey reference. This tells the WebsocketClient to use the private "wss://ws-auth.kraken.com/v2" endpoint for these private subscription requests.
   */

  try {
    const addOrderResponse = await client.submitSpotOrder({
      order_type: 'limit',
      side: 'buy',
      limit_price: 26500.4,
      order_userref: 100054,
      order_qty: 1.2,
      symbol: 'BTC/USD',
    });
    console.log('addOrderResponse: ', addOrderResponse);

    const addOrderConditionalResponse = await client.submitSpotOrder({
      order_type: 'limit',
      side: 'buy',
      order_qty: 1.2,
      symbol: 'BTC/USD',
      limit_price: 28440,
      conditional: {
        order_type: 'stop-loss-limit',
        trigger_price: 28410,
        limit_price: 28400,
      },
    });
    console.log('addOrderConditionalResponse: ', addOrderConditionalResponse);

    const addOrderTriggersResponse = await client.submitSpotOrder({
      order_type: 'stop-loss',
      side: 'sell',
      order_qty: 100,
      symbol: 'MATIC/USD',
      triggers: {
        reference: 'last',
        price: 10.0,
        price_type: 'pct',
      },
    });
    console.log('addOrderTriggersResponse: ', addOrderTriggersResponse);

    const amendOrderResponse = await client.amendSpotOrder({
      cl_ord_id: '2c6be801-1f53-4f79-a0bb-4ea1c95dfae9',
      limit_price: 10000,
      order_qty: 1.2,
    });
    console.log('amendOrderResponse: ', amendOrderResponse);

    const amendOrderPostOnlyResponse = await client.amendSpotOrder({
      order_id: 'OAIYAU-LGI3M-PFM5VW',
      order_qty: 1.2,
      limit_price: 1100.3,
      deadline: '2025-11-19T09:53:59.050Z',
      post_only: true,
    });
    console.log('amendOrderPostOnlyResponse: ', amendOrderPostOnlyResponse);

    const cancelOrderResponse = await client.cancelSpotOrder({
      order_id: ['OM5CRX-N2HAL-GFGWE9', 'OLUMT4-UTEGU-ZYM7E9'],
    });
    console.log('cancelOrderResponse: ', cancelOrderResponse);

    const cancelAllResponse = await client.cancelAllSpotOrders();
    console.log('cancelAllResponse: ', cancelAllResponse);

    const cancelAllOrdersAfterResponse = await client.cancelAllSpotOrdersAfter({
      timeout: 100,
    });
    console.log('cancelAllOrdersAfterResponse: ', cancelAllOrdersAfterResponse);

    const batchAddResponse = await client.batchSubmitSpotOrders({
      deadline: '2025-11-19T09:53:59.050Z',
      orders: [
        {
          limit_price: 1010.1,
          order_qty: 1.2,
          order_type: 'limit',
          order_userref: 1,
          side: 'buy',
        },
        {
          limit_price: 1100.3,
          order_qty: 1.2,
          order_type: 'limit',
          order_userref: 2,
          side: 'sell',
          stp_type: 'cancel_both',
        },
      ],
      symbol: 'BTC/USD',
      validate: false,
    });
    console.log('batchAddResponse: ', batchAddResponse);

    const batchCancelResponse = await client.batchCancelSpotOrders({
      orders: ['OM5CRX-N2HAL-GFGWE9', 'OLUMT4-UTEGU-ZYM7E9'],
    });
    console.log('batchCancelResponse: ', batchCancelResponse);
  } catch (e) {
    console.error('Req error: ', e);
  }
}

start();

Endpoint Function Reference

Source: View endpoint map source

Kraken TypeScript FAQ

Direct Example Files

Open the example files for typed patterns that translate well into shared interfaces, services, and stricter application code.

• Kraken REST API example file (Kraken/Derivatives/Private/orderManagement.ts)
• Kraken WebSocket example file (Kraken/Derivatives/WebSockets/privateWs.ts)
• Kraken WebSocket API example file (Kraken/Spot/WebSockets/wsAPI.ts)

Reference Links

• npm: @siebly/kraken-api
• GitHub: kraken-api
• Release feed
• Support and feature requests