dhanhq-skills

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# DhanHQ Agent Skills

Use DhanHQ APIs inside AI agents like Claude Code, Codex or any other agent of your choice.

**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](https://api.dhan.co/v2/#/).

Built for the [Agent Skills open standard](https://agentskills.io) and compatible with Claude Code, Codex, and any agent that supports SKILL.md.

---

## Installation

**You don’t need to clone the repository. Install the skill directly with `npx`.**

### Global install

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

### Claude Code or Codex

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

OR 

```bash
npx @dhan-oss/dhanhq-skill
```

---
## After Installation

Once installed, your AI agent can automatically use the `dhanhq` skill when your prompt involves DhanHQ APIs, Indian market data, portfolio, orders, funds, or trading workflows.

Example prompts:

- Show my holdings
- Get daily OHLC for RELIANCE for the last 6 months
- Show Nifty option chain for nearest expiry
- Check margin required to sell 1 lot of Nifty

## 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](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/orders.md) |
| Portfolio (holdings, positions, convert, eDIS) | [references/portfolio.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/portfolio.md) |
| Market Data (historical OHLC, quotes, depth) | [references/market-data.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/market-data.md) |
| Option Chain (Greeks, OI, expiry list) | [references/option-chain.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/option-chain.md) |
| Instruments (security master, symbol resolution) | [references/instruments.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/instruments.md) |
| Funds & Margin | [references/funds.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/funds.md) |
| Live Feed (MarketFeed, OrderUpdate, FullDepth) | [references/live-feed.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/live-feed.md) |
| ScanX real-time scanner | [references/scanx-data.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/references/scanx-data.md) |
| Error codes, rate limits, retry patterns | [references/error-codes.md](https://github.com/dhan-oss/dhanhq-skills/blob/HEAD/skills/dhanhq/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](https://pypi.org/project/dhanhq/))
- **Version**: 2.2.0+
- **Base URL**: `https://api.dhan.co/v2`
- **Docs**: [dhanhq.co/docs/v2](https://dhanhq.co/docs/v2/)
- **GitHub**: [github.com/dhan-oss/DhanHQ-py](https://github.com/dhan-oss/DhanHQ-py)

---

## Contributing

This skill is built for the [Agent Skills](https://agentskills.io) 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

DhanHQ Agent Skills

Use DhanHQ APIs inside AI agents like Claude Code, Codex or any other agent of your choice.

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

You don’t need to clone the repository. Install the skill directly with npx.

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

npx @dhan-oss/dhanhq-skill

After Installation

Once installed, your AI agent can automatically use the dhanhq skill when your prompt involves DhanHQ APIs, Indian market data, portfolio, orders, funds, or trading workflows.

Example prompts:

Show my holdings
Get daily OHLC for RELIANCE for the last 6 months
Show Nifty option chain for nearest expiry
Check margin required to sell 1 lot of Nifty

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:

SKILL.md (~300 lines) gives the agent setup, safety rules, constants, and core code patterns — enough for 80% of tasks.
references/*.md are loaded only when a task needs deeper detail (e.g., full order parameter tables, WebSocket setup).
scripts/ provide reusable utilities the agent can call directly.
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:

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

License

MIT