Superr API - Instruments

Instruments and Market Quotes:

Methods	APIs	Endpoint	Description
GET	Instrument list API (download in json)	/scrip-master	Retrive the json dump file for all instruments
GET	Instrument list API (download in CSV)	/scrip-master/csv	Retrive the CSV dump file all instruments
GET	Exchange wise instrument list API (download in json)	/scrip-master/exchange	Retrieve the json dump of instruments in the particular exchange (i.e. nse,bse,nfo,mcx,nsecd)
GET	Exchange wise instrument list API (download in CSV)	/scrip-master/csv/exchange	Retrieve the CSV dump of instruments in the particular exchange (i.e. nse,bse,nfo,mcx,nsecd)
POST	Market quotes API	/quotes	Retrive market quotes for one or more instruments
POST	OHLC quotes API	/quotes/ohlc	Retrive OHLC quotes for one or more instruments
POST	LTP quotes API	/quotes/ltp	Retrive LTP quotes for one or more instruments

Instruments

There are thousands of different kinds of instruments traded in between multiple exchanges & segments. Any application that facilitates trading needs to have a master list of these instruments. The instruments API provides a consolidated, import-ready CSV or json format list of instruments available for trading.

Fetching the full instrument list:

The instrument list API returns a gzipped CSV or json dump of instruments across all exchanges that can be imported into a database. The dump is generated once every day and hence last_price is not real time.

Sample Response

exchange,market_segment_id,token,symbol,symbol_description,series,instrument_type,option_type,expiry_date,lot_size,strike_price,isin_code,tick_size
NSE,1,17939,HINDCOPPER,HINDUSTAN COPPER LTD,EQ,EQUITIES,,,1,0,INE531E01026,5
BSE,3,535693,BRAHMINFRA,BRAHMAPUTRA INFRASTRUCTUR,X,EQUITIES,,,1,0,INE320I01017,1
NFO,2,79291,INDIAMART,INDIAMART23JUN2120PE,,OPTSTK,PE,28-06-2023,300,212000,,5
NSECD,13,2522,JPYINR,JPYINR2391554.25PE,,OPTCUR,PE,15-09-2023,1000,542500000,,25000
MCX,5,249565,GOLD,GOLD.995,,OPTFUT,CE,26-09-2023,1,5710000,,50

CSV response columns:-

Parameters	Description
exchange	Name of the exchange
market_segment_id	Market segment id that instruments belongs to
token	Symbol token is unique identifier
symbol	Exchange trading symbol of the instrument
symbol_description	Trading symbol description
series	Exchange provided security series
instrument_type	Type of contract
option_type	Applicable of options only
expiry_date	Expiry date of contracts(applicable for options only)
lot_size	Quantity of a single lot
strike_price	Srike price for scrip (applicable for options only)
isin_code	12 digit code that assignes to every security issuance
tick_size	Value of a single

Note:-

For storage, it is recommended to use a combination of exchange and trading symbol as the unique key, not the numeric instrument token. Exchanges may reuse instrument tokens for different derivative instruments after each expiry.
The instrument list API returns large amounts of data. It's good to request it once a day (ideally at around 08:30 AM) and store in a database at your end.

Retrieving full market quotes

This API returns the complete market data screenshot of up to 50 instruments in one go.It includes the last trade time,quantity,volume, average price,OHLC, Open Interest fields and the complete bid/ask market depth amongst others.

Instruments are identified by the “exchange":"exchange_name" and "token":"token of trading symbol" combination and are passed as values to the query parameter which is repeated for every instrument.

Sample Request (Body)

{
  "exchange": "NSE",
  "tokens": ["11536"]
}

Sample Response

