dhan-tradehull

Dhan-Tradehull スキル（v3.3.2）

Dhan API をラップする TradeHull の Python ラッパーです。必ず最初にインポートして初期化してください。

📐 コードを生成する際は、必ず TradeHull のコーディングスタイルに従ってください。 戦略やアルゴのコードを書く前に、references/coding-style.md をお読みください。 主なルール：縦方向の位置合わせ、bc1/bc2/sc1/sc2 条件、ブロックコメント、フラットな構造。

参照ファイル — 必要に応じて読み込む

タスク	読むファイル
ログイン、認証、トークンの設定	references/auth.md
LTP、OHLC、気配値、ヒストリカルデータ	references/market-data.md
オプションチェーン、ストライク選択、期限切れデータ	references/options.md
注文の発注、変更、キャンセル、スーパー注文／無期限注文	references/orders.md
保有資産、ポジション、注文一覧、残高、損益	references/portfolio.md
ロットサイズ、証拠金、Telegram、損益による決済、キルスイッチ	references/utilities.md
エラー、SEBI 規制、既知の問題	references/error-log.md
アルゴを最初から最後まで構築する（認証→データ→シグナル→注文→決済）	references/algo-dev-workflow.md
スキャナー：ウォッチリスト全体の指標／クロスオーバー（TA-Lib）	references/algo-scanner.md
アルゴ上で動作するブラウザーダッシュボード／UI（Flask）	references/flask-ui.md
ダッシュボードの設計：レイアウト、色、進捗、ライブ注文の安全性	references/ui-ux.md
サーバー上でアルゴを実行する：デタッチ、再起動、systemd、ログ、ポート	references/deployment.md

---

1. インストール

pip install --pre dhanhq
pip install Dhan-Tradehull

---

2. 認証（3 つのモード）

from Dhan_Tradehull import Tradehull

# Mode 1: Access Token
# ⚠️  TOKEN EXPIRES DAILY — must regenerate every morning before market open
# Get new token from: Dhan web → My Profile → API Access
tsl = Tradehull(client_code, token_id, mode="access_token")

# Mode 2: API Key (browser-based login flow)
tsl = Tradehull(client_code, mode="api_key", api_key=api_key, api_secret=api_secret)

# Mode 3: PIN + TOTP
# ✅ PIN IS VALID FOR LIFETIME — no daily regeneration needed
# Best for fully automated algos running without manual intervention
tsl = Tradehull(ClientCode=client_code, mode="pin_totp", pin=pin, totp_secret=totp_secret)

認証モードの比較：

モード	トークンの有効期間	最適な用途
access_token	⚠️ 1 日 — 毎朝再生成	手動／半自動取引
api_key	毎回ブラウザーフローを実行	単発スクリプト
pin_totp	✅ 無期限（PIN は期限切れになりません）	全自動アルゴ、スケジュールされたジョブ

---

3. マーケットデータ

# LTP (Last Traded Price)
# ✅ Up to 500 symbols in one call, returns in under 1 second
# Returns dict → {symbol (str): ltp (float)}
data = tsl.get_ltp_data(names=['NIFTY', 'BANKNIFTY', 'CRUDEOIL'])
nifty_ltp = data['NIFTY']        # 24523.5
crude_ltp = data['CRUDEOIL']     # 6570.0

# Full Quote
data = tsl.get_quote_data(names=['RELIANCE'])

# OHLC
data = tsl.get_ohlc_data(names=['NIFTY', 'CRUDEOIL'])

# Historical Data (timeframe: '1','5','15','25','60','DAY')
df = tsl.get_historical_data(tradingsymbol='NIFTY', exchange='INDEX', timeframe='5')
df = tsl.get_historical_data(tradingsymbol='ACC', exchange='NSE', timeframe='1')

# Long-Term Historical (custom date range)
df = tsl.get_long_term_historical_data(
    tradingsymbol='RELIANCE', exchange='NSE', timeframe='5',
    from_date='2024-01-01', to_date='2025-01-01'
)

# Sector Data
df = tsl.get_historical_data(tradingsymbol="NIFTY 100", exchange="NSE",
                              timeframe="DAY", sector="YES")

取引所の値： 'NSE'、'BSE'、'NFO'、'BFO'、'MCX'、'INDEX'

---

4. オプションのストライク選択

# ATM
CE_sym, PE_sym, strike = tsl.ATM_Strike_Selection(Underlying='NIFTY', Expiry=0)

# OTM (OTM_count = steps away from ATM)
CE_sym, PE_sym, CE_strike, PE_strike = tsl.OTM_Strike_Selection(
    Underlying='NIFTY', Expiry=0, OTM_count=5)

