dhanhq

DhanHQ — 印度市场交易技能

设置

稳定版安装：

pip install dhanhq

需要 200 档深度或最新辅助函数支持等较新的 v2 功能时，请使用当前 SDK 分支：

pip install --upgrade dhanhq

最简初始化：

from dhanhq import DhanContext, dhanhq

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

环境变量设置：

import os
from dhanhq import DhanContext, dhanhq

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

为此仓库生成脚本时，优先使用：

from scripts.dhan_helpers import get_client

dhan, dhan_context = get_client()

安全规则 — 始终遵守

1. 下达实盘订单前必须确认。
2. 执行前显示易读的订单预览。
3. 默认使用 LIMIT 订单，除非用户明确要求使用 MARKET。
4. 名义金额超过 Rs. 50,000 时发出警告。
5. 对于 F&O，下单前验证手数。
6. 绝不在 F&O、商品或货币市场板块使用 CNC 或 MTF。
7. 生成的代码中绝不硬编码凭证。
8. 调用 modify_order、cancel_order、kill_switch 或执行任何多腿实盘交易前，必须征求确认。

实盘使用前的访问检查

将账户用于实盘操作前，请确认：

1. 访问令牌有效。
2. dhan_login.user_profile(...) 或 GET /profile 显示所需的账户设置。
3. 使用行情报价／历史数据／行情 Feed／期权链时，dataPlan 已激活。
4. 下单、修改订单、取消订单、超级订单和永久订单均已配置静态 IP。

有用的个人资料字段：

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

当前 SDK 常量

类别	常量	值
交易所	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
交易方向	dhanhq.BUY	BUY
	dhanhq.SELL	SELL
订单类型	dhanhq.LIMIT	LIMIT
	dhanhq.MARKET	MARKET
	dhanhq.SL	STOP_LOSS
	dhanhq.SLM	STOP_LOSS_MARKET
产品	dhanhq.CNC	CNC
	dhanhq.INTRA	INTRADAY
	dhanhq.MARGIN	MARGIN
	dhanhq.MTF	MTF
有效期	dhanhq.DAY	DAY
	dhanhq.IOC	IOC

优先使用的当前 SDK 方法

任务	方法
下单	dhan.place_order()
拆分大额订单	dhan.place_slice_order()
修改订单	dhan.modify_order()
取消订单	dhan.cancel_order()
订单簿	dhan.get_order_list()
按 ID 查询订单	dhan.get_order_by_id()
按关联 ID 查询订单	dhan.get_order_by_correlationID()
成交簿	dhan.get_trade_book()
成交历史	dhan.get_trade_history()
账本	dhan.ledger_report()
超级订单	place_super_order()、modify_super_order()、cancel_super_order()、get_super_order_list()
永久订单	place_forever()、modify_forever()、cancel_forever()、get_forever()
持仓	dhan.get_holdings()
仓位	dhan.get_positions()
转换仓位	dhan.convert_position()
eDIS	dhan.generate_tpin()、dhan.open_browser_for_tpin()、dhan.edis_inquiry()
资金限额	dhan.get_fund_limits()
保证金计算器	dhan.margin_calculator()
日线历史数据	dhan.historical_daily_data()
分钟线历史数据	dhan.intraday_minute_data()
到期期权数据	dhan.expired_options_data()
市场行情快照	dhan.ticker_data()、dhan.ohlc_data()、dhan.quote_data()
到期日列表	dhan.expiry_list()
期权链	dhan.option_chain()
证券主数据	dhanhq.fetch_security_list()
实时行情 Feed	MarketFeed
实时订单更新	OrderUpdate
完整市场深度	FullDepth
熔断开关	dhan.kill_switch()、dhan.status_kill_switch()

高价值注意事项

