bandl 0.4.0

Unified market data and account history with pluggable providers

Unified market data for Indian equities and crypto
One client, multiple providers — historical OHLCV as pandas or structured bars.

---

Install

pip install bandl

Requires Python 3.10+. For development: pip install -e ".[dev]" (see CONTRIBUTING.md).

---

Quick start

Import bandl, create a Bandl client, and fetch candles. Binance and CoinDCX public endpoints work without API keys.

from datetime import datetime, timedelta, timezone

from bandl import Bandl, Interval

client = Bandl()
end = datetime.now(timezone.utc)
start = end - timedelta(days=30)

# Crypto — daily BTC/USDT from Binance (default crypto provider)
df = client.crypto.get_ohlcv_dataframe("BTC/USDT", Interval.D1, start, end)
print(df[["timestamp", "open", "high", "low", "close", "volume"]].tail())

Indian equities (Zerodha Kite) need a Kite Connect API key and access token:

from bandl import Bandl, BandlConfig, Interval, ProviderSettings

client = Bandl(
    BandlConfig(
        providers={
            "zerodha": ProviderSettings(
                api_key="your_kite_api_key",
                access_token="your_daily_access_token",
            ),
        },
    ),
)

df = client.equity.get_ohlcv_dataframe(
    "RELIANCE",
    Interval.D1,
    start,
    end,
    source="zerodha",
)
print(df.tail())

Indices use the same API (aliases like NIFTY 50 → NIFTY50 are handled for you):

nifty = client.equity.get_ohlcv_dataframe(
    "NIFTY 50",
    Interval.D1,
    start,
    end,
    source="zerodha",
)

---

What you can fetch

Market	Provider	Auth	Example symbols
Crypto spot	binance	None (public klines)	BTC/USDT, BTCUSDT, ETHUSDT
Crypto spot	coindcx	None (public candles)	BTCUSDT, ETHUSDT
NSE equities & indices	zerodha	Kite API key + access token	RELIANCE, NIFTY 50, BANKNIFTY

Switch provider with source="binance" | "coindcx" | "zerodha", or use client.crypto / client.equity (defaults per facet).

Binance HTTP 451 (restricted location)? Binance blocks many regions and cloud IPs (e.g. US, Google Colab). Use CoinDCX instead — same symbols, no API key:

df = client.crypto.get_ohlcv_dataframe("BTCUSDT", Interval.D1, start, end, source="coindcx")

Or set BandlConfig(default_crypto_provider="coindcx").

CoinDCX empty DataFrame? The public candles API can lag (latest daily bars may end months before “today”). If your start/end are entirely after the feed, bandl raises DataNotAvailableError with the available date span. Use a window that overlaps the feed, for example:

end = datetime(2025, 7, 20, tzinfo=timezone.utc)
start = end - timedelta(days=30)
df = client.crypto.get_ohlcv_dataframe("BTCUSDT", Interval.D1, start, end, source="coindcx")

---

Common patterns

Pandas DataFrame (default for analysis)

df = client.crypto.get_ohlcv_dataframe("ETHUSDT", Interval.D1, start, end)

Typed list of bars (no pandas required in your pipeline)

from bandl import OHLCV

bars: list[OHLCV] = client.crypto.get_ohlcv("BTCUSDT", Interval.H1, start, end)
for bar in bars[-5:]:
    print(bar.timestamp, bar.close, bar.source)

Another crypto exchange

df = client.crypto.get_ohlcv_dataframe(
    "BTCUSDT",
    Interval.D1,
    start,
    end,
    source="coindcx",
)

List tradable symbols

# Crypto (Binance spot, trading status)
symbols = client.list_symbols(source="binance", search="BTC", limit=20)

# NSE equities + indices (Zerodha — requires credentials)
symbols = client.list_symbols(
    source="zerodha",
    exchange="NSE",
    instrument_types=("EQ",),
    search="RELI",
    limit=10,
)

Intervals

Use Interval enums or provider-native strings where supported:

from bandl import Interval

Interval.M1   # 1m
Interval.H1   # 1h
Interval.D1   # 1d

Timestamps in responses are UTC. Convert for display if you need IST:

df["timestamp"] = df["timestamp"].dt.tz_convert("Asia/Kolkata")

---

Configuration

Variable / setting	Purpose
BandlConfig.providers["zerodha"]	api_key, access_token for Kite
BandlConfig.providers["binance"]	Optional keys for future signed APIs
BandlConfig.timeout_seconds	HTTP timeout (default 30s)
BandlConfig.default_crypto_provider	Default for client.crypto (binance)
BandlConfig.default_equity_provider	Default for client.equity (zerodha)

Zerodha: access tokens expire daily — regenerate after login. A 403 on historical data usually means an expired token, wrong API key, or missing historical API access on your Kite app.

Runnable demos:

cp examples/.env.example .env   # add ZERODHA_* if testing Kite
python examples/main.py
python examples/futures_24hr_leaders.py --source coindcx

Account history

Fetch orders, fills, and PnL with client.account. See docs/ACCOUNT_HISTORY.md.

fills = client.account.get_fills(start, end, source="coindcx")
pnl = client.account.get_pnl(start, end, source="zerodha", prefer="auto")
bundle = client.account.export_analysis_bundle(start, end)

Futures 24h leaders

tickers = client.crypto.get_24hr_tickers(source="coindcx", asset_type=AssetType.CRYPTO_PERP)

---

Demo

---

For AI agents

AGENTS.md is the agent API reference (provider matrix, recipes, errors). It is not shipped inside the PyPI wheel — share a GitHub link with your agent, for example:

https://github.com/stockalgo/bandl/blob/master/AGENTS.md

Install the library with pip install bandl; point the agent at that file for how to call it. Pin a release tag in the URL (e.g. .../blob/v0.3.0/AGENTS.md) when you need a fixed doc version. See agents/README.md.

---

Documentation & development

• docs/BANDL.md — layout and design notes
• docs/ACCOUNT_HISTORY.md — account facet
• docs/PYPI_TRUSTED_PUBLISHING.md — release process for maintainers
• CONTRIBUTING.md — tests, Ruff, pull requests
• SECURITY.md — reporting vulnerabilities

pytest tests/bandl/
ruff check lib/bandl/account lib/bandl/core lib/bandl/models lib/bandl/providers tests/bandl

---

Roadmap

• Live streams / WebSockets
• More brokers and MCX commodity history
• Broader SymbolInfo and fundamentals

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening a pull request.

---

License

MIT