delta-india-sdk

TypeScript-first, zero-dependency SDK for the Delta Exchange India crypto derivatives API.

Features

• Full REST + WebSocket coverage of Delta India's v2 API
• Complete TypeScript types for every request and response
• Zero runtime dependencies — uses native fetch and WebSocket
• Dual ESM + CommonJS build with .d.ts for both
• Built-in HMAC SHA256 request signing
• Sliding-window rate limiter with auto-queue or throw modes
• Auto-reconnect WebSocket with exponential backoff and ping/pong

Requirements

• Node.js 22 or later (uses native fetch and WebSocket)

Installation

npm install delta-india-sdk

Get API keys

Generate an API key + secret from your Delta India account (or testnet). For trading you must enable the "Trade" permission. Store the secret in an environment variable, never in source code.

export DELTA_API_KEY=...
export DELTA_API_SECRET=...

Quick Start

import { DeltaClient } from 'delta-india-sdk';

const client = new DeltaClient({
  apiKey: process.env.DELTA_API_KEY,
  apiSecret: process.env.DELTA_API_SECRET,
  testnet: true,
});

// Public market data — no API key needed
const ticker = await client.products.ticker('BTCUSD');
console.log(`BTCUSD mark: ${ticker.mark_price}`);

// Authenticated call
const balances = await client.wallet.balances();

client.destroy(); // releases the rate-limiter timer

Common Recipes

Place a limit order

const order = await client.orders.create({
  product_symbol: 'BTCUSD',
  size: '1',                 // contracts, not USD
  side: 'buy',
  order_type: 'limit_order',
  limit_price: '60000',
  time_in_force: 'gtc',
});

Cancel an order

await client.orders.cancel(order.id, order.product_id);

Delta India's cancel is DELETE /v2/orders with {id, product_id} in the body — cancel(id, productId) handles that for you.

List options tickers (filtered)

The unfiltered /v2/tickers returns 10 000+ rows for options. Always filter:

const callsAndPuts = await client.products.tickers({
  contract_types: 'call_options,put_options',
  underlying_asset_symbols: 'BTC',
  expiry_date: '27-12-2026', // DD-MM-YYYY
});

for (const t of callsAndPuts) {
  console.log(t.symbol, t.strike_price, t.greeks?.delta);
}

Positions for one underlying

// Single position by product
const btcPerpPos = await client.positions.list({ product_id: 27 });

// All positions on an underlying
const ethPositions = await client.positions.list({
  underlying_asset_symbol: 'ETH',
});

list() returns Position[] even when Delta responds with a single object (filtered by product_id).

Bracket order with trigger method

await client.orders.create({
  product_id: 27,
  size: '1',
  side: 'buy',
  order_type: 'market_order',
  bracket_stop_loss_price: '58000',
  bracket_stop_trigger_method: 'mark_price', // or 'last_traded_price', 'spot_price'
  bracket_take_profit_price: '65000',
});

Batch operations

await client.orders.batchCreate({
  product_id: 27,           // required at the top level
  orders: [
    { size: '1', side: 'buy',  order_type: 'limit_order', limit_price: '59000' },
    { size: '1', side: 'sell', order_type: 'limit_order', limit_price: '61000' },
  ],
});

await client.orders.batchDelete({
  product_id: 27,
  orders: [{ id: 1234 }, { id: 1235 }],
});

WebSocket — public channels

client.ws.on('connected', () => {
  client.ws.subscribe('v2/ticker', ['BTCUSD']);
  client.ws.subscribe('recent_trade', ['BTCUSD']);
});

client.ws.on('v2/ticker', (data) => console.log(data.symbol, data.close));
client.ws.on('recent_trade', (trade) => console.log('trade', trade));

client.ws.connect();

Delta sends recent-trade messages typed all_trades / all_trades_snapshot; the SDK re-emits them under the canonical recent_trade event so your handler always fires.

WebSocket — private channels (auto-auth)

const client = new DeltaClient({
  apiKey: process.env.DELTA_API_KEY,
  apiSecret: process.env.DELTA_API_SECRET,
});

client.ws.on('connected', () => {
  client.ws.subscribe('orders');
  client.ws.subscribe('positions');
});

client.ws.on('authenticated', () => console.log('private channels live'));
client.ws.on('orders', (o) => console.log('order update', o.id, o.state));

client.ws.connect();

Working with numeric fields

Delta returns most numeric fields (size, entry_price, mark_price, greeks.delta, quotes.best_bid, …) as strings to preserve precision. Convert them at the edge using the bundled num() / int() helpers instead of scattering parseFloat(x) || 0 through your code:

import { DeltaClient, num, int } from 'delta-india-sdk';

const [pos] = await client.positions.list({ product_id: 27 });

const size      = num(pos.size);                                // "1"      -> 1
const entry     = num(pos.entry_price ?? pos.avg_entry_price);  // string-or-null -> number
const mark      = num(pos.mark_price, num(ticker.mark_price));  // chained fallback
const productId = int(req.query.productId, 27);                 // URL/DB string -> int

