Instruments
In addition to real-time and historical market data, the Developer API provides instruments files—lists containing trading symbols, exchange codes, tokens, and other metadata. These files are typically updated on a daily basis, ensuring you always have the most current mapping of instruments for:
- Equities (NSE, BSE)
- Futures & Options (NFO, BFO)
- Other segments (Indices, etc.)
Having a local or cached copy of these instrument files is extremely useful for validating user inputs (e.g., a tradingSymbol), auto-completing symbol searches, or building watchlists.
Files Format
Common File Types & Columns
- CSV: The instrument files are often provided in CSV format, easily downloadable via an endpoint or link.
- Fields / Columns:
- Token: An internal numeric identifier recognized by the API.
- Exchange: E.g., "NSE", "BSE", "NFO", "BFO".
- Trading Symbol: The symbol used in API calls (e.g., "RELIANCE-EQ", "NIFTY06JUL25C15000").
- Instrument Name: "Equity", "FUTSTK", "OPTIDX", etc.
- Expiry (for derivatives): Expiry date or code, often in DDMONYYYY format.
- Lot Size (for F&O): The number of shares per lot.
Usage & Parsing
- Download & Store: Typically, you’ll download these files daily, store them locally (in a database or CSV format), then parse for quick lookups.
- Mapping: Use the token or tradingSymbol to integrate with other endpoints (quotes, option chains, order placement).
- Validation: Check if a user-supplied symbol actually exists in the file before sending an API request.
File Update Every Day
Frequency & Timing
- Daily Refresh: The instrument files are generally refreshed once every trading day, capturing new listings, expired contracts, or renamed symbols.
- Update Schedule: Look for an official update time (e.g., early morning before market open) in the documentation or from support announcements.
Automation
- Cron Jobs: Consider setting up a early-morning cron job to download the latest CSV.
- Version Control: Keep older files if needed for auditing or historical references, but note that they can quickly grow in size.
- Performance Considerations: If your application deals with thousands of symbols, parse and index them in a local database for faster lookups.
Data Types
Instrument Fields
- Token (integer)
- Internal numeric code, used in certain quote or order requests.
- Example: 26000 for “NIFTY” index.
- TradingSymbol (string)
- “Human-readable” symbol used in tradingSymbol API fields.
- Example: "IDEA-EQ", "NIFTY24APR25C22500".
- Exchange (string)
- "NSE", "BSE", "NFO", "BFO", or "INDEX" for certain lists.
- Instrument Name (string)
- "Equity", "FUTSTK", "OPTSTK", "OPTIDX", etc.
- Expiry (string, optional)
- Present for derivatives, e.g., "27APR2025".
- Lot Size (integer, optional)
- E.g., 75 for NIFTY options/futures.
Parsing & Validation
- Convert numeric fields (token, lot size) from strings if your CSV parser reads everything as text.
- Watch for optional fields (like expiry or lot size) which might be blank for equities.
Example Record
| token | exchange | tradingSymbol | instrumentName | expiry | lotSize |
|---|---|---|---|---|---|
| 14366 |
NSE |
IDEA-EQ |
Equity |
(none) |
(none) |
| 79501 |
NFO |
NIFTY24APR |
OPTIDX |
24APR2025 |
50 |
Best Practices
- Daily Download
- Automate a script to fetch the instrument file(s) each morning, update local references, and handle newly listed or expired symbols.
- Symbol Validation
- When a user enters a symbol, cross-check it in your local instrument list to avoid “resource not found” errors.
- API Integration
- Combine the local instrument data with other endpoints—like Get Multi Quotes or Get Option Chain—to easily pivot between a user-friendly name and the token or tradingSymbol the APIs require.
- Version Awareness
- If new columns or data types appear in the instrument files, ensure your parsing logic can handle them gracefully (particularly if they come with new features or expansions in the Developer API).
Conclusion
Managing Instruments effectively is crucial for a seamless user experience and robust data validation. By leveraging daily-updated instrument files—which include fields like token, tradingSymbol, and exchange—you can:
- Quickly validate if a symbol is active,
- Support user-friendly auto-complete or search features,
- Ensure accurate and up-to-date references for all your F&O or equity trading flows.
For further details, see the Downloaders Documentation or contact support if you need guidance on large-scale or specialized use cases.
