DhanHQ — Indian Market Trading Skill

Setup

Stable install:

python

pip install dhanhq

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

python

pip install --upgrade dhanhq

Minimal initialization:

python

from dhanhq import DhanContext, dhanhq

dhan_context = DhanContext("YOUR_CLIENT_ID", "YOUR_ACCESS_TOKEN")
dhan = dhanhq(dhan_context)

Environment-variable setup:

python

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:

python

from scripts.dhan_helpers import get_client

dhan, dhan_context = get_client()

Safety Rules — Always Enforce

Confirm before placing live orders.
Show a readable order preview before execution.
Default to
```
LIMIT
```
orders unless the user explicitly wants
```
MARKET
```
.
Warn when notional exceeds
```
Rs. 50,000
```
.
For F&O, validate lot size before placement.
Never use
```
CNC
```
or
```
MTF
```
for F&O, commodity, or currency segments.
Never hardcode credentials in generated code.
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:

Access token is valid.

dhan_login.user_profile(...)

GET /profile

shows the needed account setup.

```
dataPlan
```
is active for quote/history/feed/option-chain use.
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

python

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

python

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

python

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

python

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

python

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

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

dhanhq

NPX Install

Tags

SKILL.md Content

DhanHQ — Indian Market Trading Skill

Setup

Safety Rules — Always Enforce

Access Checks Before Live Use

Current SDK Constants

Current SDK Methods To Prefer

High-Value Gotchas

Product-Type Rules

Instrument Resolution Rules

Preferred Helper Layer

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

Data API Subscription Invalid