indiaopt

Enterprise-grade Python library for Indian stock market (NSE & BSE) data.

indiaopt provides a robust, highly-performant, and production-ready interface to fetch Option Chain and Market Data from both the National Stock Exchange (NSE) and Bombay Stock Exchange (BSE) of India.

It includes built-in circuit breakers, exponential backoff, browser impersonation (via curl_cffi), automatic retry logic, and zero-overhead data models.

Features

• Multi-Exchange: Unified API for both NSE and BSE.
• Resilience: Built-in circuit breakers, automatic retries with exponential backoff and jitter.
• Evasion: Uses curl_cffi to impersonate browsers and avoid NSE rate-limiting/bot-protection.
• Performance: Asynchronous via thread-pools, memory-efficient dataclasses (slots=True), and connection pooling.
• Type-Safe: Fully typed with PEP 561 compliance (py.typed).
• Configuration: Flexible configuration via environment variables, .env files, or code.

Installation

pip install indiaopt

Requires Python 3.10+

Quick Start

import asyncio
from indiaopt import NSEClient

async def main():
    # Context manager automatically handles session lifecycle
    async with NSEClient() as nse:
        # Fetch the option chain for NIFTY
        result = await nse.fetch_option_chain("NIFTY")
        
        print(f"Spot Price: {result.spot_price}")
        print(f"ATM Strike: {result.atm_strike}")
        print(f"Total Call OI: {result.total_call_oi}")
        print(f"Total Put OI: {result.total_put_oi}")
        print(f"PCR: {result.pcr:.2f}")

        # Iterate over the 5 strikes above and below ATM
        for row in result.atm_window(n=5):
            print(f"Strike: {row.strike} | CE OI: {row.call_oi} | PE OI: {row.put_oi}")

if __name__ == "__main__":
    asyncio.run(main())

Advanced Configuration

You can configure indiaopt via a .env file or environment variables:

INDIAOPT_MAX_RETRIES=5
INDIAOPT_FETCH_TIMEOUT=15.0
INDIAOPT_PROXY_URLS=http://proxy1:8080,http://proxy2:8080
INDIAOPT_LOG_LEVEL=INFO

Or configure it in code:

from indiaopt import NSEClient, Settings

settings = Settings(
    max_retries=3,
    fetch_timeout=10.0,
    circuit_failure_threshold=5,
)

async with NSEClient(settings=settings) as nse:
    result = await nse.fetch_option_chain("BANKNIFTY")

Exception Handling

The library provides a detailed exception hierarchy under IndiaOptError:

from indiaopt import RateLimitError, CircuitOpenError, NSEClient

try:
    async with NSEClient() as nse:
        await nse.fetch_option_chain("NIFTY")
except RateLimitError as e:
    print(f"Rate limited by exchange! Try again in {e.retry_after} seconds.")
except CircuitOpenError as e:
    print(f"Circuit breaker is open. Fails fast without hitting network.")

Documentation

Full documentation is available at https://indiaopt.readthedocs.io.

License

MIT License. See LICENSE for details.