Get Instruments¶

Use InstrumentData to resolve tradable instruments and fetch the instruments master as a pandas DataFrame. This is the main reference page to use before generating quote, market-data, WebSocket, or order code.

What This Page Covers¶

This page covers two reference-data sources:

Instruments Master Tradable exchange instruments such as stocks, futures, and options.
Index Master Public index metadata such as NIFTY and BANKNIFTY.

Use the Instruments Master for orders, quotes, and WebSocket subscriptions.
Use the Index Master for index-aware logic, dashboards, and symbol mapping.

LLM guidance

Use this page before generating order or quote examples. Do not invent ref_id values from symbols. Resolve the instrument first, then carry ref_id, tick_size, and lot_size into downstream workflows.

When To Use This Page¶

Use this page when you need to:

resolve a trading symbol into a Nubra instrument record
fetch ref_id for quote and trading workflows
inspect lot_size, tick_size, expiry, and option metadata
filter instruments by exchange, asset, derivative type, or option fields
fetch supported index metadata

Walkthrough Video¶

If the embedded video does not load, watch it on YouTube: Get Instruments Walkthrough

Basic Usage¶

The SDK automatically fetches the tradable instruments master and keeps it available locally as a pandas DataFrame. This gives you a local source for market-data and trading workflows without repeated manual lookups.

Exchange behavior

By default, the instruments cache loads NSE instruments.
To work with BSE instruments, pass exchange="BSE" explicitly.

from nubra_python_sdk.refdata.instruments import InstrumentData
from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

# Initialize the SDK client.
# Use NubraEnv.UAT for testing and NubraEnv.PROD for production.
nubra = InitNubraSdk(NubraEnv.UAT, env_creds=True)

instruments = InstrumentData(nubra)

# Get all instruments as a pandas DataFrame.
instruments_df = instruments.get_instruments_dataframe()
print(f"Total instruments: {len(instruments_df)}")

# Get one instrument by ref_id.
instrument = instruments.get_instrument_by_ref_id(71878)
print(instrument)

# Get one instrument by exchange trading symbol.
instrument = instruments.get_instrument_by_symbol("HDFCBANK", exchange="BSE")
print(instrument)

# Get one instrument by Nubra internal name.
instrument = instruments.get_instrument_by_nubra_name("STOCK_HDFCBANK.NSECM")
print(instrument)

# Fetch matching instruments with structured filters.
matches = instruments.get_instruments_by_pattern([
    {
        "exchange": "NSE",
        "asset": "NIFTY",
        "derivative_type": "OPT",
        "expiry": "20260217",
        "strike_price": "2580000",
        "option_type": "CE",
        "asset_type": "INDEX_FO"
    }
])
print(matches)

SDK Surface¶

from nubra_python_sdk.refdata.instruments import InstrumentData

InstrumentData.get_instruments_dataframe(exchange=None)
InstrumentData.get_instrument_by_ref_id(ref_id, exchange=None)
InstrumentData.get_instrument_by_symbol(instr, exchange=None)
InstrumentData.get_instrument_by_nubra_name(nubra_name)
InstrumentData.get_instruments(
    exchange=None,
    asset=None,
    derivative_type=None,
    asset_type=None,
    expiry=None,
    strike_price=None,
    option_type=None,
    isin=None,
)
InstrumentData.get_instruments_by_pattern(request)

Main Methods¶

Method	Input	Returns	Best use case
`get_instruments_dataframe()`	optional `exchange`	pandas DataFrame	local filtering and dashboards
`get_instrument_by_ref_id()`	`ref_id`	one instrument object	quote and trade lookups
`get_instrument_by_symbol()`	trading symbol	one instrument object	common stock or derivative lookup
`get_instrument_by_nubra_name()`	Nubra internal name	one instrument object	internal mappings
`get_instruments()`	structured filters	filtered result set	scanners and discovery
`get_instruments_by_pattern()`	list of request dictionaries	filtered result set	deterministic batch lookup

Instruments Master¶

The Instruments Master is typically used for:

getting the Nubra ref_id required in downstream APIs
mapping instruments in real-time or option-chain workflows
retrieving lot_size, tick_size, expiry, and derivative metadata

# NSE instruments (default)
instruments_df = instruments.get_instruments_dataframe()

# BSE instruments (explicit)
instruments_df = instruments.get_instruments_dataframe(exchange="BSE")

Filtered Lookup Example¶

Use get_instruments() or DataFrame filtering when you need multiple matching instruments instead of a single exact lookup.

from nubra_python_sdk.refdata.instruments import InstrumentData
from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv

nubra = InitNubraSdk(NubraEnv.UAT, env_creds=True)
instruments = InstrumentData(nubra)

results = instruments.get_instruments(
    exchange="NSE",
    asset="HDFCBANK",
    derivative_type="STOCK",
)

print(results)

Response Fields¶

These fields are commonly used in downstream workflows:

Field	Type	Nullable	Meaning
`ref_id`	`int`	no	Nubra internal instrument identifier used by other APIs
`stock_name`	`str`	no	trading symbol
`nubra_name`	`str`	no	Nubra internal instrument name
`asset`	`str`	no	underlying asset name
`exchange`	`str`	no	exchange
`derivative_type`	`str`	yes	broad instrument category
`asset_type`	`str`	yes	grouping such as `STOCKS` or `INDEX_FO`
`expiry`	`int`	yes	derivative expiry
`strike_price`	`int`	yes	strike in exchange-native units
`option_type`	`str`	yes	`CE`, `PE`, or non-option marker
`lot_size`	`int`	yes	minimum tradable quantity
`tick_size`	`int`	yes	minimum price increment
`underlying_prev_close`	`int`	yes	underlying previous close

Reference Response Shape¶

class Instrument:
    ref_id: int
    strike_price: int
    option_type: str
    token: int
    stock_name: str
    nubra_name: str
    lot_size: int
    asset: str
    expiry: int
    exchange: str
    derivative_type: str
    isin: str
    asset_type: str
    tick_size: int
    underlying_prev_close: int

Index Master¶

In addition to tradable instruments, Nubra provides a public Index Master for supported indices and their metadata.

Use the Index Master for:

discovering supported indices such as NIFTY and BANKNIFTY
mapping index names to market-data symbols
building dashboards and index-aware logic

The Index Master is a public CSV endpoint and does not require authentication.

import requests
import csv
from io import StringIO

INDEX_URL = "https://api.nubra.io/public/indexes?format=csv"

def fetch_indices_master():
    response = requests.get(INDEX_URL, timeout=10)
    response.raise_for_status()

    csv_buffer = StringIO(response.text)
    reader = csv.DictReader(csv_buffer)
    return list(reader)

indices = fetch_indices_master()
print(f"Total indices fetched: {len(indices)}")
print(indices)

Rules And Best Practices¶

Resolve the instrument before placing orders or calling quote APIs.
Use ref_id for quote and order workflows when possible.
Persist lot_size and tick_size with the selected instrument.
Treat the Index Master as metadata only, not as tradable instruments.
Refresh local caches periodically if your workflow depends on daily contract changes.

Important Rules

UAT and PROD can have different ref_id values. Do not reuse a ref_id from one environment in the other.
Resolve instruments separately in each environment before calling market-data or trading workflows.
ref_id is required in several downstream quote, market-data, real-time, and trading workflows.
get_instruments_dataframe() loads NSE instruments by default.
Pass exchange="BSE" explicitly if you want the DataFrame for BSE instruments.
The instruments master is intended for currently tradable instruments and live workflow metadata.
Use fields such as lot_size, tick_size, expiry, option_type, and asset_type for validation and order construction.
Do not hardcode instrument assumptions when symbol resolution is available through the SDK.

What To Read Next¶

After instrument resolution, the most common next pages are: