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

Backtesting With Dhan Data

Daily Equity Backtest Skeleton

import pandas as pd

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

if response["status"] == "success":
    data = response["data"]
    df = pd.DataFrame(data)
    df["timestamp"] = pd.to_datetime(df["timestamp"], unit="s", utc=True).dt.tz_convert("Asia/Kolkata")
    df.set_index("timestamp", inplace=True)

Typical next steps:

• create signals
• shift positions to avoid look-ahead bias
• apply transaction costs
• compute CAGR / drawdown / Sharpe / win rate

Minute-Level Backtest Skeleton

response = dhan.intraday_minute_data(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    instrument_type="EQUITY",
    from_date="2024-09-11 09:30:00",
    to_date="2024-09-15 13:00:00",
    interval=5,
    oi=False,
)

if response["status"] == "success":
    minute_data = response["data"]

Practical note:

• current v2 API docs describe minute data for active instruments over up to last 5 years

Expired Options Backtest Skeleton

response = dhan.expired_options_data(
    security_id=13,
    exchange_segment=dhanhq.NSE_FNO,
    instrument_type="OPTIDX",
    expiry_flag="MONTH",
    expiry_code=1,
    strike="ATM",
    drv_option_type="CALL",
    required_data=["open", "high", "low", "close", "volume", "oi", "spot"],
    from_date="2021-08-01",
    to_date="2021-08-31",
    interval=1,
)

if response["status"] == "success":
    ce = response["data"]["ce"]

Current raw output shape:

• arrays live under response["data"]["ce"] or response["data"]["pe"]
• timestamps are epoch integers

Cost Model Reminders

At minimum consider:

• brokerage
• STT
• transaction charges
• GST
• stamp duty
• SEBI charges
• slippage

Use a single cost function and keep it explicit in the notebook/script.

Guidance

• Do not assume timestamps are ISO strings.
• Do not mix raw option-chain parsing with expired-options data shapes.
• For derivative strategies, separate:
• live contract discovery
• historical rolling data analysis
• Paper trade before live deployment.

Common Workflows — Agent Playbooks

Portfolio Rebalance

Recommended sequence:

1. Fetch holdings and funds 2. Compute target deltas 3. Resolve symbols and quantities 4. Preview all proposed orders 5. Confirm with the user 6. Place live orders only after confirmation

Skeleton:

holdings_resp = dhan.get_holdings()
funds_resp = dhan.get_fund_limits()

if holdings_resp["status"] == "success" and funds_resp["status"] == "success":
    holdings = holdings_resp["data"]
    funds = funds_resp["data"]
    available_cash = funds["availabelBalance"]

Guardrails:

• do not assume all holdings are NSE equities
• use current market data or a user-provided limit price
• do not submit all orders blindly without a preview

Delivery Sell With eDIS

Use this flow for selling demat holdings:

1. Fetch holdings and identify ISIN 2. Generate TPIN 3. Open the authorization form 4. Check edis_inquiry(isin) 5. Only after approval, place the sell order

Skeleton:

dhan.generate_tpin()
dhan.open_browser_for_tpin(isin="INE002A01018", qty=5, exchange="NSE")
status = dhan.edis_inquiry("INE002A01018")

Do not use this flow for:

• intraday equity sells
• F&O
• commodity
• currency

Single-Leg F&O Execution

Recommended sequence:

1. Resolve current contract from option chain or security master 2. Resolve lot size 3. Validate quantity 4. Check margin 5. Preview 6. Confirm 7. Place live order

Skeleton:

from scripts.dhan_helpers import fetch_chain_df, find_atm_row, check_margin

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

margin = check_margin(
    dhan,
    security_id=atm["ce_security_id"],
    exchange_segment=dhanhq.NSE_FNO,
    transaction_type=dhanhq.BUY,
    quantity=75,
    product_type=dhanhq.INTRA,
    price=float(atm["ce_ltp"]),
)

Multi-Leg Option Strategy

Recommended sequence:

1. Fetch option chain 2. Normalize with fetch_chain_df() 3. Build the strategy legs 4. Check live contract IDs and lot sizes 5. Check margin impact 6. Preview the complete basket 7. Confirm 8. Place buy-protection legs first where relevant 9. Monitor fills with OrderUpdate

Practical rules:

• use normalized helper output, not raw oc parsing in every script
• never hardcode current derivative security IDs
• for naked-risk strategies, be explicit about user confirmation

Daily P&L Summary

Recommended sequence:

1. Fetch holdings 2. Fetch positions 3. Fetch funds 4. Aggregate P&L and capital snapshot 5. Present a concise summary

Skeleton:

from scripts.dhan_helpers import format_pnl_report

holdings_resp = dhan.get_holdings()
positions_resp = dhan.get_positions()
summary = format_pnl_report(holdings_resp, positions_resp)

Data API Subscription Invalid

Do not re-explain the full flow here.

Point the user to:

• references/error-codes.md

Minimal workflow: 1. check dataPlan 2. activate data subscription if needed 3. refresh token 4. retry a simple data endpoint

Error Codes — Complete Reference

SDK note:

• on HTTP failure, the current Python SDK maps raw Dhan error payloads into:

{
    "status": "failure",
    "remarks": {
        "error_code": "...",
        "error_type": "...",
        "error_message": "..."
    },
    "data": ""
}

• on success, response["data"] contains the raw endpoint payload.

Trading API Errors

From the current v2 annexure:

Data API Errors

From the current v2 annexure:

Decision Tree

If the error is 807, 808, 809, or 810

Fix authentication first:

• refresh or regenerate token
• verify client ID
• retry only after credentials are corrected

If the error is 806 or DH-902

Treat it as access/subscription first:

• check dataPlan
• check dataValidity
• verify the account has the right API access

If the error is DH-911

Treat it as a trading infrastructure issue:

• check static IP setup
• verify the request is coming from the whitelisted IP

If the error is DH-905 or DH-906

Treat it as a request-shape or order-validation problem:

• product type
• lot size
• trigger/price fields
• segment
• security ID

Data API Subscription Invalid — User Playbook

When the user gets DH-902 or 806, do this:

1. Log in to web.dhan.co 2. Open My Profile -> Access DhanHQ APIs 3. Check whether dataPlan is active 4. If not active, subscribe/activate the Data API plan 5. Generate a fresh access token 6. Verify dataValidity 7. Re-test a simple snapshot call such as ticker_data() or ohlc_data()

If order APIs still fail after that:

• this is a separate issue
• check static IP setup next

Retry Guidance

Safe to retry automatically:

• DH-904
• 800
• 805
• rare transient DH-908 / DH-909

Do not blindly retry:

• DH-901
• DH-902
• DH-905
• DH-906
• DH-911
• 806
• 807
• 808
• 809
• 810
• 811
• 812
• 813
• 814

Rate Limits

Current documented rate limits:

Practical Rule

Never use the error code alone without endpoint context.

Examples:

• 805 on WebSocket can mean too many live connections
• 805 on data calls can mean request throttling
• DH-902 can surface when the user expects quotes/history but only has trading access

Funds & Margin — Complete Reference

The installed dhanhq SDK exposes get_fund_limits() and single-order margin_calculator().

Fund Limits

SDK method:

response = dhan.get_fund_limits()

Example:

if response["status"] == "success":
    funds = response["data"]
    print(funds["availabelBalance"])
    print(funds["utilizedAmount"])

Current fund-limit fields:

• dhanClientId
• availabelBalance
• sodLimit
• collateralAmount
• receiveableAmount
• utilizedAmount
• blockedPayoutAmount
• withdrawableBalance

Important:

• availabelBalance is Dhan's actual field spelling.

Margin Calculator — Single Order

SDK signature:

dhan.margin_calculator(
    security_id,
    exchange_segment,
    transaction_type,
    quantity,
    product_type,
    price,
    trigger_price=0,
)

Example:

response = dhan.margin_calculator(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    transaction_type=dhanhq.BUY,
    quantity=10,
    product_type=dhanhq.CNC,
    price=2450.0,
    trigger_price=0,
)

if response["status"] == "success":
    margin = response["data"]
    print(margin["totalMargin"])
    print(margin["availableBalance"])
    print(margin["brokerage"])

Current single-order margin fields:

• totalMargin
• spanMargin
• exposureMargin
• availableBalance
• variableMargin
• insufficientBalance
• brokerage
• leverage

Multi-Order Margin

Current v2 REST supports:

• POST /margincalculator/multi

Current installed SDK status:

• the local dhanhq 2.2.0 install does not expose a first-class margin_calculator_multi() method

Practical guidance:

• if you only need a pre-trade check, use the single-order SDK method
• if you need true portfolio-style multi-leg margin from this repo, either:
• call the raw REST endpoint directly, or
• extend the SDK wrapper in a controlled way

Do not document or generate calls to margin_calculator_multi() unless you add that wrapper explicitly.

Recommended Agent Pattern

Use the repo helper:

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,
)

if margin["sufficient"]:
    print("Order can be funded")
else:
    print("Insufficient balance", margin["shortfall"])

Derivative Margin Notes

• Resolve lot size from the security master or current contract metadata.
• Do not hardcode lot sizes in margin examples as if they are permanent.
• Use INTRADAY or MARGIN for F&O, commodity, and currency segments.
• Never use CNC or MTF for derivative products.

Troubleshooting

Margin call fails immediately

Check:

• security_id
• exchange_segment
• product_type
• trigger_price for SL/SLM

Available cash seems lower than expected

Inspect:

• utilizedAmount
• collateralAmount
• blockedPayoutAmount
• withdrawableBalance

User wants a multi-leg strategy

Do this in order: 1. Resolve live contract IDs from security master or option chain 2. Check margin impact leg by leg if no multi-order wrapper exists 3. Preview the sequence 4. Confirm with the user before any live execution

Instruments — Complete Reference

Use the security master as the primary source for:

• security_id
• lot size
• expiry
• strike
• tick size
• display symbol

Do not treat hardcoded derivative IDs as stable.

Preferred SDK Entry Point

Current SDK static method:

from dhanhq import dhanhq

df = dhanhq.fetch_security_list("compact")

The installed SDK downloads the CSV locally and returns a pandas DataFrame.

Official instrument sources:

• compact CSV: https://images.dhan.co/api-data/api-scrip-master.csv
• detailed CSV: https://images.dhan.co/api-data/api-scrip-master-detailed.csv

Key Columns

Recommended Resolution Flow

1. Exact trading-symbol match 2. Exact custom-symbol match 3. Filter by exchange and instrument type 4. Only then fall back to contains-search and disambiguation

Prefer the helper layer:

from scripts.dhan_helpers import resolve_symbol, resolve_derivative, get_lot_size

cash = resolve_symbol("RELIANCE", exchange_segment="NSE_EQ")
contract = resolve_derivative("NIFTY", strike=24000, option_type="CE", expiry="2025-03-27")
lot_size = get_lot_size(underlying="NIFTY")

Cash-Market Lookup Example

df = dhanhq.fetch_security_list("compact")

match = df[
    (df["SEM_EXM_EXCH_ID"] == "NSE")
    & (df["SEM_INSTRUMENT_NAME"] == "EQUITY")
    & (df["SEM_TRADING_SYMBOL"] == "RELIANCE")
]

security_id = str(match.iloc[0]["SEM_SMST_SECURITY_ID"])

Derivative Lookup Example

df = dhanhq.fetch_security_list("compact")

contract = df[
    (df["SEM_EXM_EXCH_ID"] == "NSE")
    & (df["SEM_INSTRUMENT_NAME"] == "OPTIDX")
    & (df["SEM_CUSTOM_SYMBOL"] == "NIFTY")
    & (df["SEM_STRIKE_PRICE"] == 24000.0)
    & (df["SEM_OPTION_TYPE"] == "CE")
    & (df["SEM_EXPIRY_DATE"] == "2025-03-27")
]

security_id = str(contract.iloc[0]["SEM_SMST_SECURITY_ID"])
lot_size = int(contract.iloc[0]["SEM_LOT_UNITS"])

Quick-Reference Fallback IDs

These are convenience references only. Re-check the security master if there is any ambiguity.

Index Underlyings

Common NSE Equities

Practical Rules

• Equity security IDs are relatively stable.
• Derivative contract IDs are not stable across expiries.
• Resolve derivative IDs fresh for live trading.
• Use lot size from the security master, not from stale constants.

Troubleshooting

No symbol match

Check:

• exchange
• instrument type
• expiry
• strike
• option type

Too many matches

Add filters for:

• SEM_EXM_EXCH_ID
• SEM_INSTRUMENT_NAME
• SEM_EXPIRY_DATE
• SEM_OPTION_TYPE

Contract not found

Possible causes:

• contract expired
• wrong expiry date
• wrong exchange segment
• stale assumption about current listed contracts

Live Feed — Complete Reference

SDK classes: MarketFeed, OrderUpdate, FullDepth.

MarketFeed

Current SDK signature:

MarketFeed(
    dhan_context,
    instruments,
    version="v2",
    on_connect=None,
    on_message=None,
    on_close=None,
    on_error=None,
    on_ticks=None,
)

Example:

from dhanhq import DhanContext, MarketFeed

dhan_context = DhanContext("client_id", "access_token")
instruments = [
    (MarketFeed.NSE, "2885", MarketFeed.Ticker),
    (MarketFeed.NSE, "1333", MarketFeed.Quote),
    (MarketFeed.NSE_FNO, "49081", MarketFeed.Full),
]

def on_message(instance, message):
    print(message)

feed = MarketFeed(
    dhan_context,
    instruments,
    version="v2",
    on_message=on_message,
)
feed.run_forever()

Current SDK Constants

Exchange constants:

• MarketFeed.IDX = 0
• MarketFeed.NSE = 1
• MarketFeed.NSE_FNO = 2
• MarketFeed.NSE_CURR = 3
• MarketFeed.BSE = 4
• MarketFeed.MCX = 5
• MarketFeed.BSE_CURR = 7
• MarketFeed.BSE_FNO = 8

Subscription constants:

• MarketFeed.Ticker = 15
• MarketFeed.Quote = 17
• MarketFeed.Depth = 19
• MarketFeed.Full = 21

Use version="v2" when you need full packet mode.

Connection Limits

From the current v2 API docs:

• up to 5 concurrent websockets per user
• up to 5000 instruments per connection
• up to 100 instruments per subscription message

SDK helper methods:

feed.subscribe_symbols(symbols)
feed.unsubscribe_symbols(symbols)
feed.close_connection()
feed.disconnect()

Parsed Packet Shapes From The Installed SDK

Representative Ticker packet:

{
    "type": "Ticker Data",
    "exchange_segment": 1,
    "security_id": 2885,
    "LTP": "2450.00",
    "LTT": "2025-01-15 10:30:00+00:00"
}

Representative Quote packet:

{
    "type": "Quote Data",
    "exchange_segment": 1,
    "security_id": 2885,
    "LTP": "2450.00",
    "LTQ": 10,
    "LTT": "...",
    "avg_price": "2445.50",
    "volume": 1234567,
    "total_sell_quantity": 450000,
    "total_buy_quantity": 500000,
    "open": "2430.00",
    "close": "2440.00",
    "high": "2465.00",
    "low": "2425.00"
}

Representative Full packet:

{
    "type": "Full Data",
    "exchange_segment": 2,
    "security_id": 49081,
    "LTP": "368.15",
    "LTQ": 50,
    "LTT": "...",
    "avg_price": "365.00",
    "volume": 10000,
    "total_sell_quantity": 2500,
    "total_buy_quantity": 3000,
    "OI": 1250000,
    "oi_day_high": 1265000,
    "oi_day_low": 1210000,
    "open": "360.00",
    "close": "355.00",
    "high": "372.00",
    "low": "352.00",
    "depth": [
        {
            "bid_quantity": 100,
            "ask_quantity": 75,
            "bid_orders": 2,
            "ask_orders": 1,
            "bid_price": "368.10",
            "ask_price": "368.20"
        }
    ]
}

OrderUpdate

Current SDK signature:

OrderUpdate(dhan_context)

Minimal usage:

from dhanhq import OrderUpdate

order_client = OrderUpdate(dhan_context)

def on_order_update(order_data):
    print(order_data)

order_client.on_update = on_order_update
order_client.connect_to_dhan_websocket_sync()

Use this for:

• live order-status monitoring
• fill confirmations
• multi-leg execution monitoring

FullDepth

Current SDK signature:

FullDepth(dhan_context, instruments, depth_level=20)

Example:

from dhanhq import FullDepth

depth = FullDepth(
    dhan_context,
    instruments=[(FullDepth.NSE, "2885")],
    depth_level=20,
)
depth.run_forever()
print(depth.get_data())

Current SDK constants:

• FullDepth.NSE = 1
• FullDepth.NSE_FNO = 2

Current API limits:

• 20-level depth: up to 50 instruments per connection
• 200-level depth: 1 instrument per connection
• only NSE_EQ and NSE_FNO are supported for full depth

SDK methods:

depth.subscribe_symbols(symbols)
depth.unsubscribe_symbols(symbols)
depth.close_connection()
depth.disconnect()

Parsed Depth Output

FullDepth receives bid and ask packets separately and the SDK formats them into a combined representation. Treat the output as SDK-parsed depth data, not raw binary packet layout.

When To Use What

• Use ticker_data(), ohlc_data(), or quote_data() for snapshots.
• Use MarketFeed for live monitoring of LTP, quote, or full packets.
• Use OrderUpdate for execution tracking.
• Use FullDepth only when you genuinely need deeper order-book visibility because it is heavier and more restrictive than regular live market feed usage.

Market Data — Complete Reference

Historical timestamps are epoch integers inside response["data"]["timestamp"] — always convert explicitly.

Historical Daily Data

SDK signature:

dhan.historical_daily_data(
    security_id,
    exchange_segment,
    instrument_type,
    from_date,
    to_date,
    expiry_code=0,
    oi=False,
)

Example:

response = dhan.historical_daily_data(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    instrument_type="EQUITY",
    from_date="2024-01-01",
    to_date="2024-12-31",
    expiry_code=0,
    oi=False,
)

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

Raw API payload fields:

• securityId
• exchangeSegment
• instrument
• expiryCode
• oi
• fromDate
• toDate

Documented instrument values from the v2 annexure:

• INDEX
• FUTIDX
• OPTIDX
• EQUITY
• FUTSTK
• OPTSTK
• FUTCOM
• OPTFUT
• FUTCUR
• OPTCUR

Response data fields:

• open
• high
• low
• close
• volume
• timestamp
• open_interest when oi=True

Important:

• The raw API docs currently document expiryCode values 0, 1, 2.
• The installed SDK validation still accepts 3.
• Prefer the documented values unless Dhan updates the API docs.

Intraday Minute Data

SDK signature:

dhan.intraday_minute_data(
    security_id,
    exchange_segment,
    instrument_type,
    from_date,
    to_date,
    interval=1,
    oi=False,
)

Example:

response = dhan.intraday_minute_data(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    instrument_type="EQUITY",
    from_date="2024-09-11 09:30:00",
    to_date="2024-09-15 13:00:00",
    interval=1,
    oi=False,
)

if response["status"] == "success":
    minute_data = response["data"]
    minute_times = [dhan.convert_to_date_time(ts) for ts in minute_data["timestamp"]]

Current API truth:

• Intraday data is ranged minute data, not "today only".
• The v2 historical-data page documents last 5 years for active instruments.
• The installed SDK docstring still says "last 5 trading day". Prefer the current v2 API docs when planning data windows.

Supported intervals:

• 1
• 5
• 15
• 25
• 60

Market Quote Snapshots

SDK methods:

dhan.ticker_data(securities)
dhan.ohlc_data(securities)
dhan.quote_data(securities)

Request format:

securities = {
    "NSE_EQ": [2885, 1333],
    "NSE_FNO": [49081],
}

Ticker Data

response = dhan.ticker_data({"NSE_EQ": [2885]})

if response["status"] == "success":
    ltp = response["data"]["NSE_EQ"]["2885"]["last_price"]

OHLC Data

response = dhan.ohlc_data({"NSE_EQ": [2885]})

if response["status"] == "success":
    ohlc = response["data"]["NSE_EQ"]["2885"]["ohlc"]

Quote Data

