Instruments

Find the instrument token to trade, its lot size and expiries.

Search instruments #

GET /v1/instruments scope read

Searches today's instrument list.

More about this

Give q or at least one filter. q is matched literally and case-insensitively (no wildcards): exact trading symbol first, then symbol prefix, then a word prefix of the name or underlying; every word of a multi-word q must match. Filters are exact (case-insensitive). At most limit items (default 20, at most 100) per page; when more match, next_cursor fetches the next page (send it as cursor with the same parameters).

exchange is the catalog's exchange as this route returns it: futures and options (index and stock) are listed under NSE / BSE (e.g. NIFTY / SENSEX options), which is the value an item carries here. exchange=NFO / BFO is accepted too and finds the futures and options listed under NSE / BSE.

Parameters

q query · string

Search text (at most 64 characters).
exchange query · string

Exchange as this route returns it (NSE, BSE, MCX, ...); futures and options are under NSE / BSE. NFO / BFO find the futures and options listed under NSE / BSE.
underlying query · string

Exact underlying symbol, e.g. NIFTY (not a prefix).
instrument query · string

Instrument type, e.g. EQUITY, OPTIDX, FUTSTK.
expiry query · string

Expiry date YYYY-MM-DD.
strike query · number (double)

Strike price.
option_type query · string

CE or PE.
limit query · integer (int32)

Most items to return (default 20; above 100 means 100).
cursor query · string

next_cursor of the previous page (opaque).

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

GET

curl "https://cirrus.pocketful.in/v1/instruments" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/instruments",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/instruments', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "items": [
      {
        "exchange": "NSE",
        "instrument": "EQUITY",
        "exchange_token": "2885",
        "lot_size": 1,
        "expiry": null,
        "strike": null,
        "option_type": null,
        "tick_size": 0.1,
        "underlying_symbol": "RELIANCE",
        "isin": "INE002A01018",
        "freeze_qty": 81195,
        "name": "RELIANCE",
        "tradingsymbol": "RELIANCE",
        "sector": "Oil Gas & Consumable Fuels",
        "indices": [
          "NIFTY",
          "NIFTY100",
          "NIFTYENERGY"
        ],
        "instrument_token": "CT:1:2:RELIANCE-EQ"
      },
      {
        "exchange": "BSE",
        "instrument": "EQUITY",
        "exchange_token": "500325",
        "lot_size": 1,
        "expiry": null,
        "strike": null,
        "option_type": null,
        "tick_size": 0.05,
        "underlying_symbol": "RELIANCE",
        "isin": "INE002A01018",
        "freeze_qty": null,
        "name": "RELIANCE",
        "tradingsymbol": "RELIANCE",
        "sector": "Oil Gas & Consumable Fuels",
        "indices": [
          "NIFTY",
          "NIFTY100",
          "NIFTYENERGY"
        ],
        "instrument_token": "CT:2:2:RELIANCE-A"
      }
    ],
    "count": 2,
    "next_cursor": "2-839b1b69914e"
  },
  "error": null
}

Download the instrument list (CSV) #

GET /v1/instruments.csv scope read

Today's full instrument list as one CSV file (UTF-8, header row), gzip-compressed when the request accepts it (Accept-Encoding: gzip).

More about this

Send the ETag back in If-None-Match (or Last-Modified in If-Modified-Since) to get 304 Not Modified while it is unchanged; validators are the same on every server.

Columns (find them by header name; new columns may be added): the instrument id (under its legacy name; the same value as instrument_token), exchange, instrument (type), exchange_token, lot_size, expiry (YYYY-MM-DD), strike, option_type (CE / PE), tick_size, underlying_symbol, isin, freeze_qty, name, tradingsymbol, sector, indices (|-separated). Empty cells mean no value; numbers may be written with a decimal point (1.0).

Parameters

If-None-Match header · string

An ETag received earlier.
If-Modified-Since header · string

A Last-Modified received earlier.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

GET

curl "https://cirrus.pocketful.in/v1/instruments.csv" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/instruments.csv",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/instruments.csv', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Expiry dates of an underlying #

GET /v1/instruments/expiries scope read

Distinct expiry dates of every contract (futures and options) on underlying in today's instrument list, earliest first.

More about this

exchange narrows to the exchange the list gives the contracts (index options: NSE / BSE).

Parameters

underlying query · string required

Exact underlying symbol, e.g. NIFTY.
exchange query · string

Only contracts on this exchange, as GET /v1/instruments returns it (NFO / BFO mean the contracts listed under NSE / BSE).

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
422	invalid_request	The request is well-formed but not valid; `field` names the input.
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	instruments_unavailable	The instrument master is not loaded yet; retry shortly.

All fields (request and response schema)

Loading fields…

GET

curl "https://cirrus.pocketful.in/v1/instruments/expiries?underlying=<underlying>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/instruments/expiries",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    params={
        "underlying": "<underlying>",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/instruments/expiries?underlying=<underlying>', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "underlying": "FINNIFTY",
    "expiries": [
      "2026-10-27"
    ]
  },
  "error": null
}

One instrument #

GET /v1/instruments/{instrument_token} scope read

The instrument with this id, from today's instrument list, else from the live instrument master (fields it lacks are null).

Parameters

instrument_token path · string required

Instrument id.

Errors

HTTP	Code	When
401	unauthorized	No credential, or the credential is invalid, expired or revoked.
403	forbidden	The credential may not use this route (missing scope, app-session-only route, IP not allowed).
404	instrument_not_found	No instrument with this token (unknown or expired).
429	rate_limited	Too many requests for this credential (or too many failed attempts); retry after the `Retry-After` header (seconds; `error.retry_after_ms` has the exact wait).
503	service_unavailable	A dependency is temporarily unavailable, or the feature is off on this server; retry later.

All fields (request and response schema)

Loading fields…

GET

curl "https://cirrus.pocketful.in/v1/instruments/<instrument_token>" \
  -H "Authorization: token $CIRRUS_API_KEY"

import os

import requests

response = requests.get(
    "https://cirrus.pocketful.in/v1/instruments/<instrument_token>",
    headers={
        "Authorization": f"token {os.environ['CIRRUS_API_KEY']}",
    },
    timeout=10,
)
print(response.status_code, response.json())

const response = await fetch('https://cirrus.pocketful.in/v1/instruments/<instrument_token>', {
  method: 'GET',
  headers: {
    Authorization: `token ${process.env.CIRRUS_API_KEY}`,
  },
});
const body = await response.json();
console.log(response.status, body);

Response · 200

{
  "status": "success",
  "data": {
    "exchange": "NSE",
    "instrument": "OPTIDX",
    "exchange_token": "50319",
    "lot_size": 60,
    "expiry": "2026-10-27",
    "strike": 25000,
    "option_type": "CE",
    "tick_size": 0.05,
    "underlying_symbol": "FINNIFTY",
    "isin": null,
    "freeze_qty": 1801,
    "name": "FINNIFTY",
    "tradingsymbol": "FINNIFTY27OCT202625000CE",
    "sector": null,
    "indices": [],
    "instrument_token": "CT:1:6:FINNIFTY27OCT202625000CE"
  },
  "error": null
}