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("YOUR_CLIENT_ID", "YOUR_ACCESS_TOKEN")
dhan = dhanhq(dhan_context)

Environment-variable setup:

import os
from dhanhq import DhanContext, dhanhq

dhan_context = DhanContext(
    os.environ["DHAN_CLIENT_ID"],
    os.environ["DHAN_ACCESS_TOKEN"],
)
dhan = dhanhq(dhan_context)

If generating scripts for this repo, prefer:

from scripts.dhan_helpers import get_client

dhan, dhan_context = get_client()

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

from dhanhq import DhanLogin

dhan_login = DhanLogin("YOUR_CLIENT_ID")
profile = dhan_login.user_profile("YOUR_ACCESS_TOKEN")

print(profile["dataPlan"])
print(profile["dataValidity"])

2. Fetch historical data with epoch conversion

data = dhan.historical_daily_data(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    instrument_type="EQUITY",
    from_date="2024-01-01",
    to_date="2024-12-31",
)

if data["status"] == "success":
    candles = data["data"]
    timestamps = [dhan.convert_to_date_time(ts) for ts in candles["timestamp"]]

3. Normalize option-chain data for analysis

from scripts.dhan_helpers import fetch_chain_df, find_atm_row

chain_df, spot = fetch_chain_df(dhan, under_security_id=13, expiry="2025-03-27")
atm = find_atm_row(chain_df, spot)

print(spot)
print(atm["strike"])
print(atm["ce_security_id"], atm["ce_ltp"])

4. Margin check before live order placement

from scripts.dhan_helpers import check_margin

margin = check_margin(
    dhan,
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    transaction_type=dhanhq.BUY,
    quantity=10,
    product_type=dhanhq.CNC,
    price=2450.0,
)

print(margin["sufficient"], margin["total_margin"], margin["available_balance"])

5. Live market feed

from dhanhq import MarketFeed

instruments = [
    (MarketFeed.NSE, "2885", MarketFeed.Ticker),
    (MarketFeed.NSE_FNO, "49081", MarketFeed.Full),
]

feed = MarketFeed(dhan_context, instruments, "v2")
feed.run_forever()
print(feed.get_data())

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