@lynx-crypto/kraken-api 0.1.2 → 1.0.0

package/README.md

@@ -8,326 +8,369 @@
 [![last commit](https://img.shields.io/github/last-commit/lynx-laboratory/kraken-api?branch=master)](https://github.com/lynx-laboratory/kraken-api/commits/master)
 [![license](https://img.shields.io/github/license/lynx-laboratory/kraken-api)](./LICENSE.md)
 
-TypeScript client for **Kraken SPOT**:
-
+A modern, strongly-typed TypeScript client for the **Kraken Spot API**, providing both **REST** and **WebSocket v2** access in a single package.
 - **REST API** (public + private endpoints)
 - **WebSocket v2** (public market-data + authenticated user-data/trading)
 
 See [Kraken Official Documentation](https://docs.kraken.com/api/docs/category/guides)
 
-IMPORTANT
-
+## Important
 - This package is currently **SPOT only**. It does **not** implement Kraken Futures.
 - Unofficial project. Not affiliated with Kraken.
 
 ---
 
-## Install
+## Features
+
+### Spot REST API
+- Public market data (time, assets, pairs, ticker, OHLC, order book, trades, spreads)
+- Private account data (balances, orders, trades, ledgers, export reports)
+- Trading endpoints (add/amend/edit/cancel orders, batch operations)
+- Funding endpoints (deposits, withdrawals, transfers)
+- Earn endpoints (strategies, allocations, status)
+- Subaccounts (master account operations)
+- Transparency endpoints (pre-trade / post-trade data)
+
+### Spot WebSocket v2 API
+- Public streams (ticker, trades, book, OHLC, instruments)
+- Private user streams (balances, executions)
+- Private trading RPC methods
+- Automatic request/response correlation (`req_id`)
+- Optional auto-reconnect with backoff
+- Works in Node.js (via `ws`) or browser environments
 
-NPM:
+---
 
-```
-npm i @lynx-crypto/kraken-api
-```
+## Installation
 
-Yarn:
+Using Yarn:
 
-```
+```sh
 yarn add @lynx-crypto/kraken-api
 ```
 
-pnpm:
+Using npm:
 
+```sh
+npm install @lynx-crypto/kraken-api
 ```
-pnpm add @lynx-crypto/kraken-api
-```
-
-Node support
-
-- Node >= 18 recommended (uses built-in fetch / AbortController)
 
 ---
 
-## Quick start
+## Requirements
 
-ESM:
+- Node.js 18+ recommended
+- TypeScript 4.9+ recommended
+- For private endpoints:
+  - Kraken API key and secret
+  - Appropriate permissions enabled in Kraken
+  - “WebSocket interface” enabled for private WS usage
 
-```
-import { KrakenSpotRestClient, KrakenSpotWebsocketV2Client } from "@lynx-crypto/kraken-api";
-```
+---
 
-CJS:
+## Environment Variables (for private usage)
 
-```
-const { KrakenSpotRestClient, KrakenSpotWebsocketV2Client } = require("@lynx-crypto/kraken-api");
+```bash
+KRAKEN_API_KEY="your_api_key"
+KRAKEN_API_SECRET="your_api_secret"
 ```
 
 ---
 
-## REST (Spot)
+## Package Exports
 
-### Create a REST client
+### REST
+- `KrakenSpotRestClient`
 
-```ts
-const kraken = new KrakenSpotRestClient({
-  // Optional:
-  //   baseUrl: "https://api.kraken.com",
-  //   timeoutMs: 10_000,
-  //   userAgent: "my-app/1.0.0",
+Sub-APIs available on the client:
+- `marketData`
+- `accountData`
+- `trading`
+- `funding`
+- `subaccounts`
+- `earn`
+- `transparency`
 
-  // Required for private endpoints:
-  apiKey: process.env.KRAKEN_API_KEY,
-  apiSecret: process.env.KRAKEN_API_SECRET,
+### WebSocket
+- `KrakenSpotWebsocketV2Client`
+- `KrakenWebsocketBase` (advanced / custom integrations)
 
-  // Optional logger:
-  // logger: console,
-});
-```
+Typed channel namespaces:
+- `admin`
+- `marketData`
+- `userData`
+- `userTrading`
 
-### Public endpoint example
+All public request/response and stream payloads are exported as TypeScript types.
 
-(Your exact public endpoints depend on what you’ve implemented in src/spot/rest.)
+---
+## REST Usage
 
-Example shape:
+### Public REST example (no authentication)
 
 ```ts
-const serverTime = await kraken.public.getServerTime();
-```
+import { KrakenSpotRestClient } from '@lynx-crypto/kraken-api';
 
-### Private endpoint example
+async function main() {
+  const kraken = new KrakenSpotRestClient({
+    userAgent: 'example-app/1.0.0',
+  });
 
-(Your exact private endpoints depend on what you’ve implemented in src/spot/rest.)
+  const time = await kraken.marketData.getServerTime();
+  console.log('Kraken time:', time.rfc1123);
+}
 
-Example shape:
-const balances = await kraken.accountData.getAccountBalance();
-console.log("USD:", balances["ZUSD"]);
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});
+```
 
----
+### Private REST example (authenticated)
 
-## WebSocket v2 (Spot)
+```ts
+import 'dotenv/config';
+import { KrakenSpotRestClient } from '@lynx-crypto/kraken-api';
+
+function requireEnv(name: string): string {
+  const v = process.env[name];
+  if (!v) throw new Error(`Missing env var: ${name}`);
+  return v;
+}
+
+async function main() {
+  const kraken = new KrakenSpotRestClient({
+    userAgent: 'example-app/1.0.0',
+    apiKey: requireEnv('KRAKEN_API_KEY'),
+    apiSecret: requireEnv('KRAKEN_API_SECRET'),
+  });
+
+  const balances = await kraken.accountData.getAccountBalance();
+  console.log('Asset count:', Object.keys(balances).length);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});
+```
 
-This package provides a top-level v2 WS client that creates:
+---
 
-- a **public connection** (market data + admin)
-- a **private/auth connection** (user-data + user-trading)
+## WebSocket v2 Usage
 
-### Create a WS v2 client
+### Public WebSocket (market data)
 
 ```ts
-const ws = new KrakenSpotWebsocketV2Client({
-  // Optional override URLs:
-  // publicUrl: "wss://ws.kraken.com/v2",
-  // privateUrl: "wss://ws-auth.kraken.com/v2",
-
-  // IMPORTANT: private WS requires a session token
-  authToken: process.env.KRAKEN_WS_AUTH_TOKEN,
-
-  // Optional connection tuning:
-  // autoReconnect: true,
-  // reconnectDelayMs: 1_000,
-  // requestTimeoutMs: 10_000,
-
-  // Optional logger:
-  // logger: console,
-
-  // Optional WS implementation:
-  // - In Node, ws is used by default.
-  // - In browsers, pass the browser WebSocket if needed.
-  // WebSocketImpl: WebSocket,
-});
-```
+import { KrakenSpotWebsocketV2Client } from '@lynx-crypto/kraken-api';
 
-Available sub-APIs:
+async function main() {
+  const wsClient = new KrakenSpotWebsocketV2Client({
+    autoReconnect: false,
+  });
 
-- `ws.admin` (public connection)
-- `ws.marketData` (public connection)
-- `ws.userData` (private connection)
-- `ws.userTrading` (private connection)
+  await wsClient.publicConnection.connect();
 
-### Connect
+  const ack = await wsClient.marketData.subscribeTrade(
+    { symbol: ['BTC/USD'], snapshot: true },
+    { reqId: 1 },
+  );
 
-You can connect explicitly:
+  if (!ack.success) {
+    throw new Error(`Subscribe failed: ${ack.error}`);
+  }
 
-```ts
-await ws.publicConnection.connect();
-await ws.privateConnection.connect();
-```
+  const unsubscribe = wsClient.publicConnection.addMessageHandler((msg) => {
+    console.log(JSON.stringify(msg));
+  });
 
-Or let calls auto-connect (methods like `request()/sendRaw()` will connect if needed).
+  setTimeout(() => {
+    unsubscribe();
+    wsClient.publicConnection.close(1000, 'example done');
+  }, 20_000);
+}
 
----
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});
+```
 
-## WS routing: receiving streaming messages
+### Private WebSocket (balances / executions)
 
-The underlying `KrakenWebsocketBase` supports message fan-out:
+Authenticated WebSocket usage requires a token obtained via REST.
 
 ```ts
-const unsubscribe = ws.publicConnection.addMessageHandler((msg) => {
-  // msg is already JSON-parsed when possible
-  // route based on msg.channel / msg.type, etc.
-  // console.log(msg);
+import 'dotenv/config';
+import {
+  KrakenSpotRestClient,
+  KrakenSpotWebsocketV2Client,
+} from '@lynx-crypto/kraken-api';
+
+function requireEnv(name: string): string {
+  const v = process.env[name];
+  if (!v) throw new Error(`Missing env var: ${name}`);
+  return v;
+}
+
+async function main() {
+  const rest = new KrakenSpotRestClient({
+    userAgent: 'example-app/1.0.0',
+    apiKey: requireEnv('KRAKEN_API_KEY'),
+    apiSecret: requireEnv('KRAKEN_API_SECRET'),
+  });
+
+  const { token } = await rest.trading.getWebSocketsToken();
+
+  const wsClient = new KrakenSpotWebsocketV2Client({
+    authToken: token,
+    autoReconnect: false,
+  });
+
+  await wsClient.privateConnection.connect();
+
+  const ack = await wsClient.userData.subscribeBalances({}, { reqId: 10 });
+
+  if (!ack.success) {
+    throw new Error(`Subscribe failed: ${ack.error}`);
+  }
+
+  const off = wsClient.privateConnection.addMessageHandler((msg) => {
+    console.log(JSON.stringify(msg));
+  });
+
+  setTimeout(() => {
+    off();
+    wsClient.privateConnection.close(1000, 'example done');
+  }, 30_000);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
 });
-
-// later:
-unsubscribe();
 ```
 
 ---
 
-## WS v2: Admin
+## REST rate limiting & retries
+
+This library supports Kraken-style rate limiting with optional automatic retries:
 
-Admin utilities exist on the public connection (ex: ping/status/heartbeat).
+- Lightweight in-memory token bucket limiter by default
+- Automatic retries are configurable
+- Handles:
+  - EAPI:Rate limit exceeded
+  - EService: Throttled: <unix timestamp>
+  - HTTP 429 Too Many Requests
 
 Example:
 
 ```ts
-const pong = await ws.admin.ping({ reqId: 123 });
-if (!pong.success) console.error('ping failed:', pong.error);
+const kraken = new KrakenSpotRestClient({
+  apiKey: process.env.KRAKEN_API_KEY,
+  apiSecret: process.env.KRAKEN_API_SECRET,
+  rateLimit: {
+    mode: 'auto',
+    tier: 'starter',
+    retryOnRateLimit: true,
+    maxRetries: 5,
+    // restCostFn: (path) => (path.includes("Ledgers") ? 2 : 1),
+  },
+});
 ```
 
----
-
-## WS v2: Market Data (public)
-
-Market data subscriptions live on ws.marketData (public connection).
-(Exact channel helpers depend on your implemented market-data modules.)
+Disable built-in throttling:
 
-Typical pattern:
-
-1. call subscribe helper (await ack)
-2. listen via `addMessageHandler` and route messages by channel/type
-
----
+```ts
+rateLimit: {
+  mode: 'off';
+}
+```
 
-## WS v2: User Data (authenticated)
+### Redis rate limiting (multi-process / multi-container)
 
-User-data streams live on `ws.userData` (private connection).
+If you run multiple Node processes, Docker containers, or workers, they all share the same Kraken IP-level limits. In-memory rate limiting only protects a single process.
 
-Implemented channels:
+For cross-process coordination, you can use the Redis-backed token bucket limiter.
 
-- executions (order lifecycle + fills)
-- balances (balance snapshots + ledger-derived updates)
+Example (you provide the Redis client + EVAL wrapper):
 
-Example (executions):
+```ts
+import { KrakenSpotRestClient } from '@lynx-crypto/kraken-api';
+import { RedisTokenBucketLimiter } from '@lynx-crypto/kraken-api/base/redisRateLimit';
+
+// Your Redis EVAL wrapper should return a number:
+// - 0 means "proceed now"
+// - >0 means "wait this many ms then retry"
+const evalRedis = async (
+  key: string,
+  maxCounter: number,
+  decayPerSec: number,
+  cost: number,
+  ttlSeconds: number,
+  minWaitMs: number,
+): Promise<number> => {
+  // Example shape (pseudo-code):
+  // return await redis.eval(luaScript, { keys: [key], arguments: [maxCounter, decayPerSec, cost, ttlSeconds, minWaitMs] });
+  return 0;
+};
 
-```
-const ack = await ws.userData.subscribeExecutions({
-    snap_trades: true,
-    snap_orders: true,
-    order_status: true,
+const kraken = new KrakenSpotRestClient({
+  apiKey: process.env.KRAKEN_API_KEY,
+  apiSecret: process.env.KRAKEN_API_SECRET,
+  rateLimit: {
+    mode: 'auto',
+    tier: 'starter',
+    retryOnRateLimit: true,
+    maxRetries: 5,
+
+    // Cross-process limiter (Redis):
+    redis: {
+      limiter: new RedisTokenBucketLimiter({
+        key: 'kraken:rest:global',
+        maxCounter: 15,
+        decayPerSec: 0.33,
+        ttlSeconds: 30,
+        minWaitMs: 50,
+        evalRedis,
+      }),
+    },
+  },
 });
-
-if (!ack.success) console.error("executions subscribe error:", ack.error);
 ```
 
-Then route messages:
+Notes:
 
-```
-ws.privateConnection.addMessageHandler((msg: any) => {
-    if (msg?.channel === "executions" && (msg.type === "snapshot" || msg.type === "update")) {
-        for (const report of msg.data ?? []) {
-            console.log("[exec]", report.exec_type, report.order_id, report.order_status);
-        }
-    }
-});
-```
-
-Example (balances):
-
-````ts
-const ack2 = await ws.userData.subscribeBalances({ snapshot: true });
-if (!ack2.success) console.error("balances subscribe error:", ack2.error);
-
-ws.privateConnection.addMessageHandler((msg: any) => {
-    if (msg?.channel === "balances" && msg.type === "snapshot") {
-        for (const asset of msg.data ?? []) {
-            console.log("[balances snapshot]", asset.asset, "total:", asset.balance);
-        }
-    }
-    if (msg?.channel === "balances" && msg.type === "update") {
-            for (const tx of msg.data ?? []) {
-            console.log("[balances update]", tx.asset, tx.type, "delta:", tx.amount, "new:", tx.balance);
-        }
-    }
-});
+- Redis is optional. Only use it when you need cross-process coordination.
+- If Redis is down / eval fails, the request fails (no silent bypass).
 
 ---
 
-## WS v2: User Trading (authenticated RPC)
+## Examples
 
-User-trading methods live on `ws.userTrading` (private connection).
+The repository includes a comprehensive [examples](./examples) directory:
 
-Implemented RPCs:
+- REST (public + safe private endpoints)
+- WebSocket v2 public streams
+- WebSocket v2 private streams (balances, executions)
+- Clean lifecycle examples (connect → subscribe → receive → close)
 
-- `add_order`
-- `amend_order`
-- `edit_order` (legacy)
-- `cancel_order`
-- `cancel_all`
-- `cancel_all_orders_after` (Dead Man’s Switch)
-- `batch_add`
-- `batch_cancel`
-
-Add order:
-```ts
-const res = await ws.userTrading.addOrder({
-    order_type: "limit",
-    side: "buy",
-    symbol: "BTC/USD",
-    order_qty: 0.01,
-    limit_price: 30000,
-    time_in_force: "gtc",
-    cl_ord_id: "demo-0001",
-});
-
-
-if (res.success) console.log("order_id:", res.result?.order_id);
-else console.error("add_order error:", res.error);
-````
-
-Dead Man’s Switch:
-
-```
-// recommended: refresh every 15–30s with timeout=60
-await ws.userTrading.cancelAllOrdersAfter({ timeout: 60 });
-```
+Examples are designed to be:
+- Runnable
+- Safe by default
+- Self-contained
+- Easy to copy into your own project
 
 ---
 
-## Options reference
-
-### `KrakenSpotRestClient` options
-
-- `baseUrl?: string`
-  Default: https://api.kraken.com
-- `timeoutMs?: number`
-  Default: 10_000
-- `userAgent?: string`
-- `apiKey?: string`
-  Required for private endpoints
-- `apiSecret?: string` (base64)
-  Required for private endpoints
-- `logger?: KrakenLogger`
-  debug/info/warn/error(msg, meta?)
-
-### KrakenSpotWebsocketV2Client options
-
-- `publicUrl?: string`
-  Default: wss://ws.kraken.com/v2
-- `privateUrl?: string`
-  Default: wss://ws-auth.kraken.com/v2
-- `authToken?: string`
-  Required for authenticated/private connection features
-- `WebSocketImpl?: constructor`
-  Optional override (browser / custom WS)
-- `autoReconnect?: boolean`
-  Default: true
-- `reconnectDelayMs?: number`
-  Default: 1000
-- `requestTimeoutMs?: number`
-  Default: 10_000
-- `logger?: KrakenWebsocketLogger`
-  debug/info/warn/error(msg, meta?)
+## Design Philosophy
+
+- Explicit APIs over magic
+- Strong typing without sacrificing usability
+- Clear separation of REST vs WebSocket concerns
+- No hidden background workers
+- Safe defaults, especially for trading operations
 
 ---
 
@@ -349,11 +392,11 @@ Build:
 
 ## Security notes
 
-- Keep API keys/secrets out of source control.
-- Use least-privilege API key permissions.
+- Keep API keys and secrets out of source control
+- Use least-privilege API key permissions
 
 ---
 
 ## License
 
-MIT (see LICENSE)
+MIT (see LICENSE.md)