5paisa TypeScript SDK

TypeScript SDK for 5paisa APIs.

Installation

npm install 5paisa-ts
# or
pnpm add 5paisa-ts
# or
bun add 5paisa-ts

The package targets Node.js 18+ (or compatible runtimes such as Bun) where fetch and WebSocket are available globally.

Getting started

import {
  FivePaisaClient,
  type FivePaisaCredentials,
} from '5paisa-ts';

const credentials: FivePaisaCredentials = {
  APP_NAME: 'YOUR_APP_NAME',
  APP_SOURCE: 'YOUR_APP_SOURCE',
  USER_ID: 'YOUR_USER_ID',
  PASSWORD: 'YOUR_PASSWORD',
  USER_KEY: 'YOUR_USER_KEY',
  ENCRYPTION_KEY: 'YOUR_ENCRYPTION_KEY',
};

const client = new FivePaisaClient(credentials);

// Example: authenticate using an OAuth request token from 5paisa
const accessToken = await client.getOauthSession('REQUEST_TOKEN_FROM_5PAISA');

// Or: if you already have an access token
client.setAccessToken(accessToken, 'CLIENT_CODE');

// Fetch basic information
const holdings = await client.holdings();
const margin = await client.margin();

console.log('Holdings', holdings);
console.log('Margin', margin);

For full API authentication details, see the sections below.

Credentials and authentication

1. Configure API keys

Get your API keys from the 5paisa developer portal and keep them outside of source control (for example in env files):

[KEYS]
APP_NAME=YOUR_APP_NAME
APP_SOURCE=YOUR_APP_SOURCE
USER_ID=YOUR_USER_ID
PASSWORD=YOUR_PASSWORD
USER_KEY=YOUR_USER_KEY
ENCRYPTION_KEY=YOUR_ENCRYPTION_KEY

2. Create a client

import {
  FivePaisaClient,
  type FivePaisaCredentials,
} from '5paisa-ts';

const credentials: FivePaisaCredentials = {
  APP_NAME: process.env.APP_NAME!,
  APP_SOURCE: process.env.APP_SOURCE!,
  USER_ID: process.env.USER_ID!,
  PASSWORD: process.env.PASSWORD!,
  USER_KEY: process.env.USER_KEY!,
  ENCRYPTION_KEY: process.env.ENCRYPTION_KEY!,
};

const client = new FivePaisaClient(credentials);

3. OAuth request token flow

This is the recommended flow and mirrors the py5paisa behaviour.

1. Log in to the vendor login url from a browser and obtain a short lived request token.
2. Exchange the request token for an access token.

// After you obtain `requestToken` from the 5paisa login redirect url:
const accessToken = await client.getOauthSession(requestToken);

// You can also call getAccessToken(requestToken) directly
// const accessToken = await client.getAccessToken(requestToken);

console.log('Access token', accessToken);

Once you have the token, you can reuse it on a new process without repeating the browser flow:

client.setAccessToken(accessToken, 'CLIENT_CODE');

4. TOTP + PIN flow

The client also exposes the TOTP login flow equivalent to the Python SDK.

// Step 1: request token via TOTP + PIN
const requestToken = await client.getRequestToken(
  'CLIENT_CODE',
  'TOTP_VALUE',
  'PIN',
);

// Step 2: exchange the request token for access token
if (requestToken) {
  const accessToken = await client.getAccessToken(requestToken);
  console.log('Access token', accessToken);
}

// Or use the convenience helper which does both steps internally
const accessTokenFromTotp = await client.getTotpSession(
  'CLIENT_CODE',
  'TOTP_VALUE',
  'PIN',
);

5. Session helpers

The following helpers are available for session management and diagnostics:

• getAccessToken(requestToken?) get or refresh the current access token
• getOauthSession(requestToken) convenience wrapper around getAccessToken
• getTotpSession(clientCode, totp, pin) run the full TOTP login flow
• setAccessToken(accessToken, clientCode) set an existing token and client code
• loginCheck() validate an existing session for the current client code
• jwtValidate() validate the current JWT token and get the message from the server

Working with scrip master and symbols

The TypeScript client provides the same scrip master utilities as py5paisa.

Fetch the full scrip master

const scrips = await client.getScrips();
console.log('Total scrips', scrips.length);

Query a specific scrip

The arguments map to the Python query_scrips function: exchange, exchangeType, symbol, strike, type, expiry.

// Example: cash equity
const cash = await client.queryScrips(
  'N',      // exchange
  'C',      // exchange type
  'ITC',    // symbol
  '0',      // strike, 0 for cash stocks
  'XX',     // type: XX for cash and futures, EQ for indices, CE or PE for options
  '',       // expiry (empty for cash)
);

// Example: options
const options = await client.queryScrips(
  'N',
  'D',
  'NIFTY',
  '22300',
  'CE',
  '2024-04-25',
);

User information, reports and portfolio

These methods give you holdings, positions, margins and reports.

// Holdings
const holdings = await client.holdings();

// Margin
const margin = await client.margin();

// Net positions (current positions)
const positions = await client.positions();

// Day-wise net positions
const intradayPositions = await client.positionsDay();

// Order book
const orderBook = await client.orderBook();

// Trade book
const tradeBook = await client.getTradebook();

// Idea buy and trade recommendations
const buyIdeas = await client.getBuy();
const tradeIdeas = await client.getTrade();

// Tax report
const taxReport = await client.taxReport('2024-01-01', '2024-06-26');

// Ledger report
const ledger = await client.fetchLedger('2024-01-01', '2024-06-26');

The taxReport and fetchLedger helpers validate the date format and ensure that fromDate is not later than toDate.

Market data and option chain

Market feed (snapshot)

// Example option instruments for NIFTY
const reqList = [
  {
    Exch: 'N',
    ExchType: 'D',
    Symbol: 'NIFTY 22 APR 2021 CE 15200.00',
    Expiry: '20210422',
    StrikePrice: '15200',
    OptionType: 'CE',
  },
  {
    Exch: 'N',
    ExchType: 'D',
    Symbol: 'NIFTY 22 APR 2021 PE 15200.00',
    Expiry: '20210422',
    StrikePrice: '15200',
    OptionType: 'PE',
  },
];

const feed = await client.fetchMarketFeed(reqList);
console.log(feed);

Market feed by scrip

When you already know the scrip code, you can use fetchMarketFeedScrip.

const scripFeed = await client.fetchMarketFeedScrip([
  { Exch: 'N', ExchType: 'C', ScripCode: 2885 },
]);

Market status

const marketStatus = await client.getMarketStatus();
console.log(marketStatus);

Market depth and snapshot

// Market depth from the V3 endpoint
const depth = await client.fetchMarketDepth([
  { Exch: 'N', ExchType: 'C', ScripCode: 1660 },
]);

// Market depth by symbol
const depthBySymbol = await client.fetchMarketDepthBySymbol([
  {
    Exch: 'N',
    ExchType: 'C',
    Symbol: 'RELIANCE',
  },
]);

// Market depth by scrip convenience helper
const depthByScrip = await client.fetchMarketDepthByScrip({
  Exchange: 'N',
  ExchangeType: 'C',
  ScripCode: '1660',
});

// Full market snapshot for multiple scrips
const snapshot = await client.fetchMarketSnapshot([
  { Exchange: 'N', ExchangeType: 'C', ScripCode: '2885' },
  { Exchange: 'N', ExchangeType: 'C', ScripData: 'ITC_EQ' },
]);

Option chain

// Get all active expiries for a symbol
const expiries = await client.getExpiry('N', 'NIFTY');

// Pick one expiry timestamp from the response and fetch the option chain
const someExpiryTs = 1647507600000;
const optionChain = await client.getOptionChain('N', 'NIFTY', someExpiryTs);

Historical OHLC data

// historicalData(exch, exchangeSegment, scripCode, timeframe, from, to)
const candles = await client.historicalData(
  'N',
  'C',
  1660,
  '15m',
  '2021-05-25',
  '2021-06-16',
);