response = dhan.quote_data({"NSE_FNO": [49081]})

if response["status"] == "success":
    quote = response["data"]["NSE_FNO"]["49081"]
    print(quote["last_price"], quote["oi"], quote["volume"])

Current raw fields exposed by the v2 quote endpoint include:

• last_price
• average_price
• buy_quantity
• sell_quantity
• depth.buy[]
• depth.sell[]
• last_quantity
• last_trade_time
• lower_circuit_limit
• upper_circuit_limit
• net_change
• volume
• oi
• oi_day_high
• oi_day_low
• ohlc.open
• ohlc.close
• ohlc.high
• ohlc.low

Quote API limits:

• up to 1000 instruments per request
• 1 request/sec

Expired Options Data

SDK signature:

dhan.expired_options_data(
    security_id,
    exchange_segment,
    instrument_type,
    expiry_flag,
    expiry_code,
    strike,
    drv_option_type,
    required_data,
    from_date,
    to_date,
    interval=1,
)

Example:

response = dhan.expired_options_data(
    security_id=13,
    exchange_segment=dhanhq.NSE_FNO,
    instrument_type="OPTIDX",
    expiry_flag="MONTH",
    expiry_code=1,
    strike="ATM",
    drv_option_type="CALL",
    required_data=["open", "high", "low", "close", "volume", "oi", "spot"],
    from_date="2021-08-01",
    to_date="2021-08-31",
    interval=1,
)

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

Current v2 API notes:

• rolling expired options data is available for up to last 5 years
• fetch up to 30 days per call
• strike supports ATM, ATM+N, ATM-N
• near-expiry index options go up to ATM+10 / ATM-10
• other contracts go up to ATM+3 / ATM-3

Allowed required_data values:

• open
• high
• low
• close
• iv
• volume
• strike
• oi
• spot

Timestamp Conversion

Prefer explicit conversion instead of assuming ISO strings:

timestamps = [dhan.convert_to_date_time(ts) for ts in response["data"]["timestamp"]]

Or with pandas:

df["timestamp"] = pd.to_datetime(df["timestamp"], unit="s", utc=True).dt.tz_convert("Asia/Kolkata")

Practical Guidance

• Use historical APIs for candles and backtests.
• Use quote APIs for point-in-time snapshots.
• Use MarketFeed for live monitoring instead of polling quote endpoints aggressively.
• Use the security master to validate derivative instrument type, expiry, and lot size before mixing historical data with live execution.

Option Chain — Complete Reference

For analysis code use the normalized helper layer from scripts/dhan_helpers.py. See raw payload shape below when you need to parse the response directly.

Expiry List

SDK signature:

dhan.expiry_list(under_security_id, under_exchange_segment)

Example:

response = dhan.expiry_list(
    under_security_id=13,
    under_exchange_segment="IDX_I",
)

if response["status"] == "success":
    expiries = response["data"]

Option Chain

SDK signature:

dhan.option_chain(under_security_id, under_exchange_segment, expiry)

Index example:

response = dhan.option_chain(
    under_security_id=13,
    under_exchange_segment="IDX_I",
    expiry="2025-03-27",
)

Equity-underlying example:

response = dhan.option_chain(
    under_security_id=2885,
    under_exchange_segment="NSE_EQ",
    expiry="2025-03-27",
)

Rate limit:

• one unique option-chain request every 3 seconds

Raw Payload Shape

Raw response structure from Dhan v2:

{
    "data": {
        "last_price": 25642.8,
        "oc": {
            "25650.000000": {
                "ce": {
                    "security_id": 12345,
                    "last_price": 146.99,
                    "average_price": 146.99,
                    "oi": 1250000,
                    "oi_change": 50000,
                    "implied_volatility": 12.5,
                    "top_bid_price": 146.9,
                    "top_bid_quantity": 50,
                    "top_ask_price": 147.0,
                    "top_ask_quantity": 75,
                    "volume": 85000,
                    "greeks": {
                        "delta": 0.65,
                        "gamma": 0.002,
                        "theta": -15.2,
                        "vega": 28.5
                    }
                },
                "pe": {...}
            }
        }
    }
}

Important:

• oc is keyed by strike string, not a list.
• Raw field names are last_price, oi, implied_volatility, top_bid_price, top_ask_price, and nested greeks.

Repo-Normalized Analysis Layer

For analysis code, prefer:

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",
    under_exchange_segment="IDX_I",
)

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

Normalized helper columns:

• strike
• ce_security_id, pe_security_id
• ce_ltp, pe_ltp
• ce_oi, pe_oi
• ce_oi_change, pe_oi_change
• ce_volume, pe_volume
• ce_iv, pe_iv
• ce_bid_price, pe_bid_price
• ce_ask_price, pe_ask_price
• ce_delta, pe_delta
• ce_gamma, pe_gamma
• ce_theta, pe_theta
• ce_vega, pe_vega

These normalized names are repo-defined conveniences. They are not raw Dhan field names.

Practical Patterns

Get ATM row

atm = find_atm_row(chain_df, spot)
print(atm["strike"])
print(atm["ce_ltp"], atm["pe_ltp"])

Filter nearby strikes

nearby = chain_df[(chain_df["strike"] >= spot - 500) & (chain_df["strike"] <= spot + 500)]

Find a contract security ID

row = chain_df[chain_df["strike"] == 24000].iloc[0]
ce_security_id = row["ce_security_id"]
pe_security_id = row["pe_security_id"]

Compute simple OI totals

total_ce_oi = chain_df["ce_oi"].fillna(0).sum()
total_pe_oi = chain_df["pe_oi"].fillna(0).sum()

Guidance

• Use index examples first for Nifty/BankNifty workflows.
• Cover equity underlyings only when the user explicitly needs stock options.
• For current liquid contracts, option chain is a fast way to get security IDs.
• For robust contract resolution across expiries and underlyings, fall back to the security master.

Options Analysis Patterns

Use the normalized helper output from scripts/dhan_helpers.py for analysis code.

from scripts.dhan_helpers import fetch_chain_df, find_atm_row

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

Put-Call Ratio (PCR)

total_ce_oi = chain_df["ce_oi"].fillna(0).sum()
total_pe_oi = chain_df["pe_oi"].fillna(0).sum()
pcr = total_pe_oi / total_ce_oi if total_ce_oi else 0
print(f"PCR: {pcr:.2f}")

OI Support / Resistance

ce_walls = chain_df[["strike", "ce_oi"]].dropna().sort_values("ce_oi", ascending=False).head(3)
pe_walls = chain_df[["strike", "pe_oi"]].dropna().sort_values("pe_oi", ascending=False).head(3)

Interpretation:

• highest CE OI often acts like resistance
• highest PE OI often acts like support

IV Skew

otm_puts = chain_df[chain_df["strike"] < spot].nlargest(3, "strike")
otm_calls = chain_df[chain_df["strike"] > spot].nsmallest(3, "strike")

put_iv = otm_puts["pe_iv"].dropna().mean()
call_iv = otm_calls["ce_iv"].dropna().mean()
skew = put_iv - call_iv

Max Pain

def calculate_max_pain(df):
    strikes = df["strike"].tolist()
    pain = {}

    for test_price in strikes:
        total = 0
        for _, row in df.iterrows():
            strike = row["strike"]
            ce_oi = row.get("ce_oi") or 0
            pe_oi = row.get("pe_oi") or 0
            total += max(0, test_price - strike) * ce_oi
            total += max(0, strike - test_price) * pe_oi
        pain[test_price] = total

    return min(pain, key=pain.get)

Contract Selection

ATM contract lookup:

atm = find_atm_row(chain_df, spot)
ce_security_id = atm["ce_security_id"]
pe_security_id = atm["pe_security_id"]

Nearby strikes:

nearby = chain_df[(chain_df["strike"] >= spot - 500) & (chain_df["strike"] <= spot + 500)]

Guidance

• Use option chain for current listed option contracts.
• Use the security master when you need broader derivative resolution logic.
• Treat helper fields like ce_ltp, pe_oi, ce_iv, etc. as repo-defined normalized fields, not raw Dhan field names.

Orders — Complete Reference

Critical API rule:

• order placement, modification, cancellation, super orders, and forever orders require static IP whitelisting

Current API note:

• Dhan's current order docs say API market orders are converted to limit orders with MPP

Regular Orders

Place Order

Current SDK signature:

dhan.place_order(
    security_id,
    exchange_segment,
    transaction_type,
    quantity,
    order_type,
    product_type,
    price,
    trigger_price=0,
    disclosed_quantity=0,
    after_market_order=False,
    validity="DAY",
    amo_time="OPEN",
    bo_profit_value=None,
    bo_stop_loss_Value=None,
    tag=None,
    should_slice=False,
)

Recommended pattern:

response = dhan.place_order(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    transaction_type=dhanhq.BUY,
    quantity=10,
    order_type=dhanhq.LIMIT,
    product_type=dhanhq.CNC,
    price=2450.0,
    validity=dhanhq.DAY,
    tag="rebalance_001",
)

if response["status"] == "success":
    print(response["data"]["orderId"], response["data"]["orderStatus"])

Validation rules to enforce before placement:

• price required for LIMIT and STOP_LOSS
• trigger_price required for STOP_LOSS and STOP_LOSS_MARKET
• derivatives require lot-size multiples
• derivatives only allow INTRADAY or MARGIN
• quote market structure first if you need a sensible limit price

Slice Order

Use should_slice=True or the explicit SDK helper:

response = dhan.place_slice_order(
    security_id="49081",
    exchange_segment=dhanhq.NSE_FNO,
    transaction_type=dhanhq.BUY,
    quantity=2500,
    order_type=dhanhq.LIMIT,
    product_type=dhanhq.INTRA,
    price=150.0,
    validity=dhanhq.DAY,
)

Use this only after checking current freeze-quantity requirements.

Modify Order

Current SDK signature:

dhan.modify_order(order_id, order_type, leg_name, quantity, price, trigger_price, disclosed_quantity, validity)

Example:

response = dhan.modify_order(
    order_id="112111182198",
    order_type=dhanhq.LIMIT,
    leg_name=None,
    quantity=10,
    price=2455.0,
    trigger_price=0,
    disclosed_quantity=0,
    validity=dhanhq.DAY,
)

The SDK and release notes expect full placed quantity in modification requests, not pending quantity.

Cancel Order

response = dhan.cancel_order(order_id="112111182198")

Order Retrieval

order = dhan.get_order_by_id("112111182198")
order_by_tag = dhan.get_order_by_correlationID("my_tag")
orders = dhan.get_order_list()
trades = dhan.get_trade_book()
single_trade = dhan.get_trade_book(order_id="112111182198")
history = dhan.get_trade_history("2025-01-01", "2025-01-31", page_number=0)
ledger = dhan.ledger_report("2025-01-01", "2025-01-31")

Super Orders

Current SDK support exists for:

• place_super_order
• modify_super_order
• cancel_super_order
• get_super_order_list

Place Super Order

Current SDK signature:

dhan.place_super_order(
    security_id,
    exchange_segment,
    transaction_type,
    quantity,
    order_type,
    product_type,
    price,
    targetPrice=0.0,
    stopLossPrice=0.0,
    trailingJump=0.0,
    tag=None,
)

Example:

response = dhan.place_super_order(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    transaction_type=dhanhq.BUY,
    quantity=1,
    order_type=dhanhq.LIMIT,
    product_type=dhanhq.INTRA,
    price=2450.0,
    targetPrice=2500.0,
    stopLossPrice=2420.0,
    trailingJump=10.0,
)

Modify Super Order

Current SDK signature:

dhan.modify_super_order(order_id, order_type, leg_name, quantity=0, price=0.0, targetPrice=0.0, stopLossPrice=0.0, trailingJump=0.0)

Key rule from the API docs:

• ENTRY_LEG can modify the whole structure while the entry order is PENDING or PART_TRADED
• after entry is TRADED, only TARGET_LEG and STOP_LOSS_LEG changes remain

Cancel Super Order

response = dhan.cancel_super_order(order_id="...", order_leg="ENTRY_LEG")

Super Order Book

response = dhan.get_super_order_list()

Forever Orders

Current SDK support exists for:

• place_forever
• modify_forever
• cancel_forever
• get_forever

Place Forever Order

Current SDK signature:

dhan.place_forever(
    security_id,
    exchange_segment,
    transaction_type,
    product_type,
    order_type,
    quantity,
    price,
    trigger_Price,
    order_flag="SINGLE",
    disclosed_quantity=0,
    validity="DAY",
    price1=0,
    trigger_Price1=0,
    quantity1=0,
    tag=None,
    symbol="",
)

Single trigger example:

response = dhan.place_forever(
    security_id="2885",
    exchange_segment=dhanhq.NSE,
    transaction_type=dhanhq.BUY,
    product_type=dhanhq.CNC,
    order_type=dhanhq.LIMIT,
    quantity=1,
    price=2400.0,
    trigger_Price=2405.0,
)

Important:

• the SDK parameter is trigger_Price
• OCO fields use price1, trigger_Price1, quantity1

Order Validation Checklist

Before live placement, confirm: 1. account access token is valid 2. required segment is active 3. data plan is active if quotes are needed 4. static IP is configured for trading APIs 5. product type matches segment 6. quantity matches lot size for derivatives 7. trigger/price fields are consistent with order type 8. limit price is reasonable for the market state

Troubleshooting

Order rejected with access/IP issue

Check:

• static IP whitelisting
• DH-911 invalid IP

Order rejected with product-type issue

Check:

• CNC / MTF only for eligible equity flows
• INTRADAY / MARGIN only for derivative segments

User thinks a data error is an order error

Separate the failure domain:

• 806 / DH-902 usually points to Data API access
• trading placement failures often point to static IP or order validation

Destructive actions

Always preview and confirm before:

• place_order
• modify_order
• cancel_order
• cancel_super_order
• cancel_forever
• kill_switch

Portfolio And Positions — Complete Reference

Holdings

SDK method:

response = dhan.get_holdings()

Example:

if response["status"] == "success":
    holdings = response["data"]
    for holding in holdings:
        print(holding["tradingSymbol"], holding["securityId"], holding["availableQty"])

Useful holding fields from the v2 API:

• exchange
• tradingSymbol
• securityId
• isin
• totalQty
• dpQty
• t1Qty
• availableQty
• collateralQty
• avgCostPrice

Positions

SDK method:

response = dhan.get_positions()

Example:

if response["status"] == "success":
    positions = response["data"]
    open_positions = [p for p in positions if p["netQty"] != 0]

Useful position fields from the v2 API:

• tradingSymbol
• securityId
• positionType
• exchangeSegment
• productType
• buyAvg
• buyQty
• sellAvg
• sellQty
• netQty
• realizedProfit
• unrealizedProfit
• drvExpiryDate
• drvOptionType
• drvStrikePrice

Convert Position

SDK signature:

dhan.convert_position(
    from_product_type,
    exchange_segment,
    position_type,
    security_id,
    convert_qty,
    to_product_type,
)

Example:

response = dhan.convert_position(
    from_product_type=dhanhq.INTRA,
    exchange_segment=dhanhq.NSE,
    position_type="LONG",
    security_id="2885",
    convert_qty=1,
    to_product_type=dhanhq.CNC,
)