• SDK 会将 HTTP 响应封装为 {"status": "success"|"failure", "remarks": ..., "data": ...}。响应结构因端点而异，成功负载会根据 API 的不同而显著变化（数组、扁平对象、嵌套字典）。
• 仓库辅助函数会增加一层规范化处理。ce_ltp、ce_oi、ce_iv 等字段是仓库定义的名称，并非 Dhan 的原始字段名称。
• intraday_minute_data(...) 是当前的 SDK 方法。不要引用 historical_minute_data()。
• 历史时间戳是 epoch 值。请显式转换。
• SDK 当前使用 [0, 1, 2, 3] 校验 expiry_code，但 Dhan 的 v2 附录文档规定为 0、1、2。除非 Dhan 更新 API 文档，否则请优先使用文档规定的值。
• 报价 API 的速率限制为 1 request/sec。
• 期权链 REST 数据以行权价字符串为键，存放在 data["oc"] 中。请使用仓库辅助函数生成便于分析的行。
• 通过 API 下达的市价单目前会被 Dhan 转换为带有 MPP 的限价单。
• 下单 API 要求将静态 IP 加入白名单。
• Dhan 用户可免费使用交易 API；数据 API 则要求有效的数据套餐。
• 手数和冻结数量会发生变化。硬编码值仅应作为后备值。

产品类型规则

板块	允许的产品类型
NSE_EQ, BSE_EQ	CNC, INTRADAY, MARGIN, MTF
NSE_FNO, BSE_FNO, MCX_COMM, NSE_CURRENCY, BSE_CURRENCY	INTRADAY, MARGIN

工具解析规则

将证券主数据作为以下内容的主要来源：

• security_id
• lot_size
• tick_size
• 到期日
• 行权价
• 衍生品合约查询

指数标的快速参考：

标的	security_id	标的板块
NIFTY 50	13	IDX_I
BANK NIFTY	25	IDX_I
FINNIFTY	27	IDX_I
MIDCPNIFTY	442	IDX_I
SENSEX	51	IDX_I

推荐的辅助函数层

在此仓库中生成脚本时，优先使用：

• get_client() 初始化 SDK
• resolve_symbol() 查询现货市场标的
• resolve_derivative() 查询合约
• fetch_chain_df() 规范化期权链
• find_atm_row() 选择 ATM 行
• check_margin() 进行下单前保证金检查
• preview_order() 提供易读的确认信息

核心模式

1. 在调用数据 API 前检查账户访问权限

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. 获取历史数据并转换 epoch 时间戳

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. 规范化期权链数据以便分析

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. 实时下单前检查保证金

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. 实时市场行情流

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

速率限制

API 类别	每秒	每分钟	每小时	每天
订单 API	10	250	1000	7000
数据 API	5	-	-	100000
报价 API	1	不限	不限	不限
非交易 API	20	不限	不限	不限

参考文件

Dhan API 涵盖交易执行、报价、OHLC、期权链和投资组合。对于 Dhan 不提供的基本面数据（PE、EPS、营收）、技术指标（RSI、MACD）或持股模式，请使用 ScanX——参见 references/scanx-data.md。

需求	文件
订单、超级订单、永久订单	references/orders.md
持仓、仓位、eDIS	references/portfolio.md
日线/分钟线历史数据、报价、已到期的期权	references/market-data.md
期权链的用法与标准化	references/option-chain.md
资金限额与保证金检查	references/funds.md
实时行情流与深度	references/live-feed.md
错误处理与订阅问题排查	references/error-codes.md
标的解析	references/instruments.md
多步骤执行模式	references/common-workflows.md
期权分析	references/options-analysis-patterns.md
回测模式	references/backtesting-with-dhan.md
PE 比率、RSI、财务数据、筛选器——Dhan 不提供的数据	references/scanx-data.md

数据 API 订阅无效

如果用户遇到 DH-902 或 806：

1. 登录 web.dhan.co
2. 打开 My Profile -> Access DhanHQ APIs
3. 确认 dataPlan 已激活
4. 如有需要，激活 Data API 计划
5. 生成新的访问令牌
6. 使用 ticker_data() 或 ohlc_data() 重新测试
7. 如果订单 API 仍然失败，请另行检查静态 IP