llms.txt

This file is a merged representation of a subset of the codebase, containing files not matching ignore patterns, combined into a single document by Repomix.
The content has been processed where content has been compressed (code blocks are separated by ⋮---- delimiter).

================================================================
File Summary
================================================================

Purpose:
--------
This file contains a packed representation of a subset of the repository's contents that is considered the most important context.
It is designed to be easily consumable by AI systems for analysis, code review,
or other automated processes.

File Format:
------------
The content is organized as follows:
1. This summary section
2. Repository information
3. Directory structure
4. Repository files (if enabled)
5. Multiple file entries, each consisting of:
  a. A separator line (================)
  b. The file path (File: path/to/file)
  c. Another separator line
  d. The full contents of the file
  e. A blank line

Usage Guidelines:
-----------------
- This file should be treated as read-only. Any changes should be made to the
  original repository files, not this packed version.
- When processing this file, use the file path to distinguish
  between different files in the repository.
- Be aware that this file may contain sensitive information. Handle it with
  the same level of security as you would the original repository.

Notes:
------
- Some files may have been excluded based on .gitignore rules and Repomix's configuration
- Binary files are not included in this packed representation. Please refer to the Repository Structure section for a complete list of file paths, including binary files
- Files matching these patterns are excluded: .github/, examples/apidoc/, docs/images/, docs/endpointFunctionList.md, test/, src/util/, dist/, lib/
- Files matching patterns in .gitignore are excluded
- Files matching default ignore patterns are excluded
- Content has been compressed - code blocks are separated by ⋮---- delimiter
- Files are sorted by Git change count (files with more changes are at the bottom)


================================================================
Directory Structure
================================================================
docs/
  KRAKEN_SDK_QUICKSTART_GUIDE.md
examples/
  Derivatives/
    Private/
      account.ts
      orderManagement.ts
      submitOrder.ts
      testnet.ts
    Public/
      marketData.ts
    WebSockets/
      privateWs.ts
      publicWs.ts
      testnetWs.ts
  Spot/
    Private/
      account.ts
      depositWithdraw.ts
      orderManagement.ts
      submitOrder.ts
    Public/
      marketData.ts
    WebSockets/
      privateWs.ts
      publicWs.ts
      wsAPI.RAW.ts
      wsAPI.ts
src/
  lib/
    websocket/
      logger.ts
      rest-client-cache.ts
      websocket-util.ts
      WsStore.ts
      WsStore.types.ts
    BaseRestClient.ts
    BaseWSClient.ts
    misc-util.ts
    requestUtils.ts
    webCryptoAPI.ts
  types/
    request/
      derivatives.types.ts
      institutional.types.ts
      partner.types.ts
      spot.types.ts
      wsapi.types.ts
    response/
      derivatives.types.ts
      institutional.types.ts
      partner.types.ts
      shared.types.ts
      spot.types.ts
      ws.ts
      wsapi.types.ts
    websockets/
      ws-api.ts
      ws-events.ts
      ws-general.ts
      ws-subscriptions.ts
  DerivativesClient.ts
  index.ts
  InstitutionalClient.ts
  PartnerClient.ts
  SpotClient.ts
  WebsocketAPIClient.ts
  WebsocketClient.ts
webpack/
  webpack.config.cjs
.eslintrc.cjs
.gitignore
.nvmrc
.prettierrc
jest.config.ts
LICENSE.md
package.json
postBuild.sh
README.md
tsconfig.cjs.json
tsconfig.esm.json
tsconfig.json
tsconfig.linting.json

================================================================
Files
================================================================

================
File: examples/Spot/Public/marketData.ts
================
import { SpotClient } from '../../../src/index.js';
⋮----
// 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 PUBLIC MARKET DATA that requires no authentication
⋮----
/**
 * import { SpotClient } from '@siebly/kraken-api';
 */
⋮----
// you can initialise public client without api keys as public calls do not require auth
⋮----
async function publicCalls()
⋮----
// Get server time
⋮----
// Get system status
⋮----
// Get asset info
⋮----
// Get tradable asset pairs
⋮----
// Get ticker information
⋮----
// Get order book
⋮----
// Get OHLC data (candles)
⋮----
interval: 60, // 1 minute
⋮----
// Get recent trades
⋮----
// Get recent spreads

================
File: src/lib/websocket/logger.ts
================
export type LogParams = null | any;
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log(_params);
⋮----
export type DefaultLogger = typeof DefaultLogger;

================
File: src/lib/websocket/rest-client-cache.ts
================
import { AxiosRequestConfig } from 'axios';
⋮----
import { DerivativesClient } from '../../DerivativesClient.js';
import { SpotClient } from '../../SpotClient.js';
import { RestClientOptions } from '../requestUtils.js';
import { DefaultLogger } from './logger.js';
⋮----
interface RestClientStore {
  spot: SpotClient;
  derivatives: DerivativesClient;
}
⋮----
interface WebSocketTokenCache {
  spot?: { token: string; expiresAtMs: number };
  derivatives?: { token: string; expiresAtMs: number };
}
⋮----
/**
 * Caches REST clients and WebSocket tokens to avoid redundant requests.
 */
export class RestClientCache
⋮----
public setLogger(logger: DefaultLogger, loggerCategory: object): void
⋮----
public getSpotRESTClient(
    restOptions: RestClientOptions,
    requestOptions?: AxiosRequestConfig,
): SpotClient
⋮----
public async fetchSpotWebSocketToken(
    restOptions: RestClientOptions,
    requestOptions?: AxiosRequestConfig,
): Promise<
⋮----
// still valid for at least 10s
⋮----
public getDerivativesRESTClient(
    restOptions: RestClientOptions,
    requestOptions?: AxiosRequestConfig,
): DerivativesClient

================
File: src/lib/websocket/WsStore.types.ts
================
import WebSocket from 'isomorphic-ws';
⋮----
export enum WsConnectionStateEnum {
  INITIAL = 0,
  CONNECTING = 1,
  CONNECTED = 2,
  CLOSING = 3,
  RECONNECTING = 4,
  // ERROR_RECONNECTING = 5,
  ERROR = 5,
}
⋮----
// ERROR_RECONNECTING = 5,
⋮----
export interface DeferredPromise<TSuccess = any, TError = any> {
  resolve?: (value: TSuccess) => TSuccess;
  reject?: (value: TError) => TError;
  promise?: Promise<TSuccess>;
}
⋮----
export interface WSConnectedResult {
  wsKey: string;
  ws: WebSocket;
}
⋮----
export interface WsStoredState<TWSTopicSubscribeEvent extends string | object> {
  /** The currently active websocket connection */
  ws?: WebSocket;

  /** The current lifecycle state of the connection (enum) */
  connectionState?: WsConnectionStateEnum;
  connectionStateChangedAt?: Date;

  /** A timer that will send an upstream heartbeat (ping) when it expires */
  activePingTimer?: ReturnType<typeof setTimeout> | undefined;

  /** A timer tracking that an upstream heartbeat was sent, expecting a reply before it expires */
  activePongTimer?: ReturnType<typeof setTimeout> | undefined;

  /** If a reconnection is in progress, this will have the timer for the delayed reconnect */
  activeReconnectTimer?: ReturnType<typeof setTimeout> | undefined;
  /**
   * When a connection attempt is in progress (even for reconnect), a promise is stored here.
   *
   * This promise will resolve once connected (and will then get removed);
   */
  deferredPromiseStore: Record<string, DeferredPromise>;

  /**
   * All the topics we are expected to be subscribed to on this connection (and we automatically resubscribe to if the connection drops)
   *
   * A "Set" and a deep-object-match are used to ensure we only subscribe to a topic once (tracking a list of unique topics we're expected to be connected to)
   */
  subscribedTopics: Set<TWSTopicSubscribeEvent>;

  /** Whether this connection has completed authentication (only applies to private connections) */
  isAuthenticated?: boolean;

  /**
   * Whether this connection has completed authentication before for the Websocket API, so it knows to automatically reauth if reconnected
   */
  didAuthWSAPI?: boolean;

  /** To reauthenticate on the WS API, which channel do we send to? */
  WSAPIAuthChannel?: string;
}
⋮----
/** The currently active websocket connection */
⋮----
/** The current lifecycle state of the connection (enum) */
⋮----
/** A timer that will send an upstream heartbeat (ping) when it expires */
⋮----
/** A timer tracking that an upstream heartbeat was sent, expecting a reply before it expires */
⋮----
/** If a reconnection is in progress, this will have the timer for the delayed reconnect */
⋮----
/**
   * When a connection attempt is in progress (even for reconnect), a promise is stored here.
   *
   * This promise will resolve once connected (and will then get removed);
   */
⋮----
/**
   * All the topics we are expected to be subscribed to on this connection (and we automatically resubscribe to if the connection drops)
   *
   * A "Set" and a deep-object-match are used to ensure we only subscribe to a topic once (tracking a list of unique topics we're expected to be connected to)
   */
⋮----
/** Whether this connection has completed authentication (only applies to private connections) */
⋮----
/**
   * Whether this connection has completed authentication before for the Websocket API, so it knows to automatically reauth if reconnected
   */
⋮----
/** To reauthenticate on the WS API, which channel do we send to? */

================
File: src/lib/misc-util.ts
================
export function neverGuard(x: never, msg: string): Error

================
File: src/lib/webCryptoAPI.ts
================
import { neverGuard } from './misc-util.js';
⋮----
function bufferToB64(buffer: ArrayBuffer): string
⋮----
function b64ToBytes(b64: string)
⋮----
function latin1ToBytes(s: string)
⋮----
export type SignEncodeMethod = 'hex' | 'base64' | 'binary';
export type SignAlgorithm = 'SHA-256' | 'SHA-512';
⋮----
/**
 * Similar to node crypto's `createHash()` function
 */
export async function hashMessage(
  message: string,
  method: SignEncodeMethod,
  algorithm: SignAlgorithm,
): Promise<string>
⋮----
// Equivalent in node:crypto:
// const signMessage = createHash(algorithm)
//   .update(signInput)
//   .digest('binary');
⋮----
export interface SignMessageOptions {
  isSecretB64Encoded?: boolean;
  isInputBinaryString?: boolean;
}
⋮----
/**
 * Sign a message, with a secret, using the Web Crypto API
 */
export async function signMessage(
  message: string,
  secret: string,
  method: SignEncodeMethod,
  algorithm: SignAlgorithm,
  options?: SignMessageOptions,
): Promise<string>
⋮----
export function checkWebCryptoAPISupported()

================
File: src/types/request/institutional.types.ts
================
// Custody API - List Vaults
⋮----
export type CustodyOrderDirection = 'asc' | 'desc';
export type CustodyCaseMatching = 'insensitive' | 'sensitive';
⋮----
// Filter types for vault listing
export type CustodyVaultFilterBy =
  | 'id'
  | 'name'
  | 'default_approvals'
  | 'created_at'
  | 'updated_at'
  | 'member';
⋮----
export type CustodyVaultOrderBy = 'id' | 'name' | 'created_at' | 'updated_at';
⋮----
// Individual filter types
export interface CustodyVaultFilterIdEquals {
  type: 'equals';
  values: string[];
  by: 'id';
}
⋮----
export interface CustodyVaultFilterNameEquals {
  type: 'equals';
  values: string[];
  case?: CustodyCaseMatching;
  by: 'name';
}
⋮----
export interface CustodyVaultFilterNameStartsWith {
  type: 'starts_with';
  values: string[];
  case?: CustodyCaseMatching;
  by: 'name';
}
⋮----
export interface CustodyVaultFilterNameContains {
  type: 'contains';
  values: string[];
  case?: CustodyCaseMatching;
  by: 'name';
}
⋮----
export interface CustodyVaultFilterDefaultApprovalsEquals {
  type: 'equals';
  values: number[];
  by: 'default_approvals';
}
⋮----
export interface CustodyVaultFilterDefaultApprovalsIn {
  type: 'in';
  left?: number;
  right?: number;
  by: 'default_approvals';
}
⋮----
export interface CustodyVaultFilterCreatedAtEquals {
  type: 'equals';
  values: string[];
  by: 'created_at';
}
⋮----
export interface CustodyVaultFilterCreatedAtIn {
  type: 'in';
  left?: string;
  right?: string;
  by: 'created_at';
}
⋮----
export interface CustodyVaultFilterUpdatedAtEquals {
  type: 'equals';
  values: string[];
  by: 'updated_at';
}
⋮----
export interface CustodyVaultFilterUpdatedAtIn {
  type: 'in';
  left?: string;
  right?: string;
  by: 'updated_at';
}
⋮----
export interface CustodyVaultFilterMemberEquals {
  type: 'equals';
  values: string[];
  by: 'member';
}
⋮----
export type CustodyVaultFilterCondition =
  | CustodyVaultFilterIdEquals
  | CustodyVaultFilterNameEquals
  | CustodyVaultFilterNameStartsWith
  | CustodyVaultFilterNameContains
  | CustodyVaultFilterDefaultApprovalsEquals
  | CustodyVaultFilterDefaultApprovalsIn
  | CustodyVaultFilterCreatedAtEquals
  | CustodyVaultFilterCreatedAtIn
  | CustodyVaultFilterUpdatedAtEquals
  | CustodyVaultFilterUpdatedAtIn
  | CustodyVaultFilterMemberEquals;
⋮----
export interface VaultFilterOr {
  or: CustodyVaultFilterCondition[];
}
⋮----
export interface VaultFilters {
  and?: VaultFilterOr[];
}
⋮----
export interface VaultPagination {
  limit: number;
  offset: number;
}
⋮----
export interface VaultOrdering {
  by: CustodyVaultOrderBy;
  direction?: CustodyOrderDirection;
}
⋮----
export interface CustodyListVaultsParams {
  nonce?: number;
  resolve_policies?: boolean | null;
  filters?: VaultFilters;
  pagination?: VaultPagination;
  orderings?: VaultOrdering[];
}
⋮----
// Custody API - Deposit Methods
export type CustodyAssetClass =
  | 'currency'
  | 'forex'
  | 'equity'
  | 'equitypair'
  | 'nft'
  | 'volume';
⋮----
export interface CustodyDepositMethodsParams {
  'x-vault-id': string;
  nonce?: number;
  asset?: string;
  category: 'custody';
  aclass?: string;
}
⋮----
// Custody API - Deposit Addresses
export interface CustodyDepositAddressesParams {
  'x-vault-id': string;
  nonce?: number;
  aclass?: CustodyAssetClass;
  asset: string;
  method: string;
  new?: boolean;
}
⋮----
// Custody API - List Custody Transactions
export type CustodyTransactionTypeReq =
  | 'unspecified'
  | 'deposit'
  | 'withdrawal'
  | 'trade'
  | 'margin'
  | 'adjustment'
  | 'rollover'
  | 'interest'
  | 'credit'
  | 'transfer'
  | 'transfer_peer_to_peer'
  | 'settle'
  | 'dividend'
  | 'nft_trade'
  | 'reward'
  | 'nft_creator_fee'
  | 'nft_rebate'
  | 'nft_airdrop'
  | 'simple_order'
  | 'simple_order_with_deposit'
  | 'simple_order_failed'
  | 'custom_simple_order'
  | 'custom_simple_order_with_deposit'
  | 'custom_simple_order_failed'
  | 'recurring_simple_order'
  | 'recurring_simple_order_with_deposit'
  | 'recurring_simple_order_failed'
  | 'simple_order_opposite_side'
  | 'reserved_fee'
  | 'fee_sweep'
  | 'ic_settlement'
  | 'fee_sweep_dlt'
  | 'reward_sweep'
  | 'reward_sweep_old'
  | 'interest_sweep'
  | 'conversion'
  | 'dust_sweep'
  | 'futures_transfer'
  | 'custody_transfer'
  | 'deposit_action'
  | 'withdrawal_action'
  | 'legacy_staking_allocation'
  | 'legacy_staking_deallocation'
  | 'legacy_staking_reward'
  | 'earn_legacy_migration'
  | 'block_trade'
  | 'equity_trade'
  | 'equity_acats'
  | 'earn_staking_allocation'
  | 'earn_staking_deallocation'
  | 'earn_staking_reward'
  | 'earn_staking_auto_allocation'
  | 'earn_oir_allocation'
  | 'earn_oir_deallocation'
  | 'earn_oir_reward'
  | 'earn_oir_auto_allocation'
  | 'earn_base_reward'
  | 'earn_base_auto_allocation'
  | 'earn_base_auto_deallocation'
  | 'custody_staking'
  | 'custody_unstaking'
  | 'custody_staking_reward'
  | 'custody_staking_reward_aggregated'
  | 'credit_rollover'
  | 'airdrop'
  | 'earn_oir_auto_deallocation'
  | 'earn_staking_auto_deallocation'
  | 'bridge_deposit'
  | 'bridge_simple_order'
  | 'simple_order_deposit_action'
  | 'otc_buy'
  | 'otc_sell'
  | 'bundle_trade'
  | 'equity_fee'
  | 'equity_journal'
  | 'corporate_action'
  | 'user_account_transfer'
  | 'earn_restaking'
  | 'subscription'
  | 'custody_otc_loan_pledge'
  | 'custody_otc_collateral_liquidation'
  | 'paytag_transfer'
  | 'paylink_transfer'
  | 'paytag_request_transfer'
  | 'paylink_request_transfer'
  | 'kard_transfer'
  | 'krak_card'
  | 'custody_otc_loan_release'
  | 'fpsl_reward'
  | 'fcm_trade'
  | 'boost'
  | 'fcm_misc';
⋮----
export type CustodyRefIdType =
  | 'funding'
  | 'trade'
  | 'adjustment'
  | 'transfer'
  | 'custody_transfer'
  | 'nft_transaction'
  | 'nft_id'
  | 'equity_trade'
  | 'legacy_staking_reward'
  | 'legacy_staking'
  | 'earn_ledger'
  | 'earn_strategy'
  | 'simple_trade'
  | 'simple_order_quote'
  | 'legacy_custody_transaction';
⋮----
export type CustodyTransactionAssetClassReq =
  | 'currency'
  | 'forex'
  | 'equity'
  | 'equity_pair'
  | 'nft'
  | 'derivatives'
  | 'tokenized_asset'
  | 'futures_contract';
⋮----
export interface CustodyQuoteAsset {
  asset: string;
  class: CustodyTransactionAssetClassReq;
}
⋮----
export interface CustodyTransactionAssetFilter {
  asset: string;
  class: CustodyTransactionAssetClassReq;
}
⋮----
export interface CustodyTransactionRefIdFilter {
  type: CustodyRefIdType;
  ref_id: string;
}
⋮----
export interface CustodyTransactionSorting {
  order?: 'descending' | 'ascending';
}
⋮----
export interface CustodyListTransactionsParams {
  id: string;
  nonce?: number;
  page_size?: number;
  quote?: CustodyQuoteAsset;
  preferred_asset_name?: string;
  sorting?: CustodyTransactionSorting;
  cursor?: string;
  types?: CustodyTransactionTypeReq[];
  ids?: string[];
  assets?: CustodyTransactionAssetFilter[];
  ref_ids?: CustodyTransactionRefIdFilter[];
}
⋮----
// Custody API - Get Transaction by ID
export interface CustodyGetTransactionParams {
  id: string;
  nonce?: number;
  vault_id: string;
  with_long_timeout?: boolean | null;
  quote?: CustodyQuoteAsset;
}
⋮----
// Custody API - Withdraw Methods
export interface CustodyWithdrawMethodsParams {
  'x-vault-id': string;
  nonce?: number;
  asset?: string | null;
  category: 'custody';
  aclass?: string;
  network?: string | null;
}
⋮----
// Custody API - Withdraw Addresses
export type CustodyWithdrawAddressAssetClass =
  | 'currency'
  | 'equity'
  | 'equity-pair'
  | 'forex'
  | 'nft'
  | 'volume';
⋮----
export interface CustodyWithdrawAddressesParams {
  'x-vault-id': string;
  preferred_asset_name?: 'new' | 'alt';
  nonce?: number;
  aclass?: CustodyWithdrawAddressAssetClass;
  asset?: string | null;
  method?: string | null;
  key?: string | null;
  verified?: boolean | null;
}
⋮----
// Custody API - List Tasks
export type CustodyTaskScope = 'domain' | 'vault';
⋮----
export type CustodyTaskStateReq =
  | 'pending'
  | 'approved'
  | 'denied'
  | 'canceled'
  | 'expired'
  | 'executed'
  | 'failed';
⋮----
export type CustodyTaskAction =
  | 'update_withdrawal_addresses'
  | 'request_withdrawal'
  | 'create_vault'
  | 'update_group_users'
  | 'update_role_users'
  | 'update_vault_users'
  | 'update_domain_policies'
  | 'update_vault_policies'
  | 'create_users'
  | 'update_vault'
  | 'update_status_users'
  | 'request_transfer_to_spot'
  | 'create_group'
  | 'update_permission_users'
  | 'create_api_users'
  | 'update_api_users'
  | 'update_vaults_users'
  | 'request_allocation'
  | 'request_deallocation';
⋮----
export type CustodyTaskUserDecisionReq = 'approved' | 'denied' | 'undecided';
⋮----
export type CustodyTaskOrderBy =
  | 'id'
  | 'vault_id'
  | 'state'
  | 'created_at'
  | 'updated_at'
  | 'expires_at';
⋮----
interface TaskFilterIdEquals {
  type: 'equals';
  values: string[];
  by: 'id';
}
⋮----
interface TaskFilterApprovalIdEquals {
  type: 'equals';
  values: string[];
  by: 'approval_id';
}
⋮----
interface TaskFilterVaultIdEquals {
  type: 'equals';
  values: string[];
  by: 'vault_id';
}
⋮----
interface TaskFilterScopeEquals {
  type: 'equals';
  values: CustodyTaskScope[];
  by: 'scope';
}
⋮----
interface TaskFilterStateEquals {
  type: 'equals';
  values: CustodyTaskStateReq[];
  by: 'state';
}
⋮----
interface TaskFilterActionEquals {
  type: 'equals';
  values: CustodyTaskAction[];
  by: 'action';
}
⋮----
interface TaskFilterCreatedAtEquals {
  type: 'equals';
  values: string[];
  by: 'created_at';
}
⋮----
interface TaskFilterUpdatedAtEquals {
  type: 'equals';
  values: string[];
  by: 'updated_at';
}
⋮----
interface TaskFilterExpiresAtEquals {
  type: 'equals';
  values: string[];
  by: 'expires_at';
}
⋮----
interface TaskFilterCurrentUserDecisionEquals {
  type: 'equals';
  values: CustodyTaskUserDecisionReq[];
  by: 'current_user_decision';
}
⋮----
export type CustodyTaskFilterCondition =
  | TaskFilterIdEquals
  | TaskFilterApprovalIdEquals
  | TaskFilterVaultIdEquals
  | TaskFilterScopeEquals
  | TaskFilterStateEquals
  | TaskFilterActionEquals
  | TaskFilterCreatedAtEquals
  | TaskFilterUpdatedAtEquals
  | TaskFilterExpiresAtEquals
  | TaskFilterCurrentUserDecisionEquals;
⋮----
export interface CustodyTaskFilterOr {
  or: CustodyTaskFilterCondition[];
}
⋮----
export interface CustodyTaskFilters {
  and?: CustodyTaskFilterOr[];
}
⋮----
export interface CustodyTaskOrdering {
  by: CustodyTaskOrderBy;
  direction?: CustodyOrderDirection;
}
⋮----
export interface CustodyListTasksParams {
  nonce?: number;
  filters?: CustodyTaskFilters;
  pagination?: VaultPagination;
  orderings?: CustodyTaskOrdering[];
}
⋮----
// Custody API - List Activities
type ActivityActionReq =
  | 'created'
  | 'review_approved'
  | 'review_denied'
  | 'canceled'
  | 'executed'
  | 'failed'
  | 'expired';
⋮----
type ActivityOrderBy = 'activity_created_at';
⋮----
interface ActivityFilterIdEquals {
  type: 'equals';
  values: string[];
  by: 'id';
}
⋮----
interface ActivityFilterScopeEquals {
  type: 'equals';
  values: CustodyTaskScope[];
  by: 'scope';
}
⋮----
interface ActivityFilterVaultIdEquals {
  type: 'equals';
  values: string[];
  by: 'vault_id';
}
⋮----
interface ActivityFilterTaskIdEquals {
  type: 'equals';
  values: string[];
  by: 'task_id';
}
⋮----
interface ActivityFilterApprovalIdEquals {
  type: 'equals';
  values: string[];
  by: 'approval_id';
}
⋮----
interface ActivityFilterTaskActionEquals {
  type: 'equals';
  values: CustodyTaskAction[];
  by: 'task_action';
}
⋮----
interface ActivityFilterActivityActionEquals {
  type: 'equals';
  values: ActivityActionReq[];
  by: 'activity_action';
}
⋮----
interface ActivityFilterCreatedAtEquals {
  type: 'equals';
  values: string[];
  by: 'created_at';
}
⋮----
interface ActivityFilterUserEquals {
  type: 'equals';
  values: string[];
  by: 'user';
}
⋮----
type ActivityFilterCondition =
  | ActivityFilterIdEquals
  | ActivityFilterScopeEquals
  | ActivityFilterVaultIdEquals
  | ActivityFilterTaskIdEquals
  | ActivityFilterApprovalIdEquals
  | ActivityFilterTaskActionEquals
  | ActivityFilterActivityActionEquals
  | ActivityFilterCreatedAtEquals
  | ActivityFilterUserEquals;
⋮----
interface ActivityFilterOr {
  or: ActivityFilterCondition[];
}
⋮----
interface ActivityFilters {
  and?: ActivityFilterOr[];
}
⋮----
interface ActivityOrdering {
  by: ActivityOrderBy;
  direction?: CustodyOrderDirection;
}
⋮----
export interface CustodyListActivitiesParams {
  nonce?: number;
  filters?: ActivityFilters;
  pagination?: VaultPagination;
  orderings?: ActivityOrdering[];
}
⋮----
// OTC REST API - Quotes
export type OtcQuoteType = 'buy' | 'sell';
export type OtcQuoteStatus = 'accepted' | 'rejected';
export type OtcSettlement = 'automated' | 'flexible';
⋮----
export interface OTCCreateQuoteRequestParams {
  nonce?: number;
  base: string;
  quote: string;
  amount?: string;
  total?: string;
  type: OtcQuoteType;
}
⋮----
export interface OTCUpdateQuoteParams {
  nonce?: number;
  quote_id: string;
  status: OtcQuoteStatus;
}

================
File: src/types/request/wsapi.types.ts
================
/**
 * Websocket API v2 Spot Request Types
 */
⋮----
export interface WSAPIAddSpotOrderParams {
  order_type:
    | 'limit'
    | 'market'
    | 'iceberg'
    | 'stop-loss'
    | 'stop-loss-limit'
    | 'take-profit'
    | 'take-profit-limit'
    | 'trailing-stop'
    | 'trailing-stop-limit'
    | 'settle-position';
  side: 'buy' | 'sell';
  order_qty: number;
  symbol: string;
  limit_price?: number;
  limit_price_type?: 'static' | 'pct' | 'quote';
  triggers?: {
    reference?: 'index' | 'last';
    price: number;
    price_type?: 'static' | 'pct' | 'quote';
  };
  time_in_force?: 'gtc' | 'gtd' | 'ioc';
  margin?: boolean;
  post_only?: boolean;
  reduce_only?: boolean;
  effective_time?: string;
  expire_time?: string;
  deadline?: string;
  cl_ord_id?: string;
  order_userref?: number;
  conditional?: {
    order_type:
      | 'limit'
      | 'stop-loss'
      | 'stop-loss-limit'
      | 'take-profit'
      | 'take-profit-limit'
      | 'trailing-stop'
      | 'trailing-stop-limit';
    limit_price?: number;
    limit_price_type?: 'static' | 'pct' | 'quote';
    trigger_price?: number;
    trigger_price_type?: 'static' | 'pct' | 'quote';
    stop_price?: number;
  };
  display_qty?: number;
  fee_preference?: 'base' | 'quote';
  no_mpp?: boolean;
  stp_type?: 'cancel_newest' | 'cancel_oldest' | 'cancel_both';
  cash_order_qty?: number;
  validate?: boolean;
  sender_sub_id?: string;
}
⋮----
export interface WSAPIAmendSpotOrderParams {
  order_id?: string;
  cl_ord_id?: string;
  order_qty: number;
  display_qty?: number;
  limit_price?: number;
  limit_price_type?: 'static' | 'pct' | 'quote';
  post_only?: boolean;
  trigger_price?: number;
  trigger_price_type?: 'static' | 'pct' | 'quote';
  deadline?: string;
  symbol?: string;
}
⋮----
export interface WSAPICancelSpotOrderParams {
  order_id?: string[];
  cl_ord_id?: string[];
  order_userref?: number[];
}
⋮----
export interface WSAPICancelAllSpotOrdersAfterParams {
  timeout: number;
}
⋮----
export interface WSAPIBatchAddSpotOrdersParams {
  deadline?: string;
  symbol: string;
  validate?: boolean;
  orders: Omit<WSAPIAddSpotOrderParams, 'symbol'>[];
}
⋮----
export interface WSAPIBatchCancelSpotOrdersParams {
  orders: string[];
  cl_ord_id?: string[];
}
⋮----
export interface WSAPIEditSpotOrderParams {
  order_id: string;
  symbol: string;
  order_qty?: number;
  limit_price?: number;
  display_qty?: number;
  triggers?: {
    reference?: 'index' | 'last';
    price: number;
    price_type?: 'static' | 'pct' | 'quote';
  };
  post_only?: boolean;
  reduce_only?: boolean;
  fee_preference?: 'base' | 'quote';
  no_mpp?: boolean;
  order_userref?: number;
  deadline?: string;
  validate?: boolean;
}

================
File: src/types/response/institutional.types.ts
================
// Custody API - Response Types
⋮----
export type CustodyVaultStatus = 'pending' | 'created' | 'failed' | 'disabled';
⋮----
export interface CustodyVault {
  id: string;
  created_at: string;
  updated_at: string;
  count_assets: number;
  status: CustodyVaultStatus;
  iiban: string;
  deposit_lock_rekeying_only?: boolean | null;
  name: string;
  description?: string | null;
  balance_fiat?: string | null;
  balance_diff?: string | null;
  available_balance_fiat?: string | null;
  otc_enabled?: boolean;
}
⋮----
export interface CustodyApiError {
  severity: 'E' | 'W';
  errorClass: string;
  type: string;
  errorMessage?: string | null;
}
⋮----
export interface CustodyListVaultsResponse {
  result?: CustodyVault[] | null;
  errors?: CustodyApiError[];
  start?: number;
  total?: number;
}
⋮----
// Custody API - Get Vault Information by ID
export interface CustodyAssetBalance {
  current_usd_value?: string | null;
  quantity: string;
}
⋮----
export interface CustodyVaultAssetDetail {
  asset: string;
  current_usd_price?: string | null;
  available_balance: CustodyAssetBalance;
  total_balance: CustodyAssetBalance;
}
⋮----
export interface CustodyVaultWithAssets extends CustodyVault {
  asset_details: CustodyVaultAssetDetail[];
}
⋮----
export interface CustodyGetVaultResponse {
  result?: CustodyVaultWithAssets | null;
  errors: CustodyApiError[];
}
⋮----
// Custody API - Deposit Methods
export interface CustodyDepositMethod {
  method?: string;
  limit?: string | boolean;
  fee?: string;
  'fee-percentage'?: string | null;
  'address-setup-fee'?: string | null;
  'gen-address'?: boolean | null;
  minimum?: string | null;
}
⋮----
export interface CustodyDepositMethodsResponse {
  result?: CustodyDepositMethod[] | null;
  error: CustodyApiError[];
}
⋮----
// Custody API - Deposit Addresses
export interface CustodyDepositAddress {
  address: string;
  expiretm?: string;
  memo?: string | null;
  new?: boolean | null;
  tag?: string | null;
}
⋮----
export interface CustodyDepositAddressesResponse {
  error: CustodyApiError[];
  result?: CustodyDepositAddress[] | null;
}
⋮----
// Custody API - Transaction Types (Shared)
export type CustodyTransactionType =
  | 'unspecified'
  | 'deposit'
  | 'withdrawal'
  | 'trade'
  | 'margin'
  | 'adjustment'
  | 'rollover'
  | 'interest'
  | 'credit'
  | 'transfer'
  | 'transfer_peer_to_peer'
  | 'settle'
  | 'dividend'
  | 'nft_trade'
  | 'reward'
  | 'nft_creator_fee'
  | 'nft_rebate'
  | 'nft_airdrop'
  | 'simple_order'
  | 'simple_order_with_deposit'
  | 'simple_order_failed'
  | 'custom_simple_order'
  | 'custom_simple_order_with_deposit'
  | 'custom_simple_order_failed'
  | 'recurring_simple_order'
  | 'recurring_simple_order_with_deposit'
  | 'recurring_simple_order_failed'
  | 'simple_order_opposite_side'
  | 'reserved_fee'
  | 'fee_sweep'
  | 'ic_settlement'
  | 'fee_sweep_dlt'
  | 'reward_sweep'
  | 'reward_sweep_old'
  | 'interest_sweep'
  | 'conversion'
  | 'dust_sweep'
  | 'futures_transfer'
  | 'custody_transfer'
  | 'deposit_action'
  | 'withdrawal_action'
  | 'legacy_staking_allocation'
  | 'legacy_staking_deallocation'
  | 'legacy_staking_reward'
  | 'earn_legacy_migration'
  | 'block_trade'
  | 'equity_trade'
  | 'equity_acats'
  | 'earn_staking_allocation'
  | 'earn_staking_deallocation'
  | 'earn_staking_reward'
  | 'earn_staking_auto_allocation'
  | 'earn_oir_allocation'
  | 'earn_oir_deallocation'
  | 'earn_oir_reward'
  | 'earn_oir_auto_allocation'
  | 'earn_base_reward'
  | 'earn_base_auto_allocation'
  | 'earn_base_auto_deallocation'
  | 'custody_staking'
  | 'custody_unstaking'
  | 'custody_staking_reward'
  | 'custody_staking_reward_aggregated'
  | 'credit_rollover'
  | 'airdrop'
  | 'earn_oir_auto_deallocation'
  | 'earn_staking_auto_deallocation'
  | 'bridge_deposit'
  | 'bridge_simple_order'
  | 'simple_order_deposit_action'
  | 'otc_buy'
  | 'otc_sell'
  | 'bundle_trade'
  | 'equity_fee'
  | 'equity_journal'
  | 'corporate_action'
  | 'user_account_transfer'
  | 'earn_restaking'
  | 'subscription'
  | 'custody_otc_loan_pledge'
  | 'custody_otc_collateral_liquidation'
  | 'paytag_transfer'
  | 'paylink_transfer'
  | 'paytag_request_transfer'
  | 'paylink_request_transfer'
  | 'kard_transfer'
  | 'krak_card'
  | 'custody_otc_loan_release'
  | 'fpsl_reward'
  | 'fcm_trade'
  | 'boost'
  | 'fcm_misc';
⋮----
export type CustodyTransactionCategory =
  | 'unspecified'
  | 'deposit'
  | 'withdrawal'
  | 'transfer'
  | 'krak_card'
  | 'trade'
  | 'margin_trade'
  | 'margin_rollover'
  | 'margin_settle'
  | 'earn'
  | 'earn_rewards'
  | 'simple_trading'
  | 'nft'
  | 'block_trade'
  | 'credit'
  | 'equity_trade'
  | 'equity_acats'
  | 'equity_dividend'
  | 'reward_bonus'
  | 'conversion'
  | 'reward'
  | 'custody'
  | 'legacy_staking'
  | 'legacy_staking_rewards'
  | 'equity_fee'
  | 'equity_journal'
  | 'corporate_action'
  | 'fpsl_reward'
  | 'subscription'
  | 'other';
⋮----
export type CustodyTransactionArea =
  | 'unspecified'
  | 'funding'
  | 'transfer'
  | 'krak_card'
  | 'spot_margin'
  | 'equity'
  | 'earn'
  | 'simple_trading'
  | 'custody'
  | 'staking'
  | 'nft'
  | 'other';
⋮----
export type CustodyTransactionStatus =
  | 'unspecified'
  | 'in_progress'
  | 'successful'
  | 'failed';
⋮----
export type CustodyTransactionAssetClass =
  | 'currency'
  | 'forex'
  | 'equity'
  | 'equity_pair'
  | 'nft'
  | 'derivatives'
  | 'tokenized_asset'
  | 'futures_contract';
⋮----
export interface CustodyTransactionAmount {
  amount: string;
  asset: string;
  class: CustodyTransactionAssetClass;
}
⋮----
export interface CustodyTransactionSide {
  ledger_id?: string | null;
  time?: string | null;
  subtype?: string | null;
  amount: CustodyTransactionAmount;
  quoted_amount?: CustodyTransactionAmount | null;
  fee?: CustodyTransactionAmount | null;
  quoted_fee?: CustodyTransactionAmount | null;
  total?: CustodyTransactionAmount | null;
  quoted_total?: CustodyTransactionAmount | null;
  balance?: CustodyTransactionAmount | null;
  wallet?: Record<string, any> | null;
}
⋮----
export interface CustodyTransaction {
  id: string;
  time: string;
  type: CustodyTransactionType;
  category: CustodyTransactionCategory;
  area: CustodyTransactionArea;
  status?: CustodyTransactionStatus | null;
  ref_id: string;
  ref_id2?: string | null;
  spend?: CustodyTransactionSide | null;
  receive?: CustodyTransactionSide | null;
  details?: Record<string, any> | null;
}
⋮----
export interface CustodyTransactionStats {
  transactions_seen?: number;
}
⋮----
export interface CustodyListTransactionsResponse {
  result?: {
    transactions: CustodyTransaction[];
    stats?: CustodyTransactionStats | null;
    next_cursor?: string | null;
  } | null;
  errors: CustodyApiError[];
}
⋮----
// Custody API - Get Transaction by ID
export type CustodyTransactionResultType =
  | 'complete'
  | 'incomplete_requires_long_timeout'
  | 'incomplete';
⋮----
export interface CustodyGetTransactionResponse {
  error: CustodyApiError[];
  result?: {
    transaction: CustodyTransaction;
    result_type: CustodyTransactionResultType;
  } | null;
}
⋮----
// Custody API - Withdraw Methods
export interface CustodyWithdrawMethodLimit {
  remaining: string | number;
  maximum: string | number;
}
⋮----
export interface CustodyWithdrawMethodLimitInfo {
  limit_type: string;
  description?: string | null;
  limits: Record<string, CustodyWithdrawMethodLimit>;
}
⋮----
export interface CustodyWithdrawMethodFee {
  aclass: string;
  asset: string;
  fee: string;
  fee_percentage?: string | null;
}
⋮----
export interface CustodyWithdrawMethod {
  asset: string;
  method_id?: string | null;
  method?: string | null;
  network_id?: string | null;
  network?: string | null;
  minimum?: string | null;
  limits?: CustodyWithdrawMethodLimitInfo[] | null;
  fee?: CustodyWithdrawMethodFee | null;
}
⋮----
export interface CustodyWithdrawMethodsResponse {
  error: CustodyApiError[];
  result?: CustodyWithdrawMethod[] | null;
}
⋮----
// Custody API - Withdraw Addresses
export interface CustodyWithdrawAddress {
  address?: string | null;
  asset?: string | null;
  method?: string | null;
  key?: string | null;
  verified: boolean;
  memo?: string | null;
  tag?: string | null;
  networks?: string[] | null;
}
⋮----
export interface CustodyWithdrawAddressesResponse {
  error: CustodyApiError[];
  result?: CustodyWithdrawAddress[] | null;
}
⋮----
// Custody API - Tasks
export type CustodyUserRole = 'admin' | 'initiator' | 'reviewer' | 'auditor';
⋮----
export interface CustodyTaskUser {
  full_name?: string | null;
  role?: CustodyUserRole | null;
  ip_address?: string | null;
  iiban?: string | null;
}
⋮----
export interface CustodyTaskReviewerStatistics {
  current_count: number;
  approved: number;
  denied: number;
  undecided: number;
}
⋮----
export type CustodyTaskState =
  | 'pending'
  | 'approved'
  | 'denied'
  | 'canceled'
  | 'expired'
  | 'executed'
  | 'failed';
⋮----
export type CustodyTaskUserDecision = 'approved' | 'denied' | 'undecided';
⋮----
export interface CustodyTask {
  can_review: boolean;
  reviewer_statistics: CustodyTaskReviewerStatistics;
  current_user_decision: CustodyTaskUserDecision;
  id: string;
  approval_id: string;
  created_at: string;
  updated_at: string;
  expires_at: string;
  initiator: CustodyTaskUser;
}
⋮----
export interface CustodyListTasksResponse {
  result?: CustodyTask[] | null;
  errors: CustodyApiError[];
  start: number;
  total: number;
}
⋮----
// Custody API - Get Task by ID
export interface CustodyTaskDetails {
  state: CustodyTaskState;
  [key: string]: any; // Task details vary based on action type
}
⋮----
[key: string]: any; // Task details vary based on action type
⋮----
export interface CustodyGetTaskResponse {
  result?: CustodyTaskDetails | null;
  errors: CustodyApiError[];
}
⋮----
// Custody API - Activities
export type CustodyActivityAction =
  | 'created'
  | 'review_approved'
  | 'review_denied'
  | 'canceled'
  | 'executed'
  | 'failed'
  | 'expired';
⋮----
export interface CustodyActivity {
  task: CustodyTaskDetails;
  id: string;
  created_at: string;
}
⋮----
export interface CustodyListActivitiesResponse {
  result?: CustodyActivity[] | null;
  errors: CustodyApiError[];
  start: number;
  total: number;
}
⋮----
// Custody API - Get Activity by ID
export interface CustodyActivityDetails {
  type: CustodyActivityAction;
  comment?: string | null;
  user: CustodyTaskUser;
  [key: string]: any; // Activity details vary based on type
}
⋮----
[key: string]: any; // Activity details vary based on type
⋮----
export interface CustodyGetActivityResponse {
  result?: CustodyActivityDetails | null;
  errors: CustodyApiError[];
}
⋮----
// OTC REST API - Quotes
export interface OtcQuote {
  [key: string]: any; // Quote details vary
}
⋮----
[key: string]: any; // Quote details vary
⋮----
export interface OTCCreateQuoteResponse {
  result?: {
    quote: OtcQuote;
  };
  error: string[];
}
⋮----
export interface OTCUpdateQuoteResponse {
  result?: {
    quote_id?: string;
  };
  error: string[];
}
⋮----
export interface OtcPair {
  base: string;
  quote: string;
  pair_name: string;
  pair_decimals: number;
  lot_decimals: number;
  cost_decimals: number;
  max_base_amount: string;
  max_notional?: string;
  min_base_amount?: string;
  min_notional?: string;
}
⋮----
export interface OTCGetPairsResponse {
  result: {
    spot_pairs: OtcPair[];
  };
  error: string[];
}
⋮----
export interface OtcActiveQuote {
  expires: {
    time: number;
  };
  quote_id: string;
  client_order_id?: string | null;
  base: string;
  quote: string;
  type: string;
  price?: string;
  amount: string;
  total?: string;
  settlement: string;
}
⋮----
export interface OTCGetActiveQuotesResponse {
  result?: OtcActiveQuote[];
  error: string[];
}
⋮----
export interface OtcHistoricalQuote {
  trade_id?: string | null;
  status?: string | null;
  acceptance: {
    status: string;
    time: number;
  };
  settlement_status: string;
  quote_id: string;
  client_order_id?: string | null;
  base: string;
  quote: string;
  type: string;
  price: string;
  amount: string;
  total: string;
  settlement: string;
}
⋮----
export interface OTCGetHistoricalQuotesResponse {
  result?: OtcHistoricalQuote[];
  error: string[];
}
⋮----
export interface OtcExposures {
  max_otc: string;
  max_rfq: string;
  used_otc: string;
  used_rfq: string;
}
⋮----
export interface OTCGetExposuresResponse {
  result?: OtcExposures;
  error: string[];
}
⋮----
export interface OTCCheckClientResponse {
  result?: {
    permissions: string[];
  };
  error: string[];
}

================
File: src/types/response/ws.ts
================
export interface WsServerInfo {
  endpoint: string;
  encrypt: boolean;
  protocol: string;
  pingInterval: number;
  pingTimeout: number;
}
⋮----
export interface WsConnectionInfo {
  token: string;
  instanceServers: WsServerInfo[];
}

================
File: src/types/websockets/ws-events.ts
================
export interface WsDataEvent<TData = any, TWSKey = string> {
  data: TData;
  table: string;
  wsKey: TWSKey;
}
⋮----
export interface MessageEventLike {
  target: WebSocket;
  type: 'message';
  data: string;
}
⋮----
export function isMessageEvent(msg: unknown): msg is MessageEventLike

================
File: src/index.ts
================


================
File: .eslintrc.cjs
================
// 'no-unused-vars': ['warn'],

================
File: .nvmrc
================
v22.21.0

================
File: .prettierrc
================
{
  "tabWidth": 2,
  "singleQuote": true
}

================
File: LICENSE.md
================
Copyright 2025 Tiago Siebler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

================
File: postBuild.sh
================
#!/bin/bash
#
#   Add package.json files to cjs/mjs subtrees
#

cat >dist/cjs/package.json <<!EOF
{
    "type": "commonjs"
}
!EOF

cat >dist/mjs/package.json <<!EOF
{
    "type": "module"
}
!EOF

find src -name '*.d.ts' -exec cp {} dist/mjs \;
find src -name '*.d.ts' -exec cp {} dist/cjs \;

================
File: tsconfig.cjs.json
================
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "dist/cjs",
    "target": "esnext"
  },
  "include": ["src/**/*.*"]
}

================
File: tsconfig.esm.json
================
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "esnext",
    "outDir": "dist/mjs",
    "target": "esnext"
  },
  "include": ["src/**/*.*"]
}

================
File: tsconfig.json
================
{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true,
    "baseUrl": ".",
    "noEmitOnError": true,
    "declaration": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": false,
    "inlineSourceMap": false,
    "lib": ["esnext"],
    "listEmittedFiles": false,
    "listFiles": false,
    "moduleResolution": "node",
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedParameters": true,
    "pretty": true,
    "removeComments": false,
    "resolveJsonModule": true,
    "skipLibCheck": false,
    "sourceMap": true,
    "strict": true,
    "strictNullChecks": true,
    "types": ["node", "jest"],
    "module": "commonjs",
    "outDir": "dist/cjs",
    "target": "esnext"
  },
  "compileOnSave": true,
  "exclude": ["node_modules", "dist"],
  "include": ["src/**/*.*", "test/**/*.*", ".eslintrc.cjs"]
}

================
File: tsconfig.linting.json
================
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "dist/cjs",
    "target": "esnext",
    "rootDir": "../",
    "allowJs": true
  },
  "include": [
    "src/**/*.*",
    "test/**/*.*",
    "examples/**/*.*",
    ".eslintrc.cjs",
    "jest.config.ts"
  ]
}

================
File: examples/Derivatives/Public/marketData.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { DerivativesClient } from '../../../src/index.js';
⋮----
// 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 FUTURES PUBLIC MARKET DATA that requires no authentication
⋮----
/**
 * import { DerivativesClient } from '@siebly/kraken-api';
 */
⋮----
// you can initialise public client without api keys as public calls do not require auth
⋮----
async function getAllTickers()
⋮----
// Get all tickers (all Futures contracts and indices)
⋮----
// Response includes for each ticker:
// - symbol: Market symbol (e.g., PF_BTCUSD)
// - last: Last fill price
// - markPrice: Current mark price for margining
// - bid/ask: Best bid/ask prices
// - vol24h: 24h volume
// - openInterest: Current open interest
// - fundingRate: Current funding rate (perpetuals only)
⋮----
async function getTickerBySymbol()
⋮----
// Get ticker for specific Futures symbol
⋮----
symbol: 'PF_ETHUSD', // Perpetual BTC/USD
⋮----
async function getOrderBook()
⋮----
// Get order book for specific Futures contract
⋮----
// Response includes:
// - bids: Array of [price, size] sorted descending by price
// - asks: Array of [price, size] sorted ascending by price
⋮----
async function getTradeHistory()
⋮----
// Get recent trade history (last 100 trades)
⋮----
// Response includes:
// - price: Fill price
// - side: Taker side (buy/sell)
// - size: Fill size
// - time: Trade timestamp
// - type: Trade type (fill, liquidation, assignment, etc.)
⋮----
async function getTradeHistoryWithTime()
⋮----
// Get trades before specific time (last 100 trades before specified time)
⋮----
before: Date.now() - 3600000, // 1 hour ago
⋮----
// Returns up to 100 trades prior to before time (max 7 days back)
⋮----
async function getInstruments()
⋮----
// Get all available Futures instruments
⋮----
// Response includes for each instrument:
// - symbol: Market symbol
// - type: Instrument type (flexible_futures, futures_inverse, etc.)
// - underlying: Underlying asset
// - tickSize: Minimum price increment
// - contractSize: Contract size
// - tradeable: Whether instrument is tradeable
⋮----
async function getFeeSchedules()
⋮----
// Get fee schedules for Futures trading
⋮----
// Response includes maker and taker fees by tier
⋮----
async function getPublicExecutionEvents()
⋮----
async function getPublicOrderEvents()
⋮----
async function getPublicMarkPriceEvents()
⋮----
async function getCandles()
⋮----
// Get OHLC candles for Futures
⋮----
tickType: 'trade', // spot, mark, or trade
⋮----
resolution: '1h', // 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w
⋮----
// Response includes:
// - candles: Array of OHLC candles
//   - time: Timestamp in ms
//   - open, high, low, close: Prices
//   - volume: Volume
// - more_candles: True if more candles available
⋮----
async function getCandlesWithTimeRange()
⋮----
// Get candles for specific time range
⋮----
from: Math.floor((Date.now() - 86400000 * 7) / 1000), // 7 days ago (epoch seconds)
to: Math.floor(Date.now() / 1000), // now (epoch seconds)
⋮----
async function getCandlesWithCount()
⋮----
// Get specific number of most recent candles
⋮----
tickType: 'mark', // Use mark price candles
⋮----
// Tick types:
// - trade: Trade price candles
// - mark: Mark price candles
// - spot: Spot price candles
⋮----
// Uncomment the function you want to test:
⋮----
// getAllTickers();
// getTickerBySymbol();
// getOrderBook();
// getTradeHistory();
// getTradeHistoryWithTime();
// getInstruments();
// getFeeSchedules();
// getPublicExecutionEvents();
// getPublicOrderEvents();
// getPublicMarkPriceEvents();
// getCandles();
// getCandlesWithTimeRange();
// getCandlesWithCount();

================
File: examples/Derivatives/WebSockets/testnetWs.ts
================
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import {
  DefaultLogger,
  LogParams,
  WebsocketClient,
  WS_KEY_MAP,
  WSTopicRequest,
} from '../../../src/index.js';
import { WSDerivativesTopic } from '../../../src/types/websockets/ws-subscriptions.js';
// normally you should install this module via npm: `npm install @siebly/kraken-api` and import the module:
// import { LogParams, WebsocketClient, WsTopicRequest } from '@siebly/kraken-api';
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log(new Date(), '--> trace', ...params);
⋮----
async function start()
⋮----
// https://demo-futures.kraken.com to create demo account
⋮----
/**
   * Kraken Derivatives has a demo environment (testnet) that you can connect to via WebSocket. All you need to do is set the `testnet` option to `true` when creating the WebsocketClient instance, as shown below.
   * Everything else behaves exactly the same way.
   *
   * Note: as of November 2025, only the DerivativesClient supports testnet connections. Kraken refer to this as the "Demo" environment, but it is effectively a testnet.
   * This is a place to test your API integration. It is not a good place to test strategy performance, as the liquidity and orderbook dynamics are very different to the live environment.
   *
   * Refer to the following for more information:
   * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/CEX-Testnets
   */
⋮----
// Data received
⋮----
// Something happened, attempting to reconnect
⋮----
// Reconnect successful
⋮----
// Connection closed. If unexpected, expect reconnect -> reconnected.
⋮----
// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
⋮----
/**
   * 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.
   */
⋮----
/**
     * 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
⋮----
// 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
⋮----
// Fills: https://docs.kraken.com/api/docs/futures-api/websocket/fills
⋮----
// Optionally, the product_ids field can be used to subscribe only to specific product.
// payload: {
//   product_ids: ['PF_XBTUSD'],
// },
⋮----
// Balances: https://docs.kraken.com/api/docs/futures-api/websocket/balances
⋮----
// Open Position: https://docs.kraken.com/api/docs/futures-api/websocket/open_position
⋮----
// Account Log: https://docs.kraken.com/api/docs/futures-api/websocket/account_log
⋮----
// Notification: https://docs.kraken.com/api/docs/futures-api/websocket/notifications

================
File: src/types/request/partner.types.ts
================
// Partner API request types
⋮----
/**
 * Create User request parameters
 */
export interface PartnerCreateUserParams {
  email: string;
  external_id: string;
  tos_version_accepted: number;
  full_name: {
    first_name: string;
    middle_name?: string;
    last_name: string;
  };
  date_of_birth: string; // format: date (YYYY-MM-DD)
  residence: {
    line1: string;
    line2?: string;
    city: string;
    postal_code: string;
    province?: string;
    country: string; // CountryCode
  };
  phone: string; // E.164 format
  nationalities: string[]; // CountryCode[]
  occupation:
    | 'agriculture'
    | 'business_management'
    | 'computers_and_it'
    | 'construction'
    | 'education'
    | 'finance'
    | 'government'
    | 'healthcare'
    | 'hospitality'
    | 'manufacturing'
    | 'marketing'
    | 'media'
    | 'other'
    | 'science'
    | 'self_employed'
    | 'student'
    | 'transportation'
    | 'unemployed';
  city_of_birth?: string;
  country_of_birth?: string; // CountryCode
  tax_ids?: Array<{
    id: string;
    issuing_country: string; // CountryCode
  }>;
  language?: string; // ISO 639-1 language code
}
⋮----
date_of_birth: string; // format: date (YYYY-MM-DD)
⋮----
country: string; // CountryCode
⋮----
phone: string; // E.164 format
nationalities: string[]; // CountryCode[]
⋮----
country_of_birth?: string; // CountryCode
⋮----
issuing_country: string; // CountryCode
⋮----
language?: string; // ISO 639-1 language code
⋮----
/**
 * Update User request parameters
 */
export interface PartnerUpdateUserParams {
  user: string;
  tos_version_accepted?: number;
  full_name?: {
    first_name: string;
    middle_name?: string;
    last_name: string;
  };
  date_of_birth?: string; // format: date (YYYY-MM-DD)
  city_of_birth?: string;
  country_of_birth?: string; // CountryCode
  residence?: {
    line1: string;
    line2?: string;
    city: string;
    postal_code: string;
    province?: string;
    country: string; // CountryCode
  };
  phone?: string; // E.164 format
  nationalities?: string[]; // CountryCode[]
  tax_ids?: Array<{
    id: string;
    issuing_country: string; // CountryCode
  }>;
  occupation?:
    | 'agriculture'
    | 'business_management'
    | 'computers_and_it'
    | 'construction'
    | 'education'
    | 'finance'
    | 'government'
    | 'healthcare'
    | 'hospitality'
    | 'manufacturing'
    | 'marketing'
    | 'media'
    | 'other'
    | 'science'
    | 'self_employed'
    | 'student'
    | 'transportation'
    | 'unemployed';
  language?: string; // ISO 639-1 language code
}
⋮----
date_of_birth?: string; // format: date (YYYY-MM-DD)
⋮----
country_of_birth?: string; // CountryCode
⋮----
country: string; // CountryCode
⋮----
phone?: string; // E.164 format
nationalities?: string[]; // CountryCode[]
⋮----
issuing_country: string; // CountryCode
⋮----
language?: string; // ISO 639-1 language code
⋮----
/**
 * Submit Verification request parameters
 */
export interface PartnerSubmitVerificationParams {
  user: string;
  type: 'identity_document';
  metadata: {
    identity: {
      full_name: {
        first_name: string;
        middle_name?: string;
        last_name: string;
      };
      date_of_birth: string; // format: date (YYYY-MM-DD)
    };
    document_type:
      | 'passport'
      | 'drivers_license'
      | 'id_card'
      | 'residence_card'
      | 'special_permanent_residence_card';
    document_number: string;
    issuing_country: string; // CountryCode
    nationality?: string; // CountryCode
  };
  verifier: string; // Name of the verification provider
  verified_at: string; // ISO 8601 datetime
  verifier_response?: any;
  external_verification_id?: string;
  expiration_date?: string; // ISO 8601 date
  front: any; // File binary for front side of document
  back: any; // File binary for back side of document
  verifier_response_file?: any; // File binary for verifier response
}
⋮----
date_of_birth: string; // format: date (YYYY-MM-DD)
⋮----
issuing_country: string; // CountryCode
nationality?: string; // CountryCode
⋮----
verifier: string; // Name of the verification provider
verified_at: string; // ISO 8601 datetime
⋮----
expiration_date?: string; // ISO 8601 date
front: any; // File binary for front side of document
back: any; // File binary for back side of document
verifier_response_file?: any; // File binary for verifier response
⋮----
/**
 * List Assets request parameters
 */
export interface PartnerListAssetsParams {
  'filter[user]'?: string; // IIBAN
  'filter[assets][]'?: string[]; // AssetName[], max 100
  'filter[platform_statuses][]'?: Array<
    | 'enabled'
    | 'deposit_only'
    | 'withdrawal_only'
    | 'funding_temporarily_disabled'
    | 'disabled'
  >;
  'filter[tradable_only]'?: boolean;
  sort?:
    | 'trending'
    | 'market_cap_rank'
    | '-market_cap_rank'
    | 'symbol'
    | '-symbol'
    | 'name'
    | '-name'
    | 'change_percent_1h'
    | '-change_percent_1h'
    | 'change_percent_24h'
    | '-change_percent_24h'
    | 'change_percent_7d'
    | '-change_percent_7d'
    | 'change_percent_30d'
    | '-change_percent_30d'
    | 'change_percent_1y'
    | '-change_percent_1y'
    | 'listing_date'
    | '-listing_date';
  'page[size]'?: number; // 1-100
  'page[number]'?: number; // >= 1
  quote?: string; // AssetName, default USD
  lang?: string; // ISO language code, default en
}
⋮----
'filter[user]'?: string; // IIBAN
'filter[assets][]'?: string[]; // AssetName[], max 100
⋮----
'page[size]'?: number; // 1-100
'page[number]'?: number; // >= 1
quote?: string; // AssetName, default USD
lang?: string; // ISO language code, default en
⋮----
/**
 * Get Asset request parameters
 */
export interface PartnerGetAssetParams {
  asset: string;
  quote?: string; // AssetName, default USD
  lang?: string; // ISO language code, default en
}
⋮----
quote?: string; // AssetName, default USD
lang?: string; // ISO language code, default en
⋮----
/**
 * List Asset Rates request parameters
 */
export interface PartnerListAssetRatesParams {
  asset: string;
  quote?: string; // AssetName, default USD
  start_time?: string; // RFC 3339 datetime
  end_time?: string; // RFC 3339 datetime
  interval?: string; // ISO 8601 duration (PT15M, PT60M, P1D, etc.)
}
⋮----
quote?: string; // AssetName, default USD
start_time?: string; // RFC 3339 datetime
end_time?: string; // RFC 3339 datetime
interval?: string; // ISO 8601 duration (PT15M, PT60M, P1D, etc.)
⋮----
/**
 * Request Quote request parameters
 */
export interface PartnerRequestQuoteParams {
  user: string; // IIBAN
  type: 'receive' | 'spend'; // Type of quote
  amount: {
    asset_class?: 'currency';
    asset: string; // AssetName
    amount: string; // decimal128
  };
  quote: {
    asset: string; // AssetName
  };
  fee_bps: string; // Basis points
  spread_bps: string; // Basis points
  quote_currency?: string; // AssetName
}
⋮----
user: string; // IIBAN
type: 'receive' | 'spend'; // Type of quote
⋮----
asset: string; // AssetName
amount: string; // decimal128
⋮----
asset: string; // AssetName
⋮----
fee_bps: string; // Basis points
spread_bps: string; // Basis points
quote_currency?: string; // AssetName
⋮----
/**
 * Get Quote request parameters
 */
export interface PartnerGetQuoteParams {
  quote_id: string;
  user: string; // IIBAN
}
⋮----
user: string; // IIBAN
⋮----
/**
 * Execute Quote request parameters
 */
export interface PartnerExecuteQuoteParams {
  quote_id: string;
  user: string; // IIBAN
}
⋮----
user: string; // IIBAN
⋮----
/**
 * Get Portfolio Summary request parameters
 */
export interface PartnerGetPortfolioSummaryParams {
  user: string; // IIBAN
  quote?: string; // AssetName, default USD
  'include[current_day_pnl]'?: any; // Include the current day pnl
}
⋮----
user: string; // IIBAN
quote?: string; // AssetName, default USD
'include[current_day_pnl]'?: any; // Include the current day pnl
⋮----
/**
 * Get Portfolio History request parameters
 */
export interface PartnerGetPortfolioHistoryParams {
  user: string; // IIBAN
  'include[assets][]'?: string[]; // AssetName[]
  'include[total_balance]'?: boolean;
  'include[total_pnl]'?: boolean;
  start_date?: string; // date format
  end_date?: string; // date format
  resolution?: number; // uint32, default 1
  quote?: string; // AssetName, default USD
  cursor?: string; // Pagination cursor
}
⋮----
user: string; // IIBAN
'include[assets][]'?: string[]; // AssetName[]
⋮----
start_date?: string; // date format
end_date?: string; // date format
resolution?: number; // uint32, default 1
quote?: string; // AssetName, default USD
cursor?: string; // Pagination cursor
⋮----
/**
 * List Portfolio Details request parameters
 */
export interface PartnerListPortfolioDetailsParams {
  user: string; // IIBAN
  quote?: string; // AssetName, default USD
}
⋮----
user: string; // IIBAN
quote?: string; // AssetName, default USD
⋮----
/**
 * List Portfolio Transactions request parameters
 */
export interface PartnerListPortfolioTransactionsParams {
  user: string; // IIBAN
  cursor?: string;
  types?: Array<'simple_order' | 'simple_order_failed' | 'earn_reward'>;
  page_size?: number; // uint64
  assets?: string[]; // AssetName[], max 16 chars each
  from_time?: string; // date-time
  until_time?: string; // date-time
  statuses?: Array<
    'no_status' | 'unspecified' | 'in_progress' | 'successful' | 'failed'
  >;
  ids?: string[];
  sorting?: 'descending' | 'ascending';
  ref_ids?: any[]; // Simplified - array of reference ID filter objects
  quote?: string; // AssetName, max 16 chars
}
⋮----
user: string; // IIBAN
⋮----
page_size?: number; // uint64
assets?: string[]; // AssetName[], max 16 chars each
from_time?: string; // date-time
until_time?: string; // date-time
⋮----
ref_ids?: any[]; // Simplified - array of reference ID filter objects
quote?: string; // AssetName, max 16 chars
⋮----
/**
 * Get Earn Summary request parameters
 */
export interface PartnerGetEarnSummaryParams {
  user: string; // IIBAN
  currency?: string; // max 16 chars
}
⋮----
user: string; // IIBAN
currency?: string; // max 16 chars
⋮----
/**
 * List Earn Assets request parameters
 */
export interface PartnerListEarnAssetsParams {
  assets?: string[]; // AssetName[], max 16 chars each
  user?: string; // IIBAN, 14-42 chars
  currency?: string; // max 16 chars, required if user is set
}
⋮----
assets?: string[]; // AssetName[], max 16 chars each
user?: string; // IIBAN, 14-42 chars
currency?: string; // max 16 chars, required if user is set
⋮----
/**
 * Toggle Auto-Earn request parameters
 */
export interface PartnerToggleAutoEarnParams {
  user: string; // IIBAN
  want_enabled: boolean;
}
⋮----
user: string; // IIBAN
⋮----
/**
 * Withdraw Funds request parameters
 */
export interface PartnerWithdrawFundsParams {
  asset: string; // AssetName, 3-16 chars
  key: string; // Withdrawal key
  amount: string; // decimal128
}
⋮----
asset: string; // AssetName, 3-16 chars
key: string; // Withdrawal key
amount: string; // decimal128
⋮----
/**
 * List Funding Transactions request parameters
 */
export interface PartnerListFundingTransactionsParams {
  type: 'withdrawal' | 'deposit';
  cursor?: string;
  page_size?: number; // uint32, 1-500, default 25
}
⋮----
page_size?: number; // uint32, 1-500, default 25
⋮----
/**
 * List Settlement Reports request parameters
 */
export interface PartnerListSettlementReportsParams {
  'filter[start_date]'?: string; // RFC 3339 datetime
  'filter[end_date]'?: string; // RFC 3339 datetime
  'filter[report_type][]'?: Array<'trades' | 'transfers' | 'earn_rewards'>;
  'page[size]'?: number; // uint32, 1-100, default 20
  'page[number]'?: number; // uint32, >= 1, default 1
}
⋮----
'filter[start_date]'?: string; // RFC 3339 datetime
'filter[end_date]'?: string; // RFC 3339 datetime
⋮----
'page[size]'?: number; // uint32, 1-100, default 20
'page[number]'?: number; // uint32, >= 1, default 1
⋮----
/**
 * Get Settlement Report request parameters
 */
export interface PartnerGetSettlementReportParams {
  id: string;
}
⋮----
/**
 * Get Ramp Limits request parameters
 */
export interface PartnerGetRampLimitsParams {
  in_asset: string; // max 16 chars
  out_asset: string; // max 16 chars
  funding_type: string;
  withdrawal_method: string;
}
⋮----
in_asset: string; // max 16 chars
out_asset: string; // max 16 chars
⋮----
/**
 * Get Ramp Prospective Quote request parameters
 */
export interface PartnerGetRampProspectiveQuoteParams {
  in_asset: string; // max 16 chars
  in_amount: string; // decimal128
  out_asset: string; // max 16 chars
  funding_type: string;
  withdrawal_method: string;
}
⋮----
in_asset: string; // max 16 chars
in_amount: string; // decimal128
out_asset: string; // max 16 chars
⋮----
/**
 * Embed Custom Orders - Create Custom Order request parameters
 * Price-triggered custom orders. User in query, body has trigger, action, name.
 */
export interface PartnerCreateCustomOrderParams {
  user: string; // IIBAN, 14-42 chars
  trigger: {
    type: 'price';
    base_asset: string; // <= 16 chars
    quote_asset: string; // <= 16 chars
    target_price: string;
    condition: 'gte' | 'lte';
  };
  action: {
    type: 'receive' | 'spend';
    amount: {
      asset_class?: 'currency';
      asset: string; // <= 16 chars
      amount: string;
    };
    quote: {
      asset: string; // <= 16 chars
      fee_bps: string; // 1-5 digits
      spread_bps: string; // 1-5 digits
    };
  };
  name: string;
}
⋮----
user: string; // IIBAN, 14-42 chars
⋮----
base_asset: string; // <= 16 chars
quote_asset: string; // <= 16 chars
⋮----
asset: string; // <= 16 chars
⋮----
asset: string; // <= 16 chars
fee_bps: string; // 1-5 digits
spread_bps: string; // 1-5 digits
⋮----
/**
 * Embed Custom Orders - List Custom Orders request parameters
 */
export interface PartnerListCustomOrdersParams {
  user: string; // IIBAN, 14-42 chars
  statuses?: Array<'active' | 'cancelled' | 'completed'>;
  cursor?: string;
}
⋮----
user: string; // IIBAN, 14-42 chars
⋮----
/**
 * Embed Custom Orders - Get Custom Order request parameters
 */
export interface PartnerGetCustomOrderParams {
  user: string; // IIBAN, 14-42 chars
  order_id: string;
}
⋮----
user: string; // IIBAN, 14-42 chars
⋮----
/**
 * Embed Custom Orders - Cancel Custom Order request parameters
 */
export interface PartnerCancelCustomOrderParams {
  user: string; // IIBAN, 14-42 chars
  id: string; // order id
}
⋮----
user: string; // IIBAN, 14-42 chars
id: string; // order id
⋮----
/**
 * Embed Quotes (RFQ) - Get Quote Limits request parameters
 */
export interface PartnerGetQuoteLimitsParams {
  user: string; // IIBAN, 14-42 chars
  base_asset: string; // <= 16 chars
  quote_asset: string; // <= 16 chars
  type: 'receive' | 'spend';
  quote_currency?: string; // <= 16 chars
}
⋮----
user: string; // IIBAN, 14-42 chars
base_asset: string; // <= 16 chars
quote_asset: string; // <= 16 chars
⋮----
quote_currency?: string; // <= 16 chars
⋮----
/**
 * Embed Quotes (RFQ) - Request Prospective Quote request parameters
 */
export interface PartnerRequestProspectiveQuoteParams {
  user: string; // IIBAN, 14-42 chars
  action: {
    type: 'receive' | 'spend';
    amount: {
      asset_class?: 'currency';
      asset: string; // <= 16 chars
      amount: string;
    };
    quote: {
      asset: string; // <= 16 chars
      fee_bps: string; // 1-5 digits
      spread_bps: string; // 1-5 digits
    };
  };
  trigger?: {
    type: 'price';
    base_asset: string;
    quote_asset: string;
    target_price: string;
    condition: 'gte' | 'lte';
  };
  quote_currency?: string; // <= 16 chars
}
⋮----
user: string; // IIBAN, 14-42 chars
⋮----
asset: string; // <= 16 chars
⋮----
asset: string; // <= 16 chars
fee_bps: string; // 1-5 digits
spread_bps: string; // 1-5 digits
⋮----
quote_currency?: string; // <= 16 chars
⋮----
/**
 * Get Ramp Checkout URL request parameters
 */
export interface PartnerGetRampCheckoutUrlParams {
  in_asset: string; // max 16 chars
  in_amount: string; // decimal128
  out_asset: string; // max 16 chars
  funding_type: string;
  withdrawal_method: string;
  country?: string; // max 2 chars, ISO 3166-1 alpha-2
  redirect_url?: string; // URI
  network?: string;
  external_user_id?: string; // max 36 chars
  external_transaction_id?: string; // max 36 chars
  external_metadata?: string; // max 1000 chars
}
⋮----
in_asset: string; // max 16 chars
in_amount: string; // decimal128
out_asset: string; // max 16 chars
⋮----
country?: string; // max 2 chars, ISO 3166-1 alpha-2
redirect_url?: string; // URI
⋮----
external_user_id?: string; // max 36 chars
external_transaction_id?: string; // max 36 chars
external_metadata?: string; // max 1000 chars

================
File: src/types/request/spot.types.ts
================
/**
 * Market Data
 */
⋮----
export interface SpotGetAssetPairsParams {
  pair?: string;
  aclass_base?: 'currency' | 'tokenized_asset';
  info?: 'info' | 'leverage' | 'fees' | 'margin';
  country_code?: string;
  execution_venue?: string;
}
⋮----
export interface SpotGetOHLCParams {
  pair: string;
  interval?: 1 | 5 | 15 | 30 | 60 | 240 | 1440 | 10080 | 21600;
  since?: number;
  asset_class?: 'tokenized_asset';
}
⋮----
export interface SpotGetOrderBookParams {
  pair: string;
  count?: number;
  asset_class?: 'tokenized_asset';
}
⋮----
export interface SpotGetRecentTradesParams {
  pair: string;
  since?: string;
  count?: number;
  asset_class?: 'tokenized_asset';
}
⋮----
export interface SpotGetRecentSpreadsParams {
  pair: string;
  since?: number;
  asset_class?: 'tokenized_asset';
}
⋮----
/**
 * Account Data
 */
⋮----
export interface SpotGetOpenOrdersParams {
  trades?: boolean;
  userref?: number;
  cl_ord_id?: string;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetClosedOrdersParams {
  trades?: boolean;
  userref?: number;
  cl_ord_id?: string;
  start?: number;
  end?: number;
  ofs?: number;
  closetime?: 'open' | 'close' | 'both';
  consolidate_taker?: boolean;
  without_count?: boolean;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotQueryOrdersParams {
  trades?: boolean;
  userref?: number;
  txid: string;
  consolidate_taker?: boolean;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetTradesHistoryParams {
  type?:
    | 'all'
    | 'any position'
    | 'closed position'
    | 'closing position'
    | 'no position';
  trades?: boolean;
  start?: number;
  end?: number;
  ofs?: number;
  consolidate_taker?: boolean;
  ledgers?: boolean;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotQueryTradesParams {
  txid: string;
  trades?: boolean;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetOpenPositionsParams {
  txid?: string;
  docalcs?: boolean;
  consolidation?: 'market';
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetLedgersInfoParams {
  asset?: string;
  aclass?: string;
  type?:
    | 'all'
    | 'trade'
    | 'deposit'
    | 'withdrawal'
    | 'transfer'
    | 'margin'
    | 'adjustment'
    | 'rollover'
    | 'credit'
    | 'settled'
    | 'staking'
    | 'dividend'
    | 'sale'
    | 'nft_rebate';
  start?: number;
  end?: number;
  ofs?: number;
  without_count?: boolean;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotQueryLedgersParams {
  id: string;
  trades?: boolean;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotRequestExportReportParams {
  report: 'trades' | 'ledgers';
  format?: 'CSV' | 'TSV';
  description: string;
  fields?: string;
  starttm?: number;
  endtm?: number;
}
⋮----
/**
 * Trading
 */
⋮----
export interface SpotSubmitOrderParams {
  userref?: number;
  cl_ord_id?: string;
  ordertype:
    | 'market'
    | 'limit'
    | 'iceberg'
    | 'stop-loss'
    | 'take-profit'
    | 'stop-loss-limit'
    | 'take-profit-limit'
    | 'trailing-stop'
    | 'trailing-stop-limit'
    | 'settle-position';
  type: 'buy' | 'sell';
  volume: string;
  displayvol?: string;
  pair: string;
  asset_class?: 'tokenized_asset';
  price?: string;
  price2?: string;
  trigger?: 'index' | 'last';
  leverage?: string;
  reduce_only?: boolean;
  stptype?: 'cancel-newest' | 'cancel-oldest' | 'cancel-both';
  oflags?: string;
  timeinforce?: 'GTC' | 'IOC' | 'GTD' | 'FOK';
  starttm?: string;
  expiretm?: string;
  'close[ordertype]'?: string;
  'close[price]'?: string;
  'close[price2]'?: string;
  deadline?: string;
  validate?: boolean;
}
⋮----
export interface SpotAmendOrderParams {
  txid?: string;
  cl_ord_id?: string;
  order_qty?: string;
  display_qty?: string;
  limit_price?: string;
  trigger_price?: string;
  pair?: string;
  post_only?: boolean;
  deadline?: string;
}
⋮----
export interface SpotBatchOrderItem {
  userref?: number;
  cl_ord_id?: string;
  ordertype:
    | 'market'
    | 'limit'
    | 'iceberg'
    | 'stop-loss'
    | 'take-profit'
    | 'stop-loss-limit'
    | 'take-profit-limit'
    | 'trailing-stop'
    | 'trailing-stop-limit'
    | 'settle-position';
  type: 'buy' | 'sell';
  volume: string;
  displayvol?: string;
  price?: string;
  price2?: string;
  trigger?: 'index' | 'last';
  leverage?: string;
  reduce_only?: boolean;
  stptype?: 'cancel-newest' | 'cancel-oldest' | 'cancel-both';
  oflags?: string;
  timeinforce?: 'GTC' | 'IOC' | 'GTD' | 'FOK';
  starttm?: string;
  expiretm?: string;
  close?: {
    ordertype?: string;
    price?: string;
    price2?: string;
  };
}
⋮----
export interface SpotSubmitOrderBatchParams {
  orders: SpotBatchOrderItem[];
  pair: string;
  asset_class?: 'tokenized_asset';
  broker?: string;
  deadline?: string;
  validate?: boolean;
}
⋮----
/**
 * Funding
 */
⋮----
export interface SpotGetDepositMethodsParams {
  asset: string;
  aclass?: 'currency' | 'tokenized_asset';
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetDepositAddressesParams {
  asset: string;
  aclass?: 'currency' | 'tokenized_asset';
  method: string;
  new?: boolean;
  amount?: string | number;
}
⋮----
export interface SpotGetDepositStatusParams {
  asset?: string;
  aclass?: 'currency' | 'tokenized_asset';
  method?: string;
  start?: string;
  end?: string;
  cursor?: boolean | string;
  limit?: number;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetWithdrawalMethodsParams {
  asset?: string;
  aclass?: 'currency' | 'tokenized_asset';
  network?: string;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetWithdrawalAddressesParams {
  asset?: string;
  aclass?: 'currency' | 'tokenized_asset';
  method?: string;
  key?: string;
  verified?: boolean;
}
⋮----
export interface SpotGetWithdrawalInfoParams {
  asset: string;
  key: string;
  amount: string;
}
⋮----
export interface SpotWithdrawFundsParams {
  asset: string;
  aclass?: 'currency' | 'tokenized_asset';
  key: string;
  address?: string;
  amount: string;
  max_fee?: string;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotGetWithdrawalsStatusParams {
  asset?: string;
  aclass?: 'currency' | 'tokenized_asset';
  method?: string;
  start?: string;
  end?: string;
  cursor?: boolean | string;
  limit?: number;
  rebase_multiplier?: 'rebased' | 'base';
}
⋮----
export interface SpotWalletTransferParams {
  asset: string;
  from: 'Spot Wallet';
  to: 'Futures Wallet';
  amount: string;
}
⋮----
/**
 * Subaccounts
 */
⋮----
export interface SpotAccountTransferParams {
  asset: string;
  asset_class?: 'currency' | 'tokenized_asset';
  amount: string;
  from: string;
  to: string;
}
⋮----
/**
 * Earn
 */
⋮----
export interface SpotListEarnStrategiesParams {
  ascending?: boolean;
  asset?: string;
  cursor?: string;
  limit?: number;
  lock_type?: ('flex' | 'bonded' | 'timed' | 'instant')[];
}
⋮----
export interface SpotListEarnAllocationsParams {
  ascending?: boolean;
  converted_asset?: string;
  hide_zero_allocations?: boolean;
}
⋮----
/**
 * Transparency
 */
⋮----
export interface SpotGetPostTradeDataParams {
  symbol?: string;
  from_ts?: string;
  to_ts?: string;
  count?: number;
}
⋮----
/**
 * OAuth
 */
⋮----
export interface OauthGetAccessTokenParams {
  grant_type: 'authorization_code' | 'refresh_token';
  code?: string; // Required if grant_type = authorization_code
  redirect_uri?: string; // Required if grant_type = authorization_code
  refresh_token?: string; // Required if grant_type = refresh_token
}
⋮----
code?: string; // Required if grant_type = authorization_code
redirect_uri?: string; // Required if grant_type = authorization_code
refresh_token?: string; // Required if grant_type = refresh_token
⋮----
export interface OauthCreateFastApiKeyParams {
  api_key_name: string; // max 32 chars
  ip_allowlist: string[];
  nonce_window?: number;
  permissions: {
    export_data?: boolean;
    funds_add?: boolean;
    funds_earn?: boolean;
    funds_query?: boolean;
    funds_withdraw?: boolean;
    ledger_query?: boolean;
    trades_close?: boolean;
    trades_modify?: boolean;
    trades_query_closed?: boolean;
    trades_query_open?: boolean;
  };
  query_from?: number;
  query_to?: number;
  valid_until?: number;
}
⋮----
api_key_name: string; // max 32 chars
⋮----
export interface OauthUpdateFastApiKeyParams {
  new_api_key_name?: string; // max 32 chars
  api_key_name: string; // max 32 chars
  ip_allowlist: string[];
  nonce_window?: number;
  permissions: {
    export_data?: boolean;
    funds_add?: boolean;
    funds_earn?: boolean;
    funds_query?: boolean;
    funds_withdraw?: boolean;
    ledger_query?: boolean;
    trades_close?: boolean;
    trades_modify?: boolean;
    trades_query_closed?: boolean;
    trades_query_open?: boolean;
  };
  query_from?: number;
  query_to?: number;
  valid_until?: number;
}
⋮----
new_api_key_name?: string; // max 32 chars
api_key_name: string; // max 32 chars

================
File: src/types/response/derivatives.types.ts
================
/**
 * Market Data
 */
⋮----
export interface FuturesTradeHistoryItem {
  price: number;
  side?: string; // "buy" if taker is buyer, "sell" if taker is seller
  size?: string;
  time: string;
  trade_id?: number;
  type?: 'fill' | 'liquidation' | 'assignment' | 'termination' | 'block';
  uid?: string;
  instrument_identification_type?: string;
  isin?: string;
  execution_venue?: string;
  price_notation?: string;
  price_currency?: string;
  notional_amount?: number;
  notional_currency?: string;
  publication_time?: string;
  publication_venue?: string;
  transaction_identification_code?: string;
  to_be_cleared?: boolean;
}
⋮----
side?: string; // "buy" if taker is buyer, "sell" if taker is seller
⋮----
export interface FuturesOrderBook {
  asks: [number, number][]; // [price, size]
  bids: [number, number][]; // [price, size]
}
⋮----
asks: [number, number][]; // [price, size]
bids: [number, number][]; // [price, size]
⋮----
export interface TickerGreeks {
  iv: number; // Implied volatility, -1.0 if impossible to calculate
  delta: number;
  gamma: number | null;
  vega: number | null;
  theta: number | null;
  rho: number | null;
}
⋮----
iv: number; // Implied volatility, -1.0 if impossible to calculate
⋮----
export interface FuturesTicker {
  symbol: string;
  last?: number;
  lastTime?: string;
  lastSize?: number;
  tag: 'perpetual' | 'month' | 'quarter' | 'semiannual';
  pair: string;
  markPrice: number;
  bid?: number;
  bidSize?: number;
  ask?: number;
  askSize?: number;
  vol24h: number;
  volumeQuote: number;
  openInterest: number;
  open24h?: number;
  high24h?: number;
  low24h?: number;
  extrinsicValue?: number; // Only for options
  fundingRate?: number; // Only for perpetuals
  fundingRatePrediction?: number; // Only for perpetuals
  suspended: boolean;
  indexPrice: number;
  postOnly: boolean;
  change24h: number;
  greeks?: TickerGreeks; // Only for options
  isUnderlyingMarketClosed?: boolean; // Only for tradfi markets
}
⋮----
extrinsicValue?: number; // Only for options
fundingRate?: number; // Only for perpetuals
fundingRatePrediction?: number; // Only for perpetuals
⋮----
greeks?: TickerGreeks; // Only for options
isUnderlyingMarketClosed?: boolean; // Only for tradfi markets
⋮----
/**
 * Instrument Details
 */
⋮----
export interface FuturesMarginLevel {
  contracts?: number | null;
  numNonContractUnits?: number | null;
  initialMargin: number;
  maintenanceMargin: number;
}
⋮----
export interface FuturesMarginSchedule {
  retail: FuturesMarginLevel[];
  professional: FuturesMarginLevel[];
}
⋮----
export interface FuturesInstrument {
  symbol: string;
  type: 'flexible_futures' | 'futures_inverse' | 'futures_vanilla';
  tradeable: boolean;
  tradfi: boolean;
  pair?: string;
  base?: string;
  quote?: string;
  underlying?: string;
  tickSize?: number;
  contractSize?: number;
  contractValueTradePrecision?: number;
  impactMidSize?: number;
  maxPositionSize?: number;
  openingDate?: string;
  lastTradingTime?: string;
  category?: string;
  fundingRateCoefficient?: number;
  maxRelativeFundingRate?: number;
  isin?: string;
  marginSchedules?: Record<string, FuturesMarginSchedule>;
  retailMarginLevels?: FuturesMarginLevel[];
  marginLevels?: FuturesMarginLevel[];
  postOnly?: boolean;
  /** @deprecated Effective 2026-06-22. Fee schedules are deprecated; use Spot GetTradeVolume instead. */
  feeScheduleUid?: string;
  tags?: string[];
  underlyingFuture?: string;
  mtf?: boolean;
}
⋮----
/** @deprecated Effective 2026-06-22. Fee schedules are deprecated; use Spot GetTradeVolume instead. */
⋮----
export interface FuturesInstrumentStatus {
  tradeable: string;
  experiencingDislocation: boolean;
  priceDislocationDirection: 'ABOVE_UPPER_BOUND' | 'BELOW_LOWER_BOUND' | null;
  experiencingExtremeVolatility: boolean;
  extremeVolatilityInitialMarginMultiplier: number;
}
⋮----
/**
 * Order Management
 */
⋮----
export interface FuturesOrderJson {
  orderId: string;
  cliOrdId?: string | null;
  type:
    | 'lmt'
    | 'ioc'
    | 'post'
    | 'liquidation'
    | 'assignment'
    | 'stp'
    | 'unwind'
    | 'block'
    | 'fok'
    | 'unknown';
  symbol: string;
  side: 'buy' | 'sell' | 'unknown';
  quantity: number;
  filled: number;
  limitPrice: number;
  reduceOnly: boolean;
  timestamp: string;
  lastUpdateTimestamp: string;
  reducedQuantity?: number | null;
}
⋮----
export interface FuturesOrderTriggerJson {
  uid: string;
  clientId: string | null;
  type:
    | 'lmt'
    | 'ioc'
    | 'post'
    | 'liquidation'
    | 'assignment'
    | 'stp'
    | 'unwind'
    | 'fok'
    | 'unknown';
  symbol: string;
  side: 'buy' | 'sell' | 'unknown';
  quantity: number | null;
  limitPrice: number | null;
  triggerPrice: number | null;
  triggerSide: 'trigger_above' | 'trigger_below' | 'unknown' | null;
  triggerSignal: 'mark_price' | 'last_price' | 'spot_price' | 'unknown' | null;
  reduceOnly: boolean;
  timestamp: string;
  lastUpdateTimestamp: string;
  startTime: string | null;
}
⋮----
export interface FuturesPlaceEvent {
  type: 'PLACE';
  order: FuturesOrderJson;
}
⋮----
export interface FuturesCancelEvent {
  type: 'CANCEL';
  uid: string;
  order: FuturesOrderJson;
}
⋮----
export interface FuturesEditEvent {
  type: 'EDIT';
  old: FuturesOrderJson;
  new: FuturesOrderJson & { reducedQuantity: number | null };
}
⋮----
export interface FuturesRejectEvent {
  type: 'REJECT';
  uid: string;
  order: FuturesOrderJson;
  reason: 'POST_WOULD_EXECUTE' | 'IOC_WOULD_NOT_EXECUTE';
}
⋮----
export interface FuturesExecuteEvent {
  type: 'EXECUTION';
  executionId: string;
  price: number;
  amount: number;
  orderPriorEdit: FuturesOrderJson;
  orderPriorExecution: FuturesOrderJson & {
    takerReducedQuantity: number | null;
  };
}
⋮----
export interface FuturesPlaceTriggerEvent {
  type: 'PLACE';
  orderTrigger: FuturesOrderTriggerJson;
}
⋮----
export interface FuturesCancelTriggerEvent {
  type: 'CANCEL';
  uid: string;
  orderTrigger: FuturesOrderTriggerJson;
}
⋮----
export interface FuturesRejectTriggerEvent {
  type: 'REJECT';
  uid: string;
  orderTrigger: FuturesOrderTriggerJson;
  reason:
    | 'MARKET_SUSPENDED'
    | 'MARKET_NOT_FOUND'
    | 'INVALID_PRICE'
    | 'INVALID_QUANTITY'
    | 'SMALL_ORDER_LIMIT_EXCEEDED'
    | 'INSUFFICIENT_MARGIN'
    | 'WOULD_CAUSE_LIQUIDATION'
    | 'CLIENT_ORDER_ID_IN_USE'
    | 'CLIENT_ORDER_ID_TOO_LONG'
    | 'MAX_POSITION_EXCEEDED'
    | 'PRICE_COLLAR'
    | 'PRICE_DISLOCATION'
    | 'EDIT_HAS_NO_EFFECT'
    | 'ORDER_FOR_CANCELLATION_NOT_FOUND'
    | 'ORDER_FOR_EDIT_NOT_FOUND'
    | 'ORDER_CANNOT_HAVE_TRIGGER_PRICE'
    | 'POST_WOULD_EXECUTE'
    | 'IOC_WOULD_NOT_EXECUTE'
    | 'WOULD_EXECUTE_SELF'
    | 'WOULD_NOT_REDUCE_POSITION'
    | 'REJECTED_AFTER_EXECUTION'
    | 'MARKET_IS_POST_ONLY'
    | 'ORDER_LIMIT_EXCEEDED'
    | 'FIXED_LEVERAGE_TOO_HIGH'
    | 'CANNOT_EDIT_TRIGGER_PRICE_OF_TRAILING_STOP'
    | 'CANNOT_EDIT_LIMIT_PRICE_OF_TRAILING_STOP'
    | 'TRAILING_STOP_ORDER_LIMIT_EXCEEDED'
    | 'TRAILING_STOP_PERCENT_DEVIATION_EXCEEDS_MAX_DECIMAL_PLACES'
    | 'TRAILING_STOP_QUOTE_DEVIATION_NOT_MULTIPLE_OF_TICK_SIZE'
    | 'TRAILING_STOP_MAX_DEVIATION_TOO_LARGE'
    | 'TRAILING_STOP_MAX_DEVIATION_TOO_SMALL'
    | 'INSUFFICIENT_HEADROOM_AROUND_CURRENT_PRICE_TO_EDIT_TRAILING_STOP'
    | 'NO_REFERENCE_PRICE_AVAILABLE_FOR_CALCULATING_TRAILING_STOP_TRIGGER_PRICE'
    | 'INSUFFICIENT_CLOSING_MARGIN'
    | 'LIMIT_PRICE_SET_AS_ABSOLUTE_AND_RELATIVE'
    | 'LIMIT_PRICE_OFFSET_VALUE_INVALID'
    | 'LIMIT_PRICE_OFFSET_UNIT_INVALID'
    | 'LIMIT_PRICE_OFFSET_MUST_HAVE_VALUE_AND_UNIT'
    | 'LIMIT_PRICE_OFFSET_QUOTE_CURRENCY_VALUE_MUST_BE_MULTIPLE_OF_TICK_SIZE'
    | 'LIMIT_PRICE_OFFSET_PERCENT_VALUE_TOO_MANY_DECIMAL_PLACES'
    | 'LIMIT_PRICE_OFFSET_TOO_HIGH'
    | 'LIMIT_PRICE_OFFSET_TOO_LOW';
}
⋮----
export type FuturesOrderEvent =
  | FuturesPlaceEvent
  | FuturesCancelEvent
  | FuturesEditEvent
  | FuturesRejectEvent
  | FuturesExecuteEvent
  | FuturesPlaceTriggerEvent
  | FuturesCancelTriggerEvent
  | FuturesRejectTriggerEvent;
⋮----
export interface FuturesBatchOrderStatus {
  cliOrdId?: string;
  dateTimeReceived?: string | null;
  orderEvents: FuturesOrderEvent[];
  order_id?: string | null;
  order_tag?: string | null;
  status:
    | 'placed'
    | 'edited'
    | 'cancelled'
    | 'invalidOrderType'
    | 'invalidSide'
    | 'invalidSize'
    | 'invalidPrice'
    | 'insufficientAvailableFunds'
    | 'selfFill'
    | 'tooManySmallOrders'
    | 'marketSuspended'
    | 'marketInactive'
    | 'clientOrderIdAlreadyExist'
    | 'clientOrderIdTooLong'
    | 'outsidePriceCollar'
    | 'postWouldExecute'
    | 'iocWouldNotExecute';
}
⋮----
export interface FuturesCancelledOrder {
  cliOrdId?: string | null;
  order_id: string;
}
⋮----
export interface FuturesCancelAllOrdersStatus {
  cancelOnly: string;
  cancelledOrders: FuturesCancelledOrder[];
  orderEvents: FuturesOrderEvent[];
  receivedTime: string;
  status: 'noOrdersToCancel' | 'cancelled';
}
⋮----
export interface FuturesDeadMansSwitchStatus {
  currentTime: string;
  triggerTime: string;
}
⋮----
export interface FuturesCancelOrderStatus {
  cliOrdId?: string | null;
  orderEvents?: FuturesOrderEvent[];
  order_id?: string;
  receivedTime?: string;
  status: 'cancelled' | 'filled' | 'notFound';
}
⋮----
export interface FuturesEditOrderStatus {
  orderId?: string | null;
  cliOrdId?: string | null;
  orderEvents: FuturesOrderEvent[];
  receivedTime?: string | null;
  status:
    | 'edited'
    | 'invalidSize'
    | 'invalidPrice'
    | 'insufficientAvailableFunds'
    | 'selfFill'
    | 'tooManySmallOrders'
    | 'outsidePriceCollar'
    | 'postWouldExecute'
    | 'wouldNotReducePosition'
    | 'orderForEditNotFound'
    | 'orderForEditNotAStop';
}
⋮----
export interface FuturesOpenOrder {
  order_id: string;
  cliOrdId?: string;
  status: 'untouched' | 'partiallyFilled';
  side: 'buy' | 'sell' | 'unknown';
  orderType: 'lmt' | 'stop' | 'take_profit' | 'unknown';
  symbol: string;
  limitPrice?: number;
  stopPrice?: number;
  filledSize: number;
  unfilledSize?: number;
  reduceOnly: boolean;
  triggerSignal?: 'mark' | 'last' | 'spot' | 'unknown';
  lastUpdateTime: string;
  receivedTime: string;
}
⋮----
export interface FuturesSendOrderStatus {
  cliOrdId?: string;
  orderEvents?: FuturesOrderEvent[];
  order_id?: string;
  receivedTime?: string;
  status:
    | 'placed'
    | 'partiallyFilled'
    | 'filled'
    | 'cancelled'
    | 'edited'
    | 'marketSuspended'
    | 'marketInactive'
    | 'invalidPrice'
    | 'invalidSize'
    | 'tooManySmallOrders'
    | 'insufficientAvailableFunds'
    | 'wouldCauseLiquidation'
    | 'clientOrderIdAlreadyExist'
    | 'clientOrderIdTooBig'
    | 'maxPositionViolation'
    | 'outsidePriceCollar'
    | 'wouldIncreasePriceDislocation'
    | 'notFound'
    | 'orderForEditNotAStop'
    | 'orderForEditNotFound'
    | 'postWouldExecute'
    | 'iocWouldNotExecute'
    | 'selfFill'
    | 'wouldNotReducePosition'
    | 'marketIsPostOnly'
    | 'tooManyOrders'
    | 'fixedLeverageTooHigh'
    | 'clientOrderIdInvalid'
    | 'cannotEditTriggerPriceOfTrailingStop'
    | 'cannotEditLimitPriceOfTrailingStop'
    | 'wouldProcessAfterSpecifiedTime';
}
⋮----
export interface FuturesTriggerOptions {
  triggerPrice: number;
  triggerSide: 'TRIGGER_ABOVE' | 'TRIGGER_BELOW' | 'unknown';
  triggerSignal: 'MARK_PRICE' | 'LAST_PRICE' | 'SPOT_PRICE' | 'unknown';
  triggerTime: string | null;
}
⋮----
export interface FuturesOrderStatusInfo {
  order: {
    type: 'TRIGGER_ORDER' | 'ORDER';
    orderId: string;
    cliOrdId: string | null;
    symbol: string;
    side: string;
    quantity: number | null;
    filled: number | null;
    limitPrice: number | null;
    reduceOnly: boolean;
    timestamp: string;
    lastUpdateTimestamp: string;
    priceTriggerOptions?: FuturesTriggerOptions;
  };
  status:
    | 'ENTERED_BOOK'
    | 'FULLY_EXECUTED'
    | 'REJECTED'
    | 'CANCELLED'
    | 'TRIGGER_PLACED'
    | 'TRIGGER_ACTIVATION_FAILURE';
  updateReason:
    | 'LOADING_MARKET'
    | 'NEW_USER_ORDER'
    | 'LIQUIDATION_ORDER'
    | 'STOP_ORDER_TRIGGERED'
    | 'LIMIT_FROM_STOP'
    | 'PARTIAL_FILL'
    | 'FULL_FILL'
    | 'CANCELLED_BY_USER'
    | 'CONTRACT_EXPIRED'
    | 'NOT_ENOUGH_MARGIN'
    | 'MARKET_INACTIVE'
    | 'DEAD_MAN_SWITCH'
    | 'CANCELLED_BY_ADMIN'
    | 'POST_WOULD_EXECUTE_REASON'
    | 'IOC_WOULD_NOT_EXECUTE_REASON'
    | 'WOULD_EXECUTE_SELF_REASON'
    | 'WOULD_NOT_REDUCE_POSITION'
    | 'EDITED_BY_USER'
    | 'ORDER_FOR_EDIT_NOT_FOUND_REASON'
    | 'EXPIRED'
    | 'TRAILING_STOP_PRICE_UPDATED'
    | 'TRAILING_STOP_CANCELLED_AND_REPLACED_BY_ADMIN'
    | 'unknown';
  error?: string; // OrderError type - reusing the same errors as FuturesRejectTriggerEvent
}
⋮----
error?: string; // OrderError type - reusing the same errors as FuturesRejectTriggerEvent
⋮----
/**
 * Multi-Collateral
 */
⋮----
export interface FuturesPnlPreference {
  symbol: string;
  pnlCurrency: string;
}
⋮----
export interface FuturesLeveragePreference {
  symbol: string;
  maxLeverage: number;
}
⋮----
/**
 * Account Information
 */
⋮----
export interface FuturesFlexCurrencySummary {
  quantity: number;
  value: number;
  collateral: number;
}
⋮----
export interface FuturesPortfolioMarginBreakdown {
  totalCrossAssetNettedMarketRisk: number;
  totalMarketRisk: number;
  totalScenarioPnls: number[];
  totalAbsoluteOptionPositionDeltaNotional: number;
  netPortfolioDelta: number;
  totalPremium: number;
  isBuyOnly: boolean;
  futuresMaintenanceMargin: number;
}
⋮----
export interface FuturesFlexAccount {
  type: 'multiCollateralMarginAccount';
  currencies: Record<string, FuturesFlexCurrencySummary>;
  available: number;
  initialMargin: number;
  initialMarginWithOrders: number;
  maintenanceMargin: number;
  balanceValue: number;
  portfolioValue: number;
  collateralValue: number;
  pnl: number;
  unrealizedFunding: number;
  totalUnrealized: number;
  totalUnrealizedAsMargin: number;
  availableMargin: number;
  marginEquity: number;
  portfolioMarginBreakdown?: FuturesPortfolioMarginBreakdown;
}
⋮----
export interface FuturesCashAccount {
  type: 'cashAccount';
  balances: Record<string, string>;
}
⋮----
export interface FuturesMarginAccount {
  type: 'marginAccount';
  currency: string;
  balances: Record<string, string>;
  auxiliary: {
    usd: number;
    pv: number;
    pnl: number;
    af: number;
    funding: number;
  };
  marginRequirements: {
    im: number;
    mm: number;
    lt: number;
    tt: number;
  };
  triggerEstimates: {
    im: number;
    mm: number;
    lt: number;
    tt: number;
  };
}
⋮----
export interface FuturesAccounts {
  cash?: FuturesCashAccount;
  flex?: FuturesFlexAccount;
  [key: string]:
    | FuturesMarginAccount
    | FuturesCashAccount
    | FuturesFlexAccount
    | undefined;
}
⋮----
export interface FuturesOpenPosition {
  symbol: string;
  side: 'long' | 'short';
  size: number;
  price: number;
  fillTime: string;
  unrealizedFunding: number | null;
  pnlCurrency?: string | null; // USD, EUR, GBP, USDC, USDT, BTC, ETH
  maxFixedLeverage?: number | null;
}
⋮----
pnlCurrency?: string | null; // USD, EUR, GBP, USDC, USDT, BTC, ETH
⋮----
export interface FuturesUnwindQueuePosition {
  symbol: string;
  percentile: number;
}
⋮----
export interface FuturesOptionsUserLimitsPerBaseCurrency {
  maxTotalPositionSize: number;
  maxTotalOpenOrdersSize: number;
}
⋮----
export interface FuturesPortfolioMarginParameters {
  crossAssetNettingFactor: number;
  extremePriceShockMultiplier: number;
  volShockMultiplicationFactor: number;
  volShockExponentFactor: number;
  optionExpiryTimeShockHours: number;
  optionsInitialMarginFactor: number;
  totalOptionOrdersConsideredInInitialMarginCalc: number;
  priceShockLevels: number[];
  optionsUserLimits: {
    maxNetPositionDelta: number;
    limitsPerBaseCurrency: Record<
      string,
      FuturesOptionsUserLimitsPerBaseCurrency
    >;
  };
}
⋮----
export interface FuturesOptionGreeks {
  iv: number; // -1.0 if impossible to calculate
  delta: number;
  gamma: number | null;
  vega: number | null;
  theta: number | null;
  rho: number | null;
}
⋮----
iv: number; // -1.0 if impossible to calculate
⋮----
export interface FuturesPortfolioSimulation {
  maintenanceMargin: number;
  initialMargin: number;
  pnl: number;
  portfolioMarginBreakdown: FuturesPortfolioMarginBreakdown;
  greeks: Record<string, FuturesOptionGreeks>;
}
⋮----
/**
 * Assignment Program
 */
⋮----
export interface FuturesAssignmentProgramParticipant {
  contractType: string;
  contract: string | null;
  maxSize: number | null;
  maxPosition: number | null;
  acceptLong: boolean;
  acceptShort: boolean;
  timeFrame: 'all' | 'weekdays' | 'weekends';
  enabled: boolean;
}
⋮----
export interface FuturesAssignmentProgram {
  id: number;
  participant: FuturesAssignmentProgramParticipant;
  contractType: string;
  contract: string | null;
  maxSize: number | null;
  maxPosition: number | null;
  acceptLong: boolean;
  acceptShort: boolean;
  timeFrame: 'all' | 'weekdays' | 'weekends';
  enabled: boolean;
}
⋮----
export interface FuturesAssignmentProgramHistory {
  deleted: boolean;
  participant: FuturesAssignmentProgramParticipant;
  contractType: string;
  contract: string | null;
  maxSize: number | null;
  maxPosition: number | null;
  acceptLong: boolean;
  acceptShort: boolean;
  timeFrame: 'all' | 'weekdays' | 'weekends';
  enabled: boolean;
  timestamp: string;
}
⋮----
/**
 * Fee Schedules
 *
 * @deprecated Effective 2026-06-22. Use Spot GetTradeVolume (SpotClient.getTradingVolume) instead.
 */
⋮----
export interface FuturesFeeTier {
  makerFee: number;
  takerFee: number;
  usdVolume: number;
}
⋮----
export interface FuturesFeeSchedule {
  tiers: FuturesFeeTier[];
  name: string;
  uid: string;
}
⋮----
/**
 * General
 */
⋮----
export interface FuturesNotification {
  effectiveTime: string;
  note: string;
  priority: 'low' | 'medium' | 'high';
  type:
    | 'new_feature'
    | 'bug_fix'
    | 'settlement'
    | 'general'
    | 'maintenance'
    | 'market';
  expectedDowntimeMinutes?: number;
}
⋮----
/**
 * Historical Data
 */
⋮----
export interface FuturesFill {
  cliOrdId?: string | null;
  fillTime: string;
  fillType:
    | 'maker'
    | 'taker'
    | 'liquidation'
    | 'assignor'
    | 'assignee'
    | 'takerAfterEdit'
    | 'unwindBankrupt'
    | 'unwindCounterparty';
  fill_id: string;
  order_id: string;
  price: number;
  side: 'buy' | 'sell' | 'unknown';
  size: number;
  symbol: string;
}
⋮----
/**
 * Historical Funding Rates
 */
⋮----
export interface FuturesHistoricalFundingRate {
  fundingRate: number;
  relativeFundingRate: number;
  timestamp: string;
}
⋮----
/**
 * Subaccounts
 */
⋮----
export interface FuturesHoldingAccount {
  currency: string;
  amount: number;
}
⋮----
export interface FuturesSingleCollateralAccount {
  name: string;
  availableMargin: number;
}
⋮----
export interface FuturesSubaccountFlexCurrency {
  currency: string;
  quantity: number;
  value: number;
  collateral: number;
  available: number;
}
⋮----
export interface FuturesSubaccountFlexAccount {
  currencies: FuturesSubaccountFlexCurrency[];
  initialMargin: number;
  initialMarginWithOrders: number;
  maintenanceMargin: number;
  balanceValue: number;
  portfolioValue: number;
  collateralValue: number;
  pnl: number;
  unrealizedFunding: number;
  totalUnrealized: number;
  totalUnrealizedAsMargin: number;
  availableMargin: number;
  marginEquity: number;
  portfolioMarginBreakdown?: FuturesPortfolioMarginBreakdown;
}
⋮----
export interface FuturesSubaccount {
  accountUid: string;
  email: string;
  fullName: string | null;
  holdingAccounts: FuturesHoldingAccount[];
  futuresAccounts: FuturesSingleCollateralAccount[];
  flexAccount: FuturesSubaccountFlexAccount;
}
⋮----
export interface FuturesSubaccountsInfo {
  masterAccountUid: string;
  subaccounts: FuturesSubaccount[];
}
⋮----
/**
 * RFQs
 */
⋮----
export interface FuturesRfqLeg {
  symbol: string;
  size: number;
  markPrice: number;
}
⋮----
export interface FuturesRfq {
  rfqUid: string;
  expiry: string;
  markPrice: number;
  legs: FuturesRfqLeg[];
}
⋮----
export interface FuturesOpenOffer {
  uid: string;
  rfqUid: string;
  placementDate: string;
  lastUpdateDate: string;
  bid?: string;
  ask?: string;
}
⋮----
/**
 * Account History
 */
⋮----
export interface FuturesHistoryResponse<T> {
  accountUid: string;
  len: number;
  serverTime: string;
  elements: T[];
  continuationToken?: string;
}
⋮----
export interface FuturesHistoryEventElement<T> {
  uid: string;
  timestamp: number;
  event: T;
}
⋮----
// Complex nested structures with multiple oneOf variants - keeping generic for flexibility
export type FuturesHistoryExecutionEvent = FuturesHistoryEventElement<any>;
export type FuturesHistoryOrderEvent = FuturesHistoryEventElement<any>;
export type FuturesHistoryTriggerEvent = FuturesHistoryEventElement<any>;
⋮----
export interface FuturesPositionUpdateEvent {
  accountUid: string;
  tradeable: string;
  oldPosition: string;
  oldAverageEntryPrice: string | null;
  newPosition: string;
  newAverageEntryPrice: string;
  fillTime?: number | null;
  fee?: string;
  feeCurrency?: string;
  realizedPnL?: string;
  positionChange:
    | 'open'
    | 'close'
    | 'increase'
    | 'decrease'
    | 'reverse'
    | 'noChange'
    | 'unknown';
  executionUid?: string;
  executionPrice?: string;
  executionSize?: string;
  tradeType?:
    | 'userExecution'
    | 'liquidation'
    | 'assignment'
    | 'unwind'
    | 'unknown';
  fundingRealizationTime?: number;
  realizedFunding?: string;
  settlementPrice?: string;
  timestamp: number;
  updateReason: 'trade' | 'fundingRealisation' | 'settlement' | 'unknown';
}
⋮----
export interface FuturesAccountLogEntry {
  asset: string;
  booking_uid: string;
  collateral: string | null;
  contract: string | null;
  date: string; // RFC 3339 formatted date-time
  execution: string | null;
  fee: number | null;
  funding_rate: number | null;
  id: number;
  info: string;
  margin_account: string;
  mark_price: number | null;
  new_average_entry_price: number | null;
  new_balance: number;
  old_average_entry_price: number | null;
  old_balance: number;
  realized_funding: number | null;
  realized_pnl: number | null;
  trade_price: number | null;
  conversion_spread_percentage?: number | null;
  liquidation_fee?: number | null;
  exchange_rate?: number;
  conversion_fee?: number;
  exchange_rate_from?: string;
}
⋮----
date: string; // RFC 3339 formatted date-time
⋮----
export interface FuturesAccountLog {
  accountUid: string;
  logs: FuturesAccountLogEntry[];
}
⋮----
/**
 * Market History
 */
⋮----
export interface FuturesMarketHistoryResponse<T> {
  len: number;
  elements: T[];
  continuationToken?: string;
}
⋮----
export interface FuturesMarketHistoryEventElement<T> {
  uid: string;
  timestamp: number;
  event: T;
}
⋮----
// Complex nested structures - keeping generic for flexibility
export type FuturesPublicExecutionEvent = FuturesMarketHistoryEventElement<any>;
export type FuturesPublicOrderEvent = FuturesMarketHistoryEventElement<any>;
⋮----
export interface FuturesPublicMarkPriceEvent {
  uid: string;
  timestamp: number;
  event: {
    price: string;
  };
}
⋮----
/**
 * Charts - Candles
 */
⋮----
export type FuturesTickType = 'spot' | 'mark' | 'trade';
export type FuturesResolution =
  | '1m'
  | '5m'
  | '15m'
  | '30m'
  | '1h'
  | '4h'
  | '12h'
  | '1d'
  | '1w';
⋮----
export interface FuturesCandle {
  time: number; // Epoch in ms
  high: string;
  low: string;
  open: string;
  close: string;
  volume: number;
}
⋮----
time: number; // Epoch in ms
⋮----
export interface FuturesCandles {
  candles: FuturesCandle[];
  more_candles: boolean;
}
⋮----
/**
 * Charts - Analytics
 */
⋮----
export type FuturesAnalyticsType =
  | 'open-interest'
  | 'aggressor-differential'
  | 'trade-volume'
  | 'trade-count'
  | 'liquidation-volume'
  | 'rolling-volatility'
  | 'long-short-ratio'
  | 'long-short-info'
  | 'cvd'
  | 'top-traders'
  | 'orderbook'
  | 'spreads'
  | 'liquidity'
  | 'slippage'
  | 'future-basis';
⋮----
export interface FuturesAnalyticsError {
  severity: string;
  error_class: string;
  type: string;
  msg: string;
  value?: string;
  field?: string;
}
⋮----
export interface FuturesAnalyticsResponse {
  result: {
    timestamp: number[];
    more: boolean;
    data: any; // Complex oneOf structure with multiple types - keeping generic
  };
  errors: FuturesAnalyticsError[];
}
⋮----
data: any; // Complex oneOf structure with multiple types - keeping generic
⋮----
/**
 * Auth - API Keys
 */
⋮----
export type FuturesApiKeyV3AccessLevel =
  | 'NO_ACCESS'
  | 'READ_ONLY'
  | 'FULL_ACCESS';
⋮----
export interface FuturesApiKeyV3Check {
  apiKey: string; // base64
  accountUid: string; // uuid
  iiban: string; // Account IIBAN (format: ^AA[A-Z0-9]{2} [A-Z0-9]{4} [A-Z0-9]{4} [A-Z0-9]{4}$)
  createdAt: string; // RFC 3339 date-time
  permissions: {
    general: FuturesApiKeyV3AccessLevel;
    transfer: FuturesApiKeyV3AccessLevel;
  };
  allowedCidrBlock: string | null; // CIDR format (e.g., 192.168.0.0/16)
}
⋮----
apiKey: string; // base64
accountUid: string; // uuid
iiban: string; // Account IIBAN (format: ^AA[A-Z0-9]{2} [A-Z0-9]{4} [A-Z0-9]{4} [A-Z0-9]{4}$)
createdAt: string; // RFC 3339 date-time
⋮----
allowedCidrBlock: string | null; // CIDR format (e.g., 192.168.0.0/16)
⋮----
/**
 * Stats - Market Share
 */
⋮----
export interface FuturesMarketShareContract {
  marketShare: string;
  volume: string;
  usdRebateCredited: string;
}
⋮----
export interface FuturesMarketShare {
  contracts: Record<string, FuturesMarketShareContract>;
}
⋮----
// trading settings
⋮----
export type FuturesSelfTradeStrategy =
  | 'REJECT_TAKER'
  | 'CANCEL_MAKER_SELF'
  | 'CANCEL_MAKER_CHILD'
  | 'CANCEL_MAKER_ANY';

================
File: src/types/response/partner.types.ts
================
// Partner API response types
⋮----
/**
 * Create User response
 */
export interface PartnerCreateUserResponse {
  result: {
    user: {
      iiban: string; // Internet International Bank Account Number (IIBAN), 14-42 characters
    };
  };
}
⋮----
iiban: string; // Internet International Bank Account Number (IIBAN), 14-42 characters
⋮----
/**
 * Get User response
 */
export interface PartnerGetUserResponse {
  result?: {
    user: string; // Kraken-assigned account id, 14-42 characters
    external_id?: string; // Optional external ID for the user set by the partner
    user_type: 'individual' | 'corporate'; // Type of the user
    status: {
      state: string; // e.g., "ok"
      required_actions?: any[]; // Simplified - array of required action objects
    };
    created_at: string; // ISO 8601 datetime
  };
}
⋮----
user: string; // Kraken-assigned account id, 14-42 characters
external_id?: string; // Optional external ID for the user set by the partner
user_type: 'individual' | 'corporate'; // Type of the user
⋮----
state: string; // e.g., "ok"
required_actions?: any[]; // Simplified - array of required action objects
⋮----
created_at: string; // ISO 8601 datetime
⋮----
/**
 * Update User response
 */
export interface PartnerUpdateUserResponse {
  result?: 'success';
}
⋮----
/**
 * Submit Verification response
 */
export interface PartnerSubmitVerificationResponse {
  result?: {
    verification_id: string;
  };
}
⋮----
/**
 * List Assets response
 */
export interface PartnerListAssetsResponse {
  result: {
    assets: any[]; // Simplified - array of asset objects
    links: any; // Pagination links
    meta: {
      total_items?: number;
      total_pages?: number;
      page_size?: number;
      page_number?: number;
    };
  };
}
⋮----
assets: any[]; // Simplified - array of asset objects
links: any; // Pagination links
⋮----
/**
 * Get Asset response
 */
export interface PartnerGetAssetResponse {
  result: any; // Simplified - asset details object
}
⋮----
result: any; // Simplified - asset details object
⋮----
/**
 * List Asset Rates response
 */
export interface PartnerListAssetRatesResponse {
  result: {
    rates: Array<{
      timestamp: string; // RFC 3339 datetime
      price: string; // decimal128
    }>;
    meta: any; // Simplified - metadata object
  };
}
⋮----
timestamp: string; // RFC 3339 datetime
price: string; // decimal128
⋮----
meta: any; // Simplified - metadata object
⋮----
/**
 * Request Quote response
 */
export interface PartnerRequestQuoteResponse {
  result: {
    quote_id: string;
    type: 'receive' | 'spend';
    status: any; // Simplified - status object
    expires: string; // ISO 8601 datetime
    spend: any; // Simplified - spend details object
    quoted_spend?: any; // Simplified - optional quoted spend object
    receive: any; // Simplified - receive details object
    quoted_receive?: any; // Simplified - optional quoted receive object
    unit_price: any; // Simplified - unit price object
    quoted_unit_price?: any; // Simplified - optional quoted unit price object
  };
}
⋮----
status: any; // Simplified - status object
expires: string; // ISO 8601 datetime
spend: any; // Simplified - spend details object
quoted_spend?: any; // Simplified - optional quoted spend object
receive: any; // Simplified - receive details object
quoted_receive?: any; // Simplified - optional quoted receive object
unit_price: any; // Simplified - unit price object
quoted_unit_price?: any; // Simplified - optional quoted unit price object
⋮----
/**
 * Get Quote response
 */
export interface PartnerGetQuoteResponse {
  result?: {
    quote_id: string;
    transaction_id?: string;
    type: 'receive' | 'spend';
    status: any; // Simplified - status object
    expires: string; // ISO 8601 datetime
    spend: any; // Simplified - spend details object
    quoted_spend?: any; // Simplified - optional quoted spend object
    receive: any; // Simplified - receive details object
    quoted_receive?: any; // Simplified - optional quoted receive object
    unit_price: any; // Simplified - unit price object
    quoted_unit_price?: any; // Simplified - optional quoted unit price object
  };
}
⋮----
status: any; // Simplified - status object
expires: string; // ISO 8601 datetime
spend: any; // Simplified - spend details object
quoted_spend?: any; // Simplified - optional quoted spend object
receive: any; // Simplified - receive details object
quoted_receive?: any; // Simplified - optional quoted receive object
unit_price: any; // Simplified - unit price object
quoted_unit_price?: any; // Simplified - optional quoted unit price object
⋮----
/**
 * Execute Quote response
 */
export interface PartnerExecuteQuoteResponse {
  result?: {
    quote_id: string;
    status: any; // Simplified - status object
    transaction_id?: string;
  };
}
⋮----
status: any; // Simplified - status object
⋮----
/**
 * Get Portfolio Summary response
 */
export interface PartnerGetPortfolioSummaryResponse {
  result: {
    timestamp: string; // ISO 8601 datetime
    currency: string;
    portfolio_value: string; // decimal128
    withheld_value: string; // decimal128
    open_orders: string; // decimal128
    available_balance: string; // decimal128
    lots_upnl?: string; // decimal128
    cost_basis?: string; // decimal128
    current_day_pnl?: {
      since: string; // ISO 8601 datetime
      pnl: string; // decimal128
    };
  };
}
⋮----
timestamp: string; // ISO 8601 datetime
⋮----
portfolio_value: string; // decimal128
withheld_value: string; // decimal128
open_orders: string; // decimal128
available_balance: string; // decimal128
lots_upnl?: string; // decimal128
cost_basis?: string; // decimal128
⋮----
since: string; // ISO 8601 datetime
pnl: string; // decimal128
⋮----
/**
 * Get Portfolio History response
 */
export interface PartnerGetPortfolioHistoryResponse {
  result: {
    start_date: string; // RFC3339 date
    end_date: string; // RFC3339 date
    next_cursor?: string;
    currency?: string; // AssetName
    total_pnl?: string; // decimal128
    total_pnl_pct?: string; // decimal128
    history: any[]; // Simplified - array of historical data points
  };
}
⋮----
start_date: string; // RFC3339 date
end_date: string; // RFC3339 date
⋮----
currency?: string; // AssetName
total_pnl?: string; // decimal128
total_pnl_pct?: string; // decimal128
history: any[]; // Simplified - array of historical data points
⋮----
/**
 * List Portfolio Details response
 */
export interface PartnerListPortfolioDetailsResponse {
  result?: {
    timestamp: string; // ISO 8601 datetime
    currency: string;
    assets: any[]; // Simplified - array of asset detail objects
  };
}
⋮----
timestamp: string; // ISO 8601 datetime
⋮----
assets: any[]; // Simplified - array of asset detail objects
⋮----
/**
 * List Portfolio Transactions response
 */
export interface PartnerListPortfolioTransactionsResponse {
  result?: {
    transactions: any[]; // Simplified - array of transaction objects
    stats?: {
      transactions_seen?: number;
    };
    next_cursor?: string;
  };
}
⋮----
transactions: any[]; // Simplified - array of transaction objects
⋮----
/**
 * Get Earn Summary response
 */
export interface PartnerGetEarnSummaryResponse {
  result: {
    auto_earn_eligible: boolean;
    auto_earn_enabled: boolean;
    auto_earn_last_changed?: string; // ISO 8601 datetime
    payout_period: string; // ISO 8601 duration
    total_allocated_converted: string; // decimal128
    total_rewarded_converted_true_rates: string; // decimal128
    total_rewarded_converted_current_rate: string; // decimal128
    num_earning_assets: number; // uint32
    upcoming_rewards: any[]; // Simplified - array of upcoming reward objects
  };
}
⋮----
auto_earn_last_changed?: string; // ISO 8601 datetime
payout_period: string; // ISO 8601 duration
total_allocated_converted: string; // decimal128
total_rewarded_converted_true_rates: string; // decimal128
total_rewarded_converted_current_rate: string; // decimal128
num_earning_assets: number; // uint32
upcoming_rewards: any[]; // Simplified - array of upcoming reward objects
⋮----
/**
 * List Earn Assets response
 */
export interface PartnerListEarnAssetsResponse {
  result: {
    assets: Record<string, any>; // Simplified - object with asset names as keys
  };
}
⋮----
assets: Record<string, any>; // Simplified - object with asset names as keys
⋮----
/**
 * Toggle Auto-Earn response
 */
export interface PartnerToggleAutoEarnResponse {
  result?: any; // Empty/null on success
}
⋮----
result?: any; // Empty/null on success
⋮----
/**
 * Withdraw Funds response
 */
export interface PartnerWithdrawFundsResponse {
  result?: {
    reference_id: string;
  };
}
⋮----
/**
 * List Funding Transactions response
 */
export interface PartnerListFundingTransactionsResponse {
  result: {
    transactions: Array<{
      type: 'withdrawal' | 'deposit';
      date: string; // ISO 8601 datetime
      asset: string;
      amount: string; // decimal128
      status:
        | 'initial'
        | 'pending'
        | 'settled'
        | 'success'
        | 'partial'
        | 'failure';
      ref_id: string;
    }>;
    next_cursor?: string;
  };
}
⋮----
date: string; // ISO 8601 datetime
⋮----
amount: string; // decimal128
⋮----
/**
 * List Settlement Reports response
 */
export interface PartnerListSettlementReportsResponse {
  result?: {
    reports: Array<{
      id: string;
      date: string; // RFC3339 date
      type: 'trades' | 'transfers' | 'earn_rewards';
      size: number; // int64, bytes
      name: string;
    }>;
    links: {
      self?: string;
      first?: string;
      last?: string;
      prev?: string;
      next?: string;
    };
    meta: {
      total_items?: number;
      total_pages?: number;
      page_size?: number;
      page_number?: number;
    };
  };
}
⋮----
date: string; // RFC3339 date
⋮----
size: number; // int64, bytes
⋮----
/**
 * Get Settlement Report response
 */
export interface PartnerGetSettlementReportResponse {
  result?: {
    id: string;
    date: string; // RFC3339 date
    type: 'trades' | 'transfers' | 'earn_rewards';
    size: number; // int64, bytes
    name: string;
    download_url: string;
    expires_at: string; // ISO 8601 datetime
  };
}
⋮----
date: string; // RFC3339 date
⋮----
size: number; // int64, bytes
⋮----
expires_at: string; // ISO 8601 datetime
⋮----
/**
 * List Ramp Buy Crypto Assets response
 */
export interface PartnerListRampBuyCryptoAssetsResponse {
  result: {
    assets: any[]; // Simplified - array of crypto asset objects
  };
}
⋮----
assets: any[]; // Simplified - array of crypto asset objects
⋮----
/**
 * List Ramp Fiat Currencies response
 */
export interface PartnerListRampFiatCurrenciesResponse {
  result: {
    currencies: Array<{
      asset: string; // AssetName, 3-16 chars
      asset_class?: 'currency';
    }>;
  };
}
⋮----
asset: string; // AssetName, 3-16 chars
⋮----
/**
 * List Ramp Payment Methods response
 */
export interface PartnerListRampPaymentMethodsResponse {
  result: {
    methods: Array<{
      funding_type: string;
      external_id?: string;
    }>;
  };
}
⋮----
/**
 * List Ramp Countries response
 */
export interface PartnerListRampCountriesResponse {
  result: {
    countries: any[]; // Simplified - array of country objects
  };
}
⋮----
countries: any[]; // Simplified - array of country objects
⋮----
/**
 * Get Ramp Limits response
 */
export interface PartnerGetRampLimitsResponse {
  result: {
    limits: any; // Simplified - complex nested limits object
  };
}
⋮----
limits: any; // Simplified - complex nested limits object
⋮----
/**
 * Get Ramp Prospective Quote response
 */
export interface PartnerGetRampProspectiveQuoteResponse {
  result: {
    spend: any; // Simplified - asset breakdown object
    receive: any; // Simplified - asset breakdown object
    unit_price: any; // Simplified - unit price object
  };
}
⋮----
spend: any; // Simplified - asset breakdown object
receive: any; // Simplified - asset breakdown object
unit_price: any; // Simplified - unit price object
⋮----
/**
 * Get Ramp Checkout URL response
 */
export interface PartnerGetRampCheckoutUrlResponse {
  result: {
    checkout_url: string; // URI
    request_data: any; // Simplified - original request payload object
  };
}
⋮----
checkout_url: string; // URI
request_data: any; // Simplified - original request payload object
⋮----
/** Shared price trigger for custom orders (Embed) */
export interface PartnerCustomOrderPriceTrigger {
  type: 'price';
  base_asset: string;
  quote_asset: string;
  target_price: string;
  condition: 'gte' | 'lte';
}
⋮----
/** Shared action object for custom orders (Embed) */
export interface PartnerCustomOrderAction {
  type: 'receive' | 'spend';
  amount: {
    asset_class?: 'currency';
    asset: string;
    amount: string;
  };
  quote: {
    asset: string;
    fee_bps: string;
    spread_bps: string;
  };
}
⋮----
/** Single custom order in responses */
export interface PartnerCustomOrder {
  id: string;
  name: string;
  action: PartnerCustomOrderAction;
  trigger: PartnerCustomOrderPriceTrigger;
  created_at: string; // date-time
  updated_at: string; // date-time
  status:
    | { status: 'active' }
    | { status: 'completed' }
    | { status: 'cancelled' }
    | { status: 'paused' };
}
⋮----
created_at: string; // date-time
updated_at: string; // date-time
⋮----
/**
 * Create Custom Order response
 */
export interface PartnerCreateCustomOrderResponse {
  result?: {
    order: PartnerCustomOrder;
  };
}
⋮----
/**
 * List Custom Orders response
 */
export interface PartnerListCustomOrdersResponse {
  result?: {
    orders: PartnerCustomOrder[];
    next_cursor?: string;
  };
}
⋮----
/**
 * Get Custom Order response
 */
export interface PartnerGetCustomOrderResponse {
  result?: {
    order: PartnerCustomOrder;
  };
}
⋮----
/**
 * Cancel Custom Order response
 */
export interface PartnerCancelCustomOrderResponse {
  result?: {
    order: PartnerCustomOrder;
  };
}
⋮----
/** Asset amount object used in quote limits/limits response */
export interface PartnerQuoteLimitAmount {
  asset: string;
  amount: string;
}
⋮----
/**
 * Get Quote Limits response (RFQ)
 */
export interface PartnerGetQuoteLimitsResponse {
  result?: {
    asset: string;
    minimum: string;
    maximum: string;
    precision: number;
    minimum_tradable_amount?: string | null;
    minimum_in_display?: PartnerQuoteLimitAmount | null;
    maximum_in_display?: PartnerQuoteLimitAmount | null;
    minimum_tradable_amount_in_display?: PartnerQuoteLimitAmount | null;
  };
}
⋮----
/** Spend/receive breakdown in prospective quote */
export interface PartnerProspectiveQuoteBreakdown {
  asset: string;
  asset_class?: 'currency' | null;
  total: string;
  fee: string;
  subtotal: string;
}
⋮----
/** Unit price in prospective quote */
export interface PartnerProspectiveQuoteUnitPrice {
  asset: string;
  asset_class?: 'currency' | null;
  unit_price: string;
  denomination_asset: string;
  denomination_asset_class?: 'currency' | null;
}
⋮----
/**
 * Request Prospective Quote response (RFQ)
 */
export interface PartnerRequestProspectiveQuoteResponse {
  result?: {
    type: 'receive' | 'spend';
    spend: PartnerProspectiveQuoteBreakdown;
    receive: PartnerProspectiveQuoteBreakdown;
    unit_price: PartnerProspectiveQuoteUnitPrice;
    quoted_spend?: PartnerProspectiveQuoteBreakdown | null;
    quoted_receive?: PartnerProspectiveQuoteBreakdown | null;
    quoted_unit_price?: PartnerProspectiveQuoteUnitPrice | null;
  };
}

================
File: src/types/response/shared.types.ts
================
import { RestClientOptions } from '../../lib/requestUtils.js';
⋮----
export type DerivativesAPISuccessResponse<TData> = {
  result: 'success';
  serverTime: string;
} & TData;
⋮----
export interface DerivativesAPIErrorResponse {
  result: 'error';
  error: string;
  serverTime: string;
}
⋮----
export type DerivativesAPIResponse<TData> =
  | DerivativesAPISuccessResponse<TData>
  | DerivativesAPIErrorResponse;
⋮----
export type SpotAPISuccessResponse<TData> = {
  error: string[];
  result: TData;
};
⋮----
export interface SpotAPIErrorResponse {
  // e.g.{ error: [ 'EGeneral:Invalid arguments:ordertype' ] },
  error: string[];
}
⋮----
// e.g.{ error: [ 'EGeneral:Invalid arguments:ordertype' ] },
⋮----
export type SpotAPIResponse<TData> =
  | SpotAPISuccessResponse<TData>
  | SpotAPIErrorResponse;
⋮----
export interface GenericAPIError<TBody = any> {
  code: number;
  message: string;
  body: TBody;
  headers: Record<string, string>;
  requestOptions: RestClientOptions;
  requestParams: Record<string, any>;
}

================
File: src/types/response/spot.types.ts
================
/**
 * Market Data
 */
⋮----
export interface SpotSystemStatus {
  status: 'online' | 'maintenance' | 'cancel_only' | 'post_only';
  timestamp: string;
}
⋮----
export interface SpotAssetInfo {
  aclass: string;
  altname: string;
  decimals: number;
  display_decimals: number;
  collateral_value?: number;
  status?: string;
}
⋮----
export interface SpotAssetPair {
  altname: string;
  wsname?: string;
  aclass_base: string;
  base: string;
  aclass_quote: string;
  quote: string;
  lot?: string;
  pair_decimals: number;
  cost_decimals: number;
  lot_decimals: number;
  lot_multiplier: number;
  leverage_buy?: number[];
  leverage_sell?: number[];
  fees?: number[][];
  fees_maker?: number[][];
  fee_volume_currency?: string;
  margin_call?: number;
  margin_stop?: number;
  ordermin: string;
  costmin?: string;
  tick_size?: string;
  status?: string;
  long_position_limit?: number;
  short_position_limit?: number;
  execution_venue?: string;
}
⋮----
export interface SpotAssetTickerInfo {
  a: string[]; // Ask [price, whole lot volume, lot volume]
  b: string[]; // Bid [price, whole lot volume, lot volume]
  c: string[]; // Last trade closed [price, lot volume]
  v: string[]; // Volume [today, last 24 hours]
  p: string[]; // Volume weighted average price [today, last 24 hours]
  t: number[]; // Number of trades [today, last 24 hours]
  l: string[]; // Low [today, last 24 hours]
  h: string[]; // High [today, last 24 hours]
  o: string; // Today's opening price
}
⋮----
a: string[]; // Ask [price, whole lot volume, lot volume]
b: string[]; // Bid [price, whole lot volume, lot volume]
c: string[]; // Last trade closed [price, lot volume]
v: string[]; // Volume [today, last 24 hours]
p: string[]; // Volume weighted average price [today, last 24 hours]
t: number[]; // Number of trades [today, last 24 hours]
l: string[]; // Low [today, last 24 hours]
h: string[]; // High [today, last 24 hours]
o: string; // Today's opening price
⋮----
// [time, open, high, low, close, vwap, volume, count]
export type SpotOHLCData = [
  number,
  string,
  string,
  string,
  string,
  string,
  string,
  number,
];
⋮----
export interface SpotOHLCResponse {
  last: number;
  [pairName: string]: SpotOHLCData[] | number;
}
⋮----
// [price, volume, timestamp]
export type SpotOrderBookEntry = [string, string, number];
⋮----
export interface SpotOrderBook {
  asks: SpotOrderBookEntry[];
  bids: SpotOrderBookEntry[];
}
⋮----
export interface SpotOrderBookResponse {
  [pairName: string]: SpotOrderBook;
}
⋮----
// [price, volume, time, buy/sell, market/limit, miscellaneous, trade_id]
export type SpotTradeData = [
  string,
  string,
  number,
  string,
  string,
  string,
  number,
];
⋮----
export interface SpotRecentTradesResponse {
  last: string;
  [pairName: string]: SpotTradeData[] | string;
}
⋮----
// [time, bid, ask]
export type SpotSpreadData = [number, string, string];
⋮----
export interface SpotRecentSpreadsResponse {
  last: number;
  [pairName: string]: SpotSpreadData[] | number;
}
⋮----
/**
 * Account Data
 */
⋮----
export interface SpotAccountBalance {
  [assetName: string]: string;
}
⋮----
export interface SpotExtendedBalanceAsset {
  balance: string;
  credit: string;
  credit_used: string;
  hold_trade: string;
}
⋮----
export interface SpotExtendedBalance {
  [assetName: string]: SpotExtendedBalanceAsset;
}
⋮----
export interface SpotCreditLinesAsset {
  balance: string;
  credit_limit: string;
  credit_used: string;
  available_credit: string;
}
⋮----
export interface SpotCreditLinesMonitor {
  total_credit_usd: string | null;
  total_credit_used_usd: string | null;
  total_collateral_value_usd: string | null;
  equity_usd: string | null;
  ongoing_balance: string | null;
  debt_to_equity: string | null;
}
⋮----
export interface SpotCreditLines {
  asset_details: {
    [assetName: string]: SpotCreditLinesAsset;
  };
  limits_monitor: SpotCreditLinesMonitor;
}
⋮----
export interface SpotTradeBalance {
  eb: string; // Equivalent balance
  tb: string; // Trade balance
  m: string; // Margin amount of open positions
  n: string; // Unrealized net profit/loss of open positions
  c: string; // Cost basis of open positions
  v: string; // Current floating valuation of open positions
  e: string; // Equity: trade balance + unrealized net profit/loss
  mf: string; // Free margin
  ml: string; // Margin level
  uv: string; // Unexecuted value
}
⋮----
eb: string; // Equivalent balance
tb: string; // Trade balance
m: string; // Margin amount of open positions
n: string; // Unrealized net profit/loss of open positions
c: string; // Cost basis of open positions
v: string; // Current floating valuation of open positions
e: string; // Equity: trade balance + unrealized net profit/loss
mf: string; // Free margin
ml: string; // Margin level
uv: string; // Unexecuted value
⋮----
export interface SpotOpenOrderDescription {
  pair: string;
  type: 'buy' | 'sell';
  ordertype:
    | 'market'
    | 'limit'
    | 'iceberg'
    | 'stop-loss'
    | 'take-profit'
    | 'stop-loss-limit'
    | 'take-profit-limit'
    | 'trailing-stop'
    | 'trailing-stop-limit'
    | 'settle-position';
  price: string;
  price2: string;
  leverage: string;
  order: string;
  close: string;
}
⋮----
export interface SpotOpenOrder {
  refid: string | null;
  userref: number | null;
  cl_ord_id: string | null;
  status: 'pending' | 'open' | 'closed' | 'canceled' | 'expired';
  opentm: number;
  starttm: number;
  expiretm: number;
  descr: SpotOpenOrderDescription;
  vol: string;
  vol_exec: string;
  cost: string;
  fee: string;
  price: string;
  stopprice: string;
  limitprice: string;
  trigger?: 'last' | 'index';
  margin?: boolean;
  misc: string;
  stopped?: string;
  touched?: string;
  liquidated?: string;
  partial?: string;
  amended?: string;
  sender_sub_id: string | null;
  oflags: string;
  trades?: string[];
}
⋮----
export interface SpotOpenOrdersResponse {
  open: {
    [orderId: string]: SpotOpenOrder;
  };
}
⋮----
export interface SpotClosedOrder extends SpotOpenOrder {
  closetm: number;
  reason: string;
}
⋮----
export interface SpotClosedOrdersResponse {
  closed: {
    [orderId: string]: SpotClosedOrder;
  };
  count?: number;
}
⋮----
export interface SpotQueryOrdersResponse {
  [orderId: string]: SpotOpenOrder | SpotClosedOrder;
}
⋮----
export interface SpotOrderAmend {
  amend_id: string;
  amend_type: 'original' | 'user' | 'restated';
  order_qty: string;
  display_qty: string;
  remaining_qty: string;
  limit_price: string;
  trigger_price: string;
  reason: string;
  post_only: boolean;
  timestamp: number;
}
⋮----
export interface SpotOrderAmendsResponse {
  count: number;
  amends: SpotOrderAmend[];
}
⋮----
export interface SpotTrade {
  ordertxid: string;
  postxid: string;
  pair: string;
  time: number;
  type: string;
  ordertype: string;
  price: string;
  cost: string;
  fee: string;
  vol: string;
  margin: string;
  leverage: string;
  misc: string;
  ledgers?: string[];
  trade_id: number;
  maker: boolean;
  posstatus?: string;
  cprice?: number;
  ccost?: number;
  cfee?: number;
  cvol?: number;
  cmargin?: number;
  net?: number;
  trades?: string[];
}
⋮----
export interface SpotTradesHistoryResponse {
  count: number;
  trades: {
    [tradeId: string]: SpotTrade;
  };
}
⋮----
export interface SpotQueryTradesResponse {
  [tradeId: string]: SpotTrade;
}
⋮----
export interface SpotOpenPosition {
  ordertxid: string;
  posstatus: 'open';
  pair: string;
  time: number;
  type: string;
  ordertype: string;
  cost: string;
  fee: string;
  vol: string;
  vol_closed: string;
  margin: string;
  value?: string;
  net?: string;
  terms: string;
  rollovertm: string;
  misc: string;
  oflags: string;
}
⋮----
export interface SpotOpenPositionsResponse {
  [positionId: string]: SpotOpenPosition;
}
⋮----
export interface SpotLedgerEntry {
  refid: string;
  time: number;
  type:
    | 'none'
    | 'trade'
    | 'deposit'
    | 'withdrawal'
    | 'transfer'
    | 'margin'
    | 'adjustment'
    | 'rollover'
    | 'spend'
    | 'receive'
    | 'settled'
    | 'credit'
    | 'staking'
    | 'reward'
    | 'dividend'
    | 'sale'
    | 'conversion'
    | 'nfttrade'
    | 'nftcreatorfee'
    | 'nftrebate'
    | 'custodytransfer';
  subtype: string;
  aclass: string;
  asset: string;
  amount: string;
  fee: string;
  balance: string;
}
⋮----
export interface SpotLedgersInfoResponse {
  ledger: {
    [ledgerId: string]: SpotLedgerEntry;
  };
  count?: number;
}
⋮----
export interface SpotQueryLedgersResponse {
  [ledgerId: string]: SpotLedgerEntry;
}
⋮----
export interface SpotFeeTierInfo {
  fee: string;
  min_fee: string;
  max_fee: string;
  next_fee: string | null;
  tier_volume: string | null;
  next_volume: string | null;
}
⋮----
export interface SpotTradeVolume {
  currency: string;
  volume: string;
  fees?: {
    [pairName: string]: SpotFeeTierInfo;
  };
  fees_maker?: {
    [pairName: string]: SpotFeeTierInfo;
  };
}
⋮----
export interface SpotRequestExportReportResponse {
  id: string;
}
⋮----
export interface SpotExportReportStatus {
  id: string;
  descr: string;
  format: string;
  report: string;
  subtype: string;
  status: 'Queued' | 'Processing' | 'Processed';
  flags: string;
  fields: string;
  createdtm: string;
  expiretm: string;
  starttm: string;
  completedtm: string;
  datastarttm: string;
  dataendtm: string;
  aclass: string;
  asset: string;
}
⋮----
export interface SpotDeleteExportReportResponse {
  delete?: boolean;
  cancel?: boolean;
}
⋮----
/**
 * Trading
 */
⋮----
export interface SpotAddOrderDescription {
  order: string;
  close?: string;
}
⋮----
export interface SpotSubmitOrderResponse {
  descr: SpotAddOrderDescription;
  txid: string[];
}
⋮----
export interface SpotWebSocketsTokenResponse {
  token: string;
  expires: number;
}
⋮----
export interface SpotBatchOrderResult {
  descr?: {
    order: string;
  };
  error?: string;
  txid?: string;
}
⋮----
/**
 * Funding
 */
⋮----
export interface SpotDepositMethod {
  method: string;
  limit: string | boolean;
  fee: string;
  'address-setup-fee': string;
  'gen-address': boolean;
  minimum: string;
}
⋮----
export interface SpotDepositAddress {
  address: string;
  expiretm: string;
  new: boolean;
  tag?: string;
}
⋮----
export interface SpotDepositStatus {
  method: string;
  aclass: string;
  asset: string;
  refid: string;
  txid: string;
  info: string;
  amount: string;
  fee: string;
  time: number;
  status: string;
  'status-prop'?: 'return' | 'onhold';
  originators?: string[];
}
⋮----
export interface SpotDepositStatusResponse {
  cursor?: string;
  [key: string]: SpotDepositStatus[] | string | undefined;
}
⋮----
export interface SpotWithdrawalMethod {
  asset: string;
  method: string;
  network: string;
  minimum: string;
}
⋮----
export interface SpotWithdrawalAddress {
  address: string;
  asset: string;
  method: string;
  key: string;
  tag?: string;
  verified: boolean;
}
⋮----
export interface SpotWithdrawalInfo {
  method: string;
  limit: string;
  amount: string;
  fee: string;
}
⋮----
export interface SpotWithdrawalStatus {
  method: string;
  network: string;
  aclass: string;
  asset: string;
  refid: string;
  txid: string;
  info: string;
  amount: string;
  fee: string;
  time: number;
  status: 'Initial' | 'Pending' | 'Settled' | 'Success' | 'Failure';
  'status-prop'?:
    | 'cancel-pending'
    | 'canceled'
    | 'cancel-denied'
    | 'return'
    | 'onhold';
  key: string;
}
⋮----
/**
 * Subaccounts
 */
⋮----
export interface SpotAccountTransferResponse {
  transfer_id: string;
  status: string;
}
⋮----
/**
 * Earn
 */
⋮----
export interface SpotEarnAmount {
  native: string;
  converted: string;
}
⋮----
export interface SpotEarnAllocationDetails {
  native: string;
  converted: string;
  created_at: string;
  expires: string;
}
⋮----
export interface SpotEarnAllocationState {
  allocation_count: number;
  allocations: SpotEarnAllocationDetails[];
  native: string;
  converted: string;
}
⋮----
export interface SpotEarnPayout {
  accumulated_reward: SpotEarnAmount;
  estimated_reward: SpotEarnAmount;
  period_start: string;
  period_end: string;
}
⋮----
export interface SpotEarnAllocation {
  strategy_id: string;
  native_asset: string;
  amount_allocated: {
    total: SpotEarnAmount;
    bonding?: SpotEarnAllocationState;
    exit_queue?: SpotEarnAllocationState;
    unbonding?: SpotEarnAllocationState;
    pending?: SpotEarnAmount;
  };
  total_rewarded: SpotEarnAmount;
  payout?: SpotEarnPayout;
}
⋮----
export interface SpotListEarnAllocationsResponse {
  converted_asset: string;
  total_allocated: string;
  total_rewarded: string;
  items: SpotEarnAllocation[];
}
⋮----
export interface SpotEarnAPREstimate {
  low: string;
  high: string;
}
⋮----
export interface SpotEarnAutoCompound {
  type: 'disabled' | string;
  default?: boolean;
}
⋮----
export interface SpotEarnLockType {
  type: 'flex' | 'bonded' | 'timed' | 'instant';
  payout_frequency?: number;
  bonding_period?: number;
  bonding_period_variable?: boolean;
  bonding_rewards?: boolean;
  unbonding_period?: number;
  unbonding_period_variable?: boolean;
  unbonding_rewards?: boolean;
  exit_queue_period?: number;
}
⋮----
export interface SpotEarnYieldSource {
  type: 'staking' | 'off_chain' | string;
}
⋮----
export interface SpotEarnStrategy {
  id: string;
  asset: string;
  lock_type: SpotEarnLockType;
  apr_estimate?: SpotEarnAPREstimate;
  user_min_allocation?: string;
  allocation_fee: string | number;
  deallocation_fee: string | number;
  auto_compound: SpotEarnAutoCompound;
  yield_source: SpotEarnYieldSource;
  can_allocate: boolean;
  can_deallocate: boolean;
  allocation_restriction_info: string[];
  user_cap?: string;
}
⋮----
/**
 * Transparency
 */
⋮----
export interface SpotPreTradeLevel {
  side: 'BUY' | 'SELL';
  price: string;
  qty: string;
  count: number;
  publication_ts: string;
}
⋮----
export interface SpotPreTradeData {
  symbol: string;
  description: string;
  base_asset: string;
  base_notation: 'NOML';
  quote_asset: string;
  quote_notation: 'MONE';
  venue: string;
  system: 'CLOB';
  bids: SpotPreTradeLevel[];
  asks: SpotPreTradeLevel[];
}
⋮----
export interface SpotPostTrade {
  trade_id: string;
  price: string;
  quantity: string;
  symbol: string;
  description: string;
  base_asset: string;
  base_notation: 'UNIT';
  quote_asset: string;
  quote_notation: 'MONE';
  trade_venue: string;
  trade_ts: string;
  publication_venue: string;
  publication_ts: string;
}
⋮----
export interface SpotPostTradeDataResponse {
  last_ts: string;
  count: number;
  trades: SpotPostTrade[];
}
⋮----
/**
 * OAuth
 */
⋮----
export interface OauthGetAccessTokenResponse {
  access_token: string;
  token_type: 'bearer';
  expires_in: number;
  refresh_token: string;
}
⋮----
export interface OauthGetUserInfoResponse {
  result: {
    email: string;
    iban: string;
  };
}
⋮----
export interface OauthFastApiKey {
  api_key?: string; // Only returned on creation
  api_key_name: string;
  created_time: string;
  id: string;
  ip_allowlist: string[];
  last_used: number;
  modified_time: string;
  nonce: number;
  nonce_window: number;
  oauth_client: string;
  permissions: any; // Simplified
  purpose: string;
  query_from: number;
  query_to: number;
  valid_until: number;
}
⋮----
api_key?: string; // Only returned on creation
⋮----
permissions: any; // Simplified
⋮----
export interface OauthCreateFastApiKeyResponse {
  result: OauthFastApiKey & {
    secret: string; // Only returned on creation
  };
}
⋮----
secret: string; // Only returned on creation

================
File: src/types/response/wsapi.types.ts
================
/**
 * Websocket API v2 Spot Response Types
 */
⋮----
export interface WSAPIAddSpotOrderResult {
  order_id: string;
  cl_ord_id?: string;
  order_userref?: number;
  warnings?: string[];
}
⋮----
export interface WSAPIAmendSpotOrderResult {
  amend_id: string;
  order_id?: string;
  cl_ord_id?: string;
  warnings?: string[];
}
⋮----
export interface WSAPICancelSpotOrderResult {
  order_id: string;
  cl_ord_id?: string;
  warnings?: string[];
}
⋮----
export interface WSAPICancelAllSpotOrdersResult {
  count: number;
  warnings?: string[];
}
⋮----
export interface WSAPICancelAllSpotOrdersAfterResult {
  currentTime: string;
  triggerTime: string;
  warnings?: string[];
}
⋮----
export interface WSAPIBatchAddSpotOrdersResult {
  order_id: string;
  cl_ord_id?: string;
  order_userref?: number;
  warnings?: string[];
}
⋮----
export interface WSAPIBatchCancelSpotOrdersResult {
  count: number;
  warnings?: string[];
}
⋮----
export interface WSAPIEditSpotOrderResult {
  order_id: string;
  original_order_id: string;
  warnings?: string[];
}

================
File: src/types/websockets/ws-subscriptions.ts
================
] as const; // Note: Admin topics (Status, Heartbeat & Ping are automatically used internally and can't be subscribed to manually).
⋮----
export type WSSpotPublicTopic = (typeof WS_SPOT_PUBLIC_TOPICS)[number];
⋮----
export type WSSpotPrivateTopic = (typeof WS_SPOT_PRIVATE_TOPICS)[number];
⋮----
export type WSSpotTopic = WSSpotPublicTopic | WSSpotPrivateTopic;
⋮----
export type WSDerivativesPublicTopic =
  (typeof WS_DERIVATIVES_PUBLIC_TOPICS)[number];
⋮----
export type WSDerivativesPrivateTopic =
  (typeof WS_DERIVATIVES_PRIVATE_TOPICS)[number];
⋮----
export type WSDerivativesTopic =
  | WSDerivativesPublicTopic
  | WSDerivativesPrivateTopic;
⋮----
export type WSTopic = WSSpotTopic | WSDerivativesTopic;

================
File: src/InstitutionalClient.ts
================
import { nanoid } from 'nanoid';
⋮----
import { BaseRestClient } from './lib/BaseRestClient.js';
import { REST_CLIENT_TYPE_ENUM, RestClientType } from './lib/requestUtils.js';
import {
  CustodyDepositAddressesParams,
  CustodyDepositMethodsParams,
  CustodyGetTransactionParams,
  CustodyListActivitiesParams,
  CustodyListTasksParams,
  CustodyListTransactionsParams,
  CustodyListVaultsParams,
  CustodyWithdrawAddressesParams,
  CustodyWithdrawMethodsParams,
  OTCCreateQuoteRequestParams,
  OTCUpdateQuoteParams,
} from './types/request/institutional.types.js';
import {
  CustodyDepositAddressesResponse,
  CustodyDepositMethodsResponse,
  CustodyGetActivityResponse,
  CustodyGetTaskResponse,
  CustodyGetTransactionResponse,
  CustodyGetVaultResponse,
  CustodyListActivitiesResponse,
  CustodyListTasksResponse,
  CustodyListTransactionsResponse,
  CustodyListVaultsResponse,
  CustodyWithdrawAddressesResponse,
  CustodyWithdrawMethodsResponse,
  OTCCheckClientResponse,
  OTCCreateQuoteResponse,
  OTCGetActiveQuotesResponse,
  OTCGetExposuresResponse,
  OTCGetHistoricalQuotesResponse,
  OTCGetPairsResponse,
  OTCUpdateQuoteResponse,
} from './types/response/institutional.types.js';
⋮----
/**
 * The InstitutionalClient provides integration to the Kraken Institutional API.
 *
 * Docs:
 * - https://docs.kraken.com/api/docs/custody-api
 * - https://docs.kraken.com/api/docs/otc-api
 */
export class InstitutionalClient extends BaseRestClient
⋮----
getClientType(): RestClientType
⋮----
/**
   *
   * Misc Utility Methods
   *
   */
⋮----
generateNewOrderID(): string
⋮----
/**
   *
   * Custody REST API - Portfolios
   *
   */
⋮----
/**
   * List vaults
   *
   * Retrieve all vaults within the custody domain.
   */
listCustodyVaults(
    params: CustodyListVaultsParams,
): Promise<CustodyListVaultsResponse>
⋮----
/**
   * Get vault information by id
   *
   * Retrieve information and balances for a specific vault.
   */
getCustodyVaultbyId(params: {
    id: string;
    nonce?: number;
}): Promise<CustodyGetVaultResponse>
⋮----
/**
   * Get deposit methods
   *
   * Retrieve the available deposit funding methods for depositing a specific asset.
   * The deposit method is required to retrieve deposit addresses using the Get Deposit Addresses API.
   */
getCustodyDepositMethods(
    params: CustodyDepositMethodsParams,
): Promise<CustodyDepositMethodsResponse>
⋮----
/**
   * Get deposit addresses
   *
   * Retrieve (or generate a new) deposit addresses for a particular asset and funding method.
   * Use the Get Deposit Methods API to identify the appropriate deposit method.
   */
getCustodyDepositAddresses(
    params: CustodyDepositAddressesParams,
): Promise<CustodyDepositAddressesResponse>
⋮----
/**
   * List custody transactions
   *
   * Retrieve the transaction history for a specified vault.
   */
listCustodyTransactions(
    params: CustodyListTransactionsParams,
): Promise<CustodyListTransactionsResponse>
⋮----
/**
   * Get transaction by id
   *
   * Get transaction by id
   */
getCustodyTransactionbyId(
    params: CustodyGetTransactionParams,
): Promise<CustodyGetTransactionResponse>
⋮----
/**
   *
   * Custody REST API - Transfers
   *
   */
⋮----
/**
   * Get withdraw methods
   *
   * Retrieve a list of withdrawal methods available for a specified vault.
   */
getCustodyWithdrawMethods(
    params: CustodyWithdrawMethodsParams,
): Promise<CustodyWithdrawMethodsResponse>
⋮----
/**
   * Get withdraw addresses
   *
   * Retrieve a list of withdrawal addresses for a specified vault.
   */
getCustodyWithdrawAddresses(
    params: CustodyWithdrawAddressesParams,
): Promise<CustodyWithdrawAddressesResponse>
⋮----
/**
   *
   * Custody REST API - Tasks
   *
   */
⋮----
/**
   * List tasks
   *
   * Retrieve review tasks that match the specified filter criteria.
   */
listCustodyTasks(
    params: CustodyListTasksParams,
): Promise<CustodyListTasksResponse>
⋮----
/**
   * Get task by id
   *
   * Retrieve details for a specific task.
   */
getCustodyTaskbyId(params: {
    id: string;
    nonce?: number;
}): Promise<CustodyGetTaskResponse>
⋮----
/**
   * List activities
   *
   * Retrieve all activities that match the specified filter criteria.
   */
listCustodyActivities(
    params: CustodyListActivitiesParams,
): Promise<CustodyListActivitiesResponse>
⋮----
/**
   * Get activity by id
   *
   * Retrieve details for a specific task activity.
   */
getCustodyActivitybyId(params: {
    id: string;
    nonce?: number;
}): Promise<CustodyGetActivityResponse>
⋮----
/**
   *
   * OTC REST API - Quotes
   *
   */
⋮----
/**
   * Create OTC Quote
   *
   * Creates a new OTC request for quote.
   * API Key Permissions Required: Orders and trades - Create & modify orders
   */
createOtcQuoteRequest(
    params: OTCCreateQuoteRequestParams,
): Promise<OTCCreateQuoteResponse>
⋮----
/**
   * Update OTC Quote
   *
   * Accepts or rejects an OTC quote.
   * API Key Permissions Required: Orders and trades - Create & modify orders
   */
updateOtcQuote(
    params: OTCUpdateQuoteParams,
): Promise<OTCUpdateQuoteResponse>
⋮----
/**
   * Get OTC Pairs
   *
   * Retrieves the list of OTC trading pairs.
   * API Key Permissions Required: Funds permissions - Query and Funds permissions - Deposit
   */
getOtcPairs(params?:
⋮----
/**
   * Get OTC Active Quotes
   *
   * Retrieves a list of active OTC quotes.
   * API Key Permissions Required: Orders and trades - Query open orders & trades
   */
getOtcActiveQuotes(params?: {
    nonce?: number;
    vault_id?: string;
}): Promise<OTCGetActiveQuotesResponse>
⋮----
/**
   * Get OTC Historical Quotes
   *
   * Retrieves OTC quotes history.
   * API Key Permissions Required: Orders and trades - Query open orders & trades
   */
getOtcHistoricalQuotes(params?: {
    nonce?: number;
}): Promise<OTCGetHistoricalQuotesResponse>
⋮----
/**
   * Get OTC Exposures
   *
   * Retrieves the max and used OTC exposures.
   * API Key Permissions Required: Orders and trades - Query open orders & trades
   */
getOtcExposures(params?: {
    nonce?: number;
}): Promise<OTCGetExposuresResponse>
⋮----
/**
   * Check OTC Eligibility
   *
   * Retrieves the client permissions for the OTC Portal.
   * API Key Permissions Required: Funds permissions - Query and Funds permissions - Deposit
   */
checkOtcClient(params?:

================
File: webpack/webpack.config.cjs
================
function generateConfig(name)
⋮----
// Add '.ts' and '.tsx' as resolvable extensions.
⋮----
// Node.js core modules not available in browsers
// The REST client's https.Agent (for keepAlive) is Node.js-only and won't work in browsers
⋮----
// Code is already transpiled from TypeScript, no additional loaders needed

================
File: jest.config.ts
================
/**
 * For a detailed explanation regarding each configuration property, visit:
 * https://jestjs.io/docs/configuration
 */
⋮----
import type { Config } from 'jest';
⋮----
// All imported modules in your tests should be mocked automatically
// automock: false,
⋮----
// Stop running tests after `n` failures
// bail: 0,
bail: false, // enable to stop test when an error occur,
⋮----
// The directory where Jest should store its cached dependency information
// cacheDirectory: "/private/var/folders/kf/2k3sz4px6c9cbyzj1h_b192h0000gn/T/jest_dx",
⋮----
// Automatically clear mock calls, instances, contexts and results before every test
⋮----
// Indicates whether the coverage information should be collected while executing the test
⋮----
// An array of glob patterns indicating a set of files for which coverage information should be collected
⋮----
// The directory where Jest should output its coverage files
⋮----
// An array of regexp pattern strings used to skip coverage collection
// coveragePathIgnorePatterns: [
//   "/node_modules/"
// ],
⋮----
// Indicates which provider should be used to instrument code for coverage
⋮----
// A list of reporter names that Jest uses when writing coverage reports
// coverageReporters: [
//   "json",
//   "text",
//   "lcov",
//   "clover"
// ],
⋮----
// An object that configures minimum threshold enforcement for coverage results
// coverageThreshold: undefined,
⋮----
// A path to a custom dependency extractor
// dependencyExtractor: undefined,
⋮----
// Make calling deprecated APIs throw helpful error messages
// errorOnDeprecated: false,
⋮----
// The default configuration for fake timers
// fakeTimers: {
//   "enableGlobally": false
// },
⋮----
// Force coverage collection from ignored files using an array of glob patterns
// forceCoverageMatch: [],
⋮----
// A path to a module which exports an async function that is triggered once before all test suites
// globalSetup: undefined,
⋮----
// A path to a module which exports an async function that is triggered once after all test suites
// globalTeardown: undefined,
⋮----
// A set of global variables that need to be available in all test environments
// globals: {},
⋮----
// The maximum amount of workers used to run your tests. Can be specified as % or a number. E.g. maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker number. maxWorkers: 2 will use a maximum of 2 workers.
maxWorkers: '1', // run tests sequentially to avoid nonce issues
⋮----
// An array of directory names to be searched recursively up from the requiring module's location
// moduleDirectories: [
//   "node_modules"
// ],
⋮----
// An array of file extensions your modules use
⋮----
// modulePaths: ['src'],
⋮----
// A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
// moduleNameMapper: {},
⋮----
// An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
// modulePathIgnorePatterns: [],
⋮----
// Activates notifications for test results
// notify: false,
⋮----
// An enum that specifies notification mode. Requires { notify: true }
// notifyMode: "failure-change",
⋮----
// A preset that is used as a base for Jest's configuration
// preset: undefined,
⋮----
// Run tests from one or more projects
// projects: undefined,
⋮----
// Use this configuration option to add custom reporters to Jest
// reporters: undefined,
⋮----
// Automatically reset mock state before every test
// resetMocks: false,
⋮----
// Reset the module registry before running each individual test
// resetModules: false,
⋮----
// A path to a custom resolver
// resolver: undefined,
⋮----
// Automatically restore mock state and implementation before every test
// restoreMocks: false,
⋮----
// The root directory that Jest should scan for tests and modules within
// rootDir: undefined,
⋮----
// A list of paths to directories that Jest should use to search for files in
// roots: [
//   "<rootDir>"
// ],
⋮----
// Allows you to use a custom runner instead of Jest's default test runner
// runner: "jest-runner",
⋮----
// The paths to modules that run some code to configure or set up the testing environment before each test
// setupFiles: [],
⋮----
// A list of paths to modules that run some code to configure or set up the testing framework before each test
// setupFilesAfterEnv: [],
⋮----
// The number of seconds after which a test is considered as slow and reported as such in the results.
// slowTestThreshold: 5,
⋮----
// A list of paths to snapshot serializer modules Jest should use for snapshot testing
// snapshotSerializers: [],
⋮----
// The test environment that will be used for testing
// testEnvironment: "jest-environment-node",
⋮----
// Options that will be passed to the testEnvironment
// testEnvironmentOptions: {},
⋮----
// Adds a location field to test results
// testLocationInResults: false,
⋮----
// The glob patterns Jest uses to detect test files
⋮----
// "**/__tests__/**/*.[jt]s?(x)",
⋮----
// An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
// testPathIgnorePatterns: [
//   "/node_modules/"
// ],
⋮----
// The regexp pattern or array of patterns that Jest uses to detect test files
// testRegex: [],
⋮----
// This option allows the use of a custom results processor
// testResultsProcessor: undefined,
⋮----
// This option allows use of a custom test runner
// testRunner: "jest-circus/runner",
⋮----
// A map from regular expressions to paths to transformers
// transform: undefined,
⋮----
// An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
// transformIgnorePatterns: [
//   "/node_modules/",
//   "\\.pnp\\.[^\\/]+$"
// ],
⋮----
// Prevents import esm module error from v1 axios release, issue #5026
⋮----
// An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
// unmockedModulePathPatterns: undefined,
⋮----
// Indicates whether each individual test should be reported during the run
// verbose: undefined,
verbose: true, // report individual test
⋮----
// An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
// watchPathIgnorePatterns: [],
⋮----
// Whether to use watchman for file crawling
// watchman: true,

================
File: examples/Derivatives/WebSockets/privateWs.ts
================
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import {
  DefaultLogger,
  LogParams,
  WebsocketClient,
  WS_KEY_MAP,
  WSTopicRequest,
} from '../../../src/index.js';
import { WSDerivativesTopic } from '../../../src/types/websockets/ws-subscriptions.js';
// normally you should install this module via npm: `npm install @siebly/kraken-api` and import the module:
// import { LogParams, WebsocketClient, WsTopicRequest } from '@siebly/kraken-api';
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log(new Date(), '--> trace', ...params);
⋮----
async function start()
⋮----
/**
   * 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.
   */
⋮----
// Data received
⋮----
// Something happened, attempting to reconnect
⋮----
// Reconnect successful
⋮----
// Connection closed. If unexpected, expect reconnect -> reconnected.
⋮----
// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
⋮----
/**
   * 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.
   */
⋮----
/**
     * 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
⋮----
// 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
⋮----
// Fills: https://docs.kraken.com/api/docs/futures-api/websocket/fills
⋮----
// Optionally, the product_ids field can be used to subscribe only to specific product.
// payload: {
//   product_ids: ['PF_XBTUSD'],
// },
⋮----
// Balances: https://docs.kraken.com/api/docs/futures-api/websocket/balances
⋮----
// Open Position: https://docs.kraken.com/api/docs/futures-api/websocket/open_position
⋮----
// Account Log: https://docs.kraken.com/api/docs/futures-api/websocket/account_log
⋮----
// Notification: https://docs.kraken.com/api/docs/futures-api/websocket/notifications

================
File: examples/Spot/Private/account.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { SpotClient } from '../../../src/index.js';
⋮----
// 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 ACCOUNT INFORMATION
⋮----
/**
 * import { SpotClient } from '@siebly/kraken-api';
 */
⋮----
// initialise the client
/**
 *
 * Kraken API uses API Key and Private Key (base64 encoded)
 *
 * Example:
 * {
 *   apiKey: 'your-api-key',
 *   apiSecret: 'your-base64-encoded-private-key',
 * }
 *
 * API Key Permissions Required:
 * - Funds permissions - Query
 * - Data - Query ledger entries
 *
 */
⋮----
async function getAccountBalance()
⋮----
// Get all cash balances (net of pending withdrawals)
⋮----
// Note: Staking/Earn assets may have these extensions:
// .B - balances in new yield-bearing products
// .F - balances earning automatically in Kraken Rewards
// .T - tokenized assets
⋮----
async function getExtendedBalance()
⋮----
// Get extended balances including credits and held amounts
// Available balance = balance + credit - credit_used - hold_trade
⋮----
async function getTradeBalance()
⋮----
// Get trade balance summary (margin info)
⋮----
// Response includes:
// - eb: equivalent balance
// - tb: trade balance
// - m: margin amount
// - n: unrealized P&L
// - e: equity
// - mf: free margin
⋮----
async function getLedgers()
⋮----
// Query specific ledger entries by ID
⋮----
// Ledger entry types include:
// - trade, deposit, withdrawal, transfer, margin
// - adjustment, rollover, spend, receive, settled
// - credit, staking, reward, dividend, sale, conversion
⋮----
async function getLedgersInfo()
⋮----
// Get ledger info with filters (returns 50 most recent by default)
⋮----
asset: 'XBT', // Filter by asset
type: 'deposit', // Filter by type
⋮----
async function getTradingVolume()
⋮----
// Get 30-day USD trading volume and fee schedule
⋮----
// Response includes:
// - currency: volume currency
// - volume: current trading volume
// - fees: fee schedule by pair
// - fees_maker: maker fee schedule
⋮----
// Uncomment the function you want to test:
⋮----
// getExtendedBalance();
// getTradeBalance();
// getLedgers();
// getLedgersInfo();
// getTradingVolume();

================
File: examples/Spot/Private/orderManagement.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { SpotClient } from '../../../src/index.js';
⋮----
// 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 { SpotClient } from '@siebly/kraken-api';
 */
⋮----
// initialise the client
/**
 *
 * Kraken API uses API Key and Private Key (base64 encoded)
 *
 * Example:
 * {
 *   apiKey: 'your-api-key',
 *   apiSecret: 'your-base64-encoded-private-key',
 * }
 *
 * API Key Permissions Required:
 * - Funds permissions - Query (for balance)
 * - Orders and trades - Query open orders & trades
 * - Orders and trades - Query closed orders & trades
 *
 */
⋮----
async function getTradeBalance()
⋮----
// Get trade balance summary
⋮----
async function getOpenOrders()
⋮----
// Get all open orders
⋮----
async function getOpenOrdersWithTrades()
⋮----
// Get open orders with related trades
⋮----
trades: true, // Include trades related to orders
⋮----
async function getOpenOrdersByClientId()
⋮----
// Get open orders filtered by client order ID
⋮----
async function getClosedOrders()
⋮----
// Get closed orders (last 50)
⋮----
async function getClosedOrdersWithFilters()
⋮----
// Get closed orders with filters
⋮----
trades: true, // Include related trades
start: Math.floor(Date.now() / 1000) - 86400 * 7, // Last 7 days
closetime: 'close', // Filter by close time
⋮----
async function getClosedOrdersByClientId()
⋮----
// Get closed orders by client order ID
⋮----
async function getOrdersByTxId()
⋮----
// Query specific orders by transaction ID
⋮----
// Uncomment the function you want to test:
⋮----
// getTradeBalance();
// getOpenOrders();
// getOpenOrdersWithTrades();
// getOpenOrdersByClientId();
// getClosedOrders();
// getClosedOrdersWithFilters();
// getClosedOrdersByClientId();
// getOrdersByTxId();

================
File: examples/Spot/Private/submitOrder.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { SpotClient } from '../../../src/index.js';
⋮----
// 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 SUBMITTING ORDERS
⋮----
/**
 * import { SpotClient } from '@siebly/kraken-api';
 */
⋮----
// initialise the client
/**
 *
 * Kraken API uses API Key and Private Key (base64 encoded)
 *
 * Example:
 * {
 *   apiKey: 'your-api-key',
 *   apiSecret: 'your-base64-encoded-private-key',
 * }
 *
 * API Key Permissions Required: Orders and trades - Create & modify orders
 *
 */
⋮----
async function submitMarketOrder()
⋮----
// submit market spot order
⋮----
async function submitLimitOrder()
⋮----
// Submit limit spot order
⋮----
async function submitLimitOrderWithFlags()
⋮----
// Submit post-only limit order (maker-only)
⋮----
oflags: 'post', // post-only flag
timeinforce: 'GTC', // Good-til-cancelled
⋮----
async function submitBatchOrders()
⋮----
// Submit batch of orders (minimum 2, maximum 15)
// All orders must be for the same pair
⋮----
async function submitBatchOrdersValidateOnly()
⋮----
// Validate batch orders without submitting them
⋮----
validate: true, // Only validate, don't submit
⋮----
// Uncomment the function you want to test:
⋮----
// submitLimitOrder();
// submitLimitOrderWithFlags();
// submitBatchOrders();
// submitBatchOrdersValidateOnly();

================
File: examples/Spot/WebSockets/wsAPI.RAW.ts
================
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import {
  DefaultLogger,
  LogParams,
  WebsocketClient,
  WS_KEY_MAP,
} from '../../../src/index.js';
// normally you should install this module via npm: `npm install @siebly/kraken-api` and import the module:
// import { DefaultLogger, LogParams, WebsocketClient, WS_KEY_MAP } from '@siebly/kraken-api';
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log('trace', ...params);
⋮----
async function start()
⋮----
/**
   * 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.
   */
⋮----
// Data received
⋮----
// Something happened, attempting to reconnect
⋮----
// Reconnect successful
⋮----
// Connection closed. If unexpected, expect reconnect -> reconnected.
⋮----
// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
⋮----
/**
   * 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.
   */

================
File: examples/Spot/WebSockets/wsAPI.ts
================
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import {
  DefaultLogger,
  LogParams,
  WebsocketAPIClient,
} from '../../../src/index.js';
// normally you should install this module via npm: `npm install @siebly/kraken-api` and import the module:
// import { DefaultLogger, LogParams, WebsocketAPIClient, WS_KEY_MAP } from '@siebly/kraken-api';
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log('trace', ...params);
⋮----
async function start()
⋮----
/**
   * 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.
   */
⋮----
/**
   * 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.
   */

================
File: src/lib/websocket/WsStore.ts
================
import WebSocket from 'isomorphic-ws';
⋮----
import { DefaultLogger } from './logger.js';
import {
  DeferredPromise,
  WSConnectedResult,
  WsConnectionStateEnum,
  WsStoredState,
} from './WsStore.types.js';
⋮----
/**
 * Simple comparison of two objects, recursive for nested objects. Adoped from OKX SDK.
 */
export function isDeepObjectMatch(object1: any, object2: any): boolean
⋮----
// console.log('not same key count', { keys1, keys2 });
// not the same amount of keys or keys don't match
⋮----
// console.log('not same key names: ', { keys1, keys2 });
⋮----
type DeferredPromiseRef =
  (typeof DEFERRED_PROMISE_REF)[keyof typeof DEFERRED_PROMISE_REF];
⋮----
export class WsStore<
WsKey extends string,
⋮----
constructor(logger: DefaultLogger)
⋮----
/** Get WS stored state for key, optionally create if missing */
get(
    key: WsKey,
    createIfMissing?: true,
  ): WsStoredState<TWSTopicSubscribeEventArgs>;
⋮----
get(
    key: WsKey,
    createIfMissing?: false,
  ): WsStoredState<TWSTopicSubscribeEventArgs> | undefined;
⋮----
get(
    key: WsKey,
    createIfMissing?: boolean,
): WsStoredState<TWSTopicSubscribeEventArgs> | undefined
⋮----
getKeys(): WsKey[]
⋮----
create(key: WsKey): WsStoredState<TWSTopicSubscribeEventArgs> | undefined
⋮----
delete(key: WsKey): void
⋮----
// TODO: should we allow this at all? Perhaps block this from happening...
⋮----
/* connection websocket */
⋮----
hasExistingActiveConnection(key: WsKey): boolean
⋮----
getWs(key: WsKey): WebSocket | undefined
⋮----
setWs(key: WsKey, wsConnection: WebSocket): WebSocket
⋮----
/**
   * deferred promises
   */
⋮----
getDeferredPromise<TSuccessResult = any>(
    wsKey: WsKey,
    promiseRef: string | DeferredPromiseRef,
): DeferredPromise<TSuccessResult> | undefined
⋮----
createDeferredPromise<TSuccessResult = any>(
    wsKey: WsKey,
    promiseRef: string | DeferredPromiseRef,
    throwIfExists: boolean,
): DeferredPromise<TSuccessResult>
⋮----
// console.log('existing promise');
⋮----
// console.log('create promise');
⋮----
// TODO: Once stable, use Promise.withResolvers in future
⋮----
resolveDeferredPromise(
    wsKey: WsKey,
    promiseRef: string | DeferredPromiseRef,
    value: unknown,
    removeAfter: boolean,
): void
⋮----
rejectDeferredPromise(
    wsKey: WsKey,
    promiseRef: string | DeferredPromiseRef,
    value: unknown,
    removeAfter: boolean,
): void
⋮----
removeDeferredPromise(
    wsKey: WsKey,
    promiseRef: string | DeferredPromiseRef,
): void
⋮----
// Just in case it's pending
⋮----
rejectAllDeferredPromises(wsKey: WsKey, reason: string): void
⋮----
// Skip reserved keys, such as the connection promise
⋮----
/** Get promise designed to track a connection attempt in progress. Resolves once connected. */
getConnectionInProgressPromise(
    wsKey: WsKey,
): DeferredPromise<WSConnectedResult> | undefined
⋮----
getAuthenticationInProgressPromise(
    wsKey: WsKey,
): DeferredPromise<WSConnectedResult &
⋮----
/**
   * Create a deferred promise designed to track a connection attempt in progress.
   *
   * Will throw if existing promise is found.
   */
createConnectionInProgressPromise(
    wsKey: WsKey,
    throwIfExists: boolean,
): DeferredPromise<WSConnectedResult>
⋮----
createAuthenticationInProgressPromise(
    wsKey: WsKey,
    throwIfExists: boolean,
): DeferredPromise<WSConnectedResult &
⋮----
/** Remove promise designed to track a connection attempt in progress */
removeConnectingInProgressPromise(wsKey: WsKey): void
⋮----
removeAuthenticationInProgressPromise(wsKey: WsKey): void
⋮----
/* connection state */
⋮----
isWsOpen(key: WsKey): boolean
⋮----
getConnectionState(key: WsKey): WsConnectionStateEnum
⋮----
setConnectionState(key: WsKey, state: WsConnectionStateEnum)
⋮----
isConnectionState(key: WsKey, state: WsConnectionStateEnum): boolean
⋮----
/**
   * Check if we're currently in the process of opening a connection for any reason. Safer than only checking "CONNECTING" as the state
   * @param key
   * @returns
   */
isConnectionAttemptInProgress(key: WsKey): boolean
⋮----
const stateChangeTimeout = 15000; // allow a max 15 second timeout since the last state change before assuming stuck;
⋮----
/* subscribed topics */
⋮----
getTopics(key: WsKey): Set<TWSTopicSubscribeEventArgs>
⋮----
getTopicsAsArray(key: WsKey): TWSTopicSubscribeEventArgs[]
⋮----
getTopicsByKey(): Record<string, Set<TWSTopicSubscribeEventArgs>>
⋮----
/**
   * Find matching "topic" request from the store
   * @param key
   * @param topic
   * @returns
   */
getMatchingTopic(key: WsKey, topic: TWSTopicSubscribeEventArgs)
⋮----
addTopic(key: WsKey, topic: TWSTopicSubscribeEventArgs)
⋮----
// Check for duplicate topic. If already tracked, don't store this one
⋮----
deleteTopic(key: WsKey, topic: TWSTopicSubscribeEventArgs)
⋮----
// Check if we're subscribed to a topic like this

================
File: src/types/request/derivatives.types.ts
================
/**
 * Order Management
 */
⋮----
export interface FuturesBatchOrderSend {
  order: 'send';
  order_tag: string;
  orderType:
    | 'lmt'
    | 'post'
    | 'ioc'
    | 'mkt'
    | 'stp'
    | 'take_profit'
    | 'trailing_stop'
    | 'fok';
  symbol: string;
  side: 'buy' | 'sell';
  size: number;
  limitPrice?: number;
  stopPrice?: number;
  cliOrdId?: string;
  triggerSignal?: 'mark' | 'index' | 'last';
  reduceOnly?: boolean;
  trailingStopMaxDeviation?: number;
  trailingStopDeviationUnit?: 'PERCENT' | 'QUOTE_CURRENCY' | 'unknown';
}
⋮----
export interface FuturesBatchOrderEdit {
  order: 'edit';
  order_id: string;
  cliOrdId?: string | null;
  size?: number;
  limitPrice?: number;
  stopPrice?: number;
  trailingStopMaxDeviation?: number;
  trailingStopDeviationUnit?: 'PERCENT' | 'QUOTE_CURRENCY' | 'unknown';
  qtyMode?: 'ABSOLUTE' | 'RELATIVE';
}
⋮----
export interface FuturesBatchOrderCancel {
  order: 'cancel';
  order_id?: string;
  cliOrdId?: string;
}
⋮----
export interface FuturesBatchOrderParams {
  ProcessBefore?: string;
  json: {
    batchOrder: (
      | FuturesBatchOrderSend
      | FuturesBatchOrderEdit
      | FuturesBatchOrderCancel
    )[];
  };
}
⋮----
export interface FuturesCancelOrderParams {
  processBefore?: string;
  order_id?: string;
  cliOrdId?: string;
}
⋮----
export interface FuturesEditOrderParams {
  processBefore?: string;
  orderId?: string;
  cliOrdId?: string;
  size?: number;
  limitPrice?: number;
  stopPrice?: number;
  trailingStopMaxDeviation?: number;
  trailingStopDeviationUnit?: 'PERCENT' | 'QUOTE_CURRENCY' | 'unknown';
  qtyMode?: 'ABSOLUTE' | 'RELATIVE';
}
⋮----
export interface FuturesSendOrderParams {
  processBefore?: string;
  orderType:
    | 'lmt'
    | 'post'
    | 'ioc'
    | 'mkt'
    | 'stp'
    | 'take_profit'
    | 'trailing_stop'
    | 'fok';
  symbol: string;
  side: 'buy' | 'sell';
  size: number;
  limitPrice?: number;
  stopPrice?: number;
  cliOrdId?: string;
  triggerSignal?: 'mark' | 'index' | 'last';
  reduceOnly?: boolean;
  trailingStopMaxDeviation?: number;
  trailingStopDeviationUnit?: 'PERCENT' | 'QUOTE_CURRENCY' | 'unknown';
  limitPriceOffsetValue?: number;
  limitPriceOffsetUnit?: 'QUOTE_CURRENCY' | 'PERCENT';
  broker?: string;
}
⋮----
/**
 * Assignment Program
 */
⋮----
export interface FuturesAddAssignmentPreferenceParams {
  contractType: string;
  contract?: string;
  maxSize?: number;
  maxPosition?: number;
  acceptLong: boolean;
  acceptShort: boolean;
  timeFrame: 'all' | 'weekdays' | 'weekends';
  enabled: boolean;
}
⋮----
/**
 * Trading Settings
 */
⋮----
export interface FuturesUpdateSelfTradeStrategyParams {
  strategy:
    | 'REJECT_TAKER'
    | 'CANCEL_MAKER_SELF'
    | 'CANCEL_MAKER_CHILD'
    | 'CANCEL_MAKER_ANY';
}
⋮----
/**
 * Transfers
 */
⋮----
export interface FuturesInitiateWalletTransferParams {
  fromAccount: string;
  toAccount: string;
  unit: string;
  amount: number;
}
⋮----
export interface FuturesInitiateSubaccountTransferParams {
  fromUser: string;
  toUser: string;
  fromAccount: string;
  toAccount: string;
  unit: string;
  amount: string;
}
⋮----
export interface FuturesSubmitToSpotParams {
  currency: string;
  amount: string;
  sourceWallet?: string;
}
⋮----
/**
 * Account History
 */
⋮----
export interface FuturesHistoryBaseParams {
  since?: number; // Timestamp in milliseconds
  before?: number; // Timestamp in milliseconds
  sort?: 'asc' | 'desc';
  continuation_token?: string; // base64
  count?: number;
  tradeable?: string;
}
⋮----
since?: number; // Timestamp in milliseconds
before?: number; // Timestamp in milliseconds
⋮----
continuation_token?: string; // base64
⋮----
export interface FuturesGetOrderEventsParams extends FuturesHistoryBaseParams {
  opened?: boolean;
  closed?: boolean;
}
⋮----
export interface FuturesGetTriggerEventsParams
  extends FuturesHistoryBaseParams {
  opened?: boolean;
  closed?: boolean;
}
⋮----
export interface FuturesGetPositionEventsParams
  extends FuturesHistoryBaseParams {
  opened?: boolean;
  closed?: boolean;
  increased?: boolean;
  decreased?: boolean;
  reversed?: boolean;
  no_change?: boolean;
  trades?: boolean;
  funding_realization?: boolean;
  settlement?: boolean;
}
⋮----
export interface FuturesGetAccountLogParams {
  since?: number; // Timestamp in milliseconds
  before?: number; // Timestamp in milliseconds
  from?: number; // ID of the first entry (inclusive)
  to?: number; // ID of the last entry (inclusive)
  sort?: 'asc' | 'desc';
  info?: string[]; // Types of entry to filter by
  count?: number;
  conversion_details?: boolean;
}
⋮----
since?: number; // Timestamp in milliseconds
before?: number; // Timestamp in milliseconds
from?: number; // ID of the first entry (inclusive)
to?: number; // ID of the last entry (inclusive)
⋮----
info?: string[]; // Types of entry to filter by
⋮----
/**
 * Market History
 */
⋮----
export interface FuturesMarketHistoryBaseParams {
  tradeable: string; // Symbol of the contract
  since?: number; // Timestamp in milliseconds
  before?: number; // Timestamp in milliseconds
  sort?: 'asc' | 'desc';
  continuation_token?: string; // base64
  count?: number;
}
⋮----
tradeable: string; // Symbol of the contract
since?: number; // Timestamp in milliseconds
before?: number; // Timestamp in milliseconds
⋮----
continuation_token?: string; // base64
⋮----
/**
 * Charts - Candles
 */
⋮----
export interface FuturesGetCandlesParams {
  tickType: 'spot' | 'mark' | 'trade';
  symbol: string;
  resolution: '1m' | '5m' | '15m' | '30m' | '1h' | '4h' | '12h' | '1d' | '1w';
  from?: number; // From date in epoch seconds
  to?: number; // To date in epoch seconds
  count?: number; // Number of candles to return
}
⋮----
from?: number; // From date in epoch seconds
to?: number; // To date in epoch seconds
count?: number; // Number of candles to return
⋮----
/**
 * Charts - Analytics
 */
⋮----
export interface FuturesGetAnalyticsParams {
  symbol: string;
  analyticsType: string;
  since: number; // Epoch time in seconds (required)
  interval: 60 | 300 | 900 | 1800 | 3600 | 14400 | 43200 | 86400 | 604800; // Resolution in seconds (required)
  to?: number; // Epoch time in seconds, default now
}
⋮----
since: number; // Epoch time in seconds (required)
interval: 60 | 300 | 900 | 1800 | 3600 | 14400 | 43200 | 86400 | 604800; // Resolution in seconds (required)
to?: number; // Epoch time in seconds, default now

================
File: src/types/websockets/ws-api.ts
================
import { WS_KEY_MAP, WSOperation } from '../../lib/websocket/websocket-util.js';
import {
  WSAPIAddSpotOrderParams,
  WSAPIAmendSpotOrderParams,
  WSAPIBatchAddSpotOrdersParams,
  WSAPIBatchCancelSpotOrdersParams,
  WSAPICancelAllSpotOrdersAfterParams,
  WSAPICancelSpotOrderParams,
  WSAPIEditSpotOrderParams,
} from '../request/wsapi.types.js';
import {
  WSAPIAddSpotOrderResult,
  WSAPIAmendSpotOrderResult,
  WSAPIBatchAddSpotOrdersResult,
  WSAPIBatchCancelSpotOrdersResult,
  WSAPICancelAllSpotOrdersAfterResult,
  WSAPICancelAllSpotOrdersResult,
  WSAPICancelSpotOrderResult,
  WSAPIEditSpotOrderResult,
} from '../response/wsapi.types.js';
⋮----
export type Exact<T> = {
  // This part says: if there's any key that's not in T, it's an error
  // This conflicts sometimes for some reason...
  // [K: string]: never;
} & {
  [K in keyof T]: T[K];
};
⋮----
// This part says: if there's any key that's not in T, it's an error
// This conflicts sometimes for some reason...
// [K: string]: never;
⋮----
export interface WsRequestOperation<TWSTopic extends string> {
  id: number;
  type: WSOperation;
  topic: TWSTopic;
  privateChannel: boolean;
  response: boolean;
}
⋮----
export interface WSAPIAuthenticationRequestFromServer {
  timestamp: number;
  sessionId: string;
}
⋮----
export interface WSAPIAuthenticationConfirmedFromServer {
  pingInterval: number;
  sessionId: string;
  pingTimeout: number;
  data: 'welcome';
}
⋮----
/**
 * WS API commands (for sending requests via WS)
 */
⋮----
export type WSAPIOperation = (typeof WS_API_Operations)[number];
⋮----
export interface WSAPIRequestOperationKrakenSpot<
  TWSOperation extends WSAPIOperation = WSAPIOperation,
  TWSParams extends object = any,
> {
  method: TWSOperation;
  params?: TWSParams;
  req_id: number;
}
⋮----
export interface WSAPIWsKeyTopicMap {
  [WS_KEY_MAP.spotPrivateV2]: WSAPIOperation;
  [WS_KEY_MAP.spotBetaPrivateV2]: WSAPIOperation;
}
⋮----
export type WSAPIWsKey = keyof WSAPIWsKeyTopicMap;
⋮----
export interface WSAPISpotResponse<
  TResponseData extends object = object,
  TWSAPIOperation = WSAPIOperation,
> {
  wsKey: WSAPIWsKey;
  error?: string;
  method: TWSAPIOperation;
  req_id: number;
  success: boolean;
  time_in: string;
  time_out: string;
  result: TResponseData;
  request: any;
}
⋮----
export interface WSAPITopicRequestParamMap {
  [key: string]: unknown;

  add_order: WSAPIAddSpotOrderParams;
  amend_order: WSAPIAmendSpotOrderParams;
  cancel_order: WSAPICancelSpotOrderParams;
  cancel_all: never;
  cancel_all_orders_after: WSAPICancelAllSpotOrdersAfterParams;
  batch_add: WSAPIBatchAddSpotOrdersParams;
  batch_cancel: WSAPIBatchCancelSpotOrdersParams;
  edit_order: WSAPIEditSpotOrderParams;
}
⋮----
export interface WSAPITopicResponseMap {
  [k: string]: unknown;

  add_order: WSAPISpotResponse<WSAPIAddSpotOrderResult, 'add_order'>;
  amend_order: WSAPISpotResponse<WSAPIAmendSpotOrderResult, 'amend_order'>;
  cancel_order: WSAPISpotResponse<WSAPICancelSpotOrderResult, 'cancel_order'>;
  cancel_all: WSAPISpotResponse<WSAPICancelAllSpotOrdersResult, 'cancel_all'>;
  cancel_all_orders_after: WSAPISpotResponse<
    WSAPICancelAllSpotOrdersAfterResult,
    'cancel_all_orders_after'
  >;
  batch_add: WSAPISpotResponse<WSAPIBatchAddSpotOrdersResult[], 'batch_add'>;
  batch_cancel: WSAPISpotResponse<
    WSAPIBatchCancelSpotOrdersResult,
    'batch_cancel'
  >;
  edit_order: WSAPISpotResponse<WSAPIEditSpotOrderResult, 'edit_order'>;
}

================
File: src/WebsocketAPIClient.ts
================
import { DefaultLogger } from './lib/websocket/logger.js';
import { WS_KEY_MAP } from './lib/websocket/websocket-util.js';
import {
  WSAPIAddSpotOrderParams,
  WSAPIAmendSpotOrderParams,
  WSAPIBatchAddSpotOrdersParams,
  WSAPIBatchCancelSpotOrdersParams,
  WSAPICancelAllSpotOrdersAfterParams,
  WSAPICancelSpotOrderParams,
  WSAPIEditSpotOrderParams,
} from './types/request/wsapi.types.js';
import {
  WSAPIAddSpotOrderResult,
  WSAPIAmendSpotOrderResult,
  WSAPIBatchAddSpotOrdersResult,
  WSAPIBatchCancelSpotOrdersResult,
  WSAPICancelAllSpotOrdersAfterResult,
  WSAPICancelAllSpotOrdersResult,
  WSAPICancelSpotOrderResult,
  WSAPIEditSpotOrderResult,
} from './types/response/wsapi.types.js';
import { WSAPISpotResponse, WSAPIWsKey } from './types/websockets/ws-api.js';
import { WSClientConfigurableOptions } from './types/websockets/ws-general.js';
import { WebsocketClient } from './WebsocketClient.js';
⋮----
/**
 * Configurable options specific to only the REST-like WebsocketAPIClient
 */
export interface WSAPIClientConfigurableOptions {
  /**
   * Default: true
   *
   * Attach default event listeners, which will console log any high level
   * events (opened/reconnecting/reconnected/etc).
   *
   * If you disable this, you should set your own event listeners
   * on the embedded WS Client `wsApiClient.getWSClient().on(....)`.
   */
  attachEventListeners: boolean;
}
⋮----
/**
   * Default: true
   *
   * Attach default event listeners, which will console log any high level
   * events (opened/reconnecting/reconnected/etc).
   *
   * If you disable this, you should set your own event listeners
   * on the embedded WS Client `wsApiClient.getWSClient().on(....)`.
   */
⋮----
/**
 * This is a minimal Websocket API wrapper around the WebsocketClient.
 *
 * Some methods support passing in a custom "wsKey". This is a reference to which WS connection should
 * be used to transmit that message. This is only useful if you wish to use an alternative wss
 * domain that is supported by the SDK. E.g. WS_API_KEY_MAP.spotBetaPrivateV2.
 *
 * Note: You can also directly use the sendWSAPIRequest() method to make WS API calls, but some
 * may find the below methods slightly more intuitive.
 *
 * Refer to the WS API promises example for a more detailed example on using sendWSAPIRequest() directly:
 * https://github.com/sieblyio/kraken-api/blob/main/examples/WebSockets/Spot/wsAPI.RAW.ts#L105
 *
 * Docs:
 * - Spot WS API: https://docs.kraken.com/api/docs/websocket-v2/add_order/
 */
export class WebsocketAPIClient
⋮----
constructor(
    options?: WSClientConfigurableOptions &
      Partial<WSAPIClientConfigurableOptions>,
    logger?: DefaultLogger,
)
⋮----
public getWSClient(): WebsocketClient
⋮----
/**
   * Add a spot order
   */
submitSpotOrder(
    params: Omit<WSAPIAddSpotOrderParams, 'token' | 'req_id'>,
    wsKey?: WSAPIWsKey,
): Promise<WSAPISpotResponse<WSAPIAddSpotOrderResult, 'add_order'>>
⋮----
/**
   * Amend an existing order
   */
amendSpotOrder(
    params: WSAPIAmendSpotOrderParams,
    wsKey?: WSAPIWsKey,
): Promise<WSAPISpotResponse<WSAPIAmendSpotOrderResult, 'amend_order'>>
⋮----
/**
   * Cancel one or more orders
   */
cancelSpotOrder(
    params: WSAPICancelSpotOrderParams,
    wsKey?: WSAPIWsKey,
): Promise<WSAPISpotResponse<WSAPICancelSpotOrderResult, 'cancel_order'>>
⋮----
/**
   * Cancel all open orders
   */
cancelAllSpotOrders(
    wsKey?: WSAPIWsKey,
): Promise<WSAPISpotResponse<WSAPICancelAllSpotOrdersResult, 'cancel_all'>>
⋮----
/**
   * Cancel all orders after a timeout (Dead Man's Switch)
   */
cancelAllSpotOrdersAfter(
    params: WSAPICancelAllSpotOrdersAfterParams,
    wsKey?: WSAPIWsKey,
  ): Promise<
    WSAPISpotResponse<
      WSAPICancelAllSpotOrdersAfterResult,
      'cancel_all_orders_after'
    >
  > {
    return this.wsClient.sendWSAPIRequest(
      wsKey || WS_KEY_MAP.spotPrivateV2,
      'cancel_all_orders_after',
      params,
    );
⋮----
/**
   * Add multiple orders in a single batch (2-15 orders)
   */
batchSubmitSpotOrders(
    params: WSAPIBatchAddSpotOrdersParams,
    wsKey?: WSAPIWsKey,
): Promise<WSAPISpotResponse<WSAPIBatchAddSpotOrdersResult[], 'batch_add'>>
⋮----
/**
   * Cancel multiple orders in a single batch (2-50 orders)
   */
batchCancelSpotOrders(
    params: WSAPIBatchCancelSpotOrdersParams,
    wsKey?: WSAPIWsKey,
  ): Promise<
    WSAPISpotResponse<WSAPIBatchCancelSpotOrdersResult, 'batch_cancel'>
  > {
    return this.wsClient.sendWSAPIRequest(
      wsKey || WS_KEY_MAP.spotPrivateV2,
      'batch_cancel',
      params,
    );
⋮----
/**
   * Edit an existing order (legacy method, use amendSpotOrder instead)
   * @deprecated Use amendSpotOrder for better performance and features
   */
editSpotOrder(
    params: WSAPIEditSpotOrderParams,
    wsKey?: WSAPIWsKey,
): Promise<WSAPISpotResponse<WSAPIEditSpotOrderResult, 'edit_order'>>
/**
   *
   *
   *
   *
   *
   *
   *
   * Private methods for handling some of the convenience/automation provided by the WS API Client
   *
   *
   *
   *
   *
   *
   *
   */
⋮----
public connectWSAPI(wsKey: WSAPIWsKey)
⋮----
private setupDefaultEventListeners()
⋮----
/**
       * General event handlers for monitoring the WebsocketClient
       */
⋮----
// Blind JSON.stringify can fail on circular references
⋮----
// JSON.stringify({ ...data, target: 'WebSocket' }),

================
File: docs/KRAKEN_SDK_QUICKSTART_GUIDE.md
================
# Kraken API JavaScript Tutorial for Node.js and TypeScript

Build Kraken integrations in JavaScript or TypeScript without hand-rolling raw HTTP requests, Kraken JWTs/request signing for authenticated APIs, WebSocket authentication, heartbeats, reconnects, or exchange-specific payload handling.

This Kraken JavaScript tutorial uses [`@siebly/kraken-api`](https://www.npmjs.com/package/@siebly/kraken-api), the [Kraken JavaScript SDK by Siebly.io](https://siebly.io/sdk/kraken/javascript), to walk through the API surfaces most developers need:

- Kraken Spot REST API
- Kraken Futures REST API
- Public and private Kraken WebSockets
- Spot trading over Kraken's event-driven WebSocket API
- Automatic handling for Kraken JWTs, request signing, and private-channel authentication

Key Links

- Kraken JavaScript & Node.js SDK by Siebly: [`@siebly/kraken-api`](https://www.npmjs.com/package/@siebly/kraken-api)
- GitHub Repository: [`sieblyio/kraken-api`](https://github.com/sieblyio/kraken-api)
- SDK function-endpoint map: [Kraken JavaScript Endpoint Reference](https://siebly.io/sdk/kraken/javascript#endpoint-reference)
- More SDKs: [Siebly.io](https://siebly.io)

Topics covered in this guide

- Why use a Kraken SDK
- Install and API keys
- Start building quickstart
- Spot REST APIs
- Spot WebSockets
- Spot trading over WebSocket API
- Futures REST APIs
- Futures WebSockets
- Production notes
- FAQ and next steps

---

## Why use a Kraken SDK

A stable Kraken API integration is not just "make a few HTTP requests". There's more to it than that.

- Spot REST and Futures REST APIs use different authentication models and request shapes.
- Public & private WebSockets require connection lifecycle handling, authentication, and reconnection handling.
- Spot trading over Kraken's asynchronous WebSocket API can be complicated without JavaScript Promises to glue WebSocket API responses to the requests that triggered them.
- Production bots and trading tools need typed request schemas, consistent async behavior, resilient WebSockets, and a connectivity architecture that works.

The `@siebly/kraken-api` gives you one JavaScript and TypeScript SDK for Kraken API integration in any Node.js or JavaScript-capable environment:

- Complete API coverage with dedicated REST API clients for each product group, including Spot and Derivatives.
- One `WebsocketClient` for public and private streaming across all Kraken products.
- A `WebsocketAPIClient` for Spot trading over a persistent WebSocket connection, with the convenience of awaitable promise-wrapped WebSocket API requests. Each WebSocket API command can be awaited like a REST API request.
- Automatic heartbeats, reconnect and resubscribe handling for WebSockets. Stay connected, stay in sync.
- TypeScript-first request and response definitions for most SDK methods.
- ESM and CJS support.
- Browser-friendly HMAC signing and proxy support.

The package also includes `InstitutionalClient` and `PartnerClient`, but this guide focuses on the flows most developers look for first: Spot, Futures, market data, account data, and order management.

---

## What you can build with the [Kraken JavaScript SDK](https://siebly.io/sdk/kraken/javascript)

This Kraken JavaScript SDK is relevant for any integration with Kraken's APIs and WebSockets, especially if you are building:

- Trading bots and execution services
- Real-time market data dashboards
- Internal trader tooling
- Portfolio and balance monitors
- Alerting and signal pipelines
- Reconciliation or account state services
- AI-assisted engineering workflows that need a reliable & typed Kraken integration layer

---

## Who this guide is for

This guide is written for JavaScript developers (& LLMs) who:

- Want to build with the Kraken API offering
- Want a quick, easy, predictable, up-to-date and heavily used (reliable) way to integrate with Kraken's APIs & WebSockets
- Care about typed requests and responses
- Are working with exchange REST APIs & WebSockets for the first time
- Are already using exchange APIs elsewhere and are looking to integrate Kraken
- Need dependable connectivity for systematic trading
- Are comparing raw Kraken integration against a maintained SDK

---

## What this one-page course covers

- Installing the Kraken JavaScript SDK by Siebly
- Creating Spot and Futures REST API clients
- Making your first public Spot REST API request
- Streaming public Spot market data over WebSockets
- Subscribing to private Spot account streams
- Placing Spot orders over Kraken's REST API
- Managing Spot orders in batches
- Trading Spot over Kraken's WebSocket API
- Pulling Kraken Futures market data
- Submitting Kraken Futures orders via REST API
- Using Kraken Futures WebSockets
- Production patterns for reconnects, idempotency, logging, and safer rollout

---

## How to get started with the Kraken API in JavaScript?

If you don't have Node.js installed yet, refer to the Node.js documentation on getting started with Node.js. The Kraken JavaScript SDK is published to both [GitHub](https://github.com/sieblyio/kraken-api) and [npm](https://www.npmjs.com/package/@siebly/kraken-api).

Install the SDK with npm:

```bash
npm install @siebly/kraken-api
```

Or, if preferred, use your favourite npm-compatible package manager:

```bash
# or pnpm:
pnpm install @siebly/kraken-api
# or yarn:
yarn add @siebly/kraken-api
```

Create API keys where Kraken documents them:

- Spot: [Kraken Spot API key instructions](https://support.kraken.com/articles/360000919966-how-to-create-an-api-key)
- Futures: [Kraken Futures API key instructions](https://pro.kraken.com/app/settings/api)

> Use the minimum permissions needed for your scenario. Trading does not require withdrawal permissions. Analytics does not require trading permissions.

Important auth difference:

- Spot & futures have different API keys.
- Make sure the API keys you have created are for the correct product group.
- API keys for Spot will only work for Spot APIs.
- API keys for Futures will only work for Futures APIs.
- Most market data does not require API keys.

Typical environment variables:

```bash
export API_SPOT_KEY='your-spot-api-key'
export API_SPOT_SECRET='your-spot-api-secret'

export API_FUTURES_KEY='your-futures-api-key'
export API_FUTURES_SECRET='your-futures-api-secret'
```

For local Node.js examples that use a `.env` file, make `.env` loading automatic before reading `process.env`. Prefer Node.js built-in `--env-file` or `--env-file-if-exists` in package scripts when supported; otherwise use `process.loadEnvFile`, `dotenv/config`, or the repo's existing loader. Real process environment variables should override `.env`.

If you are only testing public endpoints, you do not need any keys at all.

---

## Start building: first Kraken API calls in JavaScript

If you only want the fastest path to a working integration, this is the section to start from.

### 1. First Spot REST API request

```typescript
import { SpotClient } from '@siebly/kraken-api';

const client = new SpotClient();

async function main() {
  const serverTime = await client.getServerTime();
  const systemStatus = await client.getSystemStatus();
  const ticker = await client.getTicker({ pair: 'XBTUSD' });
  const orderBook = await client.getOrderBook({ pair: 'XBTUSD', count: 10 });

  console.log({
    serverTime,
    systemStatus,
    ticker,
    orderBook,
  });
}

// Since each of the above API calls is wrapped in an awaited promise, a high level catch will detect any exceptions:
main().catch(console.error);
```

This is the quickest way to verify that your Kraken API JavaScript integration is wired correctly for public REST API calls.

See also: [Kraken JavaScript Example - How to query spot market data](https://siebly.io/examples/Kraken/Spot/Public/marketData)

### 2. First public Spot WebSocket stream

```typescript
import { WebsocketClient, WS_KEY_MAP } from '@siebly/kraken-api';

const ws = new WebsocketClient();

ws.on('open', (data) => console.log('connected', data?.wsKey));
ws.on('response', (data) => console.log('response', JSON.stringify(data)));
ws.on('message', (data) => console.log('message', JSON.stringify(data)));
ws.on('reconnected', (data) => console.log('reconnected', data?.wsKey));
ws.on('exception', console.error);

ws.subscribe(
  {
    topic: 'ticker',
    payload: {
      symbol: ['BTC/USD', 'ETH/USD'],
    },
  },
  WS_KEY_MAP.spotPublicV2,
);
```

This gets a public Kraken Spot WebSocket stream running in JavaScript.

See also: [Kraken JavaScript Example - How to subscribe to spot market data WebSocket stream](https://siebly.io/examples/Kraken/Spot/WebSockets/publicWs)

### 3. First private Spot WebSocket stream

```typescript
import { WebsocketClient, WS_KEY_MAP } from '@siebly/kraken-api';

const ws = new WebsocketClient({
  apiKey: process.env.API_SPOT_KEY!,
  apiSecret: process.env.API_SPOT_SECRET!,
});

ws.on('authenticated', (data) => console.log('authenticated', data?.wsKey));
ws.on('response', (data) => console.log('response', JSON.stringify(data)));
ws.on('message', (data) => console.log('message', JSON.stringify(data)));
ws.on('reconnected', (data) => console.log('reconnected', data?.wsKey));
ws.on('exception', console.error);

ws.subscribe(
  {
    topic: 'executions',
    payload: {
      snap_trades: true,
      snap_orders: true,
      order_status: true,
    },
  },
  WS_KEY_MAP.spotPrivateV2,
);

ws.subscribe(
  {
    topic: 'balances',
    payload: {},
  },
  WS_KEY_MAP.spotPrivateV2,
);
```

For private Spot v2 topics, the SDK can fetch and refresh the token for you. You do not need to manually fetch a token and inject it into every subscribe payload.

See also: [Kraken JavaScript Example - How to subscribe to spot account change WebSocket events](https://siebly.io/examples/Kraken/Spot/WebSockets/privateWs)

### 4. First Spot order over REST API

```typescript
import { SpotClient } from '@siebly/kraken-api';

const client = new SpotClient({
  apiKey: process.env.API_SPOT_KEY!,
  apiSecret: process.env.API_SPOT_SECRET!,
});

async function placeOrder() {
  const result = await client.submitOrder({
    ordertype: 'limit',
    type: 'buy',
    pair: 'XBTUSD',
    volume: '0.0001',
    price: '10000',
    validate: true,
    cl_ord_id: client.generateNewOrderID(),
  });

  console.log(result);
}

placeOrder().catch(console.error);
```

Use `validate: true` when you want to validate the request shape without sending the live order. Remove `validate: true` when you are ready to submit.

See also: [Kraken JavaScript Example - How to submit spot orders](https://siebly.io/examples/Kraken/Spot/Private/submitOrder)

### 5. First Futures order

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

const client = new DerivativesClient({
  apiKey: process.env.API_FUTURES_KEY!,
  apiSecret: process.env.API_FUTURES_SECRET!,
  // testnet: true, // optional: route Derivatives REST calls to Kraken's demo environment
});

async function placeFuturesOrder() {
  const result = await client.submitOrder({
    orderType: 'lmt',
    symbol: 'PF_ETHUSD',
    side: 'buy',
    size: 0.01,
    limitPrice: 1000,
    cliOrdId: client.generateNewOrderID(),
  });

  console.log(result);
}

placeFuturesOrder().catch(console.error);
```

See also: [Kraken JavaScript Example - How to submit futures/derivatives orders](https://siebly.io/examples/Kraken/Derivatives/Private/submitOrder)

---

## Kraken Spot REST API in JavaScript and TypeScript

Most integrations start with Spot REST APIs because it is one of the simplest ways to test basic connectivity, such as querying account state and submitting orders.

### Create a public Spot client

```typescript
import { SpotClient } from '@siebly/kraken-api';

const client = new SpotClient();
```

Public calls do not require keys.

### Create a private Spot client

If you plan on making private API calls, include API keys when creating an instance of the SpotClient class:

```typescript
import { SpotClient } from '@siebly/kraken-api';

const client = new SpotClient({
  apiKey: process.env.API_SPOT_KEY!,
  apiSecret: process.env.API_SPOT_SECRET!,
});
```

### Common public Spot market data calls

```typescript
const serverTime = await client.getServerTime();
const systemStatus = await client.getSystemStatus();
const assetInfo = await client.getAssetInfo({ asset: 'XBT,ETH' });
const assetPairs = await client.getAssetPairs({ pair: 'XBTUSD,ETHUSD' });
const ticker = await client.getTicker({ pair: 'XBTUSD' });
const orderBook = await client.getOrderBook({ pair: 'XBTUSD', count: 10 });
const candles = await client.getCandles({ pair: 'XBTUSD', interval: 60 });
const recentTrades = await client.getRecentTrades({
  pair: 'XBTUSD',
  count: 10,
});
const recentSpreads = await client.getRecentSpreads({ pair: 'XBTUSD' });
```

### Common private Spot account calls

```typescript
const balance = await client.getAccountBalance();
const tradeBalance = await client.getTradeBalance();
const openOrders = await client.getOpenOrders();
const openOrdersWithTrades = await client.getOpenOrders({ trades: true });
const closedOrders = await client.getClosedOrders({
  trades: true,
  start: Math.floor(Date.now() / 1000) - 86400 * 7, // last 7 days
});
```

See also:

- [Kraken JavaScript Example - How to query spot market data](https://siebly.io/examples/Kraken/Spot/Public/marketData)
- [Kraken JavaScript Example - How to query Kraken spot account balances, orders & transactions](https://siebly.io/examples/Kraken/Spot/Private/account)
- [Kraken JavaScript Example - How to query, manage, amend & cancel spot orders](https://siebly.io/examples/Kraken/Spot/Private/orderManagement)

### Spot order examples

Market order:

```typescript
await client.submitOrder({
  ordertype: 'market',
  type: 'buy',
  volume: '0.01',
  pair: 'XBTUSD',
});
```

Limit order:

```typescript
await client.submitOrder({
  ordertype: 'limit',
  type: 'buy',
  volume: '0.0001',
  pair: 'XBTUSD',
  price: '10000',
});
```

Post-only limit order:

```typescript
await client.submitOrder({
  ordertype: 'limit',
  type: 'buy',
  volume: '0.001',
  pair: 'XBTEUR',
  price: '1000.00',
  oflags: 'post',
  timeinforce: 'GTC',
});
```

### Spot batch order management

If you want to stage multiple orders on one pair, batch APIs are a better fit than serially sending single orders.

```typescript
await client.submitBatchOrders({
  pair: 'XBTUSD',
  orders: [
    {
      ordertype: 'limit',
      type: 'buy',
      volume: '0.0001',
      price: '10000.00',
      timeinforce: 'GTC',
      // cl_ord_id: client.generateNewOrderID(), // optional: include a custom order ID before placing your order, for easier tracking
    },
    {
      ordertype: 'limit',
      type: 'sell',
      volume: '0.0001',
      price: '13000.00',
      timeinforce: 'GTC',
      // cl_ord_id: client.generateNewOrderID(), // optional: include a custom order ID before placing your order, for easier tracking
    },
  ],
});
```

Validate the batch without sending:

```typescript
await client.submitBatchOrders({
  pair: 'XBTUSD',
  validate: true,
  orders: [
    {
      ordertype: 'limit',
      type: 'buy',
      volume: '0.0001',
      price: '45000.00',
    },
    {
      ordertype: 'limit',
      type: 'sell',
      volume: '0.0001',
      price: '55000.00',
    },
  ],
});
```

See also: [Kraken JavaScript Example - How to submit spot orders via REST API](https://siebly.io/examples/Kraken/Spot/Private/submitOrder)

---

## Kraken WebSockets in JavaScript: public and private streaming

For long-running processes, WebSockets are key for staying in sync with market data & account state changes. Latency-sensitive systems should subscribe & react to event-driven market & account updates, rather than depending on REST API polling at regular intervals.

> After subscribing to the topics needed by your system, persistent WebSocket connections will provide real-time updates on any changes to your subscribed topics. Stay informed on new market data as it becomes available. Immediately process and react to any account state changes, such as an order state change or fill. Integrating an event-driven design pattern with WebSockets will both reduce your latency and provide much higher capacity for making API calls within the available rate limits.

The Siebly Kraken JavaScript SDK's WebsocketClient handles most of the complexity of working with WebSockets for you. All you need to do is:

- Create an instance of the WebsocketClient.
- Provide read-only API keys, if private topics are required. Market data does not require API keys.
- Ask the WebsocketClient to subscribe to the topics you're interested in.

The SDK handles the connection work for you:

- Open WebSocket connections to the correct domains & endpoints.
- Use your provided proxy, if desired & configured.
- Prepare & dispatch events to authenticate, if needed.
- Prepare & dispatch events to subscribe to the topics you have requested.
- Monitor active WebSocket connections with regular heartbeats. As soon as a potential disconnect is detected (heartbeat timeout), the SDK will automatically:
  - Emit a `reconnecting` event, informing you this process has started.
    - This is a good time to pause any risky commands until the connection is restored (order management).
  - Teardown the stale connection.
  - Open a new WebSocket connection.
    - Re-authenticate if needed.
    - Re-subscribe to the topics you were subscribed to.
  - Emit a `reconnected` event, informing you this process has completed.
    - This is a good time to query the REST API for any changes you might have missed while disconnected.

### `WebsocketClient` events you will actually care about

| Event           | Meaning                                           |
| --------------- | ------------------------------------------------- |
| `open`          | Connection established                            |
| `message`       | Streaming data received                           |
| `response`      | Subscribe, unsubscribe, and auth acknowledgements |
| `reconnecting`  | Connection dropped and retrying                   |
| `reconnected`   | Connection restored and subscriptions resynced    |
| `close`         | Socket closed                                     |
| `authenticated` | Private auth succeeded                            |
| `exception`     | Errors and unexpected conditions                  |

### Understanding `WS_KEY_MAP`

[`WS_KEY_MAP`](/reference/glossary#ws-key) tells the SDK which Kraken WebSocket endpoint family to use:

- `spotPublicV2`
- `spotPrivateV2`
- `spotL3V2`
- `derivativesPublicV1`
- `derivativesPrivateV1`

> This matters because different product groups and topic families do not all live on the same connection endpoint. These keys act as primary keys, similar to a database, to uniquely identify a dedicated connection group.

### Public Spot WebSocket topics

```typescript
ws.subscribe(
  {
    topic: 'ticker',
    payload: { symbol: ['BTC/USD', 'ETH/USD'] },
  },
  WS_KEY_MAP.spotPublicV2,
);

ws.subscribe(
  {
    topic: 'trade',
    payload: { symbol: ['BTC/USD'] },
  },
  WS_KEY_MAP.spotPublicV2,
);

ws.subscribe(
  {
    topic: 'ohlc',
    payload: {
      symbol: ['BTC/USD'],
      interval: 1,
    },
  },
  WS_KEY_MAP.spotPublicV2,
);
```

You can also batch multiple subscriptions that share the same `WsKey`, by sending an array of WebSocket topics:

```typescript
ws.subscribe(
  [
    { topic: 'ticker', payload: { symbol: ['BTC/USD'] } },
    { topic: 'trade', payload: { symbol: ['BTC/USD'] } },
    {
      topic: 'instrument',
      payload: {
        symbol: ['BTC/USD'],
        include_tokenized_assets: true,
      },
    },
  ],
  WS_KEY_MAP.spotPublicV2,
);
```

### Private Spot WebSocket topics

The SDK can authenticate and manage private Spot streams for you:

```typescript
import { WebsocketClient, WS_KEY_MAP } from '@siebly/kraken-api';

const ws = new WebsocketClient({
  apiKey: process.env.API_SPOT_KEY!,
  apiSecret: process.env.API_SPOT_SECRET!,
});

ws.subscribe(
  {
    topic: 'executions',
    payload: {
      snap_trades: true,
      snap_orders: true,
      order_status: true,
      ratecounter: true,
    },
  },
  WS_KEY_MAP.spotPrivateV2,
);

ws.subscribe(
  {
    topic: 'balances',
    payload: {},
  },
  WS_KEY_MAP.spotPrivateV2,
);

ws.subscribe(
  {
    topic: 'level3',
    payload: {
      symbol: ['BTC/USD'],
    },
  },
  WS_KEY_MAP.spotL3V2,
);
```

The Level 3 order book is a special case. It uses the dedicated L3 endpoint, so `spotL3V2` matters.

See also:

- [Kraken JavaScript Example - How to subscribe to & consume spot market data events](https://siebly.io/examples/Kraken/Spot/WebSockets/publicWs)
- [Kraken JavaScript Example - How to subscribe to & consume private spot account events](https://siebly.io/examples/Kraken/Spot/WebSockets/privateWs)

---

## Spot trading over Kraken's WebSocket API with `WebsocketAPIClient`

Kraken supports Spot trading over a persistent WebSocket connection. While each REST API call requires a new connection to be opened & signed per API call, the WebSocket API allows a persistent WebSocket connection to be opened & authenticated once, and then reused for any WS-API commands sent by your system. This can significantly reduce latency for latency-sensitive and higher-frequency trading systems compared with using the REST API alone.

If that model fits your system, `WebsocketAPIClient` gives you REST-like methods over the WebSocket API.

> This utility class is wrapped around the Siebly Kraken JavaScript SDK's WebsocketClient. A persistent WebSocket API connection is automatically opened and managed as needed. Any API calls made via the WebsocketAPIClient are conveniently wrapped in JavaScript promises. This allows for much simpler asynchronous design patterns that feel very much like a REST API, with all the benefits of a persistent WebSocket API connection.

Make a WebSocket API request via a simple function call. Await the result. All of the speed with significantly less complexity.

```typescript
import { WebsocketAPIClient } from '@siebly/kraken-api';

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

wsApi.getWSClient().on('open', (data) => {
  console.log('ws api open', data?.wsKey);
});

wsApi.getWSClient().on('exception', console.error);

const order = await wsApi.submitSpotOrder({
  order_type: 'limit',
  side: 'buy',
  limit_price: 26500.4,
  order_qty: 1.2,
  symbol: 'BTC/USD',
});

await wsApi.amendSpotOrder({
  order_id: 'TEST-ORDER-ID',
  order_qty: 1.5,
  limit_price: 27000,
});

await wsApi.cancelSpotOrder({
  order_id: ['TEST-ORDER-ID'],
});

await wsApi.cancelAllSpotOrders();
```

Other supported Spot WebSocket API flows include:

- conditional Spot orders
- trigger-style orders
- batch Spot order submission
- batch Spot order cancellation
- cancel-all-after timeout handling

See also: [Kraken JavaScript Example - How to send/manage low-latency spot orders via the WebSocket API](https://siebly.io/examples/Kraken/Spot/WebSockets/wsAPI#L64)

Refer to the Kraken API documentation for a detailed list of available WebSocket API capabilities.

---

## Kraken Futures API in Node.js and TypeScript

While it looks & feels similar, Kraken's Derivatives use a different REST API surface and different request naming conventions than the Kraken Spot APIs. The [`@siebly/kraken-api` JavaScript Kraken SDK](https://www.npmjs.com/package/@siebly/kraken-api) manages this complexity for you, so you can focus on building & integrating your workflows.

Usage is similar to Spot. Create an instance of the utility class dedicated to the Kraken Derivatives API, the DerivativesClient. Provide your API keys if private API calls are desired. Call & await functions corresponding to the REST API endpoint you would like to use.

Detailed request building, routing & authentication are all handled under the hood by the SDK. Below are curated examples for common scenarios.

### Create a public Futures client

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

const client = new DerivativesClient();
```

### Create a private Futures client

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

const client = new DerivativesClient({
  apiKey: process.env.API_FUTURES_KEY!,
  apiSecret: process.env.API_FUTURES_SECRET!,
  // testnet: true, // optional: route Derivatives REST API calls to Kraken's demo environment
});
```

### Common public Futures market data calls

```typescript
const allTickers = await client.getTickers();
const ticker = await client.getTicker({ symbol: 'PF_ETHUSD' });
const orderBook = await client.getOrderbook({ symbol: 'PF_ETHUSD' });
const instruments = await client.getInstruments();
const feeSchedules = await client.getFeeSchedules();
const candles = await client.getCandles({
  tickType: 'trade',
  symbol: 'PF_ETHUSD',
  resolution: '1h',
});
```

You can also query recent public trade-style events:

```typescript
const executions = await client.getPublicExecutionEvents({
  tradeable: 'PF_ETHUSD',
});
```

See also: [Kraken JavaScript Example - How to query derivatives market data](https://siebly.io/examples/Kraken/Derivatives/Public/marketData)

### Futures order examples

Limit order:

```typescript
await client.submitOrder({
  orderType: 'lmt',
  symbol: 'PF_ETHUSD',
  side: 'buy',
  size: 0.01,
  limitPrice: 1000,
  cliOrdId: client.generateNewOrderID(),
});
```

Market order:

```typescript
await client.submitOrder({
  orderType: 'mkt',
  symbol: 'PF_ETHUSD',
  side: 'sell',
  size: 0.01,
});
```

Post-only and reduce-only:

```typescript
await client.submitOrder({
  orderType: 'post',
  symbol: 'PF_ETHUSD',
  side: 'buy',
  size: 0.01,
  limitPrice: 1000,
  cliOrdId: client.generateNewOrderID(),
});

await client.submitOrder({
  orderType: 'lmt',
  symbol: 'PF_ETHUSD',
  side: 'sell',
  size: 1,
  limitPrice: 1000,
  reduceOnly: true,
});
```

Batch order management:

```typescript
await client.batchOrderManagement({
  json: {
    batchOrder: [
      {
        order: 'send',
        order_tag: 'order-1',
        orderType: 'lmt',
        symbol: 'PF_ETHUSD',
        side: 'buy',
        size: 0.01,
        limitPrice: 1000,
        cliOrdId: client.generateNewOrderID(),
      },
    ],
  },
});
```

See also: [Kraken JavaScript Example - How to submit derivatives/futures orders](https://siebly.io/examples/Kraken/Derivatives/Private/submitOrder)

---

## Kraken Futures WebSockets in JavaScript

For subscribing to futures/derivatives market & account data in JavaScript (& Node.js), the SDK automatically handles this as well via the same `WebsocketClient` utility class.

```typescript
import { WebsocketClient, WS_KEY_MAP } from '@siebly/kraken-api';

const ws = new WebsocketClient();

ws.on('open', (data) => console.log('connected', data?.wsKey));
ws.on('message', (data) => console.log('message', JSON.stringify(data)));
ws.on('reconnected', (data) => console.log('reconnected', data?.wsKey));
ws.on('exception', console.error);

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

See also:

- [Kraken JavaScript Example - How to subscribe to derivatives/futures account change WebSocket events](https://siebly.io/examples/Kraken/Derivatives/WebSockets/privateWs)
- [Kraken JavaScript Example - How to subscribe to derivatives/futures market data WebSocket events](https://siebly.io/examples/Kraken/Derivatives/WebSockets/publicWs)

---

## Production notes for real trading systems

This is where SDKs usually earn their keep.

### 1. Use client-generated order IDs

For Spot, use `cl_ord_id`. For Futures, use `cliOrdId`. This makes retries and reconciliation safer.

```typescript
const orderIdForEntry1 = client.generateNewOrderID();

const result = await client.submitOrder({
  ordertype: 'limit',
  type: 'buy',
  pair: 'XBTUSD',
  volume: '0.0001',
  price: '10000',
  validate: true,
  cl_ord_id: orderIdForEntry1,
});

console.log(result);

// Detect entry 1 has filled, by looking for an order fill with cl_ord_id === orderIdForEntry1 either via REST API or async WebSocket updates.
```

### 2. Treat reconnects as a normal condition

Listen for `reconnecting` and `reconnected`. A dropped connection is not the exceptional case in production. Recovery behavior is part of the design. WebSockets can be unstable, especially during volatility.

The important part is detecting issues early (handled by SDK), promptly reconnecting (handled by SDK), and ensuring your system remains in sync when the SDK emits a `reconnected` event (up to your implementation).

### 3. Start public, then validate private, then trade tiny

The lowest-friction rollout path is:

1. Public REST APIs
2. Public WebSockets
3. Private account streams
4. Small live trading tests

If using WebSockets for updates, integrate a backfill workflow after connecting:

1. Connect and subscribe to WebSocket topics, but pause processing incoming data (drop data as it arrives)
2. Backfill any missing data via REST API (hydrate internal state).
3. Once backfill is complete, enable processing incoming data.

This ensures your system has the full history it needs before it starts processing new market & account updates.

### 4. Keep Spot and Futures credentials separate

Do not blur product boundaries in your code or secrets management. Spot and Futures use different credentials and different request models.

### 5. Watch symbol conventions carefully

Spot & Futures do not use the same symbol formatting. Treat symbols as product-specific inputs, not one universal string format. If needed, build your own solution to normalise outgoing & incoming symbols into a format your system can consistently work with.

### 6. Protect your API keys

- Treat your API keys like passwords. Keep them safe. Do not share them.
- Rotate API keys regularly.
- Use the minimum permissions on your API keys based on your needs. Active trading does not require withdrawal permissions. Analytics does not require trading permissions.
- Use IP whitelists to prevent API keys from being used outside your environment.

### 7. Inject your own logger if needed

If you want to integrate SDK logs into your own monitoring stack:

```typescript
import { WebsocketClient, DefaultLogger, LogParams } from '@siebly/kraken-api';

const customLogger: DefaultLogger = {
  trace: (..._params: LogParams) => {},
  info: (...params: LogParams) => console.log(...params),
  error: (...params: LogParams) => console.error(...params),
};

const ws = new WebsocketClient({}, customLogger);
```

See also: [Kraken JavaScript Example - How to subscribe to spot market data with WebSockets](https://siebly.io/examples/Kraken/Spot/WebSockets/publicWs)

---

## Why use a JavaScript SDK for Kraken's APIs & WebSockets?

If you are evaluating SDKs rather than just copying a few snippets, these are the practical reasons this SDK tends to matter:

- One Kraken JavaScript SDK for Spot REST APIs, Futures REST APIs, and WebSockets.
- Cleaner onboarding for Node.js and JavaScript developers.
- One snippet now can become hundreds of fragile snippets.
- Less low-value exchange plumbing in your codebase. Less to maintain, less that can break, fewer distractions.
- Stable connectivity with automated integration tests & thousands of daily users.
- Faster integration than building raw API connectivity with correctly crafted request signatures.
- Faster iteration when moving from public data to private trading flows.
- Better fit for bots, dashboards, and internal trading tools than raw request signing examples.
- A maintained SDK with examples, endpoint references, and a wider SDK ecosystem from [Siebly.io](https://siebly.io)

---

## FAQ

**Do I need separate keys for Spot and Futures?**
Yes. Treat Spot and Futures as separate products with separate API credentials. These can be managed within your Kraken account.

**Why both `WebsocketClient` and `WebsocketAPIClient`?**

- `WebsocketClient` is for subscriptions and streaming topics.
- `WebsocketAPIClient` is for Spot trading commands over Kraken's WebSocket API. Think "REST API" but via low-latency WebSockets.

**Does the SDK handle private authentication?**
Yes. All authentication for both REST APIs & WebSockets will be handled automatically using the underlying SDK architecture. Connectivity & authentication are both managed for you, so you can focus on integrating your system and making the API calls that you need.

**What happens if the connection drops?**
The SDK supports reconnect and resubscribe flows. Listen for `reconnecting` and `reconnected`.

The `reconnecting` event is a good trigger to pause any risky actions until the connection is restored & ready (cancel orders and prevent new orders).

The `reconnected` event is a good trigger to query the REST API for any out-of-sync account & market state before resuming normal trading activity (restore cancelled orders, resume order placement as desired).

**Can I use this Kraken API SDK in TypeScript projects?**
Yes. The package is TypeScript-first and publishes type declarations.

**Do I need TypeScript to use this JavaScript Kraken SDK?**
Pure JavaScript projects (including Node.js & Bun) can use this SDK too. TypeScript type declarations are included (and will help while working with the SDK in your IDE), but TypeScript is not required to use this [JavaScript SDK for Kraken](https://siebly.io/sdk/kraken/javascript).

**Can I use this package in both ESM and CommonJS projects?**
Yes. The package supports both. It is built & published to npm as a hybrid project. Your project will automatically import the correct bundle, due to the configuration in the SDK's package.json.

**Does this guide cover every SDK method?**
Yes, complete API coverage is expected across all available product groups in Kraken's API offering, both for REST APIs & WebSockets. We regularly monitor the API for changes & regularly keep the [Siebly JavaScript SDK for Kraken](https://siebly.io/sdk/kraken/javascript) up to date. If any functionality happens to be missing or out of date, please get in touch by [opening an issue on GitHub](https://github.com/sieblyio/kraken-api/issues).

For full method coverage, see:

- [List of all available Kraken APIs and the JavaScript method to call them](https://siebly.io/sdk/kraken/javascript#endpoint-reference)
- [Siebly SDK examples index](https://siebly.io/examples)

---

## Next steps

If you want to learn more about integrating with Kraken's APIs & WebSockets:

- Explore the [Kraken JavaScript examples on GitHub](https://github.com/sieblyio/kraken-api/tree/main/examples)
- Review the full endpoint list: [Kraken JavaScript endpoint reference](https://siebly.io/sdk/kraken/javascript#endpoint-reference)
- Check the Siebly JavaScript SDK for Kraken on npm: [`@siebly/kraken-api`](https://www.npmjs.com/package/@siebly/kraken-api)
- Browse the source code of the Siebly JavaScript SDK for Kraken on GitHub: [`sieblyio/kraken-api`](https://github.com/sieblyio/kraken-api)
- Explore the wider SDK ecosystem: [Siebly.io](https://siebly.io)

================
File: examples/Derivatives/Private/orderManagement.ts
================
/* 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 '../../../src/index.js';
⋮----
/**
 * 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',
 * }
 */
⋮----
async function editOrder()
⋮----
// Edit an existing order
⋮----
orderId: 'a04d0f84-36d4-4499-8382-96fcfc3ce7aa', // Or use cliOrdId instead
limitPrice: 1100, // New limit price
// or add some other parameters you want to edit
⋮----
// Response includes:
// - status: edited, invalidSize, invalidPrice, etc.
// - orderEvents: Array of order events
⋮----
async function cancelOrder()
⋮----
// Cancel a single order
⋮----
order_id: 'a04d0f84-36d4-4499-8382-96fcfc3ce7aa', // Or use cliOrdId
⋮----
// Response status:
// - cancelled: Successfully cancelled
// - filled: Order was already filled
// - notFound: Order not found
⋮----
async function cancelAllOrders()
⋮----
// Cancel all open orders
⋮----
// Response includes:
// - status: cancelled or noOrdersToCancel
// - cancelledOrders: Array of cancelled order IDs
⋮----
async function cancelAllOrdersBySymbol()
⋮----
// Cancel all orders for specific symbol
⋮----
async function batchOrderManagement()
⋮----
// Send, edit, and cancel orders in a single batch request
⋮----
// Edit existing order
⋮----
// Cancel existing order
⋮----
// Response includes batchStatus array with results for each order
// - status: placed, edited, cancelled, or rejection reason
// - order_tag: Maps back to your request
⋮----
// Uncomment the function you want to test:
⋮----
// editOrder();
// cancelOrder();
// cancelAllOrders();
// cancelAllOrdersBySymbol();
// batchOrderManagement();

================
File: examples/Derivatives/Private/testnet.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { DerivativesClient } from '../../../src/index.js';
⋮----
// This example shows how to call Kraken API testnet (demo) endpoints with either node.js,
// javascript (js) or typescript (ts) with the npm module "@siebly/kraken-api" for Kraken exchange
⋮----
/**
 * import { DerivativesClient } from '@siebly/kraken-api';
 */
⋮----
/**
 * Kraken Derivatives has a demo environment (testnet) that you can connect to via WebSocket. All you need to do is set the `testnet` option to `true` when creating the WebsocketClient instance, as shown below.
 * Everything else behaves exactly the same way.
 *
 * Note: as of November 2025, only the DerivativesClient supports testnet connections. Kraken refer to this as the "Demo" environment, but it is effectively a testnet.
 * This is a place to test your API integration. It is not a good place to test strategy performance, as the liquidity and orderbook dynamics are very different to the live environment.
 *
 * Refer to the following for more information:
 * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/CEX-Testnets
 */
⋮----
// https://demo-futures.kraken.com to create demo account
⋮----
async function getWallets()
⋮----
// Get all wallets (cash and margin accounts)
⋮----
// Response includes:
// - cash: Cash account with balances
// - flex: Multi-collateral wallet with margin info
// - Available margin, portfolio value, PnL
// - Initial/maintenance margin requirements
// For each margin account:
//   - balances, auxiliary (pv, pnl, af, funding)
//   - marginRequirements (im, mm, lt, tt)
//   - triggerEstimates
⋮----
async function getOpenPositions()
⋮----
// Get all open Futures positions
⋮----
// Response includes for each position:
// - symbol: Futures symbol
// - side: long or short
// - size: Position size
// - price: Average entry price
// - fillTime: When position was opened
// - unrealizedFunding: Unrealized funding
⋮----
async function getFills()
⋮----
// Get filled orders history (last 100)
⋮----
// Response includes for each fill:
// - fill_id: Unique fill identifier
// - order_id: Associated order ID
// - symbol: Futures symbol
// - side: buy or sell
// - size: Fill size
// - price: Fill price
// - fillTime: Execution time
// - fillType: maker, taker, liquidation, etc.
⋮----
async function getFillsBeforeTime()
⋮----
// Get fills before specific time
⋮----
lastFillTime: new Date(Date.now() - 86400000).toISOString(), // 24h ago
⋮----
// Returns 100 fills before specified time
⋮----
async function initiateWalletTransfer()
⋮----
// Transfer between margin accounts or to/from cash account
⋮----
fromAccount: 'cash', // or margin account name
toAccount: 'flex', // or other margin account
⋮----
// Transfers funds between accounts instantly
⋮----
async function initiateWithdrawalToSpot()
⋮----
// Withdraw from Futures to Spot wallet
⋮----
sourceWallet: 'cash', // Default is cash wallet
⋮----
// Response includes:
// - uid: Withdrawal reference ID
⋮----
async function getOrderEvents()
⋮----
// Get order history events
⋮----
sort: 'desc', // desc = newest first
opened: true, // Include opened orders
closed: true, // Include closed orders
⋮----
// Response includes:
// - elements: Array of order events
// - Order placed, cancelled, rejected, executed events
// - continuationToken: For pagination
⋮----
async function getOrderEventsBySymbol()
⋮----
// Filter order events by symbol
⋮----
async function getExecutionEvents()
⋮----
// Get execution/trade history
⋮----
// Response includes for each execution:
// - execution: Fill details (price, quantity, timestamp)
// - order: Associated order details
// - fee: Fee paid
// - positionSize: Position size after execution
⋮----
async function getExecutionEventsBySymbol()
⋮----
// Filter executions by symbol
⋮----
async function getAccountLog()
⋮----
// Get account log (all account activities)
⋮----
// Log includes:
// - futures trade, liquidation, funding rate change
// - conversions, transfers, settlements
// - interest payments, fees
⋮----
async function getAccountLogFiltered()
⋮----
// Filter account log by info types
⋮----
// Uncomment the function you want to test:
⋮----
// initiateWalletTransfer();
// initiateWithdrawalToSpot();

================
File: examples/Derivatives/WebSockets/publicWs.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import {
  DefaultLogger,
  LogParams,
  WebsocketClient,
  WS_KEY_MAP,
  WSTopicRequest,
} from '../../../src/index.js';
import { WSDerivativesTopic } from '../../../src/types/websockets/ws-subscriptions.js';
// normally you should install this module via npm: `npm install @siebly/kraken-api` and import the module:
// import { LogParams, WebsocketClient, WsTopicRequest } from '@siebly/kraken-api';
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log(new Date(), '--> trace', ...params);
⋮----
async function start()
⋮----
/**
   * 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 without API key/secret, since we're only connecting to public topics.
   *
   * 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.
   */
⋮----
// apiKey: key,
// apiSecret: secret,
⋮----
// Data received
⋮----
// Something happened, attempting to reconnect
⋮----
// Reconnect successful
⋮----
// Connection closed. If unexpected, expect reconnect -> reconnected.
⋮----
// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
⋮----
/**
   * The below examples demonstrate how you can subscribe to public topics.
   *
   * Do note that all of these include the "derivativesPublicV1" 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.
   */
⋮----
// Ticker: https://docs.kraken.com/api/docs/futures-api/websocket/ticker
⋮----
// client.subscribe(publicTickerTopicRequest, WS_KEY_MAP.derivativesPublicV1);
⋮----
// Ticker Lite: https://docs.kraken.com/api/docs/futures-api/websocket/ticker
⋮----
// client.subscribe(
//   publicTickerLiteTopicRequest,
//   WS_KEY_MAP.derivativesPublicV1,
// );
⋮----
// Book: https://docs.kraken.com/api/docs/futures-api/websocket/ticker
⋮----
// client.subscribe(publicBookTopicRequest, WS_KEY_MAP.derivativesPublicV1);
⋮----
// Trade: https://docs.kraken.com/api/docs/futures-api/websocket/ticker

================
File: examples/Spot/Private/depositWithdraw.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { SpotClient } from '../../../src/index.js';
⋮----
// 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 DEPOSIT AND WITHDRAWAL
⋮----
/**
 * import { SpotClient } from '@siebly/kraken-api';
 */
⋮----
// initialise the client
/**
 *
 * Kraken API uses API Key and Private Key (base64 encoded)
 *
 * Example:
 * {
 *   apiKey: 'your-api-key',
 *   apiSecret: 'your-base64-encoded-private-key',
 * }
 *
 * API Key Permissions Required:
 * - Funds permissions - Query
 * - Funds permissions - Deposit
 * - Funds permissions - Withdraw
 * - Data - Query ledger entries
 *
 */
⋮----
async function withdrawFunds()
⋮----
// Make a withdrawal request
⋮----
key: 'btc_2709', // Withdrawal key name from your account
⋮----
address: 'bc1kar0ssrr7xf3vy5l6d3lydnwkre5og2zz3f5ldq', // Optional confirmation
⋮----
// Response includes:
// - refid: Reference ID for the withdrawal
⋮----
async function getDepositMethods()
⋮----
// Get available deposit methods for an asset
⋮----
// Response includes:
// - method: Name of deposit method
// - limit: Maximum net amount that can be deposited
// - fee: Fees that will be paid
// - address-setup-fee: Whether method has setup fee
// - gen-address: Whether new addresses can be generated
// - minimum: Minimum net amount
⋮----
async function getDepositAddresses()
⋮----
// Get or generate deposit address
⋮----
new: false, // Set to true to generate new address
⋮----
// Response includes:
// - address: Deposit address
// - expiretm: Expiration time or 0 if not expiring
// - new: Whether address has ever been used
// - tag: Contains tags/memos for XRP, STX, XLM, EOS
⋮----
async function generateNewDepositAddress()
⋮----
// Generate a new deposit address
⋮----
new: true, // Generate new address
⋮----
async function getWithdrawalMethods()
⋮----
// Get available withdrawal methods
⋮----
// Response includes:
// - asset: Name of asset being withdrawn
// - method: Name of withdrawal method
// - network: Blockchain/network name
// - minimum: Minimum net amount that can be withdrawn
⋮----
async function getWithdrawalAddresses()
⋮----
// Get withdrawal addresses
⋮----
verified: true, // Filter by verification status
⋮----
// Response includes:
// - address: Withdrawal address
// - asset: Asset name
// - method: Withdrawal method
// - key: Withdrawal key name
// - tag: Tags/memos for XRP, STX, XLM, EOS
// - verified: Verification status
⋮----
async function getWithdrawalAddressByKey()
⋮----
// Find withdrawal address by key name
⋮----
key: 'btc_2709', // Withdrawal key name
⋮----
async function getWithdrawalsStatus()
⋮----
// Get status of recent withdrawals
⋮----
// Status values:
// - Initial: withdrawal just created
// - Pending: withdrawal pending
// - Settled: withdrawal settled
// - Success: withdrawal successful
// - Failure: withdrawal failed
⋮----
// Status properties (if available):
// - cancel-pending: cancelation requested
// - canceled: canceled
// - cancel-denied: cancelation denied
// - return: return transaction by Kraken
// - onhold: on hold pending review
⋮----
async function getWithdrawalsStatusWithPagination()
⋮----
// Get withdrawals with pagination
⋮----
cursor: true, // Enable pagination
limit: 10, // Results per page
⋮----
async function getDepositsStatus()
⋮----
// Get status of recent deposits
⋮----
// Similar status values as withdrawals
⋮----
async function cancelWithdrawal()
⋮----
// Cancel a recent withdrawal (if not yet processed)
⋮----
refid: 'AGBSO6T-UFMTTQ-I7KGS6', // Reference ID from withdrawal
⋮----
// Returns true if cancellation successful
⋮----
async function getWithdrawalInfo()
⋮----
// Get withdrawal fee information before withdrawing
⋮----
// Response includes:
// - method: Withdrawal method
// - limit: Maximum amount that can be withdrawn
// - amount: Net amount to be withdrawn
// - fee: Withdrawal fee
⋮----
async function transferToFutures()
⋮----
async function transferToSubaccount()
⋮----
from: 'UID', // get From API, getSubaccounts()
to: 'UID', // get From API, getSubaccounts()
⋮----
// Uncomment the function you want to test:
⋮----
// withdrawFunds();
// getDepositMethods();
// getDepositAddresses();
// generateNewDepositAddress();
// getWithdrawalMethods();
// getWithdrawalAddresses();
// getWithdrawalAddressByKey();
// getWithdrawalsStatus();
// getWithdrawalsStatusWithPagination();
// getDepositsStatus();
// cancelWithdrawal();
// getWithdrawalInfo();
// transferToFutures();
// transferToSubaccount();

================
File: examples/Spot/WebSockets/publicWs.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import {
  DefaultLogger,
  LogParams,
  WebsocketClient,
  WS_KEY_MAP,
  WSTopicRequest,
} from '../../../src/index.js';
// normally you should install this module via npm: `npm install @siebly/kraken-api` and import the module:
// import { LogParams, WebsocketClient, WSTopicRequest } from '@siebly/kraken-api';
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log('trace', ...params);
⋮----
async function start()
⋮----
/**
   * 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.spotPublicV2` 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.
   */
⋮----
// Optional, inject a custom logger
// const client = new WebsocketClient({}, customLogger);
⋮----
// Data received
⋮----
// Something happened, attempting to reconnect
⋮----
// Reconnect successful
⋮----
// Connection closed. If unexpected, expect reconnect -> reconnected.
⋮----
// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
⋮----
// Spot ticker level 1: https://docs.kraken.com/api/docs/websocket-v2/ticker
⋮----
// below params are optional:
// event_trigger: 'bbo', // bbo: on a change in the best-bid-offer price levels.
// event_trigger: 'trades', // trades: on every trade.
// snapshot: true, // default: true
⋮----
// client.subscribe(tickersRequestWithParams, WS_KEY_MAP.spotPublicV2);
⋮----
// Book level 2: https://docs.kraken.com/api/docs/websocket-v2/book
⋮----
// below params are optional:
// depth: 10, // default: 10, Possible values: [10, 25, 100, 500, 1000]
// snapshot: true, // default: true
⋮----
// client.subscribe(bookRequestWithParams, WS_KEY_MAP.spotPublicV2);
⋮----
// Candles (OHLC): https://docs.kraken.com/api/docs/websocket-v2/ohlc
⋮----
interval: 1, // Possible values: [1, 5, 15, 30, 60, 240, 1440, 10080, 21600]
⋮----
// below params are optional:
// snapshot: true, // default: true
⋮----
// client.subscribe(candleOhlcRequestWithParams, WS_KEY_MAP.spotPublicV2);
⋮----
// Trades: https://docs.kraken.com/api/docs/websocket-v2/trade
⋮----
// below params are optional:
// snapshot: true, // default: true
⋮----
// client.subscribe(tradesRequestWithParams, WS_KEY_MAP.spotPublicV2);
⋮----
// Instruments: https://docs.kraken.com/api/docs/websocket-v2/instrument
⋮----
// below params are optional:
// If true, include xStocks in the response, otherwise include crypto spot pairs only:
include_tokenized_assets: true, // default: false
// snapshot: true, // default: true
⋮----
/**
     * Either send one topic (with optional params) at a time (as shown above in the commented-out lines)
     */
⋮----
/**
     * Or send multiple topics in a batch (grouped by ws connection (WsKey))
     */

================
File: src/lib/websocket/websocket-util.ts
================
import WebSocket from 'isomorphic-ws';
⋮----
import { WSAPIRequestOperationKrakenSpot } from '../../types/websockets/ws-api.js';
import { WSTopic } from '../../types/websockets/ws-subscriptions.js';
⋮----
/** Should be one WS key per unique URL */
⋮----
/**
   * Public WebSocket subscriptions for Kraken Spot products, via the V2 API
   *
   * - Ref: https://docs.kraken.com/api/docs/guides/spot-ws-intro
   * - Channels: https://docs.kraken.com/api/docs/websocket-v2/add_order
   *
   * Note: Use spotPrivateV2 for private channels (requires API keys).
   */
⋮----
/**
   * Public WebSocket subscriptions for Kraken Derivatives products, via the V1 API:
   *
   * - Ref: https://docs.kraken.com/api/docs/guides/futures-websockets
   * - Channels: https://docs.kraken.com/api/docs/futures-api/websocket/open_orders
   *
   * Note: While both Public and Private channels use the same WebSocket URL, we will actually maintain separate connections for easier management. Private channels require authentication and the connection is authenticated automatically.
   */
⋮----
/** This is used to differentiate between each of the available websocket streams */
export type WsKey = (typeof WS_KEY_MAP)[keyof typeof WS_KEY_MAP];
⋮----
export type WSOperation = 'subscribe' | 'unsubscribe';
⋮----
/**
 * Normalised internal format for a request (subscribe/unsubscribe/etc) on a topic, with optional parameters.
 *
 * - Topic: the topic this event is for
 * - Payload: the parameters to include, optional. E.g. auth requires key + sign. Some topics allow configurable parameters.
 */
export interface WSTopicRequest<
  TWSTopic extends WSTopic = WSTopic,
  TWSPayload = any,
> {
  topic: TWSTopic;
  payload?: TWSPayload;
}
⋮----
/**
 * Conveniently allow users to request a topic either as string topics or objects (containing string topic + params)
 */
export type WSTopicRequestOrStringTopic<
  TWSTopic extends WSTopic,
  TWSPayload = any,
> = WSTopicRequest<TWSTopic, TWSPayload> | string;
⋮----
export interface WSRequestOperationKraken<
  TWSTopic extends string,
  TWSParams extends object = any,
> {
  // spot only
  method?: WSOperation;
  // futures only
  event?: WSOperation;
  params:
    | {
        channel: (TWSTopic | string | number)[];
        symbol?: string[];
        event_trigger?: string;
        snapshot?: boolean;
      }
    | TWSParams;
  req_id: number;
  /**
   * The following are needed for futures/derivatives requests
   */
  feed?: TWSTopic;
  api_key?: string;
  original_challenge?: string;
  signed_challenge?: string;
}
⋮----
// spot only
⋮----
// futures only
⋮----
/**
   * The following are needed for futures/derivatives requests
   */
⋮----
/**
 * #305: ws.terminate() is undefined in browsers.
 * This only works in node.js, not in browsers.
 * Does nothing if `ws` is undefined. Does nothing in browsers.
 */
export function safeTerminateWs(
  ws?: WebSocket | any,
  fallbackToClose?: boolean,
): boolean
⋮----
/**
 * WS API promises are stored using a primary key. This key is constructed using
 * properties found in every request & reply.
 *
 * The counterpart to this is in resolveEmittableEvents
 */
export function getPromiseRefForWSAPIRequest(
  wsKey: WsKey,
  requestEvent: WSAPIRequestOperationKrakenSpot,
): string
⋮----
/**
 * Users can conveniently pass topics as strings or objects (object has topic name + optional params).
 *
 * This method normalises topics into objects (object has topic name + optional params).
 */
export function getNormalisedTopicRequests(
  wsTopicRequests: WSTopicRequestOrStringTopic<WSTopic>[],
): WSTopicRequest<WSTopic>[]
⋮----
// passed as string, convert to object
⋮----
// already a normalised object, thanks to user

================
File: src/lib/BaseWSClient.ts
================
import { EventEmitter } from 'events';
import WebSocket from 'isomorphic-ws';
⋮----
import {
  isMessageEvent,
  MessageEventLike,
} from '../types/websockets/ws-events.js';
import {
  WebsocketClientOptions,
  WSClientConfigurableOptions,
  WsEventInternalSrc,
} from '../types/websockets/ws-general.js';
import { WSTopic } from '../types/websockets/ws-subscriptions.js';
import { checkWebCryptoAPISupported } from './webCryptoAPI.js';
import { DefaultLogger } from './websocket/logger.js';
import {
  getNormalisedTopicRequests,
  safeTerminateWs,
  WSOperation,
  WSTopicRequest,
  WSTopicRequestOrStringTopic,
} from './websocket/websocket-util.js';
import { WsStore } from './websocket/WsStore.js';
import {
  WSConnectedResult,
  WsConnectionStateEnum,
} from './websocket/WsStore.types.js';
⋮----
type UseTheExceptionEventInstead = never;
⋮----
interface WSClientEventMap<WsKey extends string> {
  /** Connection opened. If this connection was previously opened and reconnected, expect the reconnected event instead */
  open: (evt: {
    wsKey: WsKey;
    event: any;
    wsUrl: string;
    ws: WebSocket;
  }) => void;

  /** Reconnecting a dropped connection */
  reconnecting: (evt: { wsKey: WsKey; event: any }) => void;

  /** Successfully reconnected a connection that dropped */
  reconnected: (evt: {
    wsKey: WsKey;
    event: any;
    wsUrl: string;
    ws: WebSocket;
  }) => void;

  /** Connection closed */
  close: (evt: { wsKey: WsKey; event: any }) => void;

  /** Received reply to websocket command (e.g. after subscribing to topics) */
  response: (response: any & { wsKey: WsKey }) => void;

  /** Received data for topic */
  message: (response: any & { wsKey: WsKey }) => void;

  /** Exception from ws client OR custom listeners (e.g. if you throw inside your event handler) */
  exception: (response: any & { wsKey: WsKey }) => void;

  /**
   * See for more information: https://github.com/tiagosiebler/bybit-api/issues/413
   * @deprecated Use the 'exception' event instead. The 'error' event had the unintended consequence of throwing an unhandled promise rejection.
   */
  error: UseTheExceptionEventInstead;

  /** Confirmation that a connection successfully authenticated */
  authenticated: (event: { wsKey: WsKey; event: any }) => void;
}
⋮----
/** Connection opened. If this connection was previously opened and reconnected, expect the reconnected event instead */
⋮----
/** Reconnecting a dropped connection */
⋮----
/** Successfully reconnected a connection that dropped */
⋮----
/** Connection closed */
⋮----
/** Received reply to websocket command (e.g. after subscribing to topics) */
⋮----
/** Received data for topic */
⋮----
/** Exception from ws client OR custom listeners (e.g. if you throw inside your event handler) */
⋮----
/**
   * See for more information: https://github.com/tiagosiebler/bybit-api/issues/413
   * @deprecated Use the 'exception' event instead. The 'error' event had the unintended consequence of throwing an unhandled promise rejection.
   */
⋮----
/** Confirmation that a connection successfully authenticated */
⋮----
export interface EmittableEvent<
  TEventType extends
    keyof WSClientEventMap<string> = keyof WSClientEventMap<string>,
> {
  eventType:
    | TEventType
    | 'pong'
    | 'connectionReady' // tied to "requireConnectionReadyConfirmation";
    | 'connectionReadyForAuth'; // tied to specific events we need to wait for, before we can begin post-connect auth
  event: Parameters<WSClientEventMap<string>[TEventType]>[0];
  isWSAPIResponse?: boolean;
}
⋮----
| 'connectionReady' // tied to "requireConnectionReadyConfirmation";
| 'connectionReadyForAuth'; // tied to specific events we need to wait for, before we can begin post-connect auth
⋮----
// Type safety for on and emit handlers: https://stackoverflow.com/a/61609010/880837
export interface BaseWebsocketClient<
  TWSKey extends string,
  TWSRequestEvent extends object,
> {
  on<U extends keyof WSClientEventMap<TWSKey>>(
    event: U,
    listener: WSClientEventMap<TWSKey>[U],
  ): this;

  emit<U extends keyof WSClientEventMap<TWSKey>>(
    event: U,
    ...args: Parameters<WSClientEventMap<TWSKey>[U]>
  ): boolean;
}
⋮----
on<U extends keyof WSClientEventMap<TWSKey>>(
    event: U,
    listener: WSClientEventMap<TWSKey>[U],
  ): this;
⋮----
emit<U extends keyof WSClientEventMap<TWSKey>>(
    event: U,
    ...args: Parameters<WSClientEventMap<TWSKey>[U]>
  ): boolean;
⋮----
/**
 * A midflight WS request event (e.g. subscribe to these topics).
 *
 * - requestKey: unique identifier for this request, if available. Can be anything as a string.
 * - requestEvent: the raw request, as an object, that will be sent on the ws connection. This may contain multiple topics/requests in one object, if the exchange supports it.
 */
export interface MidflightWsRequestEvent<TEvent = object> {
  requestKey: string | number;
  requestEvent: TEvent;
}
⋮----
/**
 * Appends wsKey and isWSAPIResponse to all events.
 * Some events are arrays, this handles that nested scenario too.
 */
function getFinalEmittable(
  emittable: EmittableEvent | EmittableEvent[],
  wsKey: any,
  isWSAPIResponse?: boolean,
): any
⋮----
// Some topics just emit an array.
// This is consistent with how it was before the WS API upgrade:
⋮----
// const { event, ...others } = emittable;
// return {
//   ...others,
//   event: event.map((subEvent) =>
//     getFinalEmittable(subEvent, wsKey, isWSAPIResponse),
//   ),
// };
⋮----
// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
export abstract class BaseWebsocketClient<
TWSKey extends string,
⋮----
constructor(
    options?: WSClientConfigurableOptions & { wsLoggerCategory: string },
    logger?: DefaultLogger,
)
⋮----
// Requires a confirmation "response" from the ws connection before assuming it is ready
⋮----
// Automatically auth after opening a connection?
⋮----
// Automatically include auth/sign/token with every WS request.
// Automatically handled during getWsRequestEvents.
⋮----
// Automatically re-auth WS API, if we were auth'd before and get reconnected
⋮----
// Whether to use native heartbeats (depends on the exchange)
⋮----
// Check Web Crypto API support when credentials are provided and no custom sign function is used
⋮----
/**
   * Return true if this wsKey connection should automatically authenticate immediately after connecting
   */
protected abstract isAuthOnConnectWsKey(wsKey: TWSKey): boolean;
⋮----
protected abstract isCustomReconnectionNeeded(wsKey: TWSKey): boolean;
⋮----
protected abstract triggerCustomReconnectionWorkflow(
    wsKey: TWSKey,
  ): Promise<void>;
⋮----
protected abstract sendPingEvent(wsKey: TWSKey, ws: WebSocket): void;
⋮----
protected abstract sendPongEvent(wsKey: TWSKey, ws: WebSocket): void;
⋮----
protected abstract isWsPing(data: any): boolean;
⋮----
protected abstract isWsPong(data: any): boolean;
⋮----
protected abstract authPrivateConnectionsOnConnect(_wsKey: TWSKey): boolean;
⋮----
/**
   * Return the event sent to the server to trigger authentication. If the event requires waiting for another event first (e.g. a challenge), return 'waitForEvent' and the library will wait for that event before calling this method again.
   *
   * Usually only called once per connection, unless the connection drops/is reset.
   */
protected abstract getWsAuthRequestEvent(
    wsKey: TWSKey,
    eventToAuth?: object,
  ): Promise<object | string | 'waitForEvent' | void>;
⋮----
protected abstract isPrivateTopicRequest(
    request: WSTopicRequest<WSTopic>,
    wsKey: TWSKey,
  ): boolean;
⋮----
/**
   * Returns a list of string events that can be individually sent upstream to complete subscribing/unsubscribing/etc to these topics
   */
// protected abstract getWsOperationEventsForTopics(
//   topics: WsTopicRequest<WSTopic>[],
//   wsKey: TWSKey,
//   operation: WsOperation,
// ): Promise<string[]>;
⋮----
protected abstract getPrivateWSKeys(): TWSKey[];
⋮----
protected abstract getWsUrl(wsKey: TWSKey): Promise<string>;
⋮----
protected abstract getMaxTopicsPerSubscribeEvent(
    wsKey: TWSKey,
  ): number | null;
⋮----
/**
   * @returns one or more correctly structured request events for performing a operations over WS. This can vary per exchange spec.
   */
protected abstract getWsRequestEvents(
    wsKey: TWSKey,
    operation: WSOperation,
    requests: WSTopicRequest<WSTopic>[],
  ): Promise<MidflightWsRequestEvent<TWSRequestEvent>[]>;
⋮----
/**
   * Abstraction called to sort ws events into emittable event types (response to a request, data update, etc)
   */
protected abstract resolveEmittableEvents(
    wsKey: TWSKey,
    event: MessageEventLike,
  ): EmittableEvent[];
⋮----
/**
   * Request connection of all dependent (public & private) websockets, instead of waiting for automatic connection by library
   */
protected abstract connectAll(): Promise<WSConnectedResult | undefined>[];
⋮----
protected isPrivateWsKey(wsKey: TWSKey): boolean
⋮----
/** Returns auto-incrementing request ID, used to track promise references for async requests */
protected getNewRequestId(): number
⋮----
protected abstract sendWSAPIRequest(
    wsKey: TWSKey,
    operation: string,
    params?: any,
  ): Promise<unknown>;
⋮----
protected abstract sendWSAPIRequest(
    wsKey: TWSKey,
    channel: string,
    params: any,
  ): Promise<unknown>;
⋮----
public getTimeOffsetMs()
⋮----
public setTimeOffsetMs(newOffset: number)
⋮----
/**
   * Don't call directly! Use subscribe() instead!
   *
   * Subscribe to one or more topics on a WS connection (identified by WS Key).
   *
   * - Topics are automatically cached
   * - Connections are automatically opened, if not yet connected
   * - Authentication is automatically handled
   * - Topics are automatically resubscribed to, if something happens to the connection, unless you call unsubsribeTopicsForWsKey(topics, key).
   *
   * @param wsTopicRequests array of topics to subscribe to
   * @param wsKey ws key referring to the ws connection these topics should be subscribed on
   */
protected async subscribeTopicsForWsKey(
    wsTopicRequests: WSTopicRequestOrStringTopic<WSTopic>[],
    wsKey: TWSKey,
)
⋮----
// Store topics, so future automation (post-auth, post-reconnect) has everything needed to resubscribe automatically
⋮----
// start connection process if it hasn't yet begun. Topics are automatically subscribed to on-connect
⋮----
// Subscribe should happen automatically once connected, nothing to do here after topics are added to wsStore.
⋮----
/**
       * Are we in the process of connection? Nothing to send yet.
       */
⋮----
// We're connected. Check if auth is needed and if already authenticated
⋮----
/**
       * If not authenticated yet and auth is required, don't request topics yet.
       *
       * Auth should already automatically be in progress, so no action needed from here. Topics will automatically subscribe post-auth success.
       */
⋮----
// Finally, request subscription to topics if the connection is healthy and ready
⋮----
protected async unsubscribeTopicsForWsKey(
    wsTopicRequests: WSTopicRequestOrStringTopic<WSTopic>[],
    wsKey: TWSKey,
): Promise<unknown>
⋮----
// Store topics, so future automation (post-auth, post-reconnect) has everything needed to resubscribe automatically
⋮----
// If not connected, don't need to do anything.
// Removing the topic from the store is enough to stop it from being resubscribed to on reconnect.
⋮----
// We're connected. Check if auth is needed and if already authenticated
⋮----
/**
       * If not authenticated yet and auth is required, don't need to do anything.
       * We don't subscribe to topics until auth is complete anyway.
       */
⋮----
// Finally, request subscription to topics if the connection is healthy and ready
⋮----
/**
   * Splits topic requests into two groups, public & private topic requests
   */
private sortTopicRequestsIntoPublicPrivate(
    wsTopicRequests: WSTopicRequest<WSTopic>[],
    wsKey: TWSKey,
):
⋮----
/** Get the WsStore that tracks websockets & topics */
public getWsStore(): WsStore<TWSKey, WSTopicRequest<WSTopic>>
⋮----
public close(wsKey: TWSKey, force?: boolean)
⋮----
public closeAll(force?: boolean)
⋮----
public isConnected(wsKey: TWSKey): boolean
⋮----
/**
   * Request connection to a specific websocket, instead of waiting for automatic connection.
   */
public async connect(
    wsKey: TWSKey,
    customUrl?: string | undefined,
    throwOnError?: boolean,
): Promise<WSConnectedResult | undefined>
⋮----
// Important: don't check for RECONNECTING here, or this clashes with reconnectWithDelay()!
⋮----
private connectToWsUrl(url: string, wsKey: TWSKey): WebSocket
⋮----
//
⋮----
private parseWsError(context: string, error: any, wsKey: TWSKey): boolean
⋮----
// Allow retry by default (in some places that call this). Prevent deadloop in hard failure (401)
⋮----
/** Get a signature, build the auth request and send it */
private async sendAuthRequest(
    wsKey: TWSKey,
    eventToAuth?: object,
): Promise<unknown>
⋮----
// If not required, this won't return anything
⋮----
// Short-circuit this for the next time it's called
⋮----
private reconnectWithDelay(wsKey: TWSKey, connectionDelayMs: number)
⋮----
// Some streams need a specialist reconnection workflow.
// E.g. the user data stream can't just be reconnected as is.
⋮----
private ping(wsKey: TWSKey)
⋮----
/**
   * Closes a connection, if it's even open. If open, this will trigger a reconnect asynchronously.
   * If closed, trigger a reconnect immediately
   */
protected executeReconnectableClose(wsKey: TWSKey, reason: string)
⋮----
private clearTimers(wsKey: TWSKey)
⋮----
// Send a ping at intervals
private clearPingTimer(wsKey: TWSKey)
⋮----
// Expect a pong within a time limit
private clearPongTimer(wsKey: TWSKey)
⋮----
// this.logger.trace(`Cleared pong timeout for "${wsKey}"`);
⋮----
// this.logger.trace(`No active pong timer for "${wsKey}"`);
⋮----
private clearReconnectTimer(wsKey: TWSKey)
⋮----
/**
   * Returns a list of string events that can be individually sent upstream to complete subscribing/unsubscribing/etc to these topics
   *
   * If events are an object, these should be stringified (`return JSON.stringify(event);`)
   * Each event returned by this will be sent one at a time
   *
   * Events are automatically split into smaller batches, by this method, if needed.
   */
protected async getWsOperationEventsForTopics(
    topics: WSTopicRequest<WSTopic>[],
    wsKey: TWSKey,
    operation: WSOperation,
): Promise<MidflightWsRequestEvent<TWSRequestEvent>[]>
⋮----
// Events that are ready to send (usually stringified JSON)
⋮----
/**
   * Simply builds and sends subscribe events for a list of topics for a ws key
   *
   * @private Use the `subscribe(topics)` or `subscribeTopicsForWsKey(topics, wsKey)` method to subscribe to topics. Send WS message to subscribe to topics.
   */
private async requestSubscribeTopics(
    wsKey: TWSKey,
    wsTopicRequests: WSTopicRequest<WSTopic>[],
)
⋮----
// Automatically splits requests into smaller batches, if needed
⋮----
`Subscribing to ${wsTopicRequests.length} "${wsKey}" topics in ${subscribeWsMessages.length} batches.`, // Events: "${JSON.stringify(topics)}"
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
/**
   * Simply builds and sends unsubscribe events for a list of topics for a ws key
   *
   * @private Use the `unsubscribe(topics)` method to unsubscribe from topics. Send WS message to unsubscribe from topics.
   */
private async requestUnsubscribeTopics(
    wsKey: TWSKey,
    wsTopicRequests: WSTopicRequest<WSTopic>[],
)
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
/**
   * Try sending a string event on a WS connection (identified by the WS Key)
   */
public tryWsSend(
    wsKey: TWSKey,
    wsMessage: string,
    throwExceptions?: boolean,
)
⋮----
private async onWsOpen(
    event: WebSocket.Event,
    wsKey: TWSKey,
    url: string,
    ws: WebSocket,
)
⋮----
private resolveConnectionInProgressPromise(wsKey: TWSKey)
⋮----
// Resolve & cleanup deferred "connection attempt in progress" promise
⋮----
/**
   * Called automatically once a connection is ready.
   * - Some exchanges are ready immediately after the connections open.
   * - Some exchanges send an event to confirm the connection is ready for us.
   *
   * This method is called to act when the connection is ready. Use `requireConnectionReadyConfirmation` to control how this is called.
   */
private async onWsReadyForEvents(wsKey: TWSKey)
⋮----
// Some websockets require an auth packet to be sent after opening the connection
⋮----
// Reconnect to topics known before it connected
⋮----
// Request sub to public topics, if any
⋮----
// Request sub to private topics, if auth on connect isn't needed
⋮----
/**
   * Handle subscription to private topics _after_ authentication successfully completes asynchronously.
   *
   * Only used for exchanges that require auth before sending private topic subscription requests
   */
private onWsAuthenticated(
    wsKey: TWSKey,
    event: { isWSAPI?: boolean; WSAPIAuthChannel?: string },
)
⋮----
// Resolve & cleanup deferred "auth attempt in progress" promise
⋮----
// Remove before continuing, in case there's more requests queued
⋮----
private onWsPing(
    event: any,
    wsKey: TWSKey,
    ws: WebSocket,
    source: WsEventInternalSrc,
)
⋮----
private onWsPong(event: any, wsKey: TWSKey, source: WsEventInternalSrc)
⋮----
// Necessary when native heartbeats are used
⋮----
private onWsMessage(event: unknown, wsKey: TWSKey, ws: WebSocket)
⋮----
// console.log('onMessageRaw: ', (event as any).data);
// any message can clear the pong timer - wouldn't get a message if the ws wasn't working
⋮----
// console.log(`raw event: `, { data, dataType, emittableEvents });
⋮----
// Not used for kraken. At least for spot, auth is included per req during subscribe
⋮----
// Not used for kraken. At least for spot, auth is included per req during subscribe
⋮----
// Other event types are automatically emitted here
⋮----
// this.logger.trace(
//   `onWsMessage().emit(${emittable.eventType}).done()`,
//   emittableFinalEvent,
// );
⋮----
private onWsClose(event: unknown, wsKey: TWSKey)
⋮----
// unintentional close, attempt recovery
⋮----
// clean up any pending promises for this connection
⋮----
// this.clearTopicsPendingSubscriptions(wsKey, true, 'WS Closed');
⋮----
// intentional close - clean up
// clean up any pending promises for this connection
⋮----
// This was an intentional close, delete all state for this connection, as if it never existed:
⋮----
private getWs(wsKey: TWSKey)
⋮----
private setWsState(wsKey: TWSKey, state: WsConnectionStateEnum)
⋮----
/**
   * Promise-driven method to assert that a ws has successfully connected (will await until connection is open)
   */
protected async assertIsConnected(wsKey: TWSKey): Promise<unknown>
⋮----
// Already in progress? Await shared promise and retry
⋮----
// Start connection, it should automatically store/return a promise.
⋮----
/**
   * Promise-driven method to assert that a ws has been successfully authenticated (will await until auth is confirmed)
   */
public async assertIsAuthenticated(wsKey: TWSKey): Promise<unknown>
⋮----
// Already in progress? Await shared promise and retry
⋮----
// Start authentication, it should automatically store/return a promise.

================
File: src/lib/requestUtils.ts
================
/**
 * Used to switch how authentication/requests work under the hood
 */
⋮----
/** Spot */
⋮----
/** Futures */
⋮----
/** Futures Demo */
⋮----
/** Institutional */
⋮----
/** Partner */
⋮----
export type RestClientType =
  (typeof REST_CLIENT_TYPE_ENUM)[keyof typeof REST_CLIENT_TYPE_ENUM];
⋮----
export interface RestClientOptions {
  /** Your API key */
  apiKey?: string;

  /** Your API secret */
  apiSecret?: string;

  /**
   * Set to `true` to connect to testnet (Kraken's demo environment). The live environment is used by default.
   *
   * Note: as of November 2025, only the DerivativesClient supports testnet connections. Kraken refer to this as the "Demo" environment, but it is effectively a testnet.
   * This is a place to test your API integration. It is not a good place to test strategy performance, as the liquidity and orderbook dynamics are very different to the live environment.
   *
   * Refer to the following for more information:
   * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/CEX-Testnets
   */
  testnet?: boolean;

  /**
   * Use access token instead of sign, if this is provided.
   * For guidance refer to: https://github.com/tiagosiebler/kucoin-api/issues/2
   */
  apiAccessToken?: string;

  /** Default: false. If true, we'll throw errors if any params are undefined */
  strictParamValidation?: boolean;

  /**
   * Optionally override API protocol + domain
   * e.g baseUrl: 'https://api.kraken.com'
   **/
  baseUrl?: string;

  /** Default: true. whether to try and post-process request exceptions (and throw them). */
  parseExceptions?: boolean;

  customTimestampFn?: () => number;

  /**
   * Enable keep alive for REST API requests (via axios).
   */
  keepAlive?: boolean;

  /**
   * When using HTTP KeepAlive, how often to send TCP KeepAlive packets over sockets being kept alive. Default = 1000.
   * Only relevant if keepAlive is set to true.
   * Default: 1000 (defaults comes from https agent)
   */
  keepAliveMsecs?: number;

  /**
   * Allows you to provide a custom "signMessage" function, e.g. to use node's much faster createHmac method
   *
   * Look in the examples folder for a demonstration on using node's createHmac instead.
   */
  customSignMessageFn?: (message: string, secret: string) => Promise<string>;
}
⋮----
/** Your API key */
⋮----
/** Your API secret */
⋮----
/**
   * Set to `true` to connect to testnet (Kraken's demo environment). The live environment is used by default.
   *
   * Note: as of November 2025, only the DerivativesClient supports testnet connections. Kraken refer to this as the "Demo" environment, but it is effectively a testnet.
   * This is a place to test your API integration. It is not a good place to test strategy performance, as the liquidity and orderbook dynamics are very different to the live environment.
   *
   * Refer to the following for more information:
   * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/CEX-Testnets
   */
⋮----
/**
   * Use access token instead of sign, if this is provided.
   * For guidance refer to: https://github.com/tiagosiebler/kucoin-api/issues/2
   */
⋮----
/** Default: false. If true, we'll throw errors if any params are undefined */
⋮----
/**
   * Optionally override API protocol + domain
   * e.g baseUrl: 'https://api.kraken.com'
   **/
⋮----
/** Default: true. whether to try and post-process request exceptions (and throw them). */
⋮----
/**
   * Enable keep alive for REST API requests (via axios).
   */
⋮----
/**
   * When using HTTP KeepAlive, how often to send TCP KeepAlive packets over sockets being kept alive. Default = 1000.
   * Only relevant if keepAlive is set to true.
   * Default: 1000 (defaults comes from https agent)
   */
⋮----
/**
   * Allows you to provide a custom "signMessage" function, e.g. to use node's much faster createHmac method
   *
   * Look in the examples folder for a demonstration on using node's createHmac instead.
   */
⋮----
export function serializeParams<T extends Record<string, any> | undefined = {}>(
  params: T,
  strict_validation: boolean | undefined,
  encodeValues: boolean,
  prefixWith: string,
  repeatArrayValuesAsKVPairs: boolean,
): string
⋮----
// Only prefix if there's a value
⋮----
export function isEmptyObject(obj: any, acceptStringIfNotEmpty: boolean)
⋮----
export function getRestBaseUrl(
  restClientOptions: RestClientOptions,
  restClientType: RestClientType,
): string

================
File: src/types/websockets/ws-general.ts
================
import { AxiosRequestConfig } from 'axios';
import type { ClientRequestArgs } from 'http';
import WebSocket from 'isomorphic-ws';
⋮----
import { RestClientOptions } from '../../lib/requestUtils.js';
⋮----
/** General configuration for the WebsocketClient */
export interface WSClientConfigurableOptions {
  /** Your API key */
  apiKey?: string;

  /** Your API secret */
  apiSecret?: string;

  /**
   * Set to `true` to connect to testnet (Kraken's demo environment). The live environment is used by default.
   *
   * Note: as of November 2025, only the derivatives environment supports testnet connections. Kraken refer to this as the "Demo" environment, but it is effectively a testnet.
   * This is a place to test your API integration. It is not a good place to test strategy performance, as the liquidity and orderbook dynamics are very different to the live environment.
   *
   * Refer to the following for more information:
   * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/CEX-Testnets
   */
  testnet?: boolean;

  /** Define a recv window when preparing a private websocket signature. This is in milliseconds, so 5000 == 5 seconds */
  recvWindow?: number;

  /** How often to check if the connection is alive */
  pingInterval?: number;

  /** How long to wait for a pong (heartbeat reply) before assuming the connection is dead */
  pongTimeout?: number;

  /** Delay in milliseconds before respawning the connection */
  reconnectTimeout?: number;

  restOptions?: RestClientOptions;
  requestOptions?: AxiosRequestConfig;

  wsOptions?: {
    protocols?: string[];
    agent?: any;
  } & Partial<WebSocket.ClientOptions | ClientRequestArgs>;

  wsUrl?: string;

  /**
   * Allows you to provide a custom "signMessage" function, e.g. to use node's much faster createHmac method
   *
   * Look in the examples folder for a demonstration on using node's createHmac instead.
   */
  customSignMessageFn?: (message: string, secret: string) => Promise<string>;

  /**
   * If you authenticated the WS API before, automatically try to re-authenticate the WS API if you're disconnected/reconnected for any reason.
   */
  reauthWSAPIOnReconnect?: boolean;
}
⋮----
/** Your API key */
⋮----
/** Your API secret */
⋮----
/**
   * Set to `true` to connect to testnet (Kraken's demo environment). The live environment is used by default.
   *
   * Note: as of November 2025, only the derivatives environment supports testnet connections. Kraken refer to this as the "Demo" environment, but it is effectively a testnet.
   * This is a place to test your API integration. It is not a good place to test strategy performance, as the liquidity and orderbook dynamics are very different to the live environment.
   *
   * Refer to the following for more information:
   * https://github.com/tiagosiebler/awesome-crypto-examples/wiki/CEX-Testnets
   */
⋮----
/** Define a recv window when preparing a private websocket signature. This is in milliseconds, so 5000 == 5 seconds */
⋮----
/** How often to check if the connection is alive */
⋮----
/** How long to wait for a pong (heartbeat reply) before assuming the connection is dead */
⋮----
/** Delay in milliseconds before respawning the connection */
⋮----
/**
   * Allows you to provide a custom "signMessage" function, e.g. to use node's much faster createHmac method
   *
   * Look in the examples folder for a demonstration on using node's createHmac instead.
   */
⋮----
/**
   * If you authenticated the WS API before, automatically try to re-authenticate the WS API if you're disconnected/reconnected for any reason.
   */
⋮----
/**
 * WS configuration that's always defined, regardless of user configuration
 * (usually comes from defaults if there's no user-provided values)
 */
export interface WebsocketClientOptions extends WSClientConfigurableOptions {
  pingInterval: number;
  pongTimeout: number;
  reconnectTimeout: number;
  recvWindow: number;

  /**
   * If true, require a "receipt" that the connection is ready for use (e.g. a specific event type)
   */
  requireConnectionReadyConfirmation: boolean;
  authPrivateConnectionsOnConnect: boolean;
  authPrivateRequests: boolean;
  reauthWSAPIOnReconnect: boolean;

  /**
   * Whether to use native WebSocket ping/pong frames for heartbeats
   */
  useNativeHeartbeats: boolean;
}
⋮----
/**
   * If true, require a "receipt" that the connection is ready for use (e.g. a specific event type)
   */
⋮----
/**
   * Whether to use native WebSocket ping/pong frames for heartbeats
   */
⋮----
export type WsMarket = 'spot' | 'futures';
⋮----
export type WsEventInternalSrc = 'event' | 'function' | 'frame';

================
File: src/PartnerClient.ts
================
import { BaseRestClient } from './lib/BaseRestClient.js';
import { REST_CLIENT_TYPE_ENUM, RestClientType } from './lib/requestUtils.js';
import {
  PartnerCancelCustomOrderParams,
  PartnerCreateCustomOrderParams,
  PartnerCreateUserParams,
  PartnerExecuteQuoteParams,
  PartnerGetAssetParams,
  PartnerGetCustomOrderParams,
  PartnerGetEarnSummaryParams,
  PartnerGetPortfolioHistoryParams,
  PartnerGetPortfolioSummaryParams,
  PartnerGetQuoteLimitsParams,
  PartnerGetQuoteParams,
  PartnerGetRampCheckoutUrlParams,
  PartnerGetRampLimitsParams,
  PartnerGetRampProspectiveQuoteParams,
  PartnerGetSettlementReportParams,
  PartnerListAssetRatesParams,
  PartnerListAssetsParams,
  PartnerListCustomOrdersParams,
  PartnerListEarnAssetsParams,
  PartnerListFundingTransactionsParams,
  PartnerListPortfolioDetailsParams,
  PartnerListPortfolioTransactionsParams,
  PartnerListSettlementReportsParams,
  PartnerRequestProspectiveQuoteParams,
  PartnerRequestQuoteParams,
  PartnerSubmitVerificationParams,
  PartnerToggleAutoEarnParams,
  PartnerUpdateUserParams,
  PartnerWithdrawFundsParams,
} from './types/request/partner.types.js';
import {
  PartnerCancelCustomOrderResponse,
  PartnerCreateCustomOrderResponse,
  PartnerCreateUserResponse,
  PartnerExecuteQuoteResponse,
  PartnerGetAssetResponse,
  PartnerGetCustomOrderResponse,
  PartnerGetEarnSummaryResponse,
  PartnerGetPortfolioHistoryResponse,
  PartnerGetPortfolioSummaryResponse,
  PartnerGetQuoteLimitsResponse,
  PartnerGetQuoteResponse,
  PartnerGetRampCheckoutUrlResponse,
  PartnerGetRampLimitsResponse,
  PartnerGetRampProspectiveQuoteResponse,
  PartnerGetSettlementReportResponse,
  PartnerGetUserResponse,
  PartnerListAssetRatesResponse,
  PartnerListAssetsResponse,
  PartnerListCustomOrdersResponse,
  PartnerListEarnAssetsResponse,
  PartnerListFundingTransactionsResponse,
  PartnerListPortfolioDetailsResponse,
  PartnerListPortfolioTransactionsResponse,
  PartnerListRampBuyCryptoAssetsResponse,
  PartnerListRampCountriesResponse,
  PartnerListRampFiatCurrenciesResponse,
  PartnerListRampPaymentMethodsResponse,
  PartnerListSettlementReportsResponse,
  PartnerRequestProspectiveQuoteResponse,
  PartnerRequestQuoteResponse,
  PartnerSubmitVerificationResponse,
  PartnerToggleAutoEarnResponse,
  PartnerUpdateUserResponse,
  PartnerWithdrawFundsResponse,
} from './types/response/partner.types.js';
⋮----
/**
 * The PartnerClient provides integration to the Kraken Partner API.
 *
 * Docs:
 * - https://docs.kraken.com/api/docs/embed-api
 * - https://docs.kraken.com/api/docs/ramp-api
 */
export class PartnerClient extends BaseRestClient
⋮----
getClientType(): RestClientType
⋮----
/**
   *
   * Partner REST API - Embed API - Users
   *
   */
⋮----
/**
   * Create User
   *
   * Create a new user in the Kraken system.
   */
createEmbedUser(
    params: PartnerCreateUserParams,
): Promise<PartnerCreateUserResponse>
⋮----
/**
   * Get User
   *
   * Get a previously created user.
   */
getEmbedUser(params:
⋮----
/**
   * Update User
   *
   * Update an existing user's profile.
   */
updateEmbedUser(
    params: PartnerUpdateUserParams,
): Promise<PartnerUpdateUserResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Verifications
   *
   */
⋮----
/**
   * Submit Verification
   *
   * Submit a verification for a user with documents and details.
   * A verification is defined as a check that has been performed on a user to verify information provided by the user.
   * Note: This endpoint uses multipart/form-data for file uploads.
   */
submitEmbedVerification(
    params: PartnerSubmitVerificationParams,
): Promise<PartnerSubmitVerificationResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Assets
   *
   */
⋮----
/**
   * List Assets
   *
   * List all assets available on the platform.
   * This endpoint returns a list of all assets available on the platform.
   */
listEmbedAssets(
    params?: PartnerListAssetsParams,
): Promise<PartnerListAssetsResponse>
⋮----
/**
   * Get Asset
   *
   * Get information about a specific asset.
   */
getEmbedAsset(
    params: PartnerGetAssetParams,
): Promise<PartnerGetAssetResponse>
⋮----
/**
   * List Asset Rates
   *
   * Returns historical rates for a given asset.
   * This endpoint returns historical rates for a given asset with timestamp and median price for each period.
   */
listEmbedAssetRates(
    params: PartnerListAssetRatesParams,
): Promise<PartnerListAssetRatesResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Quotes
   *
   */
⋮----
/**
   * Request Quote
   *
   * Request a price quote for an asset, that may be used to execute a trade later on.
   */
requestEmbedQuote(
    params: PartnerRequestQuoteParams,
): Promise<PartnerRequestQuoteResponse>
⋮----
/**
   * Get Quote
   *
   * Gets the status of a quote that was previously requested.
   */
getEmbedQuote(
    params: PartnerGetQuoteParams,
): Promise<PartnerGetQuoteResponse>
⋮----
/**
   * Execute Quote
   *
   * Executes a quote that was previously requested.
   */
executeEmbedQuote(
    params: PartnerExecuteQuoteParams,
): Promise<PartnerExecuteQuoteResponse>
⋮----
/**
   * Get Quote Limits (RFQ)
   *
   * Request minimum, maximum and precision for trade using a given asset pair.
   */
getEmbedQuoteLimits(
    params: PartnerGetQuoteLimitsParams,
): Promise<PartnerGetQuoteLimitsResponse>
⋮----
/**
   * Request Prospective Quote (RFQ)
   *
   * Request a prospective quote for an asset pair, to receive an indicative price and fee.
   */
requestEmbedProspectiveQuote(
    params: PartnerRequestProspectiveQuoteParams,
): Promise<PartnerRequestProspectiveQuoteResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Custom Orders
   *
   */
⋮----
/**
   * Create Custom Order
   *
   * Submit a custom order with a specified trigger condition (e.g. price-triggered).
   */
createEmbedCustomOrder(
    params: PartnerCreateCustomOrderParams,
): Promise<PartnerCreateCustomOrderResponse>
⋮----
/**
   * List Custom Orders
   *
   * Get a list of custom orders that were previously submitted.
   */
listEmbedCustomOrders(
    params: PartnerListCustomOrdersParams,
): Promise<PartnerListCustomOrdersResponse>
⋮----
/**
   * Get Custom Order
   *
   * Get a single custom order by ID.
   */
getEmbedCustomOrder(
    params: PartnerGetCustomOrderParams,
): Promise<PartnerGetCustomOrderResponse>
⋮----
/**
   * Cancel Custom Order
   *
   * Cancels a custom order that was previously submitted but not yet completed.
   */
cancelEmbedCustomOrder(
    params: PartnerCancelCustomOrderParams,
): Promise<PartnerCancelCustomOrderResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Portfolios
   *
   */
⋮----
/**
   * Get Portfolio Summary
   *
   * Get the portfolio summary for a user.
   */
getEmbedPortfolioSummary(
    params: PartnerGetPortfolioSummaryParams,
): Promise<PartnerGetPortfolioSummaryResponse>
⋮----
/**
   * Get Portfolio History
   *
   * Gets a portfolio's historical balances and valuations over time.
   * Note: Balance for the last day shows up at UTC + 5h due to processing times.
   */
getEmbedPortfolioHistory(
    params: PartnerGetPortfolioHistoryParams,
): Promise<PartnerGetPortfolioHistoryResponse>
⋮----
/**
   * List Portfolio Details
   *
   * Lists owned assets in a user's portfolio.
   */
listEmbedPortfolioDetails(
    params: PartnerListPortfolioDetailsParams,
): Promise<PartnerListPortfolioDetailsResponse>
⋮----
/**
   * List Portfolio Transactions
   *
   * Lists the user's trades and transactions.
   */
listEmbedPortfolioTransactions(
    params: PartnerListPortfolioTransactionsParams,
): Promise<PartnerListPortfolioTransactionsResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Earn
   *
   */
⋮----
/**
   * Get Earn Summary
   *
   * Get Earn summary of a user.
   * Response holds total amounts (all-time). For per-asset granularity, use listEarnAssets().
   */
getEmbedEarnSummary(
    params: PartnerGetEarnSummaryParams,
): Promise<PartnerGetEarnSummaryResponse>
⋮----
/**
   * List Earn Assets
   *
   * List Earn Assets.
   * The user can optionally be passed in the request, which shows active asset allocations of the user in the response.
   */
listEmbedEarnAssets(
    params?: PartnerListEarnAssetsParams,
): Promise<PartnerListEarnAssetsResponse>
⋮----
/**
   * Toggle Auto-Earn
   *
   * Toggle Auto-Earn of a user.
   * Toggling Auto-Earn is an async operation. The response is empty on success.
   * To fetch the user's current Auto-Earn status, use getEarnSummary().
   */
toggleEmbedAutoEarn(
    params: PartnerToggleAutoEarnParams,
): Promise<PartnerToggleAutoEarnResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Transfers
   *
   */
⋮----
/**
   * Withdraw Funds
   *
   * Withdraw funds.
   * Note: Currently, this is a master-only operation. No User parameter exists.
   */
withdrawEmbedFunds(
    params: PartnerWithdrawFundsParams,
): Promise<PartnerWithdrawFundsResponse>
⋮----
/**
   * List Funding Transactions
   *
   * List Funding transactions.
   * Funding transactions can be of type withdrawal or deposit.
   * Note: Currently, this is a master-only operation. No User parameter exists.
   */
listEmbedFundingTransactions(
    params: PartnerListFundingTransactionsParams,
): Promise<PartnerListFundingTransactionsResponse>
⋮----
/**
   *
   * Partner REST API - Embed API - Reports
   *
   */
⋮----
/**
   * List Settlement Reports
   *
   * Retrieves a paginated list of settlement reports available to the authenticated master user,
   * with optional filters for date range and report type.
   */
listEmbedSettlementReports(
    params?: PartnerListSettlementReportsParams,
): Promise<PartnerListSettlementReportsResponse>
⋮----
/**
   * Get Settlement Report
   *
   * Retrieves a settlement report and provides a secure download URL for the authenticated master user.
   */
getEmbedSettlementReport(
    params: PartnerGetSettlementReportParams,
): Promise<PartnerGetSettlementReportResponse>
⋮----
/**
   *
   * Partner REST API - Ramp API - Supported Options
   *
   */
⋮----
/**
   * List Buy Crypto Assets
   *
   * List cryptocurrency assets available for Ramp buy transactions,
   * including the networks, withdrawal methods, and provider-specific identifiers.
   */
listRampBuyCryptoAssets(): Promise<PartnerListRampBuyCryptoAssetsResponse>
⋮----
/**
   * List Fiat Currencies
   *
   * List fiat currencies supported for funding Ramp transactions.
   */
listRampFiatCurrencies(): Promise<PartnerListRampFiatCurrenciesResponse>
⋮----
/**
   * List Payment Methods
   *
   * List fiat payment methods supported for Ramp deposits,
   * including optional mapping to provider-specific identifiers.
   */
listRampPaymentMethods(): Promise<PartnerListRampPaymentMethodsResponse>
⋮----
/**
   * List Countries
   *
   * List countries and regions where Ramp is available.
   * Depending on regulatory rules, availability may be scoped to specific states, provinces, or regions.
   */
listRampCountries(): Promise<PartnerListRampCountriesResponse>
⋮----
/**
   *
   * Partner REST API - Ramp API - Quotes
   *
   */
⋮----
/**
   * Get Limits
   *
   * Retrieve combined min/max limits for a Ramp transaction configuration.
   */
getRampLimits(
    params: PartnerGetRampLimitsParams,
): Promise<PartnerGetRampLimitsResponse>
⋮----
/**
   * Get Prospective Quote
   *
   * Retrieve a prospective quote for a Ramp transaction without reserving liquidity.
   * Use this to preview spend/receive amounts before creating a checkout URL.
   */
getRampProspectiveQuote(
    params: PartnerGetRampProspectiveQuoteParams,
): Promise<PartnerGetRampProspectiveQuoteResponse>
⋮----
/**
   *
   * Partner REST API - Ramp API - Checkout
   *
   */
⋮----
/**
   * Get Checkout URL
   *
   * Generate a hosted Ramp checkout URL for the provided transaction configuration.
   * The response echoes the request parameters so the Ramp partner can confirm what was submitted.
   */
getRampCheckoutUrl(
    params: PartnerGetRampCheckoutUrlParams,
): Promise<PartnerGetRampCheckoutUrlResponse>

================
File: src/SpotClient.ts
================
import { BaseRestClient } from './lib/BaseRestClient.js';
import { REST_CLIENT_TYPE_ENUM, RestClientType } from './lib/requestUtils.js';
import {
  OauthCreateFastApiKeyParams,
  OauthGetAccessTokenParams,
  OauthUpdateFastApiKeyParams,
  SpotAccountTransferParams,
  SpotAmendOrderParams,
  SpotGetAssetPairsParams,
  SpotGetClosedOrdersParams,
  SpotGetDepositAddressesParams,
  SpotGetDepositMethodsParams,
  SpotGetDepositStatusParams,
  SpotGetLedgersInfoParams,
  SpotGetOHLCParams,
  SpotGetOpenOrdersParams,
  SpotGetOpenPositionsParams,
  SpotGetOrderBookParams,
  SpotGetPostTradeDataParams,
  SpotGetRecentSpreadsParams,
  SpotGetRecentTradesParams,
  SpotGetTradesHistoryParams,
  SpotGetWithdrawalAddressesParams,
  SpotGetWithdrawalInfoParams,
  SpotGetWithdrawalMethodsParams,
  SpotGetWithdrawalsStatusParams,
  SpotListEarnAllocationsParams,
  SpotListEarnStrategiesParams,
  SpotQueryLedgersParams,
  SpotQueryOrdersParams,
  SpotQueryTradesParams,
  SpotRequestExportReportParams,
  SpotSubmitOrderBatchParams,
  SpotSubmitOrderParams,
  SpotWalletTransferParams,
  SpotWithdrawFundsParams,
} from './types/request/spot.types.js';
import { SpotAPISuccessResponse } from './types/response/shared.types.js';
import {
  OauthCreateFastApiKeyResponse,
  OauthFastApiKey,
  OauthGetAccessTokenResponse,
  OauthGetUserInfoResponse,
  SpotAccountBalance,
  SpotAccountTransferResponse,
  SpotAssetInfo,
  SpotAssetPair,
  SpotAssetTickerInfo,
  SpotBatchOrderResult,
  SpotClosedOrdersResponse,
  SpotCreditLines,
  SpotDeleteExportReportResponse,
  SpotDepositAddress,
  SpotDepositMethod,
  SpotDepositStatusResponse,
  SpotEarnStrategy,
  SpotExportReportStatus,
  SpotExtendedBalance,
  SpotLedgersInfoResponse,
  SpotListEarnAllocationsResponse,
  SpotOHLCResponse,
  SpotOpenOrdersResponse,
  SpotOpenPositionsResponse,
  SpotOrderAmendsResponse,
  SpotOrderBookResponse,
  SpotPostTradeDataResponse,
  SpotPreTradeData,
  SpotQueryLedgersResponse,
  SpotQueryOrdersResponse,
  SpotQueryTradesResponse,
  SpotRecentSpreadsResponse,
  SpotRecentTradesResponse,
  SpotRequestExportReportResponse,
  SpotSubmitOrderResponse,
  SpotSystemStatus,
  SpotTradeBalance,
  SpotTradesHistoryResponse,
  SpotTradeVolume,
  SpotWebSocketsTokenResponse,
  SpotWithdrawalAddress,
  SpotWithdrawalInfo,
  SpotWithdrawalMethod,
  SpotWithdrawalStatus,
} from './types/response/spot.types.js';
⋮----
/**
 * The SpotClient provides integration to the Kraken Spot API.
 *
 * Docs:
 * - https://docs.kraken.com/api/docs/guides/spot-rest-intro/
 * - https://docs.kraken.com/api/docs/rest-api/get-server-time
 */
export class SpotClient extends BaseRestClient
⋮----
getClientType(): RestClientType
⋮----
// Points to api.kraken.com
⋮----
/**
   *
   * Misc Utility Methods
   *
   */
⋮----
generateNewOrderID(): string
⋮----
// Generate a short UUID format (32 hex characters without dashes)
// Compatible with Kraken's cl_ord_id parameter
⋮----
/**
   *
   * Spot REST API - Market Data
   *
   */
⋮----
/**
   * Get Server Time
   *
   * Get the server's time.
   */
getServerTime(): Promise<
    SpotAPISuccessResponse<{
      unixtime: number;
      rfc1123: string;
    }>
  > {
    return this.get('0/public/Time');
⋮----
/**
   * Get System Status
   *
   * Get the current system status or trading mode.
   */
getSystemStatus(): Promise<SpotAPISuccessResponse<SpotSystemStatus>>
⋮----
/**
   * Get Asset Info
   *
   * Get information about the assets that are available for deposit, withdrawal, trading and earn.
   */
getAssetInfo(params?: {
    asset?: string;
    aclass?: 'currency' | 'tokenized_asset';
}): Promise<SpotAPISuccessResponse<Record<string, SpotAssetInfo>>>
⋮----
/**
   * Get Tradable Asset Pairs
   *
   * Get tradable asset pairs
   */
getAssetPairs(
    params?: SpotGetAssetPairsParams,
): Promise<SpotAPISuccessResponse<Record<string, SpotAssetPair>>>
⋮----
/**
   * Get Ticker Information
   *
   * Get ticker information for all or requested markets.
   * Note: Today's prices start at midnight UTC.
   * Leaving the pair parameter blank will return tickers for all tradeable assets on Kraken.
   */
getTicker(params?: {
    pair?: string;
    asset_class?: 'tokenized_asset' | 'forex';
}): Promise<SpotAPISuccessResponse<Record<string, SpotAssetTickerInfo>>>
⋮----
/**
   * Get OHLC Data
   *
   * Retrieve OHLC market data. The last entry in the OHLC array is for the current, not-yet-committed timeframe,
   * and will always be present, regardless of the value of since. Returns up to 720 of the most recent entries
   * (older data cannot be retrieved, regardless of the value of since).
   */
getCandles(
    params: SpotGetOHLCParams,
): Promise<SpotAPISuccessResponse<SpotOHLCResponse>>
⋮----
/**
   * Get Order Book
   *
   * Returns level 2 (L2) order book, which describes the individual price levels in the book with aggregated
   * order quantities at each level.
   */
getOrderBook(
    params: SpotGetOrderBookParams,
): Promise<SpotAPISuccessResponse<SpotOrderBookResponse>>
⋮----
/**
   * Get Recent Trades
   *
   * Returns the last 1000 trades by default
   */
getRecentTrades(
    params: SpotGetRecentTradesParams,
): Promise<SpotAPISuccessResponse<SpotRecentTradesResponse>>
⋮----
/**
   * Get Recent Spreads
   *
   * Returns the last ~200 top-of-book spreads for a given pair
   */
getRecentSpreads(
    params: SpotGetRecentSpreadsParams,
): Promise<SpotAPISuccessResponse<SpotRecentSpreadsResponse>>
⋮----
/**
   *
   * Spot REST API - Account Data
   *
   */
⋮----
/**
   * Get Account Balance
   *
   * Retrieve all cash balances, net of pending withdrawals.
   */
getAccountBalance(params?: {
    rebase_multiplier?: 'rebased' | 'base';
}): Promise<SpotAPISuccessResponse<SpotAccountBalance>>
⋮----
/**
   * Get Extended Balance
   *
   * Retrieve all extended account balances, including credits and held amounts.
   * Balance available for trading is calculated as: available balance = balance + credit - credit_used - hold_trade
   */
getExtendedBalance(params?: {
    rebase_multiplier?: 'rebased' | 'base';
}): Promise<SpotAPISuccessResponse<SpotExtendedBalance>>
⋮----
/**
   * Get Credit Lines
   *
   * Retrieve all credit line details for VIPs with this functionality.
   */
getCreditLines(params?: {
    rebase_multiplier?: 'rebased' | 'base';
}): Promise<SpotAPISuccessResponse<SpotCreditLines | null>>
⋮----
/**
   * Get Trade Balance
   *
   * Retrieve a summary of collateral balances, margin position valuations, equity and margin level.
   */
getTradeBalance(params?: {
    rebase_multiplier?: 'rebased' | 'base';
}): Promise<SpotAPISuccessResponse<SpotTradeBalance>>
⋮----
/**
   * Get Open Orders
   *
   * Retrieve information about currently open orders.
   */
getOpenOrders(
    params?: SpotGetOpenOrdersParams,
): Promise<SpotAPISuccessResponse<SpotOpenOrdersResponse>>
⋮----
/**
   * Get Closed Orders
   *
   * Retrieve information about orders that have been closed (filled or cancelled).
   * 50 results are returned at a time, the most recent by default.
   */
getClosedOrders(
    params?: SpotGetClosedOrdersParams,
): Promise<SpotAPISuccessResponse<SpotClosedOrdersResponse>>
⋮----
/**
   * Query Orders Info
   *
   * Retrieve information about specific orders.
   */
getOrders(
    params: SpotQueryOrdersParams,
): Promise<SpotAPISuccessResponse<SpotQueryOrdersResponse>>
⋮----
/**
   * Get Order Amends
   *
   * Retrieves an audit trail of amend transactions on the specified order.
   * The list is ordered by ascending amend timestamp.
   */
getOrderAmends(params: {
    order_id: string;
    rebase_multiplier?: 'rebased' | 'base';
}): Promise<SpotAPISuccessResponse<SpotOrderAmendsResponse>>
⋮----
/**
   * Get Trades History
   *
   * Retrieve information about trades/fills. 50 results are returned at a time, the most recent by default.
   */
getTradesHistory(
    params?: SpotGetTradesHistoryParams,
): Promise<SpotAPISuccessResponse<SpotTradesHistoryResponse>>
⋮----
/**
   * Query Trades Info
   *
   * Retrieve information about specific trades/fills.
   */
getTrades(
    params: SpotQueryTradesParams,
): Promise<SpotAPISuccessResponse<SpotQueryTradesResponse>>
⋮----
/**
   * Get Open Positions
   *
   * Get information about open margin positions.
   */
getOpenPositions(
    params?: SpotGetOpenPositionsParams,
): Promise<SpotAPISuccessResponse<SpotOpenPositionsResponse>>
⋮----
/**
   * Get Ledgers Info
   *
   * Retrieve information about ledger entries. 50 results are returned at a time, the most recent by default.
   */
getLedgersInfo(
    params?: SpotGetLedgersInfoParams,
): Promise<SpotAPISuccessResponse<SpotLedgersInfoResponse>>
⋮----
/**
   * Query Ledgers
   *
   * Retrieve information about specific ledger entries.
   */
getLedgers(
    params: SpotQueryLedgersParams,
): Promise<SpotAPISuccessResponse<SpotQueryLedgersResponse>>
⋮----
/**
   * Get Trade Volume
   *
   * Returns 30 day USD trading volume and resulting fee schedule for any asset pair(s) provided.
   * Also use this endpoint (with a Spot API key) to determine Futures fee rates as of 2026-06-22.
   */
getTradingVolume(params?: {
    pair?: string;
    rebase_multiplier?: 'rebased' | 'base';
}): Promise<SpotAPISuccessResponse<SpotTradeVolume>>
⋮----
/**
   * Request Export Report
   *
   * Request export of trades or ledgers.
   */
requestLedgersExport(
    params: SpotRequestExportReportParams,
): Promise<SpotAPISuccessResponse<SpotRequestExportReportResponse>>
⋮----
/**
   * Get Export Report Status
   *
   * Get status of requested data exports.
   */
getLedgersExportStatus(params: {
    report: 'trades' | 'ledgers';
}): Promise<SpotAPISuccessResponse<SpotExportReportStatus[]>>
⋮----
/**
   * Retrieve Data Export
   *
   * Retrieve a processed data export (binary zip archive).
   */
getLedgersExport(params:
⋮----
/**
   * Delete Export Report
   *
   * Delete or cancel exported trades/ledgers report.
   */
deleteLedgersExport(params: {
    id: string;
    type: 'cancel' | 'delete';
}): Promise<SpotAPISuccessResponse<SpotDeleteExportReportResponse>>
⋮----
/**
   *
   * Spot REST API - Trading
   *
   */
⋮----
/**
   * Add Order
   *
   * Place a new order.
   * Note: See the getAssetPairs() endpoint for details on the available trading pairs, their price and quantity precisions,
   * order minimums, available leverage, etc.
   */
submitOrder(
    params: SpotSubmitOrderParams,
): Promise<SpotAPISuccessResponse<SpotSubmitOrderResponse>>
⋮----
/**
   * Amend Order
   *
   * Amend an existing order. The order identifiers assigned by Kraken and/or client will stay the same.
   * Queue priority in the order book will be maintained where possible.
   */
amendOrder(params: SpotAmendOrderParams): Promise<
    SpotAPISuccessResponse<{
      amend_id: string;
    }>
  > {
    return this.postPrivate('0/private/AmendOrder', {
      body: params,
    });
⋮----
/**
   * Cancel Order
   *
   * Cancel a particular open order (or set of open orders) by txid, userref or cl_ord_id.
   */
cancelOrder(params: { txid?: string | number; cl_ord_id?: string }): Promise<
    SpotAPISuccessResponse<{
      count: number;
      pending?: boolean;
    }>
  > {
    return this.postPrivate('0/private/CancelOrder', {
      body: params,
    });
⋮----
/**
   * Cancel All Orders
   *
   * Cancel all open orders.
   */
cancelAllOrders(): Promise<
    SpotAPISuccessResponse<{
      count: number;
      pending: boolean;
    }>
  > {
return this.postPrivate('0/private/CancelAll',
⋮----
/**
   * Cancel All Orders After X
   *
   * CancelAllOrdersAfter provides a "Dead Man's Switch" mechanism to protect the client from network malfunction,
   * extreme latency or unexpected matching engine downtime. The client can send a request with a timeout (in seconds),
   * that will start a countdown timer which will cancel all client orders when the timer expires.
   */
cancelAllOrdersAfter(params: { timeout: number }): Promise<
    SpotAPISuccessResponse<{
      currentTime: string;
      triggerTime: string;
    }>
  > {
    return this.postPrivate('0/private/CancelAllOrdersAfter', {
      body: params,
    });
⋮----
/**
   * Get Websockets Token
   *
   * An authentication token must be requested via this REST API endpoint in order to connect to and authenticate
   * with the Websockets API. The token should be used within 15 minutes of creation.
   */
getWebSocketsToken(): Promise<
    SpotAPISuccessResponse<SpotWebSocketsTokenResponse>
  > {
return this.postPrivate('0/private/GetWebSocketsToken',
⋮----
/**
   * Add Order Batch
   *
   * Sends a collection of orders (minimum of 2 and maximum 15). All orders in batch are limited to a single pair.
   * Validation is performed on the whole batch prior to submission. If an order fails validation, the whole batch will be rejected.
   */
submitBatchOrders(params: SpotSubmitOrderBatchParams): Promise<
    SpotAPISuccessResponse<{
      orders: SpotBatchOrderResult[];
    }>
  > {
    return this.postPrivate('0/private/AddOrderBatch', {
      body: params,
    });
⋮----
/**
   * Cancel Order Batch
   *
   * Cancel multiple open orders by txid, userref or cl_ord_id (maximum 50 total unique IDs/references).
   */
cancelBatchOrders(params: {
    orders?: Array<string | number>;
    cl_ord_ids?: string[];
  }): Promise<
    SpotAPISuccessResponse<{
      count: number;
    }>
  > {
    return this.postPrivate('0/private/CancelOrderBatch', {
      body: params,
    });
⋮----
/**
   *
   * Spot REST API - Funding
   *
   */
⋮----
/**
   * Get Deposit Methods
   *
   * Retrieve methods available for depositing a particular asset.
   */
getDepositMethods(
    params: SpotGetDepositMethodsParams,
): Promise<SpotAPISuccessResponse<SpotDepositMethod[]>>
⋮----
/**
   * Get Deposit Addresses
   *
   * Retrieve (or generate a new) deposit addresses for a particular asset and method.
   */
getDepositAddresses(
    params: SpotGetDepositAddressesParams,
): Promise<SpotAPISuccessResponse<SpotDepositAddress[]>>
⋮----
/**
   * Get Status of Recent Deposits
   *
   * Retrieve information about recent deposits. Results are sorted by recency.
   */
getDepositsStatus(
    params?: SpotGetDepositStatusParams,
): Promise<SpotAPISuccessResponse<SpotDepositStatusResponse>>
⋮----
/**
   * Get Withdrawal Methods
   *
   * Retrieve a list of withdrawal methods available for the user.
   */
getWithdrawalMethods(
    params?: SpotGetWithdrawalMethodsParams,
): Promise<SpotAPISuccessResponse<SpotWithdrawalMethod[]>>
⋮----
/**
   * Get Withdrawal Addresses
   *
   * Retrieve a list of withdrawal addresses available for the user.
   */
getWithdrawalAddresses(
    params?: SpotGetWithdrawalAddressesParams,
): Promise<SpotAPISuccessResponse<SpotWithdrawalAddress[]>>
⋮----
/**
   * Get Withdrawal Information
   *
   * Retrieve fee information about potential withdrawals for a particular asset, key and amount.
   */
getWithdrawalInfo(
    params: SpotGetWithdrawalInfoParams,
): Promise<SpotAPISuccessResponse<SpotWithdrawalInfo>>
⋮----
/**
   * Withdraw Funds
   *
   * Make a withdrawal request.
   */
submitWithdrawal(params: SpotWithdrawFundsParams): Promise<
    SpotAPISuccessResponse<{
      refid: string;
    }>
  > {
return this.postPrivate('0/private/Withdraw',
⋮----
/**
   * Get Status of Recent Withdrawals
   *
   * Retrieve information about recent withdrawals. Results are sorted by recency.
   */
getWithdrawalsStatus(
    params?: SpotGetWithdrawalsStatusParams,
): Promise<SpotAPISuccessResponse<SpotWithdrawalStatus[]>>
⋮----
/**
   * Request Withdrawal Cancellation
   *
   * Cancel a recently requested withdrawal, if it has not already been successfully processed.
   */
cancelWithdrawal(params: {
    asset: string;
    refid: string;
}): Promise<SpotAPISuccessResponse<boolean>>
⋮----
/**
   * Request Wallet Transfer
   *
   * Transfer from a Kraken spot wallet to a Kraken Futures wallet.
   * Note: Transfer in the other direction must be requested via the Kraken Futures API.
   */
submitTransferToFutures(params: SpotWalletTransferParams): Promise<
    SpotAPISuccessResponse<{
      refid: string;
    }>
  > {
return this.postPrivate('0/private/WalletTransfer',
⋮----
/**
   *
   * Subaccounts
   *
   */
⋮----
/**
   * Create Subaccount
   *
   * Create a trading subaccount.
   * Note: CreateSubaccount must be called using an API key from the master account.
   */
createSubaccount(params: {
    username: string;
    email: string;
}): Promise<SpotAPISuccessResponse<boolean>>
⋮----
/**
   * Account Transfer
   *
   * Transfer funds to and from master and subaccounts.
   * Note: AccountTransfer must be called using an API key from the master account.
   */
submitSubaccountTransfer(
    params: SpotAccountTransferParams,
): Promise<SpotAPISuccessResponse<SpotAccountTransferResponse>>
⋮----
/**
   *
   * Earn
   *
   */
⋮----
/**
   * Allocate Earn Funds
   *
   * Allocate funds to the Strategy.
   * This method is asynchronous. Use getAllocationStatus() to poll the result.
   */
allocateEarnFunds(params: {
    amount: string;
    strategy_id: string;
}): Promise<SpotAPISuccessResponse<boolean>>
⋮----
/**
   * Deallocate Earn Funds
   *
   * Deallocate funds from a strategy.
   * This method is asynchronous. Use getDeallocationStatus() to poll the result.
   */
deallocateEarnFunds(params: {
    amount: string;
    strategy_id: string;
}): Promise<SpotAPISuccessResponse<boolean>>
⋮----
/**
   * Get Allocation Status
   *
   * Get the status of the last allocation request.
   */
getEarnAllocationStatus(params: { strategy_id: string }): Promise<
    SpotAPISuccessResponse<{
      pending: boolean;
    }>
  > {
return this.postPrivate('0/private/Earn/AllocateStatus',
⋮----
/**
   * Get Deallocation Status
   *
   * Get the status of the last deallocation request.
   */
getEarnDeallocationStatus(params: { strategy_id: string }): Promise<
    SpotAPISuccessResponse<{
      pending: boolean;
    }>
  > {
    return this.postPrivate('0/private/Earn/DeallocateStatus', {
      body: params,
    });
⋮----
/**
   * List Earn Strategies
   *
   * List earn strategies along with their parameters.
   * Returns only strategies that are available to the user based on geographic region.
   */
getEarnStrategies(params?: SpotListEarnStrategiesParams): Promise<
    SpotAPISuccessResponse<{
      items: SpotEarnStrategy[];
      next_cursor?: string;
    }>
  > {
return this.postPrivate('0/private/Earn/Strategies',
⋮----
/**
   * List Earn Allocations
   *
   * List all allocations for the user.
   * By default all allocations are returned, even for strategies that have been used in the past and have zero balance now.
   */
getEarnAllocations(
    params?: SpotListEarnAllocationsParams,
): Promise<SpotAPISuccessResponse<SpotListEarnAllocationsResponse>>
⋮----
/**
   *
   * Transparency
   *
   */
⋮----
/**
   * Pre-Trade Data
   *
   * Returns the price levels in the order book with aggregated order quantities at each price level.
   * The top 10 levels are returned for each trading pair.
   */
getPreTradeData(params: {
    symbol: string;
}): Promise<SpotAPISuccessResponse<SpotPreTradeData>>
⋮----
/**
   * Post-Trade Data
   *
   * Returns a list of trades on the spot exchange.
   * If no filter parameters are specified, the last 1000 trades for all pairs are received.
   */
getPostTradeData(
    params?: SpotGetPostTradeDataParams,
): Promise<SpotAPISuccessResponse<SpotPostTradeDataResponse>>
⋮----
/**
   *
   * Spot REST API - OAuth
   *
   */
⋮----
/**
   * Get Access Token
   *
   * Retrieve the access token.
   * Note: This endpoint uses Basic authentication (Authorization header with base64-encoded client credentials).
   */
getOAuthAccessToken(
    params: OauthGetAccessTokenParams,
): Promise<OauthGetAccessTokenResponse>
⋮----
/**
   * Get User Info
   *
   * Returns the email address and IIBAN of the user.
   * Note: Requires OAuth2 Bearer token. Scopes required: account.info:basic
   */
getOAuthUserInfo(): Promise<OauthGetUserInfoResponse>
⋮----
/**
   * Create Fast API Key
   *
   * Creates a Fast API key.
   * Note: Requires OAuth2 Bearer token. Scopes required: account.fast-api-key:write
   */
createOAuthFastApiKey(
    params: OauthCreateFastApiKeyParams,
): Promise<OauthCreateFastApiKeyResponse>
⋮----
/**
   * Delete Fast API Key
   *
   * Deletes a Fast API key.
   * Note: Requires OAuth2 Bearer token. Scopes required: account.fast-api-key:write
   */
deleteOAuthFastApiKey(params: {
    api_key_name: string; // max 32 chars
}): Promise<
⋮----
api_key_name: string; // max 32 chars
⋮----
/**
   * Update Fast API Key
   *
   * Updates a Fast API key.
   * Note: Requires OAuth2 Bearer token. Scopes required: account.fast-api-key:write
   */
updateOAuthFastApiKey(params: OauthUpdateFastApiKeyParams): Promise<
⋮----
/**
   * List Fast API Keys
   *
   * List all Fast API keys.
   * Note: Requires OAuth2 Bearer token. Scopes required: account.fast-api-key:read
   */
listOAuthFastApiKeys(): Promise<

================
File: .gitignore
================
!.gitkeep
.DS_STORE
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
pids
*.pid
*.seed
*.pid.lock
node_modules/
.npm
.eslintcache
.node_repl_history
*.tgz
.yarn-integrity
.env
.env.test
.cache
dist
bundleReport.html
.history/
examples/ignoreme
localtest.sh
repomix.sh
doc

================
File: examples/Derivatives/Private/account.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { DerivativesClient } from '../../../src/index.js';
⋮----
// 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 FUTURES ACCOUNT INFORMATION
⋮----
/**
 * 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',
 * }
 *
 * API Key Permissions Required:
 * - Read access for account information
 * - Withdrawal permissions for transfers
 *
 */
⋮----
async function getWallets()
⋮----
// Get all wallets (cash and margin accounts)
⋮----
// Response includes:
// - cash: Cash account with balances
// - flex: Multi-collateral wallet with margin info
// - Available margin, portfolio value, PnL
// - Initial/maintenance margin requirements
// For each margin account:
//   - balances, auxiliary (pv, pnl, af, funding)
//   - marginRequirements (im, mm, lt, tt)
//   - triggerEstimates
⋮----
async function getOpenPositions()
⋮----
// Get all open Futures positions
⋮----
// Response includes for each position:
// - symbol: Futures symbol
// - side: long or short
// - size: Position size
// - price: Average entry price
// - fillTime: When position was opened
// - unrealizedFunding: Unrealized funding
⋮----
async function getFills()
⋮----
// Get filled orders history (last 100)
⋮----
// Response includes for each fill:
// - fill_id: Unique fill identifier
// - order_id: Associated order ID
// - symbol: Futures symbol
// - side: buy or sell
// - size: Fill size
// - price: Fill price
// - fillTime: Execution time
// - fillType: maker, taker, liquidation, etc.
⋮----
async function getFillsBeforeTime()
⋮----
// Get fills before specific time
⋮----
lastFillTime: new Date(Date.now() - 86400000).toISOString(), // 24h ago
⋮----
// Returns 100 fills before specified time
⋮----
async function initiateWalletTransfer()
⋮----
// Transfer between margin accounts or to/from cash account
⋮----
// Transfers funds between accounts instantly
⋮----
async function initiateWithdrawalToSpot()
⋮----
// Withdraw from Futures to Spot wallet
⋮----
sourceWallet: 'cash', // Default is cash wallet
⋮----
// Response includes:
// - uid: Withdrawal reference ID
⋮----
async function getOrderEvents()
⋮----
// Get order history events
⋮----
sort: 'desc', // desc = newest first
opened: true, // Include opened orders
closed: true, // Include closed orders
⋮----
// Response includes:
// - elements: Array of order events
// - Order placed, cancelled, rejected, executed events
// - continuationToken: For pagination
⋮----
async function getOrderEventsBySymbol()
⋮----
// Filter order events by symbol
⋮----
async function getExecutionEvents()
⋮----
// Get execution/trade history
⋮----
// Response includes for each execution:
// - execution: Fill details (price, quantity, timestamp)
// - order: Associated order details
// - fee: Fee paid
// - positionSize: Position size after execution
⋮----
async function getExecutionEventsBySymbol()
⋮----
// Filter executions by symbol
⋮----
async function getAccountLog()
⋮----
// Get account log (all account activities)
⋮----
// Log includes:
// - futures trade, liquidation, funding rate change
// - conversions, transfers, settlements
// - interest payments, fees
⋮----
async function getAccountLogFiltered()
⋮----
// Filter account log by info types
⋮----
async function enableFuturesSubTrading()
⋮----
async function getSubaccountTradingStatus()
⋮----
async function getSubaccounts()
// Uncomment the function you want to test:
⋮----
// getWallets();
// getOpenPositions();
// getFills();
// getFillsBeforeTime();
// initiateWalletTransfer();
// initiateWithdrawalToSpot();
// getOrderEvents();
// getOrderEventsBySymbol();
// getExecutionEvents();
// getExecutionEventsBySymbol();
// getAccountLog();
// getAccountLogFiltered();
// enableFuturesSubTrading();
// getSubaccountTradingStatus();
// getSubaccounts();

================
File: examples/Spot/WebSockets/privateWs.ts
================
// eslint-disable-next-line @typescript-eslint/no-unused-vars
import {
  DefaultLogger,
  LogParams,
  WebsocketClient,
  WS_KEY_MAP,
  WSTopicRequest,
} from '../../../src/index.js';
import { WSSpotTopic } from '../../../src/types/websockets/ws-subscriptions.js';
// normally you should install this module via npm: `npm install @siebly/kraken-api` and import the module:
// import { LogParams, WebsocketClient, WSTopicRequest } from '@siebly/kraken-api';
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
⋮----
// console.log('trace', ...params);
⋮----
async function start()
⋮----
/**
   * 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.
   */
⋮----
// Data received
⋮----
// Something happened, attempting to reconnect
⋮----
// Reconnect successful
⋮----
// Connection closed. If unexpected, expect reconnect -> reconnected.
⋮----
// Reply to a request, e.g. "subscribe"/"unsubscribe"/"authenticate"
⋮----
/**
   * 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:
   * - Most private topics use "spotPrivateV2" WsKey, which connects to "wss://ws-auth.kraken.com/v2"
   * - The level3 topic uses "spotL3V2" WsKey, which connects to "wss://ws-l3.kraken.com/v2" (dedicated L3 endpoint)
   */
⋮----
// Balances, requires auth: https://docs.kraken.com/api/docs/websocket-v2/executions
⋮----
// below params are optional:
snap_trades: true, // default: false
snap_orders: true, // default: true
order_status: true, // default: true
// rebased: false, // default: true
ratecounter: true, // default: false
// users: 'all', // default: undefined
// snapshot: true, // default: false, deprecated, use 'snap_orders' or 'snap_trades' instead
⋮----
// Balances, requires auth: https://docs.kraken.com/api/docs/websocket-v2/balances
⋮----
// below params are optional:
// snapshot: true, // default: true
// rebased: false, // default: true
// users: 'all',
⋮----
// Orders Level 3, requires auth: https://docs.kraken.com/api/docs/websocket-v2/level3
// Note: level3 uses a dedicated endpoint (wss://ws-l3.kraken.com/v2), so use WS_KEY_MAP.spotL3V2
⋮----
// topic: 'level3',
⋮----
// below params are optional:
// depth: 10, // default: 10, Possible values: [10, 100, 1000]
// snapshot: true, // default: true

================
File: examples/Derivatives/Private/submitOrder.ts
================
/* eslint-disable @typescript-eslint/no-unused-vars */
import { DerivativesClient } from '../../../src/index.js';
⋮----
// 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 FUTURES 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',
 * }
 *
 * API Key Permissions Required: Orders and trades - Create & modify orders
 *
 */
⋮----
async function submitLimitOrder()
⋮----
// Submit limit order for Futures
⋮----
symbol: 'PF_ETHUSD', // Perpetual ETH/USD
⋮----
size: 0.01, // Contract size
⋮----
// Response includes:
// - status: placed, partiallyFilled, filled, or rejection reason
// - order_id: Unique order identifier
// - orderEvents: Array of order events (PLACE, EXECUTE, etc.)
⋮----
async function submitMarketOrder()
⋮----
// Submit market order (IOC with 1% price protection)
⋮----
side: 'sell', // or "buy"
⋮----
async function submitPostOnlyOrder()
⋮----
// Submit post-only order (maker-only)
⋮----
async function submitReduceOnlyOrder()
⋮----
// Submit reduce-only order (only closes position, won't open new)
⋮----
reduceOnly: true, // Only reduce existing position
⋮----
async function batchOrderSubmit()
⋮----
// Send, edit, and cancel orders in a single batch request
⋮----
// Send new order
⋮----
order_tag: 'order-1', // Tag to map responses
⋮----
// Send another order
⋮----
// Response includes batchStatus array with results for each order
// - status: placed, edited, cancelled, or rejection reason
// - order_tag: Maps back to your request
⋮----
// Uncomment the function you want to test:
⋮----
// submitLimitOrder();
// submitMarketOrder();
// submitPostOnlyOrder();
// submitReduceOnlyOrder();
//batchOrderSubmit();

================
File: README.md
================
# Node.js & JavaScript SDK for Kraken REST APIs & WebSockets

[![Build & Test](https://github.com/sieblyio/kraken-api/actions/workflows/e2etest.yml/badge.svg?branch=main)](https://github.com/sieblyio/kraken-api/actions/workflows/e2etest.yml)
[![npm version](https://img.shields.io/npm/v/@siebly/kraken-api)][1]
[![npm size](https://img.shields.io/bundlephobia/min/@siebly/kraken-api/latest)][1]
[![npm downloads](https://img.shields.io/npm/dt/@siebly/kraken-api)][1]
[![last commit](https://img.shields.io/github/last-commit/sieblyio/kraken-api)][1]
[![Telegram](https://img.shields.io/badge/chat-on%20telegram-blue.svg)](https://t.me/nodetraders)

<p align="center">
  <a href="https://www.npmjs.com/package/@siebly/kraken-api">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/sieblyio/kraken-api/blob/main/docs/images/logoDarkMode2.svg?raw=true#gh-dark-mode-only">
      <img alt="SDK Logo" src="https://github.com/sieblyio/kraken-api/blob/main/docs/images/logoBrightMode2.svg?raw=true#gh-light-mode-only">
    </picture>
  </a>
</p>

[1]: https://www.npmjs.com/package/@siebly/kraken-api

Complete & robust JavaScript & Node.js SDK for the Kraken REST APIs and WebSockets:

- Professional, robust & performant Kraken SDK with extensive production use in live trading environments.
- Complete integration with all Kraken REST APIs and WebSockets.
  - Dedicated REST clients for Spot, Derivatives (Futures), Institutional, and Partner operations
  - Unified WebSocket client for all markets
- Complete TypeScript support (with type declarations for most API requests & responses).
  - Strongly typed requests and responses.
  - Automated end-to-end tests ensuring reliability.
- Actively maintained with a modern, promise-driven interface.
- Robust WebSocket integration with configurable connection heartbeats & automatic reconnect then resubscribe workflows.
  - Event driven messaging.
  - Smart WebSocket persistence with automatic reconnection handling.
  - Emit `reconnected` event when dropped connection is restored.
  - Support for both public and private WebSocket streams.
- Browser-friendly HMAC signature mechanism.
- Automatically supports both ESM and CJS projects.
- Heavy automated end-to-end testing with real API calls.
- Proxy support via axios integration.
- Active community support & collaboration in telegram: [Node.js Algo Traders](https://t.me/nodetraders).

## Table of Contents

- [Installation](#installation)
- [Examples](#examples)
- [Issues & Discussion](#issues--discussion)
- [Related Projects](#related-projects)
- [Documentation](#documentation)
- [Structure](#structure)
- [Usage](#usage)
  - [REST API Clients](#rest-api)
    - [Spot Trading](#spot-trading)
    - [Derivatives (Futures) Trading](#derivatives-futures-trading)
  - [WebSockets](#websockets)
    - [Public WebSocket Streams](#public-websocket-streams)
    - [Private WebSocket Streams](#private-websocket-streams)
    - [WebSocket API (WebsocketAPIClient)](#websocket-api-websocketapiclient)
- [Customise Logging](#customise-logging)
- [Browser/Frontend Usage](#browserfrontend-usage)
  - [Webpack](#webpack)
- [LLMs & AI](#use-with-llms--ai)
- [Used By](#used-by)
- [Contributions & Thanks](#contributions--thanks)

## Installation

`npm install --save @siebly/kraken-api`

## Examples

Refer to the [examples](./examples) folder for implementation demos, including:

- **Spot Trading Examples**: market data, account management, order placement
- **Derivatives Trading Examples**: futures market data, account management, order placement
- **WebSocket Examples**: public market data streams, private account data

## Issues & Discussion

- Issues? Check the [issues tab](https://github.com/sieblyio/kraken-api/issues).
- Discuss & collaborate with other node devs? Join our [Node.js Algo Traders](https://t.me/nodetraders) engineering community on telegram.
- Follow our announcement channel for real-time updates on [X/Twitter](https://x.com/sieblyio)

<!-- template_related_projects -->

## Related Projects

Check out our JavaScript/TypeScript/Node.js SDKs & Projects:

- Visit our website: [https://Siebly.io](https://siebly.io/?ref=gh)
- Try our REST API & WebSocket SDKs published on npmjs:
  - [Bybit Node.js SDK: bybit-api](https://www.npmjs.com/package/bybit-api)
  - [Kraken Node.js SDK: @siebly/kraken-api](https://www.npmjs.com/package/@siebly/kraken-api)
  - [OKX Node.js SDK: okx-api](https://www.npmjs.com/package/okx-api)
  - [Binance Node.js SDK: binance](https://www.npmjs.com/package/binance)
  - [Gate (gate.com) Node.js SDK: gateio-api](https://www.npmjs.com/package/gateio-api)
  - [Bitget Node.js SDK: bitget-api](https://www.npmjs.com/package/bitget-api)
  - [Kucoin Node.js SDK: kucoin-api](https://www.npmjs.com/package/kucoin-api)
  - [Coinbase Node.js SDK: coinbase-api](https://www.npmjs.com/package/coinbase-api)
  - [Bitmart Node.js SDK: bitmart-api](https://www.npmjs.com/package/bitmart-api)
- Try my misc utilities:
  - [OrderBooks Node.js: orderbooks](https://www.npmjs.com/package/orderbooks)
  - [Crypto Exchange Account State Cache: accountstate](https://www.npmjs.com/package/accountstate)
- Check out my examples:
  - [awesome-crypto-examples Node.js](https://github.com/tiagosiebler/awesome-crypto-examples)
  <!-- template_related_projects_end -->

## Documentation

Most methods accept JS objects. These can be populated using parameters specified by Kraken's API documentation, or check the type definition in each class within this repository.

### API Documentation Links

- [Kraken API Documentation](https://docs.kraken.com/api/)
  - [Spot Trading API](https://docs.kraken.com/api/docs/rest-api/get-server-time)
  - [Futures Trading API](https://docs.futures.kraken.com/)

## Structure

This project uses typescript. Resources are stored in 2 key structures:

- [src](./src) - the whole connector written in typescript
- [examples](./examples) - some implementation examples & demonstrations. Contributions are welcome!

---

# Usage

Create API credentials on Kraken's website:

- [Kraken API Key Management](https://www.kraken.com/u/security/api)
- [Kraken Futures API Key Management](https://futures.kraken.com/settings/api)

## REST API

The SDK provides dedicated REST clients for different trading products:

- **SpotClient** - for spot trading, staking, and account operations
- **DerivativesClient** - for futures trading operations
- **InstitutionalClient** - for institutional trading and custody
- **PartnerClient** - for partner and affiliate operations

### Spot Trading

To use Kraken's Spot APIs, import (or require) the `SpotClient`:

```javascript
import { SpotClient } from '@siebly/kraken-api';
// or if you prefer require:
// const { SpotClient } = require('@siebly/kraken-api');

// For public endpoints, API credentials are optional
const publicClient = new SpotClient();

// For private endpoints, provide API credentials
const client = new SpotClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-base64-encoded-private-key',
});

// Public API Examples

// Get ticker information
const ticker = await publicClient.getTicker({
  pair: 'XBTUSD',
});
console.log('Ticker: ', ticker);

// Get order book
const orderBook = await publicClient.getOrderBook({
  pair: 'XBTUSD',
  count: 10,
});
console.log('Order Book: ', orderBook);

// Private API Examples (requires authentication)

// Submit a market order
client
  .submitOrder({
    ordertype: 'market',
    type: 'buy',
    volume: '0.01',
    pair: 'XBTUSD',
    cl_ord_id: client.generateNewOrderID(),
  })
  .then((result) => {
    console.log('Market Order Result: ', result);
  })
  .catch((err) => {
    console.error('Error: ', err);
  });

// Submit a limit order
client
  .submitOrder({
    ordertype: 'limit',
    type: 'buy',
    volume: '0.0001',
    pair: 'XBTUSD',
    price: '10000',
    cl_ord_id: client.generateNewOrderID(),
  })
  .then((result) => {
    console.log('Limit Order Result: ', result);
  })
  .catch((err) => {
    console.error('Error: ', err);
  });

// Submit batch of orders (minimum 2, maximum 15)
client
  .submitBatchOrders({
    pair: 'XBTUSD',
    orders: [
      {
        ordertype: 'limit',
        type: 'buy',
        volume: '0.0001',
        price: '10000.00',
        timeinforce: 'GTC',
        cl_ord_id: client.generateNewOrderID(),
      },
      {
        ordertype: 'limit',
        type: 'buy',
        volume: '0.0001',
        price: '11111.00',
        timeinforce: 'GTC',
        cl_ord_id: client.generateNewOrderID(),
      },
      {
        ordertype: 'limit',
        type: 'sell',
        volume: '0.0001',
        price: '13000.00',
        timeinforce: 'GTC',
        cl_ord_id: client.generateNewOrderID(),
      },
    ],
  })
  .then((result) => {
    console.log('Batch Order Result: ', JSON.stringify(result, null, 2));
  })
  .catch((err) => {
    console.error('Error: ', err);
  });

// Get account balances
client
  .getAccountBalance()
  .then((balance) => {
    console.log('Account Balance: ', balance);
  })
  .catch((err) => {
    console.error('Error: ', err);
  });
```

See [SpotClient](./src/SpotClient.ts) for further information, or the [examples](./examples/) for lots of usage examples.

### Derivatives (Futures) Trading

Use the `DerivativesClient` for futures trading operations:

```javascript
import { DerivativesClient } from '@siebly/kraken-api';
// or if you prefer require:
// const { DerivativesClient } = require('@siebly/kraken-api');

// For public endpoints, API credentials are optional
const publicClient = new DerivativesClient();

// For private endpoints, provide API credentials
const client = new DerivativesClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
});

// Public API Examples

// Get order book for a specific instrument
const orderBook = await publicClient.getOrderBook({
  symbol: 'PF_XBTUSD',
});
console.log('Futures Order Book: ', orderBook);

// Get ticker information
const ticker = await publicClient.getTickers({
  symbol: 'PF_XBTUSD',
});
console.log('Futures Ticker: ', ticker);

// Private API Examples (requires authentication)

// Get account balances
client
  .getAccountsDetails()
  .then((accounts) => {
    console.log('Accounts Details: ', accounts);
  })
  .catch((err) => {
    console.error('Error: ', err);
  });

// Submit a limit order
client
  .submitOrder({
    orderType: 'lmt',
    symbol: 'PF_ETHUSD', // Perpetual ETH/USD
    side: 'buy',
    size: 0.01, // Contract size
    limitPrice: 1000,
    cliOrdId: client.generateNewOrderID(),
  })
  .then((result) => {
    console.log('Limit Order Result: ', JSON.stringify(result, null, 2));
  })
  .catch((err) => {
    console.error('Error: ', err);
  });
```

See [DerivativesClient](./src/DerivativesClient.ts) for further information.

## WebSockets

Kraken supports two types of WebSocket connections:

1. **WebSocket Subscriptions** - Real-time market data and account updates via the `WebsocketClient`
2. **WebSocket API** - REST-like request/response trading via the `WebsocketAPIClient`

### WebSocket Subscriptions (WebsocketClient)

The unified `WebsocketClient` handles all Kraken WebSocket streams with automatic connection management and reconnection.

Key WebSocket features:

- Event driven messaging
- Smart WebSocket persistence with automatic reconnection
- Heartbeat mechanisms to detect disconnections
- Automatic resubscription after reconnection
- Support for both Spot and Futures markets
- Support for both public and private WebSocket streams

### Public WebSocket Streams

For public market data, API credentials are not required:

```javascript
import { WebsocketClient } from '@siebly/kraken-api';
// or if you prefer require:
// const { WebsocketClient } = require('@siebly/kraken-api');
// Create WebSocket client for public streams
const wsClient = new WebsocketClient();

// Set up event handlers
wsClient.on('open', (data) => {
  console.log('WebSocket connected: ', data?.wsKey);
});

wsClient.on('message', (data) => {
  console.log('Data received: ', JSON.stringify(data, null, 2));
});

wsClient.on('reconnected', (data) => {
  console.log('WebSocket reconnected: ', data);
});

wsClient.on('exception', (data) => {
  console.error('WebSocket error: ', data);
});

// Spot - Subscribe to public data streams
wsClient.subscribe(
  {
    topic: 'ticker',
    payload: {
      symbol: ['BTC/USD', 'ETH/USD'],
    },
  },
  'spotPublicV2',
);

wsClient.subscribe(
  {
    topic: 'book',
    payload: {
      symbol: ['BTC/USD'],
      depth: 10,
    },
  },
  'spotPublicV2',
);

// Derivatives - Subscribe to public data streams
wsClient.subscribe(
  {
    topic: 'ticker',
    payload: {
      product_ids: ['PI_XBTUSD', 'PI_ETHUSD'],
    },
  },
  'derivativesPublicV1',
);

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

### Private WebSocket Streams

For private account data streams, API credentials are required:

```javascript
import { WebsocketClient } from '@siebly/kraken-api';

// Create WebSocket client with API credentials for private streams
const wsClient = new WebsocketClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
});

// Set up event handlers
wsClient.on('open', (data) => {
  console.log('Private WebSocket connected: ', data?.wsKey);
});

wsClient.on('message', (data) => {
  console.log('Private data received: ', JSON.stringify(data, null, 2));
});

wsClient.on('authenticated', (data) => {
  console.log('WebSocket authenticated: ', data);
});

wsClient.on('response', (data) => {
  console.log('WebSocket response: ', data);
});

wsClient.on('exception', (data) => {
  console.error('WebSocket error: ', data);
});

// Spot - Subscribe to private data streams
wsClient.subscribe(
  {
    topic: 'executions',
    payload: {
      snap_trades: true,
      snap_orders: true,
      order_status: true,
    },
  },
  'spotPrivateV2',
);

wsClient.subscribe(
  {
    topic: 'balances',
    payload: {
      snapshot: true,
    },
  },
  'spotPrivateV2',
);

// Derivatives - Subscribe to private data streams
// Note: SDK automatically handles authentication and challenge tokens
wsClient.subscribe('open_orders', 'derivativesPrivateV1');

wsClient.subscribe(
  {
    topic: 'fills',
    payload: {
      product_ids: ['PF_XBTUSD'],
    },
  },
  'derivativesPrivateV1',
);

wsClient.subscribe('balances', 'derivativesPrivateV1');

wsClient.subscribe('open_positions', 'derivativesPrivateV1');
```

For more comprehensive examples, including custom logging and error handling, check the [examples](./examples/WebSockets) folder.

### WebSocket API (WebsocketAPIClient)

The `WebsocketAPIClient` provides a REST-like interface for trading operations over WebSocket, offering lower latency than REST APIs. Currently, only Spot trading is supported.

```javascript
import { WebsocketAPIClient } from '@siebly/kraken-api';

// Create WebSocket API client with credentials
const wsApiClient = new WebsocketAPIClient({
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
});

// The client handles event listeners automatically, but you can customize them
wsApiClient
  .getWSClient()
  .on('open', (data) => {
    console.log('WebSocket API connected:', data.wsKey);
  })
  .on('response', (data) => {
    console.log('Response:', data);
  })
  .on('exception', (data) => {
    console.error('Error:', data);
  });

// Trading operations return promises

// Submit a spot order
const orderResponse = await wsApiClient.submitSpotOrder({
  order_type: 'limit',
  side: 'buy',
  limit_price: 26500.4,
  order_qty: 1.2,
  symbol: 'BTC/USD',
});
console.log('Order placed:', orderResponse);

// Amend an existing order
const amendResponse = await wsApiClient.amendSpotOrder({
  order_id: 'OAIYAU-LGI3M-PFM5VW',
  order_qty: 1.5,
  limit_price: 27000,
});

// Cancel specific orders
const cancelResponse = await wsApiClient.cancelSpotOrder({
  order_id: ['OM5CRX-N2HAL-GFGWE9', 'OLUMT4-UTEGU-ZYM7E9'],
});

// Cancel all open orders
const cancelAllResponse = await wsApiClient.cancelAllSpotOrders();
```

The WebSocket API provides several advantages:

- **Lower Latency** - Faster than REST API for high-frequency trading
- **Connection Reuse** - Single persistent connection for multiple requests
- **Better Performance** - Batch operations for submitting/canceling multiple orders
- **Type Safety** - Full TypeScript support with typed requests and responses

See the [WebSocket API examples](./examples/WebSockets/Spot/wsAPI.ts) for more detailed usage.

---

## Customise Logging

Pass a custom logger which supports the log methods `trace`, `info` and `error`, or override methods from the default logger as desired.

```javascript
import { WebsocketClient, DefaultLogger } from '@siebly/kraken-api';

// E.g. customise logging for only the trace level:
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);
  },
};

const ws = new WebsocketClient(
  {
    apiKey: 'apiKeyHere',
    apiSecret: 'apiSecretHere',
  },
  customLogger,
);
```

## Browser/Frontend Usage

### Webpack

Build a bundle using webpack:

- `npm install`
- `npm run build`
- `npm run pack`

The bundle can be found in `dist/`. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.

## Use with LLMs & AI

This SDK includes a bundled `llms.txt` file in the root of the repository. If you're developing with LLMs, use the included `llms.txt` with your LLM - it will significantly improve the LLMs understanding of how to correctly use this SDK.

This file contains AI optimised structure of all the functions in this package, and their parameters for easier use with any learning models or artificial intelligence.

---

## Used By

[![Repository Users Preview Image](https://dependents.info/sieblyio/kraken-api/image)](https://github.com/sieblyio/kraken-api/network/dependents)

---

<!-- template_contributions -->

### Contributions & Thanks

Have my projects helped you? Share the love, there are many ways you can show your thanks:

- Star & share my projects.
- Are my projects useful? Sponsor me on Github and support my effort to maintain & improve them: https://github.com/sponsors/tiagosiebler
- Have an interesting project? Get in touch & invite me to it.
- Or buy me all the coffee:
  - ETH(ERC20): `0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C` <!-- metamask -->
- Sign up with my referral links:
  - OKX (receive a 20% fee discount!): https://www.okx.com/join/42013004
  - Binance (receive a 20% fee discount!): https://accounts.binance.com/register?ref=OKFFGIJJ
  - HyperLiquid (receive a 4% fee discount!): https://app.hyperliquid.xyz/join/SDK
  - Gate: https://www.gate.io/signup/NODESDKS?ref_type=103

<!---
old ones:
  - BTC: `1C6GWZL1XW3jrjpPTS863XtZiXL1aTK7Jk`
  - BTC(SegWit): `bc1ql64wr9z3khp2gy7dqlmqw7cp6h0lcusz0zjtls`
  - ETH(ERC20): `0xe0bbbc805e0e83341fadc210d6202f4022e50992`
  - USDT(TRC20): `TA18VUywcNEM9ahh3TTWF3sFpt9rkLnnQa
  - gate: https://www.gate.io/signup/AVNNU1WK?ref_type=103

-->
<!-- template_contributions_end -->

### Contributions & Pull Requests

Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.

<!-- template_star_history -->

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=tiagosiebler/bybit-api,tiagosiebler/okx-api,tiagosiebler/binance,tiagosiebler/bitget-api,tiagosiebler/bitmart-api,tiagosiebler/gateio-api,tiagosiebler/kucoin-api,tiagosiebler/coinbase-api,tiagosiebler/orderbooks,tiagosiebler/accountstate,tiagosiebler/awesome-crypto-examples&type=Date)](https://star-history.com/#tiagosiebler/bybit-api&tiagosiebler/okx-api&tiagosiebler/binance&tiagosiebler/bitget-api&tiagosiebler/bitmart-api&tiagosiebler/gateio-api&tiagosiebler/kucoin-api&tiagosiebler/coinbase-api&tiagosiebler/orderbooks&tiagosiebler/accountstate&tiagosiebler/awesome-crypto-examples&Date)

<!-- template_star_history_end -->

================
File: src/WebsocketClient.ts
================
import {
  BaseWebsocketClient,
  EmittableEvent,
  MidflightWsRequestEvent,
} from './lib/BaseWSClient.js';
import { neverGuard } from './lib/misc-util.js';
import { RestClientOptions } from './lib/requestUtils.js';
import {
  hashMessage,
  SignAlgorithm,
  SignEncodeMethod,
  signMessage,
  SignMessageOptions,
} from './lib/webCryptoAPI.js';
import { DefaultLogger } from './lib/websocket/logger.js';
import { RestClientCache } from './lib/websocket/rest-client-cache.js';
import {
  getPromiseRefForWSAPIRequest,
  WS_KEY_MAP,
  WsKey,
  WSOperation,
  WSRequestOperationKraken,
  WSTopicRequest,
} from './lib/websocket/websocket-util.js';
import { WSConnectedResult } from './lib/websocket/WsStore.types.js';
import {
  Exact,
  WS_API_Operations,
  WSAPIAuthenticationRequestFromServer,
  WSAPIRequestOperationKrakenSpot,
  WSAPITopicRequestParamMap,
  WSAPITopicResponseMap,
  WSAPIWsKey,
  WSAPIWsKeyTopicMap,
} from './types/websockets/ws-api.js';
import { MessageEventLike } from './types/websockets/ws-events.js';
import {
  WSClientConfigurableOptions,
  WsMarket,
} from './types/websockets/ws-general.js';
import {
  WS_DERIVATIVES_PRIVATE_TOPICS,
  WS_SPOT_PRIVATE_TOPICS,
  WSTopic,
} from './types/websockets/ws-subscriptions.js';
⋮----
export interface WSAPIRequestFlags {
  /** If true, will skip auth requirement for WS API connection */
  authIsOptional?: boolean | undefined;
}
⋮----
/** If true, will skip auth requirement for WS API connection */
⋮----
export class WebsocketClient extends BaseWebsocketClient<WsKey, any>
⋮----
constructor(options?: WSClientConfigurableOptions, logger?: DefaultLogger)
⋮----
/**
   * Request connection of all dependent (public & private) websockets, instead of waiting for automatic connection by library.
   *
   * Returns array of promises that individually resolve when each connection is successfully opened.
   */
public connectAll(): Promise<WSConnectedResult | undefined>[]
⋮----
/**
   * Ensures the WS API connection is active and ready.
   *
   * You do not need to call this, but if you call this before making any WS API requests,
   * it can accelerate the first request (by preparing the connection in advance).
   */
public connectWSAPI(wsKey: WSAPIWsKey, skipAuth?: boolean): Promise<unknown>
⋮----
/** This call automatically ensures the connection is active AND authenticated before resolving */
⋮----
/**
   * Request subscription to one or more topics. Pass topics as either an array of strings, or array of objects (if the topic has parameters).
   * Objects should be formatted as {topic: string, params: object}.
   *
   * - Subscriptions are automatically routed to the correct websocket connection.
   * - Authentication/connection is automatic.
   * - Resubscribe after network issues is automatic.
   *
   * Call `unsubscribe(topics)` to remove topics
   */
public subscribe(
    requests:
      | (WSTopicRequest<WSTopic> | WSTopic)
      | (WSTopicRequest<WSTopic> | WSTopic)[],
    wsKey: WsKey,
)
⋮----
/**
   * Unsubscribe from one or more topics. Similar to subscribe() but in reverse.
   *
   * - Requests are automatically routed to the correct websocket connection.
   * - These topics will be removed from the topic cache, so they won't be subscribed to again.
   */
public unsubscribe(
    requests:
      | (WSTopicRequest<WSTopic> | WSTopic)
      | (WSTopicRequest<WSTopic> | WSTopic)[],
    wsKey: WsKey,
)
⋮----
/**
   * WS API Methods - similar to the REST API, but via WebSockets
   */
⋮----
/**
   * Send a Websocket API event on a connection. Returns a promise that resolves on reply.
   *
   * Returned promise is rejected if an exception is detected in the reply OR the connection disconnects for any reason (even if automatic reconnect will happen).
   *
   * After a fresh connection, you should always send a login request first.
   *
   * If you authenticated once and you're reconnected later (e.g. connection temporarily lost), the SDK will by default automatically:
   * - Detect you were authenticated to the WS API before
   * - Try to re-authenticate (up to 5 times, in case something (bad timestamp) goes wrong)
   * - If it succeeds, it will emit the 'authenticated' event.
   * - If it fails and gives up, it will emit an 'exception' event (type: 'wsapi.auth', reason: detailed text).
   *
   * You can turn off the automatic re-auth WS API logic using `reauthWSAPIOnReconnect: false` in the WSClient config.
   *
   * @param wsKey - The connection this event is for (e.g. "spotV4" | "perpFuturesUSDTV4" | "perpFuturesBTCV4" | "deliveryFuturesUSDTV4" | "deliveryFuturesBTCV4" | "optionsV4")
   * @param channel - The channel this event is for (e.g. "spot.login" to authenticate)
   * @param params - Any request parameters for the payload (contents of req_param in the docs). Signature generation is automatic, only send parameters such as order ID as per the docs.
   * @returns Promise - tries to resolve with async WS API response. Rejects if disconnected or exception is seen in async WS API response
   */
⋮----
// This overload allows the caller to omit the 3rd param, if it isn't required (e.g. for the login call)
async sendWSAPIRequest<
    TWSKey extends keyof WSAPIWsKeyTopicMap,
    TWSOperation extends WSAPIWsKeyTopicMap[TWSKey],
    TWSParams extends Exact<WSAPITopicRequestParamMap[TWSOperation]>,
    TWSAPIResponse extends
      | WSAPITopicResponseMap[TWSOperation]
      | object = WSAPITopicResponseMap[TWSOperation],
  >(
    wsKey: TWSKey,
    operation: TWSOperation,
    params?: TWSParams extends void | never ? undefined : TWSParams,
    requestFlags?: WSAPIRequestFlags,
  ): Promise<TWSAPIResponse>;
⋮----
async sendWSAPIRequest<
    TWSKey extends keyof WSAPIWsKeyTopicMap,
    TWSOperation extends WSAPIWsKeyTopicMap[TWSKey],
    // if this throws a type error, probably forgot to add a new operation to WsAPITopicRequestParamMap
    TWSParams extends Exact<WSAPITopicRequestParamMap[TWSOperation]>,
    TWSAPIResponse extends
      | WSAPITopicResponseMap[TWSOperation]
      | object = WSAPITopicResponseMap[TWSOperation],
  >(
    wsKey: TWSKey,
    operation: TWSOperation,
    params: TWSParams & { signRequest?: boolean },
    requestFlags?: WSAPIRequestFlags,
): Promise<TWSAPIResponse | any>
⋮----
// if this throws a type error, probably forgot to add a new operation to WsAPITopicRequestParamMap
⋮----
/**
     * Base Info:
     * - https://docs.kraken.com/api/docs/websocket-v2/add_order
     *
     * Currently only supported for Spot markets
     */
⋮----
// Some commands don't require authentication.
⋮----
// Sign request
⋮----
// Store deferred promise
⋮----
// Enrich returned promise with request context for easier debugging
⋮----
// Send event
⋮----
// Return deferred promise, so caller can await this call
⋮----
/**
   *
   * Internal methods - not intended for public use
   *
   */
⋮----
private getRestClientOptions(): RestClientOptions
⋮----
/**
   * Note: implementing this method will wipe the WsStore state for this WsKey, once this method returns
   */
protected isCustomReconnectionNeeded(): boolean
⋮----
protected async triggerCustomReconnectionWorkflow(): Promise<void>
⋮----
protected async getWsUrl(wsKey: WsKey): Promise<string>
⋮----
/**
       * https://docs.kraken.com/api/docs/guides/spot-ws-intro/
       *
       * Note: Kraken's v2 WebSockets clean up a number idiosyncrasies and ambiguities from v1 with the overall aim to enable easier integration with applications. It is intended that v1 will be maintained but future enhancements will be developed in v2.
       *
       * Given the above, we are only integrating with V2 for now.
       *
       * V2 SpotWebSocket Reference: https://docs.kraken.com/api/docs/websocket-v2/add_order/
       */
⋮----
// Uses the same URL, but we maintain separate connections for easier management
⋮----
protected sendPingEvent(wsKey: WsKey)
⋮----
// let pingChannel: WsRequestPing['channel'];
⋮----
// Spot: https://docs.kraken.com/api/docs/websocket-v2/ping
⋮----
protected sendPongEvent(wsKey: WsKey)
⋮----
// Send a protocol layer pong
⋮----
// NOT IN USE for kraken
// eslint-disable-next-line @typescript-eslint/no-unused-vars
protected isWsPing(_msg: any): boolean
⋮----
protected isWsPong(msg: any): boolean
⋮----
// Pre-parsed in resolveEmittableEvents into "pong" eventType:
⋮----
/**
   * Parse incoming events into categories, before emitting to the user
   */
protected resolveEmittableEvents(
    wsKey: WsKey,
    event: MessageEventLike,
): EmittableEvent[]
⋮----
// derivatives sends 'challenge' on successful auth-init (used for sign during subscribe)
⋮----
// spot confirmation for subscription success
⋮----
// derivatives confirmation for subscription success
⋮----
// WS API
⋮----
// WS API Exception
⋮----
// WS API Success
⋮----
} // end of WS API response processing
⋮----
// exceptions with derivatives v1 WS. E.g. { event: 'alert', message: 'Bad websocket message' }
⋮----
// Most events use event: "update" or "snapshot" for topic updates
⋮----
// These are request/reply pattern events (e.g. after subscribing to topics or authenticating)
// e.g. "method":"subscribe"
⋮----
// derivatives events include the "feed" property to identify the channel name
⋮----
// Request/reply pattern for authentication success
⋮----
/**
   * Determines if a topic is for a private channel, using a hardcoded list of strings
   */
protected isPrivateTopicRequest(request: WSTopicRequest<any>): boolean
⋮----
/**
   * Not in use for Kraken
   */
⋮----
// eslint-disable-next-line @typescript-eslint/no-unused-vars
protected getWsMarketForWsKey(_wsKey: WsKey): WsMarket
⋮----
/**
   * Whether key represents a private connection. Feeds into automatic auth on connect.
   */
protected getPrivateWSKeys(): WsKey[]
⋮----
protected isAuthOnConnectWsKey(wsKey: WsKey): boolean
⋮----
/** Force subscription requests to be sent in smaller batches, if a number is returned */
// eslint-disable-next-line @typescript-eslint/no-unused-vars
protected getMaxTopicsPerSubscribeEvent(_wsKey: WsKey): number | null
⋮----
protected authPrivateConnectionsOnConnect(wsKey: WsKey): boolean
⋮----
// derivatives require you to send a challenge on connect
⋮----
/**
   * @returns one or more correctly structured request events for performing a operations over WS. This can vary per exchange spec.
   */
protected async getWsRequestEvents(
    wsKey: WsKey,
    operation: WSOperation,
    requests: WSTopicRequest<WSTopic>[],
): Promise<MidflightWsRequestEvent<WSRequestOperationKraken<string>>[]>
⋮----
// Previously used to track topics in a request. Keeping this for subscribe/unsubscribe requests, no need for incremental values
⋮----
// Get token from REST client cache
⋮----
// Cache midflight subs on the req ID
// Enrich response with subs for that req ID
⋮----
// No auth needed, it's public topics only here
⋮----
// Cache midflight subs on the req ID
// Enrich response with subs for that req ID
⋮----
// https://docs.kraken.com/api/docs/guides/futures-websockets
// Authenticated requests must include both the original challenge message (original_challenge) and the signed (signed_challenge) in JSON format.
⋮----
// Cache midflight subs on the req ID
// Enrich response with subs for that req ID
⋮----
private async signMessage(
    paramsStr: string,
    secret: string,
    method: SignEncodeMethod,
    algorithm: SignAlgorithm,
    options?: SignMessageOptions,
): Promise<string>
⋮----
protected async getWsAuthRequestEvent(
    wsKey: WsKey,
    eventToAuth?: WSAPIAuthenticationRequestFromServer,
): Promise<object | string | 'waitForEvent' | void>
⋮----
// Not needed here, handled automatically with request during subscribe
⋮----
// Public WS - no auth
⋮----
// cleanup old challenge key (in case we were reconnected)
⋮----
// https://docs.kraken.com/api/docs/futures-api/websocket/challenge/
⋮----
/**
   *
   * @param requestEvent
   * @returns A signed updated WS API request object, ready to be sent
   */
private async signWSAPIRequest(
    requestEvent: WSAPIRequestOperationKrakenSpot,
): Promise<WSAPIRequestOperationKrakenSpot>
⋮----
// Get token from REST client cache
⋮----
// authParams.broker = APIIDMain;

================
File: src/DerivativesClient.ts
================
import { nanoid } from 'nanoid';
⋮----
import { BaseRestClient } from './lib/BaseRestClient.js';
import { REST_CLIENT_TYPE_ENUM, RestClientType } from './lib/requestUtils.js';
import {
  FuturesAddAssignmentPreferenceParams,
  FuturesBatchOrderParams,
  FuturesCancelOrderParams,
  FuturesEditOrderParams,
  FuturesGetAccountLogParams,
  FuturesGetAnalyticsParams,
  FuturesGetCandlesParams,
  FuturesGetOrderEventsParams,
  FuturesGetPositionEventsParams,
  FuturesGetTriggerEventsParams,
  FuturesHistoryBaseParams,
  FuturesInitiateSubaccountTransferParams,
  FuturesInitiateWalletTransferParams,
  FuturesMarketHistoryBaseParams,
  FuturesSendOrderParams,
  FuturesSubmitToSpotParams,
  FuturesUpdateSelfTradeStrategyParams,
} from './types/request/derivatives.types.js';
import {
  FuturesAccountLog,
  FuturesAccounts,
  FuturesAnalyticsResponse,
  FuturesApiKeyV3Check,
  FuturesAssignmentProgram,
  FuturesAssignmentProgramHistory,
  FuturesBatchOrderStatus,
  FuturesCancelAllOrdersStatus,
  FuturesCancelOrderStatus,
  FuturesCandles,
  FuturesDeadMansSwitchStatus,
  FuturesEditOrderStatus,
  FuturesFeeSchedule,
  FuturesFill,
  FuturesHistoricalFundingRate,
  FuturesHistoryExecutionEvent,
  FuturesHistoryOrderEvent,
  FuturesHistoryResponse,
  FuturesHistoryTriggerEvent,
  FuturesInstrument,
  FuturesInstrumentStatus,
  FuturesLeveragePreference,
  FuturesMarketHistoryResponse,
  FuturesMarketShare,
  FuturesNotification,
  FuturesOpenOffer,
  FuturesOpenOrder,
  FuturesOpenPosition,
  FuturesOrderBook,
  FuturesOrderStatusInfo,
  FuturesPnlPreference,
  FuturesPortfolioMarginParameters,
  FuturesPortfolioSimulation,
  FuturesPositionUpdateEvent,
  FuturesPublicExecutionEvent,
  FuturesPublicMarkPriceEvent,
  FuturesPublicOrderEvent,
  FuturesResolution,
  FuturesRfq,
  FuturesSelfTradeStrategy,
  FuturesSendOrderStatus,
  FuturesSubaccountsInfo,
  FuturesTicker,
  FuturesTickType,
  FuturesTradeHistoryItem,
  FuturesUnwindQueuePosition,
} from './types/response/derivatives.types.js';
import { DerivativesAPISuccessResponse } from './types/response/shared.types.js';
⋮----
/**
 * The DerivativesClient provides integration to the Kraken Derivatives API.
 *
 * Docs:
 * - https://docs.kraken.com/api/docs/guides/futures-introduction
 * - https://docs.kraken.com/api/docs/guides/futures-rest
 * - https://docs.kraken.com/api/docs/futures-api/trading/get-history
 */
export class DerivativesClient extends BaseRestClient
⋮----
getClientType(): RestClientType
⋮----
/**
   *
   * Misc Utility Methods
   *
   */
⋮----
generateNewOrderID(): string
⋮----
/**
   *
   * Futures REST API - Trading - Market Data
   *
   */
⋮----
/**
   * Get trade history
   *
   * This endpoint returns the most recent 100 trades prior to the specified lastTime value up to past 7 days or recent trading engine restart (whichever is sooner).
   * If no lastTime specified, it will return 100 most recent trades.
   */
getTradeHistory(params: {
    symbol: string;
    lastTime?: string;
  }): Promise<
    DerivativesAPISuccessResponse<{ history: FuturesTradeHistoryItem[] }>
  > {
    return this.get('derivatives/api/v3/history', params);
⋮----
/**
   * Get orderbook
   *
   * This endpoint returns the entire non-cumulative order book of currently listed Futures contracts.
   */
getOrderbook(params: {
    symbol: string;
}): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   * Get tickers
   *
   * This endpoint returns current market data for all currently listed Futures contracts and indices.
   */
getTickers(): Promise<
    DerivativesAPISuccessResponse<{ tickers: FuturesTicker[] }>
  > {
    return this.get('derivatives/api/v3/tickers');
⋮----
/**
   * Get ticker by symbol
   *
   * Get market data for contract or index by symbol.
   */
getTicker(params: {
    symbol: string;
}): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   *
   * Futures REST API - Trading - Instrument Details
   *
   */
⋮----
/**
   * Get instruments
   *
   * Returns specifications for all currently listed markets and indices.
   */
getInstruments(): Promise<
    DerivativesAPISuccessResponse<{ instruments: FuturesInstrument[] }>
  > {
    return this.get('derivatives/api/v3/instruments');
⋮----
/**
   * Get instrument status list
   *
   * Returns price dislocation and volatility details for all markets.
   */
getInstrumentStatusList(): Promise<
    DerivativesAPISuccessResponse<{
      instrumentStatus: FuturesInstrumentStatus[];
    }>
  > {
    return this.get('derivatives/api/v3/instruments/status');
⋮----
/**
   * Get instrument status
   *
   * Returns price dislocation and volatility details for given market.
   */
getInstrumentStatus(params: {
    symbol: string;
}): Promise<DerivativesAPISuccessResponse<FuturesInstrumentStatus>>
⋮----
/**
   *
   * Futures REST API - Trading - Order Management
   *
   */
⋮----
/**
   * Batch order management
   *
   * This endpoint allows sending limit or stop order(s) and/or cancelling open order(s) and/or editing open order(s) for a currently listed Futures contract in batch.
   * When editing an order, if the trailingStopMaxDeviation and trailingStopDeviationUnit parameters are sent unchanged, the system will recalculate a new stop price upon successful order modification.
   */
batchOrderManagement(
    params: FuturesBatchOrderParams,
  ): Promise<
    DerivativesAPISuccessResponse<{ batchStatus: FuturesBatchOrderStatus[] }>
  > {
    const { ProcessBefore, json } = params;
    return this.postPrivate('derivatives/api/v3/batchorder', {
      body: {
        ProcessBefore: ProcessBefore,
        json,
      },
    });
⋮----
/**
   * Cancel all orders
   *
   * This endpoint allows cancelling orders which are associated with a future's contract or a margin account. If no arguments are specified all open orders will be cancelled.
   */
cancelAllOrders(params?: { symbol?: string }): Promise<
    DerivativesAPISuccessResponse<{
      cancelStatus: FuturesCancelAllOrdersStatus;
    }>
  > {
    return this.postPrivate('derivatives/api/v3/cancelallorders', {
      body: params,
    });
⋮----
/**
   * Dead man's switch
   *
   * This endpoint provides a Dead Man's Switch mechanism to protect the user from network malfunctions. The user can send a request with a timeout in seconds which will trigger a countdown timer that will cancel all user orders when timeout expires. The user has to keep sending request to push back the timeout expiration or they can deactivate the mechanism by specifying a timeout of zero (0).
   * The recommended mechanism usage is making a call every 15 to 20 seconds and provide a timeout of 60 seconds. This allows the user to keep the orders in place on a brief network failure, while keeping them safe in case of a network breakdown.
   */
cancelAllOrdersAfter(params: {
    timeout: number;
  }): Promise<
    DerivativesAPISuccessResponse<{ status: FuturesDeadMansSwitchStatus }>
  > {
    return this.postPrivate('derivatives/api/v3/cancelallordersafter', {
      body: params,
    });
⋮----
/**
   * Cancel order
   *
   * This endpoint allows cancelling an open order for a Futures contract.
   */
cancelOrder(
    params: FuturesCancelOrderParams,
  ): Promise<
    DerivativesAPISuccessResponse<{ cancelStatus: FuturesCancelOrderStatus }>
  > {
    return this.postPrivate('derivatives/api/v3/cancelorder', {
      body: params,
    });
⋮----
/**
   * Edit order
   *
   * This endpoint allows editing an existing order for a currently listed Futures contract.
   * When editing an order, if the trailingStopMaxDeviation and trailingStopDeviationUnit parameters are sent unchanged, the system will recalculate a new stop price upon successful order modification.
   */
editOrder(
    params: FuturesEditOrderParams,
  ): Promise<
    DerivativesAPISuccessResponse<{ editStatus: FuturesEditOrderStatus }>
  > {
    return this.postPrivate('derivatives/api/v3/editorder', {
      body: params,
    });
⋮----
/**
   * Get open orders
   *
   * This endpoint returns information on all open orders for all Futures contracts.
   */
getOpenOrders(): Promise<
    DerivativesAPISuccessResponse<{ openOrders: FuturesOpenOrder[] }>
  > {
    return this.getPrivate('derivatives/api/v3/openorders');
⋮----
/**
   * Send order
   *
   * This endpoint allows sending a limit, stop, take profit or immediate-or-cancel order for a currently listed Futures contract.
   */
submitOrder(
    params: FuturesSendOrderParams,
  ): Promise<
    DerivativesAPISuccessResponse<{ sendStatus: FuturesSendOrderStatus }>
  > {
    return this.postPrivate('derivatives/api/v3/sendorder', {
      body: params,
    });
⋮----
/**
   * Get Specific Orders' Status
   *
   * Returns information on specified orders which are open or were filled/cancelled in the last 5 seconds.
   */
getOrderStatus(params?: {
    orderIds?: string[];
    cliOrdIds?: string[];
  }): Promise<
    DerivativesAPISuccessResponse<{ orders: FuturesOrderStatusInfo[] }>
  > {
    return this.postPrivate('derivatives/api/v3/orders/status', {
      body: params,
    });
⋮----
/**
   *
   * Futures REST API - Trading - Multi-Collateral
   *
   */
⋮----
/**
   * Get PNL currency preferences
   *
   * The PNL currency preference is used to determine which currency to pay out when realizing PNL gains.
   */
getPnlPreferences(): Promise<
    DerivativesAPISuccessResponse<{ preferences: FuturesPnlPreference[] }>
  > {
    return this.getPrivate('derivatives/api/v3/pnlpreferences');
⋮----
/**
   * Set PNL currency preference
   *
   * The PNL currency preference is used to determine which currency to pay out when realizing PNL gains.
   * Calling this API can result in the following error codes: 87 (Contract does not exist), 88 (Contract not a multi-collateral futures contract), 89 (Currency does not exist), 90 (Currency is not enabled for multi-collateral futures), 41 (Would cause liquidation).
   */
setPnlPreference(params: {
    symbol: string;
    pnlPreference: string;
}): Promise<DerivativesAPISuccessResponse<Record<string, never>>>
⋮----
/**
   * Get leverage settings
   *
   * Returns list of configured leverage preferences.
   */
getLeverageSettings(): Promise<
    DerivativesAPISuccessResponse<{
      leveragePreferences: FuturesLeveragePreference[];
    }>
  > {
    return this.getPrivate('derivatives/api/v3/leveragepreferences');
⋮----
/**
   * Set leverage settings
   *
   * Sets a contract's margin mode, either "isolated" or "cross" margin.
   * When specifying a max leverage, the contract's margin mode will be isolated.
   */
setLeverageSettings(params: {
    symbol: string;
    maxLeverage?: number;
}): Promise<DerivativesAPISuccessResponse<Record<string, never>>>
⋮----
/**
   *
   * Futures REST API - Trading - Account Information
   *
   */
⋮----
/**
   * Get wallets
   *
   * This endpoint returns key information relating to all your accounts which may either be cash accounts or margin accounts.
   * This includes digital asset balances, instrument balances, margin requirements, margin trigger estimates and
   * auxiliary information such as available funds, PnL of open positions and portfolio value.
   */
getAccounts(): Promise<
    DerivativesAPISuccessResponse<{ accounts: FuturesAccounts }>
  > {
    return this.getPrivate('derivatives/api/v3/accounts');
⋮----
/**
   * Get open positions
   *
   * This endpoint returns the size and average entry price of all open positions in Futures contracts.
   * This includes Futures contracts that have matured but have not yet been settled.
   */
getOpenPositions(): Promise<
    DerivativesAPISuccessResponse<{ openPositions: FuturesOpenPosition[] }>
  > {
    return this.getPrivate('derivatives/api/v3/openpositions');
⋮----
/**
   * Get position percentile of unwind queue
   *
   * This endpoint returns the percentile of the open position in case of unwinding.
   */
getPositionPercentile(): Promise<
    DerivativesAPISuccessResponse<{ queue: FuturesUnwindQueuePosition[] }>
  > {
    return this.getPrivate('derivatives/api/v3/unwindqueue');
⋮----
/**
   * Get portfolio margin parameters
   *
   * Retrieve current portfolio margin calculation parameters.
   * Also includes user specific limits related to options trading.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
getPortfolioMarginParameters(): Promise<
    DerivativesAPISuccessResponse<FuturesPortfolioMarginParameters>
  > {
    return this.getPrivate('derivatives/api/v3/portfolio-margining/parameters');
⋮----
/**
   * Calculate portfolio margin, pnl and greeks
   *
   * For a given portfolio of balances and positions (futures and options), calculate the margin requirements, pnl and option greeks.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
simulateMarginRequirements(params: {
    json: any; // Complex structure for portfolio simulation
}): Promise<DerivativesAPISuccessResponse<FuturesPortfolioSimulation>>
⋮----
json: any; // Complex structure for portfolio simulation
⋮----
/**
   *
   * Futures REST API - Trading - Assignment Program
   *
   */
⋮----
/**
   * List assignment programs
   *
   * This endpoint returns information on currently active assignment programs.
   */
getAssignmentPrograms(): Promise<
    DerivativesAPISuccessResponse<{ participants: FuturesAssignmentProgram[] }>
  > {
    return this.getPrivate('derivatives/api/v3/assignmentprogram/current');
⋮----
/**
   * Add assignment preference
   *
   * This endpoint adds an assignment program preference.
   */
addAssignmentPreference(
    params: FuturesAddAssignmentPreferenceParams,
): Promise<DerivativesAPISuccessResponse<FuturesAssignmentProgram>>
⋮----
/**
   * Delete assignment preference
   *
   * This endpoint deletes an assignment program preference.
   */
deleteAssignmentPreference(params: {
    id: number;
}): Promise<DerivativesAPISuccessResponse<FuturesAssignmentProgram>>
⋮----
/**
   * List assignment preferences history
   *
   * This endpoint returns information on assignment program preferences change history.
   */
getAssignmentPreferencesHistory(): Promise<
    DerivativesAPISuccessResponse<{
      participants: FuturesAssignmentProgramHistory[];
    }>
  > {
    return this.getPrivate('derivatives/api/v3/assignmentprogram/history');
⋮----
/**
   *
   * Futures REST API - Trading - Fee Schedules
   *
   */
⋮----
/**
   * Get fee schedules
   *
   * This endpoint lists all fee schedules.
   *
   * @deprecated Effective 2026-06-22. Use SpotClient.getTradingVolume() with a Spot API key instead.
   */
getFeeSchedules(): Promise<
    DerivativesAPISuccessResponse<{ feeSchedules: FuturesFeeSchedule[] }>
  > {
    return this.get('derivatives/api/v3/feeschedules');
⋮----
/**
   * Get fee schedule volumes
   *
   * Returns your fee schedule volumes for each fee schedule.
   *
   * @deprecated Effective 2026-06-22. Use SpotClient.getTradingVolume() with a Spot API key instead.
   */
getFeeScheduleVolumes(): Promise<
    DerivativesAPISuccessResponse<{
      volumesByFeeSchedule: Record<string, number>;
    }>
  > {
    return this.getPrivate('derivatives/api/v3/feeschedules/volumes');
⋮----
/**
   *
   * Futures REST API - Trading - General
   *
   */
⋮----
/**
   * Get notifications
   *
   * This endpoint provides the platform's notifications.
   */
getNotifications(): Promise<
    DerivativesAPISuccessResponse<{ notifications: FuturesNotification[] }>
  > {
    return this.getPrivate('derivatives/api/v3/notifications');
⋮----
/**
   *
   * Futures REST API - Trading - Historical Data
   *
   */
⋮----
/**
   * Get your fills
   *
   * This endpoint returns information on your filled orders for all futures contracts.
   */
getFills(params?: {
    lastFillTime?: string;
}): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   *
   * Futures REST API - Trading - Historical Funding Rates
   *
   */
⋮----
/**
   * Historical funding rates
   *
   * Returns list of historical funding rates for given market.
   */
getHistoricalFundingRates(params: {
    symbol: string;
  }): Promise<
    DerivativesAPISuccessResponse<{ rates: FuturesHistoricalFundingRate[] }>
  > {
    return this.get('derivatives/api/v3/historical-funding-rates', params);
⋮----
/**
   *
   * Futures REST API - Trading - Trading Settings
   *
   */
⋮----
/**
   * Get self trade strategy
   *
   * Returns account-wide self-trade matching strategy.
   */
getSelfTradeStrategy(): Promise<
    DerivativesAPISuccessResponse<{
      strategy: FuturesSelfTradeStrategy;
    }>
  > {
    return this.getPrivate('derivatives/api/v3/self-trade-strategy');
⋮----
/**
   * Update self trade strategy
   *
   * Updates account-wide self-trade matching behavior to given strategy.
   */
updateSelfTradeStrategy(
    params: FuturesUpdateSelfTradeStrategyParams,
  ): Promise<
    DerivativesAPISuccessResponse<{
      strategy: FuturesSelfTradeStrategy;
    }>
  > {
    return this.putPrivate('derivatives/api/v3/self-trade-strategy', {
      query: params,
    });
⋮----
/**
   *
   * Futures REST API - Trading - Subaccounts
   *
   */
⋮----
/**
   * Check subaccount trading status
   *
   * Returns trading capability info for given subaccount.
   */
getSubaccountTradingStatus(params: {
    subaccountUid: string;
}): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   * Update subaccount trading status
   *
   * Updates trading capabilities for given subaccount.
   */
updateSubaccountTradingStatus(params: {
    subaccountUid: string;
    tradingEnabled: boolean;
}): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   * Get subaccounts
   *
   * Return information about subaccounts, including balances and UIDs.
   */
getSubaccounts(): Promise<
    DerivativesAPISuccessResponse<FuturesSubaccountsInfo>
  > {
    return this.getPrivate('derivatives/api/v3/subaccounts');
⋮----
/**
   *
   * Futures REST API - Trading - Transfers
   *
   */
⋮----
/**
   * Initiate wallet transfer
   *
   * This endpoint allows you to transfer funds between two margin accounts with the same collateral currency, or between a margin account and your cash account.
   */
submitWalletTransfer(
    params: FuturesInitiateWalletTransferParams,
): Promise<DerivativesAPISuccessResponse<Record<string, never>>>
⋮----
/**
   * Initiate sub account transfer
   *
   * This endpoint allows you to transfer funds between the current account and a sub account, between two margin accounts with the same collateral currency, or between a margin account and your cash account.
   */
submitSubaccountTransfer(
    params: FuturesInitiateSubaccountTransferParams,
): Promise<DerivativesAPISuccessResponse<Record<string, never>>>
⋮----
/**
   * Initiate withdrawal to Spot wallet
   *
   * This endpoint allows you to request to withdraw digital assets to your Kraken Spot wallet.
   * Wallet names can be found in the 'accounts' structure in the Get Wallets /accounts response.
   */
submitTransferToSpot(
    params: FuturesSubmitToSpotParams,
): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   *
   * Futures REST API - Trading - RFQs
   *
   */
⋮----
/**
   * List all open RFQs
   *
   * Retrieve all currently open RFQs.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
getOpenRFQs(): Promise<
    DerivativesAPISuccessResponse<{ rfqs: FuturesRfq[] }>
  > {
    return this.get('derivatives/api/v3/rfqs');
⋮----
/**
   * Retrieve a single open RFQ
   *
   * Retrieve a specific open RFQ by its unique identifier.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
getOpenRFQ(params: {
    rfqUid: string;
}): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   * List open offers on open RFQs
   *
   * Retrieve all open offers for the account on currently open RFQs.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
getRFQOpenOffers(): Promise<
    DerivativesAPISuccessResponse<{ openOffers: FuturesOpenOffer[] }>
  > {
    return this.getPrivate('derivatives/api/v3/rfqs/open-offers');
⋮----
/**
   * Place new offer on an open RFQ
   *
   * Place a new offer for the given amount in USD on the specified open RFQ, bid and ask are optional but at least one must be provided.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
submitRFQNewOffer(params: {
    rfqUid: string;
    bid?: number;
    ask?: number;
}): Promise<DerivativesAPISuccessResponse<
⋮----
/**
   * Replace open offer on open RFQ
   *
   * Replace the current open offer on the specified open RFQ, bid and ask are optional but at least one must be provided.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
updateRFQOpenOffer(params: {
    rfqUid: string;
    bid?: number;
    ask?: number;
}): Promise<DerivativesAPISuccessResponse<Record<string, never>>>
⋮----
/**
   * Cancel open offer on open RFQ
   *
   * Cancel the current open offer on the specified open RFQ.
   * Note: This is currently available exclusively in the Kraken Futures DEMO environment.
   */
cancelRFQOffer(params: {
    rfqUid: string;
}): Promise<DerivativesAPISuccessResponse<Record<string, never>>>
⋮----
/**
   *
   * Futures REST API - History - Account History
   *
   */
⋮----
/**
   * Get execution events
   *
   * Lists executions/trades for authenticated account.
   */
getExecutionEvents(
    params?: FuturesHistoryBaseParams,
  ): Promise<
    DerivativesAPISuccessResponse<
      FuturesHistoryResponse<FuturesHistoryExecutionEvent>
    >
  > {
    return this.getPrivate('api/history/v3/executions', params);
⋮----
/**
   * Get order events
   *
   * Lists order events for authenticated account.
   */
getOrderEvents(
    params?: FuturesGetOrderEventsParams,
  ): Promise<
    DerivativesAPISuccessResponse<
      FuturesHistoryResponse<FuturesHistoryOrderEvent>
    >
  > {
    return this.getPrivate('api/history/v3/orders', params);
⋮----
/**
   * Get trigger events
   *
   * Lists trigger events for authenticated account.
   */
getTriggerEvents(
    params?: FuturesGetTriggerEventsParams,
  ): Promise<
    DerivativesAPISuccessResponse<
      FuturesHistoryResponse<FuturesHistoryTriggerEvent>
    >
  > {
    return this.getPrivate('api/history/v3/triggers', params);
⋮----
/**
   * Get position update events
   *
   * Lists position events for authenticated account.
   */
getPositionEvents(
    params?: FuturesGetPositionEventsParams,
  ): Promise<
    DerivativesAPISuccessResponse<
      FuturesHistoryResponse<FuturesPositionUpdateEvent>
    >
  > {
    return this.getPrivate('api/history/v3/positions', params);
⋮----
/**
   * Get account log
   *
   * Lists account log entries, paged by timestamp or by ID.
   * To request entries by time range, use the since and before parameters. To request entries by ID range, use the from and to parameters. Any combination of since, before, from and to can be used to restrict the requested range of entries.
   */
getAccountLog(
    params?: FuturesGetAccountLogParams,
): Promise<DerivativesAPISuccessResponse<FuturesAccountLog>>
⋮----
/**
   * Account log (CSV)
   *
   * Lists recent account log entries in CSV format.
   */
getAccountLogCsv(params?:
⋮----
/**
   *
   * Futures REST API - History - Market History
   *
   */
⋮----
/**
   * Get public execution events
   *
   * Lists trades for a market.
   */
getPublicExecutionEvents(
    params: FuturesMarketHistoryBaseParams,
): Promise<FuturesMarketHistoryResponse<FuturesPublicExecutionEvent>>
⋮----
/**
   * Get public order events
   *
   * Lists order events for a market.
   */
getPublicOrderEvents(
    params: FuturesMarketHistoryBaseParams,
): Promise<FuturesMarketHistoryResponse<FuturesPublicOrderEvent>>
⋮----
/**
   * Get public mark price events
   *
   * Lists price events for a market.
   */
getPublicMarkPriceEvents(
    params: FuturesMarketHistoryBaseParams,
): Promise<FuturesMarketHistoryResponse<FuturesPublicMarkPriceEvent>>
⋮----
/**
   *
   * Futures REST API - Charts - Candles
   *
   */
⋮----
/**
   * Tick Types
   *
   * Returns all available tick types to use with the getMarketsForTickType() endpoint.
   */
getTickTypes(): Promise<FuturesTickType[]>
⋮----
/**
   * Markets
   *
   * Markets available for specified tick type.
   * List of available tick types can be fetched from the getTickTypes() endpoint.
   */
getMarketsForTickType(params: {
    tickType: FuturesTickType;
}): Promise<string[]>
⋮----
/**
   * Resolutions
   *
   * Candle resolutions available for specified tick type and market.
   * List of available tick types can be fetched from the getTickTypes() endpoint.
   * List of available markets can be fetched from the getMarketsForTickType() endpoint.
   */
getResolutions(params: {
    tickType: FuturesTickType;
    symbol: string;
}): Promise<FuturesResolution[]>
⋮----
/**
   * Market Candles
   *
   * Candles for specified tick type, market, and resolution.
   * List of available tick types can be fetched from the getTickTypes() endpoint.
   * List of available markets can be fetched from the getMarketsForTickType() endpoint.
   * List of available resolutions can be fetched from the getResolutions() endpoint.
   */
getCandles(params: FuturesGetCandlesParams): Promise<FuturesCandles>
⋮----
/**
   *
   * Futures REST API - Charts - Analytics
   *
   */
⋮----
/**
   * Get liquidity pool statistic
   *
   * Get liquidity pool statistic including usd value.
   */
getLiquidityPoolStatistic(
    params: FuturesGetAnalyticsParams,
): Promise<FuturesAnalyticsResponse>
⋮----
/**
   * Market Analytics
   *
   * Analytics data divided into time buckets.
   */
getMarketAnalytics(
    params: FuturesGetAnalyticsParams,
): Promise<FuturesAnalyticsResponse>
⋮----
/**
   *
   * Futures REST API - Auth - API Keys
   *
   */
⋮----
/**
   * Check v3 API key
   *
   * Verify API key access and return the authenticated key's details.
   */
checkApiKeyV3(): Promise<FuturesApiKeyV3Check>
⋮----
/**
   *
   * Futures REST API - Stats - Market Share
   *
   */
⋮----
/**
   * Get account's market share
   *
   * Get account's market share, volumes, and accrued rebates data in contracts configured for rebates.
   * The data may not be available immediately. In these cases HTTP 204 is returned.
   */
getAccountMarketShare(): Promise<FuturesMarketShare>

================
File: package.json
================
{
  "name": "@siebly/kraken-api",
  "version": "1.0.6",
  "description": "Complete & robust Node.js SDK for Kraken's REST APIs and WebSockets, with TypeScript & strong end to end tests.",
  "scripts": {
    "clean": "rm -rf dist",
    "build": "npm run clean && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && bash ./postBuild.sh",
    "pack": "webpack --config webpack/webpack.config.cjs",
    "test": "jest --passWithNoTests",
    "lint": "eslint src"
  },
  "main": "dist/cjs/index.js",
  "module": "dist/mjs/index.js",
  "types": "dist/mjs/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/mjs/index.js",
      "require": "./dist/cjs/index.js",
      "types": "./dist/mjs/index.d.ts"
    }
  },
  "type": "module",
  "files": [
    "dist/*",
    "llms.txt"
  ],
  "author": "Siebly.io (https://github.com/sieblyio)",
  "contributors": [
    "Tiago Siebler (https://github.com/tiagosiebler)",
    "Jerko J (https://github.com/JJ-Cro)"
  ],
  "dependencies": {
    "axios": "^1.10.0",
    "isomorphic-ws": "^5.0.0",
    "nanoid": "^3.3.11",
    "ws": "^8.18.3"
  },
  "devDependencies": {
    "@types/jest": "^29.5.12",
    "@types/node": "^22.11.6",
    "@types/ws": "^8.18.1",
    "@typescript-eslint/eslint-plugin": "^8.18.0",
    "@typescript-eslint/parser": "^8.18.0",
    "eslint": "^8.29.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.1.3",
    "eslint-plugin-require-extensions": "^0.1.3",
    "eslint-plugin-simple-import-sort": "^12.1.1",
    "jest": "^29.7.0",
    "prettier": "^3.3.3",
    "ts-jest": "^29.2.4",
    "ts-node": "^10.9.2",
    "typescript": "^5.7.3",
    "webpack": "^5.0.0",
    "webpack-cli": "^4.0.0",
    "webpack-bundle-analyzer": "^4.10.2"
  },
  "keywords": [
    "kraken",
    "kraken api",
    "kraken nodejs",
    "kraken javascript",
    "kraken typescript",
    "kraken websocket api",
    "kraken websocket api javascript",
    "algo trading",
    "api",
    "websocket",
    "rest",
    "rest api",
    "usdt",
    "trading bots",
    "nodejs",
    "node",
    "trading",
    "cryptocurrency",
    "bitcoin",
    "best"
  ],
  "funding": {
    "type": "individual",
    "url": "https://github.com/sponsors/tiagosiebler"
  },
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/sieblyio/kraken-api"
  },
  "bugs": {
    "url": "https://github.com/sieblyio/kraken-api/issues"
  },
  "homepage": "https://github.com/sieblyio/kraken-api#readme"
}

================
File: src/lib/BaseRestClient.ts
================
import axios, { AxiosRequestConfig, AxiosResponse, Method } from 'axios';
// NOTE: https.Agent is Node.js-only and not available in browser environments
// Browser builds (via webpack) exclude this module - see webpack.config.js fallback settings
import https from 'https';
⋮----
import { neverGuard } from './misc-util.js';
import {
  APIIDMain,
  APIIDMainKey,
  getRestBaseUrl,
  isEmptyObject,
  REST_CLIENT_TYPE_ENUM,
  RestClientOptions,
  RestClientType,
  serializeParams,
} from './requestUtils.js';
import {
  checkWebCryptoAPISupported,
  hashMessage,
  SignAlgorithm,
  SignEncodeMethod,
  signMessage,
  SignMessageOptions,
} from './webCryptoAPI.js';
⋮----
interface SignedRequest<
  T extends object | undefined = {},
  TReqData = object,
  TReqQuery = object,
> {
  originalParams: T;
  paramsWithSign?: T & { sign: string };
  // all request params intended for request body (e.g. POST)
  requestData?: TReqData;
  // all params intended for request query string (e.g. GET)
  requestQuery?: TReqQuery;
  serializedParams: string;
  sign: string;
  queryParamsWithSign: string;
  timestamp: number;
  recvWindow: number;
}
⋮----
// all request params intended for request body (e.g. POST)
⋮----
// all params intended for request query string (e.g. GET)
⋮----
interface UnsignedRequest<T extends object | undefined = {}> {
  originalParams: T;
  paramsWithSign: T;
  queryParamsWithSign: undefined;
}
⋮----
type SignMethod = 'kraken';
⋮----
/**
 * Some requests require some params to be in the query string and some in the body. Some even support passing params via headers.
 * This type anticipates these are possible in any combination.
 *
 * The request builder will automatically handle where parameters should go.
 */
type ParamsInQueryBodyOrHeader = {
  query?: object;
  body?: object;
  headers?: object;
};
⋮----
// request: {
//   url: response.config.url,
//   method: response.config.method,
//   data: response.config.data,
//   headers: response.config.headers,
// },
⋮----
/**
 * Impure, mutates params to remove any values that have a key but are undefined.
 */
function deleteUndefinedValues(params?: any): void
⋮----
export abstract class BaseRestClient
⋮----
// A unique incrementing nonce
⋮----
/** Defines the client type (affecting how requests & signatures behave) */
abstract getClientType(): RestClientType;
⋮----
/**
   * Create an instance of the REST client. Pass API credentials in the object in the first parameter.
   * @param {RestClientOptions} [restClientOptions={}] options to configure REST API connectivity
   * @param {AxiosRequestConfig} [networkOptions={}] HTTP networking options for axios
   */
constructor(
    restClientOptions: RestClientOptions = {},
    networkOptions: AxiosRequestConfig = {},
)
⋮----
/** Throw errors if any request params are empty */
⋮----
/** in ms == 5 minutes by default */
⋮----
/** inject custom request options based on axios specs - see axios docs for more guidance on AxiosRequestConfig: https://github.com/axios/axios#request-config */
⋮----
// If enabled, configure a https agent with keepAlive enabled
// NOTE: This is Node.js-only functionality. In browser environments, this code is skipped
// as the 'https' module is excluded via webpack fallback configuration.
// Browser connection pooling is handled automatically by the browser itself.
⋮----
// Extract existing https agent parameters, if provided, to prevent the keepAlive flag from overwriting an existing https agent completely
⋮----
// For more advanced configuration, raise an issue on GitHub or use the "networkOptions"
// parameter to define a custom httpsAgent with the desired properties
⋮----
// Check Web Crypto API support when credentials are provided
⋮----
// Throw if one of the 3 values is missing, but at least one of them is set
⋮----
/**
   * Generates a timestamp for signing API requests.
   *
   * This method can be overridden or customized using `customTimestampFn`
   * to implement a custom timestamp synchronization mechanism.
   * If no custom function is provided, it defaults to the current system time.
   */
private getSignTimestampMs(): number
⋮----
private getNextRequestNonce(): string
⋮----
private hasValidCredentials()
⋮----
setAccessToken(newAccessToken: string)
⋮----
hasAccessToken(): boolean
⋮----
protected get(endpoint: string, params?: object)
⋮----
// GET only supports params in the query string
⋮----
protected post(endpoint: string, params?: ParamsInQueryBodyOrHeader)
⋮----
protected getPrivate(endpoint: string, params?: object)
⋮----
// GET only supports params in the query string
⋮----
protected postPrivate(endpoint: string, params?: ParamsInQueryBodyOrHeader)
⋮----
protected deletePrivate(
    endpoint: string,
    params?: ParamsInQueryBodyOrHeader,
)
⋮----
protected putPrivate(endpoint: string, params?: ParamsInQueryBodyOrHeader)
⋮----
// protected patchPrivate(endpoint: string, params?: any) {
protected patchPrivate(endpoint: string, params?: ParamsInQueryBodyOrHeader)
⋮----
/**
   * @private Make a HTTP request to a specific endpoint. Private endpoint API calls are automatically signed.
   */
private async _call(
    method: Method,
    endpoint: string,
    params?: ParamsInQueryBodyOrHeader,
    isPublicApi?: boolean,
): Promise<any>
⋮----
// Sanity check to make sure it's only ever prefixed by one forward slash
⋮----
// Build a request and handle signature process
⋮----
// Dispatch request
⋮----
// Throw if API returns an error (e.g. insufficient balance)
⋮----
// const res = {
//   result: 'error',
//   error: 'authenticationError',
//   serverTime: '2025-10-29T15:02:39.341Z',
// };
⋮----
/**
   * @private generic handler to parse request exceptions
   */
parseException(e: any, requestParams: any): unknown
⋮----
// Something happened in setting up the request that triggered an error
⋮----
// request made but no response received
⋮----
// The request was made and the server responded with a status code
// that falls out of the range of 2xx
⋮----
// console.error('err: ', response?.data);
⋮----
// Prevent credentials from leaking into error messages
⋮----
private async signMessage(
    paramsStr: string,
    secret: string,
    method: SignEncodeMethod,
    algorithm: SignAlgorithm,
    options?: SignMessageOptions,
): Promise<string>
⋮----
/**
   * @private sign request and set recv window
   */
private async signRequest<
    T extends ParamsInQueryBodyOrHeader | undefined = {},
  >(
    data: T,
    endpoint: string,
    method: Method,
    signMethod: SignMethod,
): Promise<SignedRequest<T>>
⋮----
// handle JSON preprocessing for requests, including embedded stringify
⋮----
// array
⋮----
// not array in top, but has array orders
⋮----
// not array in top, but has array batchOrder
⋮----
// Unique to batch order placement, json must be pre-stringified in request
⋮----
// not array in top, but has json object
⋮----
// For the rare non-order requests that expected pre-stringified json
⋮----
// simple object
⋮----
// Don't prefix with ? as part of sign. Prefix after sign
⋮----
// Array values are repeated into key value pairs
// E.g. orderIds:[1,2] becomes orderIds=1&orderIds=2
⋮----
// Set default nonce, if not set yet
⋮----
// Allow nonce override in reuqest
// Should never fallback to new nonce, since it's pre-set above with default val
⋮----
// for spot, serialise GET params, use JSON for POST
⋮----
// Only sign when no access token is provided
⋮----
// node:crypto equivalent
// const sign = createHmac(
//   'sha512',
//   Buffer.from(this.apiSecret!, 'base64'),
// )
//   .update(signMessage, 'binary')
//   .digest('base64');
⋮----
// Check if this is a base64 decoding error (invalid API credentials)
⋮----
// Re-throw other errors as-is
⋮----
// ONLY the query params. The rest goes in the body, if there is a body.
⋮----
const nonce = ''; //this.getNextRequestNonce();
⋮----
// Only sign when no access token is provided
⋮----
// node:crypto equivalent
// const sign = createHmac(
//   'sha512',
//   Buffer.from(this.apiSecret!, 'base64'),
// )
//   .update(signMessage, 'binary')
//   .digest('base64');
⋮----
// Submitted as query string in form body
⋮----
private async prepareSignParams<TParams extends object | undefined>(
    method: Method,
    endpoint: string,
    signMethod: SignMethod,
    params?: TParams,
    isPublicApi?: true,
  ): Promise<UnsignedRequest<TParams>>;
⋮----
private async prepareSignParams<TParams extends object | undefined>(
    method: Method,
    endpoint: string,
    signMethod: SignMethod,
    params?: TParams,
    isPublicApi?: false | undefined,
  ): Promise<SignedRequest<TParams>>;
⋮----
private async prepareSignParams<TParams extends object | undefined>(
    method: Method,
    endpoint: string,
    signMethod: SignMethod,
    params?: TParams,
    isPublicApi?: boolean,
)
⋮----
/** Returns an axios request object. Handles signing process automatically if this is a private API call */
private async buildRequest(
    method: Method,
    endpoint: string,
    url: string,
    params?: ParamsInQueryBodyOrHeader,
    isPublicApi?: boolean,
): Promise<AxiosRequestConfig>
⋮----
// Support for Authorization header, if provided:
// https://github.com/tiagosiebler/kucoin-api/issues/2
// Use restClient.setAccessToken(newToken), if you need to store a new access token
// Not supported for Kraken at this time





================================================================
End of Codebase
================================================================