{
  "status": "success",
  "data": [
    {
      "exchange": "NSE",
      "token": "11536",
      "last_trade_time": "12/07/2023 11:51:35",
      "last_trade_price": "3267.2",
      "last_trade_quantity": "5",
      "buy_quantity": "269",
      "buy_price": "3267.2",
      "sell_quantity": "2",
      "sell_price": "3267.3",
      "volume": "536535",
      "average_price": "3268.53",
      "open_interest": "0",
      "net_change_price": "-5.20000000000027",
      "percent_change": "-0.16",
      "ohlc": {
        "open": "3280.95",
        "high": "3289.15",
        "low": "3260",
        "close": "3272.4"
      },
      "depth": {
        "buy": [
          {
            "price": "3267.2",
            "quantity": "269",
            "orders": "1"
          },
          {
            "price": "3266.15",
            "quantity": "1",
            "orders": "1"
          },
          {
            "price": "3266.1",
            "quantity": "36",
            "orders": "2"
          },
          {
            "price": "3266.05",
            "quantity": "29",
            "orders": "4"
          },
          {
            "price": "3266",
            "quantity": "1",
            "orders": "1"
          }
        ],
        "sell": [
          {
            "price": "3267.3",
            "quantity": "2",
            "orders": "2"
          },
          {
            "price": "3267.5",
            "quantity": "1",
            "orders": "1"
          },
          {
            "price": "3267.55",
            "quantity": "27",
            "orders": "1"
          },
          {
            "price": "3267.6",
            "quantity": "10",
            "orders": "1"
          },
          {
            "price": "3267.7",
            "quantity": "13",
            "orders": "1"
          }
        ]
      }
    }
  ]
}

Response parameters

Parameters	Descriptions
exchange	Exchange name
token	The numerical identifier issued by the exchange representing the instrument
last_trade_time	Last trade timestamp
last_trade_price	Last traded market price
last_trade_quantity	Last traded quantity
buy_quantity	Total quantity of buy orders pending at the exchange
buy_price	Buy price
sell_quantity	Total quantity of sell orders pending at the exchange
sell_price	Sell price
volume	Volume traded today
average_price	The volume weighted average price of a stock at a given time during the day
open_interest	Total number of outstanding contracts held by market participants exchange-wide (only F&O)
net_change_price	The absolute change from yesterday's close to last traded price
percent_change	The net change from yesterday's close to last traded price
ohlc.open	Price at market opening
ohlc.high	Highest price today
ohlc.low	Lowest price today
ohlc.close	Closing price of the instrument from the last trading day
depth.buy_price	Price at which the depth stands
depth.buy_quantity	Net quantity from the pending orders
depth.buy_orders	Number of open BUY (bid) orders at the price
depth.sell_price	Price at which the depth stands
depth.sell_quantity	Net quantity from the pending orders
depth.sell_orders	Number of open SELL (ask) orders at the price

Retrieving OHLC quotes

This API returns the OHLC + LTP snapshots of up to 50 instruments in one go.

Sample Request (Body)

{
  "exchange": "NSE",
  "tokens": ["11536"]
}

Sample Response

{
  "status": "success",
  "data": [
    {
      "exchange": "NSE",
      "token": "11536",
      "last_trade_time": "12/07/2023 11:51:44",
      "last_trade_price": "3267.3",
      "volume": "536558",
      "net_change_price": "-5.09999999999991",
      "percent_change": "-0.16",
      "ohlc": {
        "open": "3280.95",
        "high": "3289.15",
        "low": "3260",
        "close": "3272.4"
      }
    }
  ]
}

Response Parameters

Parameters	Descriptions
exchange	Exchange name
token	The numerical identifier issued by the exchange representing the instrument
last_trade_time	Last trade timestamp
last_trade_price	Last traded market price
volume	Volume traded today
net_change_price	The absolute change from yesterday's close to last traded price
percent_change	The net change from yesterday's close to last traded price
ohlc.open	Price at market opening
ohlc.high	Highest price today
ohlc.low	Lowest price today
ohlc.close	Closing price of the instrument from the last trading day

Retrieving LTP quotes

This API returns the LTPs of up to 50 instruments in one go.

Sample Request (Body)

{
  "exchange": "NSE",
  "tokens": ["11536"]
}

Sample Response

{
  "status": "success",
  "data": [
    {
      "exchange": "NSE",
      "token": "11536",
      "last_trade_price": "3266.4",
      "volume": "536919",
      "net_change_price": "-6",
      "percent_change": "-0.18"
    }
  ]
}

Response Parameters

Parameters	Descriptions
exchange	Exchange name
token	The numerical identifier issued by the exchange representing the instrument
last_trade_price	Last traded market price
volume	Volume traded today
net_change_price	The absolute change from yesterday's close to last traded price
percent_change	The net change from yesterday's close to last traded price