# 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      | NIFTY24APR25C23500 | 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](https://firstock.in/api/docs/downloaders/) or contact support if you need guidance on large-scale or specialized use cases.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mindorigin1.gitbook.io/mindorigin1/instruments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.