# ITM
CE_sym, PE_sym, CE_strike, PE_strike = tsl.ITM_Strike_Selection(
    Underlying='NIFTY', Expiry=0, ITM_count=1)

満期： 0 = 今週／今月、1 = 次回、2 = それ以降

---

5. オプションのグリークス

⚠️ 実際の運用では非推奨です — 新しいコードで get_option_greek() を使用しないでください。 グリークス（Delta、Theta、Gamma、Vega、IV）は、各ストライクのグリークスを含む完全な DataFrame を返す get_option_chain() から直接取得できます。 グリークスデータには、常に get_option_chain() を優先してください。

---

6. オプションチェーン

# ✅ Returns TWO values — atm (int) + option_chain (DataFrame)
atm, chain = tsl.get_option_chain(Underlying="NIFTY", exchange="INDEX", expiry=0, num_strikes=10)

# atm = current ATM strike as int e.g. 24000
# chain = DataFrame, 21 rows × 27 columns (for num_strikes=10)

# Columns: CE OI, CE Chg in OI, CE Volume, CE IV, CE LTP,
#          CE Bid Qty, CE Bid, CE Ask, CE Ask Qty,
#          CE Delta, CE Theta, CE Gamma, CE Vega,
#          Strike Price,
#          PE Bid Qty, PE Bid, PE Ask, PE Ask Qty,
#          PE LTP, PE IV, PE Volume, PE Chg in OI, PE OI,
#          PE Delta, PE Theta, PE Gamma, PE Vega

# ATM row
atm_row      = chain[chain['Strike Price'] == atm]
ce_ltp       = atm_row['CE LTP'].values[0]
pe_ltp       = atm_row['PE LTP'].values[0]

# OI analysis
ce_resistance = chain.loc[chain['CE OI'].idxmax(), 'Strike Price']  # highest CE OI = resistance
pe_support    = chain.loc[chain['PE OI'].idxmax(), 'Strike Price']  # highest PE OI = support
pcr           = chain['PE OI'].sum() / chain['CE OI'].sum()         # Put-Call Ratio

# Exchange values
# INDEX  → NIFTY, BANKNIFTY, FINNIFTY
# MCX    → CRUDEOIL, GOLD, SILVER
# NFO    → stock options

✅ グリークスを含みます — 各ストライクの Delta、Theta、Gamma、Vega、IV。 get_option_greek() は不要です。非推奨のため、こちらを使用してください。

---

7. 注文の発注

🚨 SEBI 規制（2026 年 4 月 1 日施行） F&O では MARKET 注文が使用できなくなります。 すべての注文を LIMIT 注文にする必要があります。

指値価格のルール：

• BUY → 指値価格は LTP より高くする必要があります（即時約定させるため）
• SELL → 指値価格は LTP より低くする必要があります（即時約定させるため）

指値注文で即時約定を狙う方法：

ltp = tsl.get_ltp_data(names=['NIFTY 19 DEC 24400 CALL'])['NIFTY 19 DEC 24400 CALL']
buy_price  = round(ltp * 1.02, 1)   # BUY の場合、LTP より 2% 高くする
sell_price = round(ltp * 0.98, 1)   # SELL の場合、LTP より 2% 低くする

# BUY limit order (price > LTP for instant fill)
order_id = tsl.order_placement(
    tradingsymbol='NIFTY 19 DEC 23300 CALL',
    exchange='NFO',
    quantity=75,
    price=0.05,               # must be > LTP
    trigger_price=0,
    order_type='LIMIT',       # ✅ always LIMIT — MARKET not allowed from Apr 2026
    transaction_type='BUY',
    trade_type='MIS'          # MIS, CNC, MARGIN, MTF, CO, BO
)

# SELL limit order (price < LTP for instant fill)
order_id = tsl.order_placement(
    tradingsymbol='NIFTY 19 DEC 23300 CALL',
    exchange='NFO',
    quantity=75,
    price=0.04,               # must be < LTP
    trigger_price=0,
    order_type='LIMIT',
    transaction_type='SELL',
    trade_type='MIS'
)

# Sliced/Iceberg order (exceeds freeze limit)
order_ids = tsl.order_placement(
    tradingsymbol="NIFTY 27 JAN 26000 CALL", exchange="NFO",
    transaction_type="BUY", quantity=1820, order_type="LIMIT",
    trade_type="MIS", price=21.05, should_slice=True
)

変更／キャンセル

tsl.modify_order(order_id=orderid, order_type="LIMIT", quantity=50, price=0.1)
tsl.cancel_order(OrderID=orderid)
tsl.cancel_all_orders()  # Cancel all intraday + square off positions

