@lynx-crypto/kraken-api 0.2.0 → 1.1.0

package/README.md

@@ -8,10 +8,11 @@
 [![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)
+- **Bulk historical CSV datasets** (OHLCVT + Trades) via Kraken’s official Google Drive downloads
 
 See [Kraken Official Documentation](https://docs.kraken.com/api/docs/category/guides)
 
@@ -22,85 +23,329 @@ See [Kraken Official Documentation](https://docs.kraken.com/api/docs/category/gu
 
 ---
 
-## Install
+## Features
 
-NPM:
-`npm i @lynx-crypto/kraken-api`
+### Spot REST API
 
-Yarn:
-`yarn add @lynx-crypto/kraken-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)
 
-pnpm:
-`pnpm add @lynx-crypto/kraken-api`
+### Spot WebSocket v2 API
 
-### Node support
+- 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
 
-- Node >= 18 recommended (uses built-in fetch / AbortController)
+### Bulk historical CSV datasets (OHLCVT + Trades)
+
+Support for Kraken’s downloadable historical datasets:
+
+- OHLCVT (open/high/low/close/volume/trades)
+- Trades (time and sales)
+
+Data source (Kraken Support):
+
+- https://support.kraken.com/sections/360009899492-csv-data
+- https://support.kraken.com/articles/360047124832-downloadable-historical-ohlcvt-open-high-low-close-volume-trades-data
+- https://support.kraken.com/articles/360047543791-downloadable-historical-market-data-time-and-sales-
+
+Bulk workflow:
+
+- Download ZIPs (seamless via Drive API, or manually)
+- Extract ZIPs into a stable on-disk layout
+- Query extracted CSVs (streaming)
 
 ---
 
-## Quick start
+## Installation
 
-ESM:
+Using Yarn:
 
-```ts
-import {
-  KrakenSpotRestClient,
-  KrakenSpotWebsocketV2Client,
-} from '@lynx-crypto/kraken-api';
-```
+'''sh
+yarn add @lynx-crypto/kraken-api
+'''
 
-CJS:
+Using npm:
 
-```js
-const {
-  KrakenSpotRestClient,
-  KrakenSpotWebsocketV2Client,
-} = require('@lynx-crypto/kraken-api');
-```
+'''sh
+npm install @lynx-crypto/kraken-api
+'''
 
 ---
 
-## REST (Spot)
+## Requirements
 
-### Create a REST client
+- 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
+- For bulk downloads (optional):
+  - A Google Drive API key for seamless downloads (manual ZIP placement is supported)
 
-```ts
-const kraken = new KrakenSpotRestClient({
-  // Optional:
-  // baseUrl: "https://api.kraken.com",
-  // timeoutMs: 10_000,
-  // userAgent: "my-app/1.0.0",
+---
+
+## Environment Variables (for private usage)
+
+'''bash
+KRAKEN_API_KEY="your_api_key"
+KRAKEN_API_SECRET="your_api_secret"
+'''
+
+## Environment Variables (optional, for bulk downloads)
+
+'''bash
 
-  // Required for private endpoints:
-  apiKey: process.env.KRAKEN_API_KEY,
-  apiSecret: process.env.KRAKEN_API_SECRET,
+# If set, bulk downloads can be performed via the Google Drive API.
+
+# If not set, ZIPs can be downloaded manually and placed into the expected folders.
+
+LYNX_CRYPTO_KRAKEN_API_GOOGLE_DRIVE_API_KEY="your_google_drive_api_key"
+'''
+
+---
 
-  // Optional logger:
-  // logger: console,
+## Package Exports
+
+### REST
+
+- `KrakenSpotRestClient`
+
+Sub-APIs available on the client:
+
+- `marketData`
+- `accountData`
+- `trading`
+- `funding`
+- `subaccounts`
+- `earn`
+- `transparency`
+
+### WebSocket
+
+- `KrakenSpotWebsocketV2Client`
+- `KrakenWebsocketBase` (advanced / custom integrations)
+
+Typed channel namespaces:
+
+- `admin`
+- `marketData`
+- `userData`
+- `userTrading`
+
+### Bulk
+
+- `KrakenBulkClient`
+
+All public request/response and stream payloads are exported as TypeScript types.
+
+---
+
+## REST Usage
+
+### Public REST example (no authentication)
+
+'''ts
+import { KrakenSpotRestClient } from '@lynx-crypto/kraken-api';
 
-  // Optional rate limiting:
-  // rateLimit: { mode: "auto" },
+async function main() {
+const kraken = new KrakenSpotRestClient({
+userAgent: 'example-app/1.0.0',
 });
-```
 
-### Public endpoint example
+const time = await kraken.marketData.getServerTime();
+console.log('Kraken time:', time.rfc1123);
+}
 
-(Exact public endpoints depend on what you’ve implemented under src/spot/rest.)
+main().catch((err) => {
+console.error(err);
+process.exitCode = 1;
+});
+'''
 
-```ts
-const serverTime = await kraken.public.getServerTime();
-console.log(serverTime);
-```
+### Private REST example (authenticated)
 
-### Private endpoint example
+'''ts
+import 'dotenv/config';
+import { KrakenSpotRestClient } from '@lynx-crypto/kraken-api';
 
-(Exact private endpoints depend on what you’ve implemented under src/spot/rest.)
+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'),
+});
 
-```ts
 const balances = await kraken.accountData.getAccountBalance();
-console.log('USD:', balances['ZUSD']);
-```
+console.log('Asset count:', Object.keys(balances).length);
+}
+
+main().catch((err) => {
+console.error(err);
+process.exitCode = 1;
+});
+'''
+
+---
+
+## WebSocket v2 Usage
+
+### Public WebSocket (market data)
+
+'''ts
+import { KrakenSpotWebsocketV2Client } from '@lynx-crypto/kraken-api';
+
+async function main() {
+const wsClient = new KrakenSpotWebsocketV2Client({
+autoReconnect: false,
+});
+
+await wsClient.publicConnection.connect();
+
+const ack = await wsClient.marketData.subscribeTrade(
+{ symbol: ['BTC/USD'], snapshot: true },
+{ reqId: 1 },
+);
+
+if (!ack.success) {
+throw new Error(`Subscribe failed: ${ack.error}`);
+}
+
+const unsubscribe = wsClient.publicConnection.addMessageHandler((msg) => {
+console.log(JSON.stringify(msg));
+});
+
+setTimeout(() => {
+unsubscribe();
+wsClient.publicConnection.close(1000, 'example done');
+}, 20_000);
+}
+
+main().catch((err) => {
+console.error(err);
+process.exitCode = 1;
+});
+'''
+
+### Private WebSocket (balances / executions)
+
+Authenticated WebSocket usage requires a token obtained via REST.
+
+'''ts
+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;
+});
+'''
+
+---
+
+## Bulk historical data (OHLCVT + Trades)
+
+Bulk data is managed by `KrakenBulkClient`. It supports:
+
+- Downloading complete and quarterly ZIPs
+- Extracting ZIPs into a stable directory layout
+- Listing available pairs (and OHLC intervals)
+- Streaming query results from extracted CSVs
+
+### Storage layout
+
+A `storageDir` is provided when constructing the client (examples use `.bulk-data`). The library stores ZIPs and extracted CSVs under dataset-specific folders:
+
+'''txt
+<storageDir>/
+ohlcvt/
+zips/
+complete/complete.zip
+quarterly/<YYYYQn>.zip
+extracted/
+complete/
+quarterly/<YYYYQn>/
+trades/
+zips/
+complete/complete.zip
+quarterly/<YYYYQn>.zip
+extracted/
+complete/
+quarterly/<YYYYQn>/
+'''
+
+Recommended:
+
+- Add the storage directory to `.gitignore` (e.g. `.bulk-data/`).
+
+### Downloading ZIPs (two options)
+
+1. Seamless downloads (Drive API)
+
+- Set `LYNX_CRYPTO_KRAKEN_API_GOOGLE_DRIVE_API_KEY`.
+- Run the bulk download examples (see below).
+
+2. Manual ZIP placement (no API key)
+
+- Download the ZIP(s) from Kraken’s support pages.
+- Place the ZIP(s) into the expected `zips/complete/` or `zips/quarterly/` folders.
+- Run extraction and query examples as usual (extraction/query do not require an API key).
 
 ---
 
@@ -117,27 +362,27 @@ This library supports Kraken-style rate limiting with optional automatic retries
 
 Example:
 
-```ts
+'''ts
 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),
-  },
+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),
+},
 });
-```
+'''
 
 Disable built-in throttling:
 
-```ts
+'''ts
 rateLimit: {
-  mode: 'off';
+mode: 'off',
 }
-```
+'''
 
 ### Redis rate limiting (multi-process / multi-container)
 
@@ -147,7 +392,7 @@ For cross-process coordination, you can use the Redis-backed token bucket limite
 
 Example (you provide the Redis client + EVAL wrapper):
 
-```ts
+'''ts
 import { KrakenSpotRestClient } from '@lynx-crypto/kraken-api';
 import { RedisTokenBucketLimiter } from '@lynx-crypto/kraken-api/base/redisRateLimit';
 
@@ -155,26 +400,26 @@ import { RedisTokenBucketLimiter } from '@lynx-crypto/kraken-api/base/redisRateL
 // - 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,
+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;
+// Example shape (pseudo-code):
+// return await redis.eval(luaScript, { keys: [key], arguments: [maxCounter, decayPerSec, cost, ttlSeconds, minWaitMs] });
+return 0;
 };
 
 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,
+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: {
@@ -187,9 +432,10 @@ const kraken = new KrakenSpotRestClient({
         evalRedis,
       }),
     },
-  },
+
+},
 });
-```
+'''
 
 Notes:
 
@@ -198,142 +444,40 @@ Notes:
 
 ---
 
-## WebSocket v2 (Spot)
+## Examples
 
-This package provides a top-level v2 WS client that creates:
+The repository includes a comprehensive [examples](./examples) directory:
 
-- a public connection (market data + admin)
-- a private/auth connection (user-data + user-trading)
+- REST (public + safe private endpoints)
+- WebSocket v2 public streams
+- WebSocket v2 private streams (balances, executions)
+- Bulk historical data (OHLCVT + Trades): download, extract, list pairs/intervals, query
 
-### Create a WS v2 client
+Bulk examples live under:
 
-```ts
-const ws = new KrakenSpotWebsocketV2Client({
-  // publicUrl: "wss://ws.kraken.com/v2",
-  // privateUrl: "wss://ws-auth.kraken.com/v2",
+- [./examples/bulk/ohlcvt](./examples/bulk/ohlcvt)
+- [./examples/bulk/trades](./examples/bulk/trades)
 
-  authToken: process.env.KRAKEN_WS_AUTH_TOKEN,
+A minimal bulk flow:
 
-  // autoReconnect: true,
-  // reconnectDelayMs: 1_000,
-  // requestTimeoutMs: 10_000,
+- Download (or manually place ZIPs) → Extract → Query
 
-  // logger: console,
-  // WebSocketImpl: WebSocket,
-});
-```
-
-Available sub-APIs:
-
-- `ws.admin`
-- `ws.marketData`
-- `ws.userData`
-- `ws.userTrading`
-
-### Connect
-
-```ts
-await ws.publicConnection.connect();
-await ws.privateConnection.connect();
-```
-
----
-
-## WS routing: receiving streaming messages
-
-```ts
-const unsubscribe = ws.publicConnection.addMessageHandler((msg) => {
-  // route by msg.channel / msg.type
-});
-
-// later
-unsubscribe();
-```
-
----
-
-## WS v2: Admin
-
-```ts
-const pong = await ws.admin.ping({ reqId: 123 });
-if (!pong.success) console.error('ping failed:', pong.error);
-```
-
----
-
-## WS v2: User Data (authenticated)
-
-Implemented channels:
-
-- `executions`
-- `balances`
-
-### Executions example
-
-```ts
-const ack = await ws.userData.subscribeExecutions({
-  snap_trades: true,
-  snap_orders: true,
-  order_status: true,
-});
-```
-
-```ts
-ws.privateConnection.addMessageHandler((msg) => {
-  if (msg?.channel === 'executions') {
-    for (const report of msg.data ?? []) {
-      console.log(report.order_id, report.order_status);
-    }
-  }
-});
-```
-
-### Balances example
+Examples are designed to be:
 
-```ts
-const ack2 = await ws.userData.subscribeBalances({ snapshot: true });
-```
-
-```ts
-ws.privateConnection.addMessageHandler((msg) => {
-  if (msg?.channel === 'balances') {
-    console.log(msg.data);
-  }
-});
-```
+- Runnable
+- Safe by default
+- Self-contained
+- Easy to copy into your own project
 
 ---
 
-## WS v2: User Trading (authenticated RPC)
-
-Implemented RPCs:
-
-- `add_order`
-- `amend_order`
-- `cancel_order`
-- `cancel_all`
-- `cancel_all_orders_after`
-- `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',
-});
-```
-
-Dead Man’s Switch:
+## Design Philosophy
 
-```ts
-await ws.userTrading.cancelAllOrdersAfter({ timeout: 60 });
-```
+- 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
 
 ---