Shoonya SDK

Wrapper around Shoonya REST + WebSocket APIs.

Installation

# 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:

{
  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

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:

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:

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