注文情報

tsl.get_order_detail(orderid=orderid)
tsl.get_order_status(orderid=orderid)     # 'Pending', 'Completed', etc.
tsl.get_executed_price(orderid=orderid)
tsl.get_exchange_time(orderid=orderid)

---

8. スーパー注文（エントリー＋ターゲット＋SL を一度に発注）

✅ アルゴ戦略に推奨される注文タイプです。 エントリー＋SL＋ターゲットを含む取引アルゴの構築を依頼された場合は、 3 つの注文を個別に発注するのではなく、まず place_super_order() を使用してください。 任意のトレーリング SL を含め、1 回の呼び出しで注文ライフサイクル全体を処理します。

order_id = tsl.place_super_order(
    tradingsymbol="TRIDENT", exchange="NSE",
    transaction_type="BUY", quantity=1,
    order_type="LIMIT", trade_type="MIS",
    price=25, target_price=27,
    stop_loss_price=24, trailing_jump=0.2
)

# Modify specific leg: ENTRY_LEG, TARGET_LEG, STOP_LOSS_LEG
tsl.modify_super_order(order_id=order_id, order_type="LIMIT", quantity=1,
                        price=24.9, leg_name="ENTRY_LEG")

tsl.cancel_super_order(order_id=order_id, leg_name="STOP_LOSS_LEG")
super_orders = tsl.get_super_orders()

---

9. フォーエバー注文／GTT

✅ ポジショナル戦略（スイング、BTST、ポジショナル）に推奨される注文タイプです。 ユーザーからスイングトレード、BTST、複数日にわたるポジショナルアルゴの作成を依頼された場合は、 通常の注文ではなく、必ずフォーエバー注文（GTT）を使用してください。 フォーエバー注文は、トリガーされるかキャンセルされるまで、セッションをまたいで有効です。

戦略の種類	使用する注文
SL＋ターゲット付きのイントラデイ	place_super_order()
スイング／BTST／ポジショナル	place_forever_order()

# SINGLE trigger — fires once when price condition met
forever_id = tsl.place_forever_order(
    tradingsymbol="TRIDENT", exchange="NSE",
    transaction_type="BUY", quantity=1,
    order_type="LIMIT", trade_type="CNC",
    price=25, trigger_price=25.05, order_flag="SINGLE"
)

# OCO — One Cancels Other (target + SL together)
forever_id = tsl.place_forever_order(
    tradingsymbol="TRIDENT", exchange="NSE",
    transaction_type="SELL", quantity=1,
    order_type="LIMIT", trade_type="CNC",
    price=27, trigger_price=27.05,          # target leg
    order_flag="OCO",
    quantity_1=1, price_1=24, trigger_price_1=23.95   # SL leg
)

# Modify a specific leg
tsl.modify_forever_order(
    order_id=forever_id, order_type="LIMIT",
    quantity=1, price=24.9, trigger_price=24.7,
    disclosed_quantity=0, validity="DAY",
    leg_name="STOP_LOSS_LEG", order_flag="SINGLE"
)

# Cancel
tsl.cancel_forever_order(order_id=forever_id)   # returns cancel order_id str

# Fetch all active forever orders
forever_orders = tsl.get_forever_orders()        # returns list

---

10. 条件付きトリガー注文

⚠️ TradeHull の戦略では使用しません。 Python で条件を直接確認し、インジケーターの計算には TA-Lib を使用します。 これにより、インジケーターのパラメーター、複数条件のロジック、 カスタムシグナルを自在に制御でき、Dhan の組み込みトリガー条件よりもはるかに柔軟です。

新しいコードでは place_conditional_trigger() を使用しないでください。 代わりに get_historical_data() と TA-Lib を使用してください。

---

11. ポートフォリオ管理

holdings  = tsl.get_holdings()        # DataFrame
positions = tsl.get_positions()        # DataFrame
orderbook = tsl.get_orderbook()        # DataFrame
tradebook = tsl.get_trade_book()       # DataFrame
balance   = tsl.get_balance()          # float
pnl       = tsl.get_live_pnl()        # float

lot_size  = tsl.get_lot_size(tradingsymbol='NIFTY 19 DEC 24400 CALL')
# ⚠️ ALWAYS fetch lot size dynamically — never hardcode
# SEBI revises lot sizes periodically (e.g. NIFTY was 75, now 65)
# Hardcoded quantity causes order rejection when lot size changes

margin = tsl.margin_calculator(
    tradingsymbol='NIFTY DEC FUT', exchange='NFO',
    transaction_type='BUY', quantity=75,
    trade_type='MARGIN', price=24350, trigger_price=0
)

---

12. 全板情報（20段階）

# Single
depth_client = tsl.full_market_depth_data(("RELIANCE", "NSE"))
bid_df, ask_df = tsl.get_market_depth_df(depth_client)

# Multiple
symbol_list = [("RELIANCE","NSE"), ("NIFTY 09 DEC 26000 CALL","NFO")]
depth_data = tsl.full_market_depth_data(symbol_list)
for key, dc in depth_data.items():
    bid_df, ask_df = tsl.get_market_depth_df(dc)

---

13. 期限切れオプションの過去データ

data = tsl.get_expired_option_data(
    tradingsymbol="NIFTY", exchange="NSE",
    interval=5,               # 1,5,15,25,60
    expiry_flag="WEEK",       # WEEK or MONTH
    expiry_code=1,            # 1=near, 2=next, 3=far
    strike="ATM",             # ATM, ATM+3, ATM-3 etc.
    option_type="CALL",
    from_date="2024-10-01", to_date="2024-10-31"
)

---

14. 損益ベースの決済

# Auto exit when profit/loss threshold hit
tsl.enable_pnl_based_exit(
    profit_value=1000, loss_value=800,
    product_types=("INTRADAY", "DELIVERY"),
    enable_kill_switch=True   # True = full kill switch on trigger
)

---

15. Telegram アラート

tsl.send_telegram_alert(
    message="BUY NIFTY 24400 CE @ 120 executed",
    receiver_chat_id="123456789",
    bot_token="YOUR_BOT_TOKEN"
)

📖 ユーザーが receiver_chat_id または bot_token を持っていない場合： https://tradehull.com/telegram-integration-for-algo-trading/ を案内してください。

---

よくあるパターン

OI スキャルピングループの骨格

import time
from Dhan_Tradehull import Tradehull

tsl = Tradehull(client_code, token_id, mode="access_token")

while True:
    atm, chain = tsl.get_option_chain(Underlying="NIFTY", exchange="INDEX", expiry=0, num_strikes=5)
    # analyse chain for OI buildup / unwinding

    # place orders — always LIMIT for F&O (MARKET banned from Apr 2026)
    ce_name, pe_name, strike = tsl.ATM_Strike_Selection(Underlying="NIFTY", Expiry=0)
    ltp          = tsl.get_ltp_data(names=[ce_name])[ce_name]
    limit_price  = round(ltp * 1.02, 1)   # 2% above LTP for instant BUY fill
    order_id     = tsl.order_placement(
        tradingsymbol=ce_name, exchange="NFO", quantity=tsl.get_lot_size(ce_name),
        price=limit_price, trigger_price=0,
        order_type="LIMIT", transaction_type="BUY", trade_type="MIS"
    )
    time.sleep(1)

条件ベースのエントリー（TradeHull パターン）

# Use TA-Lib to compute indicator, check condition in Python — not conditional trigger API
import talib

chart       = tsl.get_historical_data(tradingsymbol="RELIANCE", exchange="NSE", timeframe="15")
chart["rsi"] = talib.RSI(chart["close"], timeperiod=14)
rc           = chart.iloc[-1]   # last completed candle

bc1          = rc["rsi"] < 30   # oversold
bc2          = orderbook["RELIANCE"]["traded"] is None

if bc1 and bc2:
    ltp         = tsl.get_ltp_data(names=["RELIANCE"])["RELIANCE"]
    limit_price = round(ltp * 1.002, 1)
    order_id    = tsl.order_placement(
        tradingsymbol="RELIANCE", exchange="NSE", quantity=10,
        price=limit_price, trigger_price=0,
        order_type="LIMIT", transaction_type="BUY", trade_type="CNC"
    )

---

デバッグモード

データ取得メソッドに debug="YES" を追加すると、API の生レスポンスが出力されます。

data = tsl.get_ltp_data(names=['NIFTY'], debug="YES")

---

注意事項

• access_token は毎日有効期限が切れます。市場が開く前に、毎朝再生成してください
• pin_totp の PIN は有効期限がありません。完全自動化／スケジュール実行のアルゴにはこちらを推奨します
• 取引所のフリーズ制限を超える大口注文では、should_slice=True を指定してください
• すべてのポートフォリオメソッドは pd.DataFrame を返します
• 取引所の値：株式＝NSE／BSE、指数＝INDEX、F&O＝NFO／BFO、コモディティ＝MCX
• ロットサイズは必ず get_lot_size() で動的に取得してください。ハードコードしないでください
• 最新バージョン：3.3.1（2026年6月3日）