Get Instruments¶

Python SDK V3 New

Use this reference-data page when building with Nubra Python SDK 0.4.5 and testing V3 payloads.

The resolved instruments, ref_id values, and exchange filters here feed directly into downstream V3 order, margin, and realtime examples.

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

exchange can be NSE, BSE, or MCX. If you do not pass an exchange, the default is NSE.

from nubra_python_sdk.refdata.instruments import InstrumentData
from nubra_python_sdk.start_sdk import InitNubraSdk, NubraEnv
from nubra_python_sdk.trading.trading_enum import TradingAPIVersion

# Initialize the SDK client.
# Use NubraEnv.UAT for testing.
# For SDK 0.4.5 V3 testing, enable the trading flag explicitly.
nubra = InitNubraSdk(
    NubraEnv.UAT,
    env_creds=True,
    trading_version=TradingAPIVersion.V3,
)

instruments = InstrumentData(nubra)

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

# Get one instrument by ref_id.
instrument = instruments.get_instrument_by_ref_id(71878, exchange="NSE")
print(instrument)

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

# Get one instrument by Nubra internal name.
instrument = instruments.get_instrument_by_nubra_name("STOCK_HDFCBANK.NSECM", exchange="NSE")
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)

For SDK 0.4.5, keep the same client initialization pattern throughout downstream order examples. The account-side Sentinel/OMS flag must also be enabled for V3 trading requests.

Exchange Examples¶

Use the same methods for NSE, BSE, and MCX. The only change is the exchange you pass.

NSEBSEMCX

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)

nse_df = instruments.get_instruments_dataframe(exchange="NSE")
print(nse_df.tail(10))

hdfc = instruments.get_instrument_by_symbol("HDFCBANK", exchange="NSE")
print(hdfc)

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)

bse_df = instruments.get_instruments_dataframe(exchange="BSE")
print(bse_df.tail(10))

hdfc = instruments.get_instrument_by_symbol("HDFCBANK", exchange="BSE")
print(hdfc)

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

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

mcx_df = instruments.get_instruments_dataframe(exchange="MCX")
print(mcx_df.tail(10))

crudeoil_rows = mcx_df[mcx_df["asset"] == "CRUDEOIL"]
print(crudeoil_rows.tail(10))

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`, optional `exchange`	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, optional `exchange`	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

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.
exchange can be NSE, BSE, or MCX.
get_instruments_dataframe() loads NSE instruments by default.
Pass exchange="BSE" or exchange="MCX" explicitly when you want those instrument masters.
get_instrument_by_ref_id() can resolve globally when exchange is omitted, but pass exchange explicitly when you want deterministic exchange-specific lookups.
get_instrument_by_nubra_name() and get_instrument_by_symbol() default to the NSE instrument maps when exchange is omitted.
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.
For derivative rows, the asset column is the underlying name to carry into option-chain snapshot or realtime option subscriptions.
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: