DhanHQ MCP Server

# DhanHQ MCP Server - Quick Reference ## All Available Tools (20 Total) ### 🔐 Authentication (5 tools) 1. **start_authentication** - Begin 3-step OAuth flow 2. **get_login_instructions** - Get browser login URL 3. **complete_authentication** - Complete OAuth with tokenId 4. **check_auth_status** - Check authentication status 5. **reset_authentication** - Clear auth state ### 💰 Account (1 tool) 6. **get_fund_limit** - Get balance, margins, collateral ### 📊 Order Management (8 tools) 7. **place_order** - Create new order (MARKET/LIMIT/STOP/STOP_LIMIT) 8. **modify_order** - Modify pending order 9. **cancel_order** - Cancel pending order 10. **get_order_book** - View all orders for the day 11. **get_order_by_id** - Get specific order details 12. **get_order_by_correlation_id** - Find order by correlation ID 13. **get_trade_book** - View all executed trades 14. **get_order_trades** - View trades for specific order ### 🎯 Super Orders (4 tools) 15. **place_super_order** - Create entry + target + stop-loss order 16. **modify_super_order** - Modify super order leg 17. **cancel_super_order_leg** - Cancel specific leg 18. **get_super_order_book** - View all super orders ## Quick Usage Examples ### Typical Trading Workflow ``` 1. start_authentication ↓ (Copy login URL and authenticate in browser) 2. complete_authentication (with tokenId from redirect) ↓ 3. get_fund_limit (verify balance) ↓ 4. place_order (or place_super_order) ↓ 5. get_order_book (view all orders) ↓ 6. get_order_trades (see execution prices) ``` ### Example: Place Buy Order ``` place_order: - dhanClientId: "1000000003" - correlationId: "my_order_001" - transactionType: "BUY" - exchangeSegment: "NSE_EQ" - productType: "INTRADAY" - orderType: "LIMIT" - validity: "DAY" - securityId: "11536" - quantity: 5 - price: 1500 ``` ### Example: Place Smart Super Order (Entry + Target + SL) ``` place_super_order: - dhanClientId: "1000000003" - correlationId: "smart_001" - transactionType: "BUY" - exchangeSegment: "NSE_EQ" - productType: "INTRADAY" - orderType: "LIMIT" - securityId: "11536" - quantity: 5 - price: 1500 (entry) - targetPrice: 1600 (profit target) - stopLossPrice: 1450 (stop loss) - trailingJump: 10 (optional) ``` ## Supported Values ### Transaction Types - `BUY` - Buy order - `SELL` - Sell order ### Exchange Segments - `NSE_EQ` - NSE Equities - `BSE_EQ` - BSE Equities - `NFO_FUT` - NFO Futures - `NFO_OPT` - NFO Options ### Product Types - `CNC` - Carry Forward (Delivery) - `INTRADAY` - Intraday (same-day settlement) - `MIS` - Margin Intraday Settlement - `MTF` - Margin Trading Facility - `NRML` - Normal (Futures/Options) ### Order Types - `MARKET` - Market order - `LIMIT` - Limit order - `STOP` - Stop loss order - `STOP_LIMIT` - Stop loss with limit ### Validity - `DAY` - Valid for today only - `IOC` - Immediate or Cancel - `TTL` - Time to Live - `GTC` - Good Till Cancel ### Super Order Legs - `ENTRY_LEG` - Main entry order - `TARGET_LEG` - Profit target - `STOP_LOSS_LEG` - Stop loss protection ## Build & Run ```bash # Install dependencies npm install # Build TypeScript npm run build # Start the server (production) npm start # Run MCP Inspector for testing npm run inspector # Watch for changes during development npm run watch ``` ## Troubleshooting ### "No valid access token" → Run `check_auth_status` to see if authenticated → Run `start_authentication` → `complete_authentication` flow ### Order placement fails → Verify `dhanClientId` is correct → Check `securityId` is valid for the exchange → Ensure `quantity` is within market freeze limits → For LIMIT orders, ensure `price` is provided → For STOP orders, ensure `triggerPrice` is provided ### Can't find order → Use `get_order_book` to see all orders → Use `get_order_by_id` with the order ID → Use `get_order_by_correlation_id` with correlation ID → Orders are only available for current trading day ### Modified order shows old status → Status updates after API response → Use `get_order_by_id` to fetch latest status → Check `updateTime` field for last update ## API Rate Limits Be mindful of DhanHQ API rate limits: - Space out rapid requests - Avoid polling more than necessary - Use correlation IDs to track orders efficiently ## Security Notes ⚠️ **Important:** - Never hardcode credentials in code - Use `.env` file for API credentials - Keep `DHAN_API_SECRET` confidential - Access tokens are redacted in `check_auth_status` - MCP Inspector should only run on localhost ## Performance Tips 1. Use `get_order_book` sparingly (returns all orders) 2. Use `get_order_by_id` for specific orders 3. Cache order data locally when possible 4. Use correlation IDs to avoid duplicate orders 5. Monitor API response times and throttle requests ## Common Parameters | Parameter | Type | Required | Notes | |-----------|------|----------|-------| | dhanClientId | string | For modify/cancel operations | Your Dhan account ID | | correlationId | string | For place operations | Unique identifier for tracking | | orderId | string | For modification operations | Returned from place_order | | quantity | number | Yes | Must respect market freeze limits | | price | number | For LIMIT/STOP_LIMIT | Price per share/contract | | triggerPrice | number | For STOP/STOP_LIMIT | Trigger level | | validity | string | Yes | Order validity type | ## Getting Help 1. Check tool descriptions in MCP Inspector 2. Review error messages (look for API response details) 3. Enable stderr logging by running `npm run dev` 4. Verify all required parameters are provided 5. Check DhanHQ API documentation for endpoint specifics