dhanhq

name	dhanhq
description	Use when the user mentions DhanHQ, Dhan API, or wants to trade on Indian exchanges (NSE, BSE, MCX). Triggers for: place, modify, or cancel stock/F&O/commodity orders on Dhan; fetch portfolio holdings or positions; get live or historical market data; access option chains with Greeks; check fund limits or margin; build any trading automation for Indian markets; resolve NSE/BSE instrument IDs; stream live WebSocket market feeds or order updates. Also trigger for general questions about programmatic trading on Indian exchanges if Dhan is the user's broker.
compatibility	Requires Python 3.8+ and the dhanhq package (pip install dhanhq). Order placement, modification, and cancellation require static IP whitelisting on Dhan. Data APIs (quotes, history, option chain, live feed) require an active Dhan Data Plan.

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

Category	Constant	Value
Exchange	dhanhq.NSE	NSE_EQ
	dhanhq.BSE	BSE_EQ
	dhanhq.NSE_FNO	NSE_FNO
	dhanhq.BSE_FNO	BSE_FNO
	dhanhq.MCX	MCX_COMM
	dhanhq.CUR	NSE_CURRENCY
	dhanhq.INDEX	IDX_I
Transaction	dhanhq.BUY	BUY
	dhanhq.SELL	SELL
Order Type	dhanhq.LIMIT	LIMIT
	dhanhq.MARKET	MARKET
	dhanhq.SL	STOP_LOSS
	dhanhq.SLM	STOP_LOSS_MARKET
Product	dhanhq.CNC	CNC
	dhanhq.INTRA	INTRADAY
	dhanhq.MARGIN	MARGIN
	dhanhq.MTF	MTF
Validity	dhanhq.DAY	DAY
	dhanhq.IOC	IOC

Current SDK Methods To Prefer

Task	Method
Place order	dhan.place_order()
Slice large order	dhan.place_slice_order()
Modify order	dhan.modify_order()
Cancel order	dhan.cancel_order()
Order book	dhan.get_order_list()
Order by ID	dhan.get_order_by_id()
Order by correlation ID	dhan.get_order_by_correlationID()
Trade book	dhan.get_trade_book()
Trade history	dhan.get_trade_history()
Ledger	dhan.ledger_report()
Super orders	place_super_order(), modify_super_order(), cancel_super_order(), get_super_order_list()
Forever orders	place_forever(), modify_forever(), cancel_forever(), get_forever()
Holdings	dhan.get_holdings()
Positions	dhan.get_positions()
Convert position	dhan.convert_position()
eDIS	dhan.generate_tpin(), dhan.open_browser_for_tpin(), dhan.edis_inquiry()
Fund limits	dhan.get_fund_limits()
Margin calculator	dhan.margin_calculator()
Daily history	dhan.historical_daily_data()
Minute history	dhan.intraday_minute_data()
Expired options data	dhan.expired_options_data()
Market quote snapshot	dhan.ticker_data(), dhan.ohlc_data(), dhan.quote_data()
Expiry list	dhan.expiry_list()
Option chain	dhan.option_chain()
Security master	dhanhq.fetch_security_list()
Live market feed	MarketFeed
Live order updates	OrderUpdate
Full market depth	FullDepth
Kill switch	dhan.kill_switch(), dhan.status_kill_switch()

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

Segment	Allowed Product Types
NSE_EQ, BSE_EQ	CNC, INTRADAY, MARGIN, MTF
NSE_FNO, BSE_FNO, MCX_COMM, NSE_CURRENCY, BSE_CURRENCY	INTRADAY, MARGIN

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:

Underlying	security_id	Underlying Segment
NIFTY 50	13	IDX_I
BANK NIFTY	25	IDX_I
FINNIFTY	27	IDX_I
MIDCPNIFTY	442	IDX_I
SENSEX	51	IDX_I

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

API Category	Per Second	Per Minute	Per Hour	Per Day
Order APIs	10	250	1000	7000
Data APIs	5	-	-	100000
Quote APIs	1	Unlimited	Unlimited	Unlimited
Non-Trading APIs	20	Unlimited	Unlimited	Unlimited

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.

Need	File
Orders, super orders, forever orders	references/orders.md
Holdings, positions, eDIS	references/portfolio.md
Daily/minute history, quotes, expired options	references/market-data.md
Option-chain usage and normalization	references/option-chain.md
Fund limits and margin checks	references/funds.md
Live feeds and depth	references/live-feed.md
Error handling and subscription troubleshooting	references/error-codes.md
Instrument resolution	references/instruments.md
Multi-step execution patterns	references/common-workflows.md
Options analytics	references/options-analysis-patterns.md
Backtesting patterns	references/backtesting-with-dhan.md
PE ratio, RSI, financials, screeners — data Dhan does not provide	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