Breeze (ICICI Direct)

Breeze is ICICI Direct's trading API. It's the recommended broker for multi-day historical simulations — its historical option data retention is much better than Kite's.

Prerequisites

• An ICICI Direct trading account.
• API access enabled on that account.

Obtaining API Credentials

You need an API Key and API Secret (called App Key and Secret Key on the ICICI portal) from an ICICI Direct API app.

1. Go to the ICICI Direct API portal: https://api.icicidirect.com/apiuser/home
2. Log in with your ICICI Direct credentials.
3. Click Register an App (or Create App).
4. Fill in the app details: - App name — your own value. - Redirect URL — set this to http://127.0.0.1:5000/breeze_callback (use the host/port you actually run the app on). This is required for the automatic login flow — ICICI sends the session token back to this URL.
5. Submit. Once the app is approved/created, open it and copy the API Key (App Key) and API Secret (Secret Key).

Reference: Breeze API documentation — https://api.icicidirect.com/apiuser/home and the breeze-connect Python library — https://pypi.org/project/breeze-connect/

Entering Credentials

On the Settings page (top navigation bar), in the Breeze (ICICI Direct) card, enter the API Key and API Secret and click Save & Start Breeze Login. You will be redirected to ICICI Direct to log in, then returned to the app with a session token captured automatically.

If your redirect URL is not yet registered with ICICI, use the Paste session token manually option on the Settings page as a fallback.

Credentials are stored securely in the OS keychain — you enter them once.

Daily Login

Like Kite, a Breeze session token expires and must be refreshed daily:

1. Step 1 — API Credentials: enter your Breeze API Key and API Secret once and click Save Breeze Credentials.
2. Step 2 — Session Token: click Start Breeze Login. ICICI Direct's login page opens; complete login. You are redirected back and the session token is captured automatically.
3. Click Test Breeze Connection to confirm.

If your redirect URL isn't registered yet, use Paste session token manually to fall back to the old flow.

API Contract Check

Like Kite, a Breeze session token is only saved if it passes the API contract check — the app calls the read-only endpoints it actually depends on (funds, portfolio positions, order list) before persisting the token. If login appears to succeed but the badge doesn't turn green, check the Settings page for a contract-check error naming which feature would have broken.

Breeze returns {"Error": "No Data Found"} instead of an empty list when there simply aren't any positions/orders yet — the contract check treats that as empty data, not a failure, so a fresh login before your first order of the day won't get blocked by it.

Known Strengths

Breeze is the recommended broker for multi-day historical simulations (the Multi-Day Sim / Run Again broker dropdowns default to it) — unlike Kite, its instrument list retains expired weekly option strikes well beyond 7 days, so backtests over older date ranges use real traded prices instead of falling back to Black-Scholes estimates.

ICICI's get_historical_data_v2 always includes an open_interest field for F&O contracts (confirmed via pypi.org/project/breeze-connect), so the Option Scanner's Flow (OI Analysis) tab gets a real previous-close OI baseline on Breeze too — same as Kite, no estimated fallback.

Live OI (the main scan's OI column, and Flow's current-day OI reading) comes from get_option_chain_quotes, not get_quotes — ICICI's plain quote endpoint has no open_interest field at all (confirmed against both pypi.org/project/breeze-connect and ICICI's own API reference, 2026-08-22). BreezeAdapter.quote() batches NFO options through the chain endpoint for this reason (same one ltp() already used, for the same reason).

Response Shapes That Differ From Kite

ICICI's order/position payloads don't match Kite's field names, and getting them wrong is silent rather than loud. Recorded here so they don't get re-guessed (all confirmed against ICICI's published response samples on pypi.org/project/breeze-connect):

• get_order_detail has no filled_quantity. It sends quantity, pending_quantity and cancelled_quantity; the filled amount is quantity − pending − cancelled. Reading a filled_quantity key that doesn't exist made every order look fully filled.
• Order status is Ordered / Executed / Cancelled / Rejected. The engine only treats COMPLETE / REJECTED / CANCELLED as terminal, so Executed is mapped to COMPLETE in the adapter (_STATUS_MAP).
• order_datetime has no seconds — 05-Feb-2025 09:26.
• get_portfolio_positions quantity is unsigned. Direction is in a separate action field (Buy/Sell), unlike Kite's and Dhan's signed net quantity, which reconciliation and the manual "confirm legs" flow both rely on.
• get_demat_holdings is keyed by ICICI's own stock_code (its Security Master ShortName), not the NSE tradingsymbol — the covered-call cover check compares against NSE names, so the adapter translates.

Known Limitations

ICICI enforces an undocumented daily API call quota — empirically about 6,000 calls/day (brokers.breeze.daily_call_cap in config.json if this ever needs adjusting). ThetaPrime tracks its own count and stops calling before hitting ICICI's real limit; live prices then come from the WebSocket tick cache instead, which is what keeps a feed alive once REST is blocked (brokers.breeze.ws_ticks in config.json, on by default). You may see:

• One alert a day when ThetaPrime's own cap trips ("Breeze daily call cap reached — live quotes off for the day").
• One alert a day if ICICI's own quota rejection fires first.
• An alert at most every 30 minutes if a leg can't be priced while REST is blocked and the WebSocket feed is quiet for that leg too — its stop-loss is then being evaluated on a stale, last-known price rather than a fresh one.

None of these require action — the cap resets automatically at ICICI's next daily rollover. If you've explicitly turned ws_ticks off, turning it back on gives the blind-spot alert a live feed to fall back on.

Static IP Requirement

Ask your ISP for a static IP add-on before setting up your Breeze API app — SEBI's API trading rules require a fixed IP for order placement, registered with your broker.