console.log(candles);

Accepted time frames: 1m, 3m, 5m, 10m, 15m, 30m, 60m, 1d.

Placing, modifying and cancelling orders

The core order placement APIs mirror those from py5paisa.

Basic cash order

import {
  FivePaisaClient,
  type FivePaisaCredentials,
  Exchange,
  ExchangeSegment,
} from '5paisa-ts';

// ... create credentials and client as shown earlier

await client.placeOrder({
  Exchange: Exchange.NSE,            // or 'N'
  ExchangeType: ExchangeSegment.CASH, // or 'C'
  ScripCode: 1660,
  Qty: 1,
  Price: 205,
  OrderType: 'B',                    // B for buy, S for sell
  IsIntraday: true,
});

Stop loss order

await client.placeOrder({
  Exchange: Exchange.NSE,
  ExchangeType: ExchangeSegment.CASH,
  ScripCode: 1660,
  Qty: 1,
  Price: 208,
  OrderType: 'B',
  IsIntraday: true,
  IsStopLossOrder: true,
  StopLossPrice: 207.5,
});

After market orders

Pass AHPlaced: AHPlaced.AFTER_MARKET_CLOSED for offline orders.

import { AHPlaced } from '5paisa-ts';

await client.placeOrder({
  Exchange: Exchange.NSE,
  ExchangeType: ExchangeSegment.CASH,
  ScripCode: 1660,
  Qty: 1,
  Price: 205,
  OrderType: 'B',
  IsIntraday: false,
  AHPlaced: AHPlaced.AFTER_MARKET_CLOSED,
});

Modify and cancel

// Modify an order
await client.modifyOrder({
  ExchOrderID: '1100000017861430',
  Price: 261,
});

// Cancel an order
await client.cancelOrder('1100000017795041');

// Cancel multiple regular orders in bulk
await client.cancelBulkOrder([
  { ExchOrderID: 'ORDER_ID_1' },
  { ExchOrderID: 'ORDER_ID_2' },
]);

Bracket and cover orders

// Bracket order
await client.boOrder({
  Exchange: 'N',
  ExchangeType: 'C',
  ScripCode: 1660,
  OrderType: 'B',
  Qty: 1,
  LimitPriceInitialOrder: 330,
  TriggerPriceInitialOrder: 0,
  LimitPriceProfitOrder: 345,
  TriggerPriceForSL: 320,
  RequestType: 'P',
  AtMarket: false,
});

// Modify bracket order
await client.modifyBoOrder({
  ExchangeOrderID: '1100000017861430',
  LimitPriceInitialOrder: 331,
  LimitPriceProfitOrder: 346,
});

// Cancel a bracket order leg
await client.cancelBoOrder({
  ExchangeOrderID: '1100000017861430',
});

// Cover order
await client.coverOrder({
  Exchange: 'N',
  ExchangeType: 'C',
  ScripCode: 1660,
  OrderType: 'B',
  Qty: 1,
  LimitPriceInitialOrder: 330,
  TriggerPriceForSL: 320,
});

// Modify cover order
await client.modifyCoverOrder({
  ExchangeOrderID: '1100000017861430',
  TriggerPriceForSL: 321,
});

// Cancel cover order leg
await client.cancelCoverOrder({
  ExchangeOrderID: '1100000017861430',
});

Note: for cover orders, using LimitPriceProfitOrder: 0 is equivalent to the Python behaviour.

Order margin calculation

Single order margin:

const marginResponse = await client.orderMargin({
  AtMarket: 'Y',
  LimitRate: 0,
  // other fields as per 5paisa order margin api
});

Multi leg margin for strategies:

const marginForMultipleOrders = await client.multiOrderMargin({
  CoverPositions: 'Y',
  Orders: [
    {
      Exch: 'N',
      ExchType: 'C',
      ScripCode: 2885,
      PlaceModifyCancel: 'P',
      OrderType: 'B',
      Price: 0,
      Qty: 1,
      IsIntraday: false,
    },
    {
      Exch: 'B',
      ExchType: 'C',
      ScripCode: 512070,
      PlaceModifyCancel: 'P',
      OrderType: 'S',
      Price: 0,
      Qty: 1,
      IsIntraday: true,
    },
  ],
});

Square off and position conversion

// Convert an existing position
await client.positionConversion(
  'N',          // Exch
  'C',          // ExchType
  'BPCL_EQ',    // ScripData
  'B',          // TradeType (B or S)
  5,            // ConvertQty
  'D',          // ConvertFrom (D or I)
  'I',          // ConvertTo (D or I)
);

// Square off all open positions
await client.squareoffAll();

Bulk order placement

const bulkOrderPayload = {
  Exchange: 'N',
  ExchangeType: 'C',
  OrderList: [
    {
      Exchange: 'N',
      ExchangeType: 'C',
      ScripCode: 0,
      ScripData: 'ITC_EQ',
      Price: '440',
      OrderType: 'Buy',
      Qty: 1,
      DisQty: '0',
      StopLossPrice: '0',
      IsIntraday: true,
      iOrderValidity: '0',
      RemoteOrderID: '50000091_220620',
    },
    {
      Exchange: 'N',
      ExchangeType: 'C',
      ScripCode: 0,
      ScripData: 'IDEA_EQ',
      Price: '15',
      OrderType: 'Buy',
      Qty: 1,
      DisQty: '0',
      StopLossPrice: '0',
      IsIntraday: true,
      iOrderValidity: '0',
      RemoteOrderID: '50000091_220620',
    },
  ],
};

await client.placeOrderBulk(bulkOrderPayload);

Basket orders

The SDK exposes a BasketOrder class and a family of basket helper methods.

import { BasketOrder } from '5paisa-ts';

// Create a new basket
await client.createBasket('My strategy basket');

// Get all baskets
const baskets = await client.getBasket();

// Rename a basket
await client.renameBasket('Renamed strategy basket', 1234);

// Clone an existing basket
await client.cloneBasket(1234);

// Delete baskets in bulk
await client.deleteBasket([
  { BasketID: '1234' },
  { BasketID: '5678' },
]);

// Add an order to one or more baskets
const orderToBasket = new BasketOrder({
  Exchange: 'N',
  ExchangeType: 'C',
  Price: 23000,
  OrderType: 'BUY',
  Qty: 1,
  ScripCode: '1660',
  DelvIntra: 'I',
});

const basketList = [
  { BasketID: '1234' },
  { BasketID: '5678' },
];

await client.addBasketOrder(orderToBasket, basketList);

// Execute a basket
await client.executeBasket(1234);

// Get orders inside a basket
const ordersInBasket = await client.getOrderInBasket(1234);

// Margin required for a basket
const basketMargin = await client.basketMargin('1234', 'Y');

Order status, trades and history

// Trade information
const tradeInfoRequest = [
  {
    Exch: 'N',
    ExchType: 'C',
    ScripCode: 20374,
    ExchOrderID: '1000000015310807',
  },
];

const tradeInfo = await client.fetchTradeInfo(tradeInfoRequest);

// Order status
const orderStatusRequest = [
  {
    Exch: 'N',
    ExchType: 'C',
    ScripCode: 20374,
    RemoteOrderID: '90980441',
  },
];

const orderStatus = await client.fetchOrderStatus(orderStatusRequest);

// Trade history by exchange order id
const history = await client.getTradeHistory('1000000015310807');

WebSocket streaming

WebSocket streaming closely follows the Python Request_Feed, connect and receive_data helpers.

Subscribe to one or more scrips

import {
  FivePaisaClient,
  type FivePaisaCredentials,
} from '5paisa-ts';

const credentials: FivePaisaCredentials = {
  APP_NAME: 'YOUR_APP_NAME',
  APP_SOURCE: 'YOUR_APP_SOURCE',
  USER_ID: 'YOUR_USER_ID',
  PASSWORD: 'YOUR_PASSWORD',
  USER_KEY: 'YOUR_USER_KEY',
  ENCRYPTION_KEY: 'YOUR_ENCRYPTION_KEY',
};

const client = new FivePaisaClient(credentials);

// Authenticate first using OAuth or TOTP so that jwtToken and clientCode are set
await client.getOauthSession('REQUEST_TOKEN');

const subscribeList = [
  { Exch: 'N', ExchType: 'C', ScripCode: 1660 },
  { Exch: 'N', ExchType: 'D', ScripCode: 61211 },
];

const payload = client.requestFeed('mf', 's', subscribeList);

client.connect(payload);

client.receiveData((event) => {
  const data = JSON.parse(event.data as string);
  console.log('Tick', data);
});

Unsubscribe and close

// Unsubscribe from specific scrips
const unsubscribePayload = client.requestFeed('mf', 'u', [
  { Exch: 'N', ExchType: 'C', ScripCode: 1660 },
]);

client.connect(unsubscribePayload);

// Close websocket
client.closeData();

You can also use sendData to attach a custom onopen handler and errorData to attach an error handler.

20 depth market data

The socket20Depth helper maps to the Python socket_20_depth utility.

const depthPayload = {
  method: 'subscribe',
  operation: '20depth',
  instruments: ['NC2885'],
};

await client.socket20Depth(depthPayload);

client.receiveData((event) => {
  const data = JSON.parse(event.data as string);
  console.log('Depth 20 tick', data);
});

Strategy execution (Strategies class)

The Strategies class is a TypeScript port of py5paisa.strategy.strategies. It executes multi leg strategies as market orders; use it with care.

import {
  Strategies,
  type FivePaisaCredentials,
} from '5paisa-ts';

const credentials: FivePaisaCredentials = {
  APP_NAME: 'YOUR_APP_NAME',
  APP_SOURCE: 'YOUR_APP_SOURCE',
  USER_ID: 'YOUR_USER_ID',
  PASSWORD: 'YOUR_PASSWORD',
  USER_KEY: 'YOUR_USER_KEY',
  ENCRYPTION_KEY: 'YOUR_ENCRYPTION_KEY',
};

// Use either requestToken or clientCode + TOTP + PIN
const strategy = new Strategies(credentials, 'CLIENT_CODE', 'TOTP_VALUE', 'PIN');

// Each of the following executes a full strategy at market
await strategy.shortStraddle('banknifty', '37000', 50, '20210610', 'I', {
  tag: 'MyShortStraddle',
});

await strategy.shortStrangle('banknifty', ['35300', '37000'], 50, '20210610', 'D', {
  tag: 'MyShortStrangle',
});

await strategy.longStraddle('banknifty', '37000', 50, '20210610', 'I', {
  tag: 'MyLongStraddle',
});

await strategy.longStrangle('banknifty', ['35300', '37000'], 50, '20210610', 'D', {
  tag: 'MyLongStrangle',
});

await strategy.ironCondor('NIFTY', ['15000', '15200'], ['15100', '15150'], 75, '20210603', 'I', {
  tag: 'MyIronCondor',
});

await strategy.ironFly('NIFTY', ['15000', '15200'], '15100', 75, '20210610', 'I', {
  tag: 'MyIronFly',
});

await strategy.callCalendar('nifty', '15600', 75, ['20210603', '20210610'], 'I', {
  tag: 'MyCallCalendar',
});

await strategy.putCalendar('nifty', '15600', 75, ['20210603', '20210610'], 'I', {
  tag: 'MyPutCalendar',
});

// Square off all legs that were tagged with a given strategy tag
await strategy.squareoff('MyIronCondor');

Strategies methods covered:

• shortStraddle
• shortStrangle
• longStraddle
• longStrangle
• ironFly
• ironCondor
• callCalendar
• putCalendar
• squareoff

Types, enums and helper classes

The SDK exports several enums and classes to help you build strongly typed payloads.

Order related enums

import {
  Exchange,
  ExchangeSegment,
  OrderFor,
  OrderSide,
  OrderValidity,
  AHPlaced,
  RequestType,
} from '5paisa-ts';

// Examples
const ex = Exchange.NSE;            // 'N'
const seg = ExchangeSegment.DERIVATIVE; // 'D'
const side = OrderSide.BUY;        // 'BUY'
const validity = OrderValidity.DAY; // 0

Order, BoCoOrder and BasketOrder classes

import {
  Order,
  BoCoOrder,
  BasketOrder,
} from '5paisa-ts';

const order = new Order({
  exchange: Exchange.NSE,
  exchangeSegment: ExchangeSegment.CASH,
  price: 205,
  orderType: 'B',
  quantity: 1,
  scripCode: 1660,
  isIntraday: true,
});

const bracket = new BoCoOrder({
  scripCode: 1660,
  qty: 1,
  limitPriceInitialOrder: 330,
  triggerPriceInitialOrder: 0,
  limitPriceProfitOrder: 345,
  buySell: 'B',
  exch: 'N',
  exchType: 'C',
  requestType: 'P',
  limitPriceForSL: 320,
  triggerPriceForSL: 320,
});

const basketOrder = new BasketOrder({
  Exchange: 'N',
  ExchangeType: 'C',
  Price: 23000,
  OrderType: 'BUY',
  Qty: 1,
  ScripCode: '1660',
  DelvIntra: 'I',
});

These classes mirror the structure of the Python SDK and are primarily useful for building complex orders or reusing payloads.

Low level constants

Advanced users can also import the following from 5paisa-ts for custom integrations:

• HEADERS, GENERIC_PAYLOAD, LOGIN_PAYLOAD, LOGIN_CHECK_PAYLOAD
• WS_PAYLOAD, JWT_HEADERS, JWT_PAYLOAD, SOCKET_DEPTH_PAYLOAD
• VTT_TYPE, SUBSCRIPTION_KEY, TODAY_TIMESTAMP, NEXT_DAY_TIMESTAMP
• All route constants from urlconst.ts such as BASE_URL, LOGIN_ROUTE, SCRIP_MASTER_ROUTE, ORDER_PLACEMENT_ROUTE, HISTORICAL_DATA_ROUTE, MARKET_FEED_ROUTE, etc.

These are not required for normal usage, but are exported for completeness and advanced scenarios.

Complete FivePaisaClient api overview

For quick reference, the public methods on FivePaisaClient are:

• Authentication and session

  • getRequestToken
  • getOauthSession
  • getAccessToken
  • getTotpSession
  • setAccessToken
  • loginCheck
  • jwtValidate

• Scrip master

  • getScrips
  • queryScrips

• User information and reports

  • holdings
  • margin
  • orderBook
  • positions
  • positionsDay
  • getTradebook
  • getBuy
  • getTrade
  • taxReport
  • fetchLedger

• Market data

  • fetchMarketFeed
  • fetchMarketFeedScrip
  • fetchMarketDepth
  • fetchMarketDepthBySymbol
  • fetchMarketDepthByScrip
  • fetchMarketSnapshot
  • getMarketStatus
  • historicalData
  • getExpiry
  • getOptionChain

• Orders and positions

  • placeOrder
  • modifyOrder
  • cancelOrder
  • cancelBulkOrder
  • orderMargin
  • multiOrderMargin
  • placeOrderBulk
  • positionConversion
  • squareoffAll
  • vttOrder

• Basket orders

  • getBasket
  • createBasket
  • renameBasket
  • deleteBasket
  • cloneBasket
  • executeBasket
  • getOrderInBasket
  • addBasketOrder
  • basketMargin

• Order status, trades and history

  • fetchOrderStatus
  • fetchTradeInfo
  • getTradeHistory

• WebSocket and streaming

  • requestFeed
  • connect
  • sendData
  • receiveData
  • closeData
  • errorData
  • socket20Depth

This README, combined with the examples above, provides usage coverage for all of these methods as well as all exported strategy functions and helper types.