DhanHQ Agent Skills

Dhan-native agent skill for NSE/BSE equities, F&O, and commodity trading.

Give your AI agent the ability to place live orders, read real portfolio data, stream market feeds, and access the full instrument universe of Indian exchanges — all through DhanHQ's APIs.

Built for the Agent Skills open standard and compatible with Claude Code, Codex, and any agent that supports SKILL.md.

Installation

Global install

npm install -g skills
skills add dhan-oss/dhanhq-skills --skill dhanhq

Claude Code or Codex

npx skills add dhan-oss/dhanhq-skills --skill dhanhq

OR

npx @dhan-oss/dhanhq-skill

Requirements

• Python 3.8+ and pip install dhanhq
• Order APIs: static IP whitelisting on Dhan required
• Data APIs: active Dhan Data Plan required
• Credentials via environment variables: DHAN_CLIENT_ID and DHAN_ACCESS_TOKEN

What's Included

skills/
└── dhanhq/
    ├── SKILL.md                          # Entry point — setup, safety rules, core patterns
    │
    ├── references/                       # Deep-dive docs loaded on demand
    │   ├── orders.md                     # Order lifecycle (regular, super, forever, AMO)
    │   ├── portfolio.md                  # Holdings, positions, convert position, eDIS
    │   ├── market-data.md                # Historical OHLC, intraday, quotes
    │   ├── option-chain.md               # Option chain with Greeks, expiry list
    │   ├── instruments.md                # Security master, symbol resolution
    │   ├── funds.md                      # Fund limits and margin calculator
    │   ├── live-feed.md                  # WebSocket: MarketFeed, OrderUpdate, FullDepth
    │   ├── error-codes.md                # Error codes, rate limits, retry patterns
    │   ├── scanx-data.md                 # ScanX real-time scanner data
    │   ├── common-workflows.md           # Multi-step patterns (rebalance, iron condor, P&L)
    │   ├── options-analysis-patterns.md  # PCR, max pain, payoff diagrams, IV skew
    │   └── backtesting-with-dhan.md      # Equity + F&O backtest patterns with cost model
    │
    ├── scripts/
    │   ├── dhan_helpers.py               # Composable helper library
    │   ├── resolve_security.py           # Human name → security_id resolver
    │   ├── validate_order.py             # Pre-flight order validation with guardrails
    │   └── trade_logger.py               # Persistent trade journal
    │
    └── examples/
        ├── place_equity_order.py         # Simple equity delivery order
        ├── place_fno_order.py            # F&O option order with lot-size validation
        ├── fetch_option_chain.py         # Nifty option chain with ATM analysis
        ├── iron_condor.py                # Multi-leg strategy: build + analyze + place
        ├── super_order_with_sl.py        # Entry + target + trailing SL in one order
        ├── gtt_forever_order.py          # GTT single trigger and OCO orders
        ├── order_management.py           # Full lifecycle: place, modify, cancel, book
        ├── portfolio_summary.py          # Holdings + positions + funds dashboard
        ├── margin_check.py               # Pre-order margin validation
        ├── historical_data_analysis.py   # Fetch OHLCV + moving averages + stats
        └── live_feed_setup.py            # WebSocket market data streaming

How It Works

The skill follows progressive disclosure to minimize context usage:

1. SKILL.md (~300 lines) gives the agent setup, safety rules, constants, and core code patterns — enough for 80% of tasks.
2. references/*.md are loaded only when a task needs deeper detail (e.g., full order parameter tables, WebSocket setup).
3. scripts/ provide reusable utilities the agent can call directly.
4. examples/ are complete, runnable scripts the agent can reference or adapt.

When Agents Use This Skill

The skill activates when the user:

• Wants to place, modify, or cancel stock or F&O orders
• Asks about portfolio holdings or positions
• Needs live or historical market data (OHLC, quotes, depth)
• Wants to work with option chains (Greeks, OI, IV)
• Asks about fund limits or margin requirements
• Mentions DhanHQ, Dhan API, or Indian stock market trading
• Wants to build trading automation for NSE/BSE/MCX
• Needs to backtest a strategy using historical data

Built-In Safety Guardrails

| Rule | What it does | |------|-------------| | Confirmation required | Always shows order preview and asks for user confirmation before placing | | Default to LIMIT | Never places MARKET orders unless user explicitly requests | | Default to 1 lot | Defaults to 1 share (equity) or 1 lot (F&O) when quantity is unspecified | | Lot size validation | Rejects F&O orders where quantity isn't a lot-size multiple | | Product type guardrails | Blocks CNC/MTF for F&O segments; blocks invalid product-segment combos | | Notional value warning | Warns when order value exceeds ₹50,000 | | Freeze quantity check | Warns when F&O quantity exceeds exchange freeze limits | | Market hours check | Warns when market is closed, suggests AMO | | No hardcoded tokens | Always uses environment variables for credentials |

API Coverage

| Category | Reference | |----------|-----------| | Orders (regular, super, forever/GTT, AMO, slice) | references/orders.md | | Portfolio (holdings, positions, convert, eDIS) | references/portfolio.md | | Market Data (historical OHLC, quotes, depth) | references/market-data.md | | Option Chain (Greeks, OI, expiry list) | references/option-chain.md | | Instruments (security master, symbol resolution) | references/instruments.md | | Funds & Margin | references/funds.md | | Live Feed (MarketFeed, OrderUpdate, FullDepth) | references/live-feed.md | | ScanX real-time scanner | references/scanx-data.md | | Error codes, rate limits, retry patterns | references/error-codes.md |

Example Prompts

Orders

• "Buy 10 shares of Reliance at market"
• "Place a limit order for HDFC Bank at 1650"
• "Buy 1 lot of Nifty 24000 CE expiry this week"
• "Place a super order on TCS with target 4200 and SL 3900"
• "Set a GTT to buy Infosys if it drops to 1400"

Portfolio

• "Show me my holdings"
• "What's my total portfolio value?"
• "Show my open F&O positions"
• "Convert my INFY position from intraday to delivery"

Market Data

• "Get daily OHLC for Reliance for the last 6 months"
• "What's the current LTP of HDFC Bank?"
• "Show me 5-minute candles for TCS today"

Options

• "Show me the Nifty option chain for nearest expiry"
• "What's the PCR for Bank Nifty?"
• "Build me a Nifty iron condor"

Funds & Margin

• "What's my available margin?"
• "How much margin do I need to sell 1 lot of Nifty?"

SDK Reference

• Package: dhanhq (PyPI)
• Version: 2.2.0+
• Base URL: https://api.dhan.co/v2
• Docs: dhanhq.co/docs/v2
• GitHub: github.com/dhan-oss/DhanHQ-py

Contributing

This skill is built for the Agent Skills open standard. To contribute:

1. Fork this repository
2. Make changes in skills/dhanhq/
3. Verify against the DhanHQ SDK (pip install dhanhq)
4. Submit a pull request

License

MIT