Both helpers accept string | number | null | undefined and return a finite number, falling back to 0 (or your supplied default) for null, empty, NaN, and Infinity. int() additionally truncates the result.

API Reference

Client Options

const client = new DeltaClient({
  apiKey: 'your-api-key',       // required for authenticated endpoints + private WS
  apiSecret: 'your-api-secret', // required for authenticated endpoints + private WS
  testnet: true,                // default false
  baseUrl: 'https://...',       // optional override (takes precedence over testnet)
  wsUrl: 'wss://...',           // optional WebSocket override
  timeout: 10000,               // ms, default 10000
  rateLimitMode: 'auto',        // 'auto' queues, 'manual' throws RateLimitError
  maxQueueSize: 100,            // queued requests cap in auto mode
});

REST Sub-Clients

| Sub-client | Methods | |---|---| | client.assets | list, listIndices | | client.products | list, getBySymbol, tickers, ticker | | client.marketData | orderbook, recentTrades, candles, sparklines, settlementPrice | | client.orders | create, get, getByClientId, list, edit, cancel, cancelAll, batchCreate, batchEdit, batchDelete, createBracket, editBracket, getLeverage, setLeverage | | client.positions | list, listMargined, setMarginMode | | client.history | orders, fills, fillsDownload | | client.wallet | balances, transactions, transactionsDownload, transfer, transferHistory | | client.account | getUser, getPreferences, updatePreferences, listSubaccounts, getRateLimitQuota | | client.stats | volume | | client.mmp | config, reset | | client.heartbeat | create, ack, list |

WebSocket Channels

Public (no auth): v2/ticker, l2_orderbook, recent_trade, all_trades, mark_price, spot_price, funding_rate, product_updates, announcements

Private (auto-authenticated): orders, positions, margins, fills

Error Handling

import {
  DeltaError, AuthenticationError, RateLimitError,
  APIError, WebSocketError, TimeoutError, ValidationError,
} from 'delta-india-sdk';

try {
  await client.orders.create({ /* ... */ });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401/403 — bad keys or stale system clock
  } else if (err instanceof RateLimitError) {
    console.log(`retry after ${err.retryAfter}s`);
  } else if (err instanceof TimeoutError) {
    // request exceeded the configured timeout
  } else if (err instanceof APIError) {
    console.log(`API ${err.statusCode}: ${err.errorCode ?? err.message}`);
  }
}

Endpoints

| Environment | REST | WebSocket | |---|---|---| | Production | https://api.india.delta.exchange | wss://socket.india.delta.exchange | | Testnet | https://cdn-ind.testnet.deltaex.org | wss://socket-ind.testnet.deltaex.org |

testnet: true selects the testnet pair automatically. Override either with baseUrl / wsUrl.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | AuthenticationError: invalid signature | System clock drift > a few seconds | Sync NTP / system clock | | AuthenticationError on every authed call | Wrong key/secret or wrong env (test vs prod) | Verify key matches the env you're hitting | | recent_trade listener never fires | Subscription succeeded but no live trades | Subscribe to a liquid symbol like BTCUSD; messages are re-emitted from all_trades automatically | | tickers() returns thousands of rows | Unfiltered call | Pass contract_types, underlying_asset_symbols, and/or expiry_date | | RateLimitError under load | Burst exceeded sliding window | Use rateLimitMode: 'auto' (default) so calls queue instead of throwing |

Examples

The examples/ folder is ordered so you can read it top-to-bottom; each file is a self-contained runnable script. Public examples (01–02, 10) need no API key; the rest read DELTA_API_KEY and DELTA_API_SECRET from the environment.

| # | File | What it covers | |---|---|---| | 01 | 01-basic-market-data.ts | products, tickers, orderbook, recent trades, candles, sparklines, assets | | 02 | 02-options-chain.ts | filtered tickers, greeks, ATM strike selection | | 03 | 03-place-order.ts | create / edit / cancel a limit order | | 04 | 04-bracket-order.ts | bracket order with stop trigger method, edit bracket, set leverage | | 05 | 05-batch-orders.ts | batch create / edit / delete (correct product_id body shape) | | 06 | 06-positions.ts | list with filters, computed unrealized PnL using num() | | 07 | 07-wallet.ts | balances, transactions, transfer, transfer history | | 08 | 08-account.ts | profile, preferences, subaccounts, rate-limit quota | | 09 | 09-history.ts | order history, fills, computed fees | | 10 | 10-websocket-public.ts | ticker, l2 orderbook, recent_trade, mark_price | | 11 | 11-websocket-private.ts | orders, positions, fills, margins (auto-auth) | | 12 | 12-error-handling.ts | each error class, narrowing with instanceof |

Run any of them with tsx:

npx tsx examples/01-basic-market-data.ts
DELTA_API_KEY=... DELTA_API_SECRET=... npx tsx examples/03-place-order.ts

Development

npm install
npm run typecheck    # tsc --noEmit
npm test             # vitest run
npm run build        # tsup -> dist/

License

MIT