Exit All Positions

Raw v2 API:

• DELETE /positions

Current installed SDK status:

• the local dhanhq 2.2.0 install does not expose a first-class exit_all_positions() method

Practical rule:

• do not document or generate dhan.exit_all_positions() unless you add an explicit wrapper
• if you add raw REST support for this in the repo later, always require confirmation first

This is account-wide and high-risk.

eDIS Authorization

Use eDIS for selling delivery holdings.

Do not use eDIS for:

• intraday trades
• F&O positions
• non-holdings sell flows

Step 1: Generate TPIN

response = dhan.generate_tpin()

Step 2: Open the authorization form

SDK signature:

dhan.open_browser_for_tpin(isin, qty, exchange, segment="EQ", bulk=False)

Example:

dhan.open_browser_for_tpin(
    isin="INE002A01018",
    qty=5,
    exchange="NSE",
    segment="EQ",
)

Step 3: Check approval status

SDK signature:

dhan.edis_inquiry(isin)

Example:

response = dhan.edis_inquiry("INE002A01018")

if response["status"] == "success":
    status = response["data"]
    print(status["status"], status["aprvdQty"], status["remarks"])

Current inquiry fields from the v2 API:

• clientId
• isin
• totalQty
• aprvdQty
• status
• remarks

You can also pass ALL to inspect eDIS status more broadly when needed.

Agent Guardrails

• If the user wants to sell CNC holdings and eDIS status is unclear, stop and confirm authorization first.
• Do not place the delivery sell order until approval is confirmed.
• For holdings sell, use the ISIN from holdings data rather than guessing it.

Troubleshooting

Holdings or positions look empty

Check:

• current trading day state
• correct account
• segment activation on the Dhan account

eDIS inquiry is not approved

Do this: 1. Re-run TPIN flow 2. Re-open the browser authorization form 3. Re-check edis_inquiry(isin)

User wants account-wide position exit

Treat this as a destructive account action: 1. summarize open positions first 2. ask for explicit confirmation 3. only then use a raw REST wrapper if you add one

ScanX — Fundamental and Technical Data

Use ScanX when Dhan APIs do not cover the needed data. Dhan provides execution, quotes, OHLC, option chain, and portfolio. ScanX provides fundamentals, technical indicators, shareholding, and screeners.

Capability Gap

Company Page URL Pattern

https://scanx.trade/company/{slug}

Slug rules:

• Lowercase the full registered company name
• Replace spaces with hyphens
• Include "ltd" if part of the official name

If unsure: derive the slug, fetch the URL, and verify the page returns company data. If it 404s, try a shorter form (drop "ltd", use abbreviation, or search https://scanx.trade).

Data Per Page Section

Overview tab (loaded by default):

• Current price, day change %, 52-week range
• Market Cap, PE Ratio, EPS, PB Ratio, Book Value, Dividend Yield
• EBITDA, Revenue, Net Profit, Debt-to-equity, ROE

Technicals tab:

• RSI(14) — with signal: Overbought / Neutral / Oversold
• MACD(12,26) — with signal: Bullish / Bearish
• ADX(14) — with signal: Strong Trend / Weak Trend
• ATR(14) — with volatility label

Shareholding tab:

• Promoter %, DII %, FII %, Public %

Financials tab:

• Quarterly results back to 2015
• Revenue, EBITDA, Net Profit trends

Balance Sheet / Cash Flows tabs:

• Annual statements back to 2015

Fetching Data

Fetch the company URL and extract the relevant section from the rendered page:

https://scanx.trade/company/{slug}

The Overview tab data (fundamentals) loads on the default page. Technical indicators require the Technicals tab (append #technicals or navigate to it).

Combined Workflow: Analyze on ScanX → Execute on Dhan

# Step 1: fetch ScanX page for fundamentals/technicals
# → https://scanx.trade/company/reliance-industries-ltd
# → extract: PE=18.38, RSI=42.75 (Neutral), Revenue=10,57,220 Cr

# Step 2: resolve security_id from Dhan security master
from scripts.dhan_helpers import resolve_symbol, get_client

dhan, _ = get_client()
row = resolve_symbol("RELIANCE", exchange_segment="NSE_EQ")
security_id = str(row["SEM_SMST_SECURITY_ID"])  # e.g. "2885"

# Step 3: get live quote from Dhan
from dhanhq import dhanhq

response = dhan.ticker_data({"NSE_EQ": [int(security_id)]})
ltp = response["data"]["NSE_EQ"][security_id]["last_price"]

# Step 4: place order via Dhan
response = dhan.place_order(
    security_id=security_id,
    exchange_segment=dhanhq.NSE,
    transaction_type=dhanhq.BUY,
    quantity=1,
    order_type=dhanhq.LIMIT,
    product_type=dhanhq.CNC,
    price=ltp,
)

Guidance

• ScanX does not have a documented public API — data is accessed via the web page.
• The Overview tab data is available without authentication.
• For screener results, use https://scanx.trade/screener — 1500+ community screeners covering fundamental, technical, intraday, and sector-based filters.
• ScanX integrates with Dhan for order execution via the web UI, but programmatic execution still goes through Dhan APIs directly.