dhanhq

DhanHQ — Indian Market Trading Skill

Setup

Stable install:

pip install dhanhq

Use the current SDK branch when you need newer v2 capabilities such as 200-level depth or the latest helper coverage:

pip install --upgrade dhanhq

Minimal initialization:

from dhanhq import DhanContext, dhanhq
 
dhan_context = DhanContext(

Environment-variable setup:

If generating scripts for this repo, prefer:

Safety Rules — Always Enforce

1. Confirm before placing live orders.
2. Show a readable order preview before execution.
3. Default to LIMIT orders unless the user explicitly wants MARKET.
4. Warn when notional exceeds Rs. 50,000.
5. For F&O, validate lot size before placement.
6. Never use CNC or MTF for F&O, commodity, or currency segments.
7. Never hardcode credentials in generated code.
8. Ask for confirmation before modify_order, cancel_order, kill_switch, or any multi-leg live execution.

Access Checks Before Live Use

Before using the account for live work, verify:

1. Access token is valid.
2. dhan_login.user_profile(...) or GET /profile shows the needed account setup.
3. dataPlan is active for quote/history/feed/option-chain use.
4. Static IP is configured for order placement, order modification, order cancellation, super orders, and forever orders.

Useful profile fields:

• tokenValidity
• activeSegment
• ddpi
• mtf
• dataPlan
• dataValidity

Current SDK Constants

Current SDK Methods To Prefer

High-Value Gotchas

• The SDK wraps HTTP responses as {"status": "success"|"failure", "remarks": ..., "data": ...}. Response shapes vary by endpoint — success payloads differ significantly (arrays, flat objects, nested dicts) depending on the API.
• Repo helpers add a normalization layer. Fields like ce_ltp, ce_oi, ce_iv are repo-defined names — not raw Dhan field names.
• intraday_minute_data(...) is the current SDK method. Do not reference historical_minute_data().
• Historical timestamps are epoch values. Convert them explicitly.
• The SDK currently validates expiry_code with [0, 1, 2, 3], but Dhan's v2 annexure documents 0, 1, 2. Prefer the documented values unless Dhan updates the API docs.
• Quote APIs are rate-limited to 1 request/sec.
• Option-chain REST data is keyed by strike string under data["oc"]. Use repo helpers for analysis-friendly rows.
• Market orders via API are currently converted by Dhan into limit orders with MPP.
• Order placement APIs require static IP whitelisting.
• Trading APIs are free for Dhan users; Data APIs require an active data plan.
• Lot sizes and freeze quantities change. Treat hardcoded values as fallback only.

Product-Type Rules

Instrument Resolution Rules

Use the security master as the primary source for:

• security_id
• lot_size
• tick_size
• expiry
• strike
• derivative contract lookup

Quick-reference index underlyings:

Preferred Helper Layer

When generating scripts in this repo, prefer:

• get_client() for SDK bootstrapping
• resolve_symbol() for cash-market lookup
• resolve_derivative() for contract lookup
• fetch_chain_df() for option-chain normalization
• find_atm_row() for ATM selection
• check_margin() for pre-flight margin checks
• preview_order() for readable confirmation

Core Patterns

1. Check account access before data calls

2. Fetch historical data with epoch conversion

3. Normalize option-chain data for analysis

4. Margin check before live order placement

5. Live market feed

Rate Limits

Reference Files

Dhan APIs cover execution, quotes, OHLC, option chain, and portfolio. For fundamental data (PE, EPS, revenue), technical indicators (RSI, MACD), or shareholding patterns not available via Dhan, use ScanX — see references/scanx-data.md.

Data API Subscription Invalid

If the user gets DH-902 or 806:

1. Log in to web.dhan.co
2. Open My Profile -> Access DhanHQ APIs
3. Verify that dataPlan is active
4. Activate the Data API plan if needed
5. Generate a fresh access token
6. Re-test with ticker_data() or ohlc_data()
7. If order APIs still fail, check static IP separately