# shoonya-sdk

> Wrapper around Shoonya API

Latest version **1.5.0** (published 2026-04-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install shoonya-sdk
pnpm add shoonya-sdk
yarn add shoonya-sdk
bun add shoonya-sdk
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.5.0 |
| Published | 2026-04-10 |
| First published | 2023-12-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 232 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | cryogon |
| Maintainers | cryogon |
| Keywords | SDK, Shoonya, Trading |

## Links

- npm: https://www.npmjs.com/package/shoonya-sdk
- npm.io page: https://npm.io/package/shoonya-sdk

## Dependencies (3)

- [ws](https://npm.io/package/ws.md) ^8.13.0
- [puppeteer](https://npm.io/package/puppeteer.md) ^24.40.0
- [totp-generator](https://npm.io/package/totp-generator.md) ^0.0.14

## Recent versions

- 1.5.0 (latest) — 2026-04-10
- 1.4.0 — 2026-02-26
- 1.3.3 — 2026-02-23
- 1.3.2 — 2024-11-25
- 1.3.1 — 2024-11-17
- 1.3.0 — 2024-09-06
- 1.2.0 — 2024-07-10
- 1.1.3 — 2024-06-28
- 1.1.2 — 2024-06-19
- 1.1.1 — 2024-06-18
- 1.1.0 — 2024-05-31
- 1.0.1 — 2024-04-25
- 1.0.0 — 2024-04-16
- 0.5.1 — 2024-04-09
- 0.5.0 — 2024-04-08
- … 17 more at https://npm.io/package/shoonya-sdk/versions

## README

# Shoonya SDK

Wrapper around Shoonya REST + WebSocket APIs.

## Installation

```sh
# bun
bun add shoonya-sdk
# npm
npm install shoonya-sdk
# yarn
yarn add shoonya-sdk
# pnpm
pnpm add shoonya-sdk
```

## Credentials

Current auth flow uses Shoonya OAuth code exchange (`GenAcsTok`) under the hood.

`RestClient` / `WebsocketClient` credentials:

```ts
{
  userId: "FAxxxxx",
  password: "your-login-password",
  twoFa: "your-totp-seed",
  apiKey: "your-secret-code", // from Shoonya API page
  clientId?: "FAxxxxx_U",      // optional, defaults to `${userId}_U`
  accountId?: "FAxxxxx",       // optional
  vendorCode?: "FAxxxxx_U",    // optional
  imei?: "api"                 // optional
}
```

## Quick Start

```ts
import { RestClient, WebsocketClient } from "shoonya-sdk";

const credentials = {
  userId: process.env.SHOONYA_USER_ID!,
  password: process.env.SHOONYA_USER_PASSWORD!,
  twoFa: process.env.SHOONYA_TWO_FA!,
  apiKey: process.env.SHOONYA_API_KEY!,
};

const restClient = new RestClient(credentials, { logging: true });
const wsClient = new WebsocketClient({ logging: true });

console.log(await restClient.getAccountLimits());

wsClient.on("open", () => console.log("socket opened"));
wsClient.on("connected", () => {
  console.log("ws connected");
  wsClient.subscribe("NSE|26000", "Touchline");
});
wsClient.on("subscribed", (token) => console.log("subscribed", token));
wsClient.on("priceUpdate", (data) => console.log("tick", data));
wsClient.on("error", (err) => console.error("ws error", err.message));
wsClient.on("close", () => console.log("ws closed"));

wsClient.connect();
```

`RestClient` options:

```ts
new RestClient(credentials, {
  logging: true,
  // baseUrl: "https://api.shoonya.com/NorenWClientAPI/",
  // Optional: set true only if your endpoint expects Bearer header.
  sendBearerAuthHeader: false,
});
```

## WebSocket Behavior

- Primary profile: `wss://api.shoonya.com/NorenWSAPI/` with OAuth handshake (`t: "a"`, `accesstoken`)
- Connect acknowledgement supports both `ak` and `ck`
- Optional compatibility fallback to legacy WSTP is available
- Auto reconnect, token refresh, heartbeat, and resubscribe are built in

`WebsocketClient` options:

```ts
new WebsocketClient({
  logging: true,
  reconnectInterval: 1000,
  maxRetryAttempt: 3,
  heartbeatInterval: 15000,
  connectAckTimeoutMs: 12000,
  postConnectAckDelayMs: 3000,
  enableLegacyFallback: true,
  enableOauthWstpFallback: false,
  dailyRefreshTime: "09:13+05:30",
});
```

## Environment Variables

- `SHOONYA_USER_ID`
- `SHOONYA_USER_PASSWORD`
- `SHOONYA_TWO_FA`
- `SHOONYA_API_KEY`
- `SHOONYA_VENDOR_CODE` (optional)
- `SHOONYA_IMEI` (optional)

## Puppeteer/Chrome Config

OAuth code generation uses Puppeteer.

- `.puppeteerrc.cjs` auto-detects installed Chrome from `~/.cache/puppeteer/chrome`
- Optional override: `PUPPETEER_EXECUTABLE_PATH`
- Optional sandbox toggle for server/CI: `PUPPETEER_NO_SANDBOX=true` (or `CI=true`)
- Optional auth automation speed: `SHOONYA_AUTH_SLOWMO_MS` (default `5`)

## Features

- OAuth-based token exchange (`GenAcsTok`)
- REST requests send `jKey` in body by default (optional Bearer header via `sendBearerAuthHeader`)
- WSAPI-first WebSocket flow with fallback support
- Auto reconnect and token refresh
- Configurable daily reconnect, heartbeat, and ack timeout

---
_Source: https://npm.io/package/shoonya-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._