DhanHQ 3.0.1 → 3.1.0

data/skills/dhanhq-ruby/references/common-workflows.md

@@ -0,0 +1,76 @@
+# Common Workflows — Agent Playbooks (Ruby SDK)
+
+## Portfolio Rebalance
+
+Recommended sequence:
+1. Fetch holdings and funds.
+2. Compute target deltas.
+3. Resolve symbols and quantities.
+4. Preview proposed orders.
+5. Confirm with the user.
+6. Place live orders.
+
+```ruby
+holdings = DhanHQ::Models::Holding.all rescue []
+funds = DhanHQ::Models::Funds.fetch rescue nil
+
+if funds
+  available_cash = funds.availabel_balance || funds.available_balance || 0.0
+end
+```
+
+## Delivery Sell With eDIS
+
+Use this flow for selling demat holdings:
+1. Fetch holdings and identify ISIN.
+2. Generate TPIN: `DhanHQ::Models::EDIS.generate_tpin`
+3. Open authorization form: `DhanHQ::Models::EDIS.open_browser_for_tpin(isin: "...", qty: 5, exchange: "NSE")`
+4. Check inquiry: `DhanHQ::Models::EDIS.inquiry(isin: "...")`
+5. Place the sell order.
+
+```ruby
+# Generate TPIN
+DhanHQ::Models::EDIS.generate_tpin
+
+# Open authorization portal
+DhanHQ::Models::EDIS.open_browser_for_tpin(isin: "INE002A01018", qty: 5, exchange: "NSE")
+
+# Inquiry
+status = DhanHQ::Models::EDIS.inquiry(isin: "INE002A01018")
+```
+
+## Single-Leg F&O Execution
+
+Recommended sequence:
+1. Resolve current contract from option chain or security master.
+2. Resolve lot size.
+3. Validate quantity.
+4. Check margin.
+5. Preview & Confirm.
+6. Place live order.
+
+```ruby
+require_relative "../scripts/dhan_helpers"
+
+chain_df, spot = fetch_chain_df(under_security_id: 13, expiry: "2025-03-27")
+atm = find_atm_row(chain_df, spot)
+
+margin = check_margin(
+  security_id: atm["ce_security_id"],
+  exchange_segment: "NSE_FNO",
+  transaction_type: "BUY",
+  quantity: 75,
+  product_type: "INTRADAY",
+  price: atm["ce_ltp"].to_f
+)
+```
+
+## Daily P&L Summary
+
+```ruby
+require_relative "../scripts/dhan_helpers"
+
+holdings = DhanHQ::Models::Holding.all
+positions = DhanHQ::Models::Position.all
+summary = format_pnl_report(holdings, positions)
+```

data/skills/dhanhq-ruby/references/error-codes.md

@@ -0,0 +1,50 @@
+# Error Codes — Complete Reference (Ruby SDK)
+
+In the Ruby SDK, raw API error codes are automatically mapped in the client layer and raised as structured exceptions.
+
+## Exception Mapping
+
+The Ruby client maps Dhan error codes to specific error classes under the `DhanHQ` module:
+
+| Error Code | Error Class | Meaning |
+|------------|-------------|---------|
+| `DH-901` | `DhanHQ::InvalidAuthenticationError` | Client ID or access token is invalid or expired |
+| `DH-902` | `DhanHQ::InvalidAccessError` | User does not have required Data API or Trading API access |
+| `DH-903` | `DhanHQ::UserAccountError` | Account setup issue or segment activation requirement |
+| `DH-904` | `DhanHQ::RateLimitError` | Rate limit exceeded |
+| `DH-905` | `DhanHQ::InputExceptionError` | Missing or invalid request fields |
+| `DH-906` | `DhanHQ::OrderError` | Order request cannot be processed |
+| `DH-907` | `DhanHQ::DataError` | Data unavailable or parameters invalid |
+| `DH-908` | `DhanHQ::InternalServerError` | Server-side failure |
+| `DH-909` | `DhanHQ::NetworkError` | Backend communication failure |
+| `DH-1111` | `DhanHQ::NoHoldingsError` | No holdings present in the account |
+| `DH-910` / other | `DhanHQ::OtherError` / `DhanHQ::Error` | Other failure reasons |
+
+## Data API Errors
+
+| Code | Exception | Meaning |
+|------|-----------|---------|
+| `800` | `DhanHQ::InternalServerError` | Internal Server Error |
+| `804` | `DhanHQ::Error` | Requested number of instruments exceeds limit |
+| `805` | `DhanHQ::RateLimitError` | Too many requests or connections |
+| `806` | `DhanHQ::DataError` | Data APIs not subscribed |
+| `807` | `DhanHQ::TokenExpiredError` | Access token is expired |
+| `808` | `DhanHQ::AuthenticationFailedError` | Authentication failed - client ID or access token invalid |
+| `809` | `DhanHQ::InvalidTokenError` | Access token is invalid |
+| `810` | `DhanHQ::InvalidClientIDError` | Client ID is invalid |
+| `811` | `DhanHQ::InvalidRequestError` | Invalid expiry date |
+| `812` | `DhanHQ::InvalidRequestError` | Invalid date format |
+| `813` | `DhanHQ::InvalidRequestError` | Invalid security ID |
+| `814` | `DhanHQ::InvalidRequestError` | Invalid request |
+
+## User Action Checklist
+
+### Invalid Data Subscription (`806` or `DH-902`)
+If you receive access errors:
+1. Log in to `web.dhan.co`.
+2. Go to **My Profile** -> **Access DhanHQ APIs**.
+3. Verify that the **Data API** plan is active.
+4. If not active, activate it, generate a fresh access token, and retry.
+
+### Static IP Error (`DH-911` or IP issue)
+If placing or managing orders fails with IP errors, ensure that the server's public IP is whitelisted in your Dhan console.

data/skills/dhanhq-ruby/references/funds.md

@@ -0,0 +1,67 @@
+# Funds & Margin — Complete Reference (Ruby SDK)
+
+The Ruby SDK exposes first-class models `DhanHQ::Models::Funds` and `DhanHQ::Models::Margin` for funds retrieval and pre-flight margin checks (both single-order and multi-leg).
+
+## Fund Limits
+
+Use `DhanHQ::Models::Funds.fetch`:
+
+```ruby
+funds = DhanHQ::Models::Funds.fetch
+
+puts "Available Balance: Rs. #{funds.availabel_balance || funds.available_balance}"
+puts "Utilized:          Rs. #{funds.utilized_amount}"
+puts "Collateral:        Rs. #{funds.collateral_amount}"
+puts "Withdrawable:      Rs. #{funds.withdrawable_balance}"
+```
+
+Normalized model attributes:
+- `dhan_client_id`
+- `availabel_balance` (or alias `available_balance`)
+- `sod_limit`
+- `collateral_amount`
+- `receiveable_amount`
+- `utilized_amount`
+- `blocked_payout_amount`
+- `withdrawable_balance`
+
+---
+
+## Margin Calculator — Single Order
+
+Use `DhanHQ::Models::Margin.calculate(params)`:
+
+```ruby
+margin = DhanHQ::Models::Margin.calculate(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  quantity: 10,
+  product_type: "CNC",
+  price: 2450.0
+)
+
+puts "Total Margin:       Rs. #{margin.total_margin}"
+puts "Available Balance:  Rs. #{margin.available_balance}"
+puts "Brokerage Charges:  Rs. #{margin.brokerage}"
+puts "Leverage Offered:   #{margin.leverage}x"
+```
+
+---
+
+## Multi-Order Margin
+
+Unlike the Python SDK, the Ruby SDK has first-class support for multi-leg portfolio margin calculation via `DhanHQ::Models::Margin.calculate_multi(params)`:
+
+```ruby
+margin = DhanHQ::Models::Margin.calculate_multi(
+  include_position: true,
+  include_orders: true,
+  scripts: [
+    { exchange_segment: "NSE_EQ", transaction_type: "BUY", quantity: 100, product_type: "CNC", security_id: "1333", price: 1428.0 },
+    { exchange_segment: "NSE_EQ", transaction_type: "SELL", quantity: 50, product_type: "INTRADAY", security_id: "11536", price: 3000.0 }
+  ]
+)
+
+puts "Portfolio Total Margin Required: Rs. #{margin.total_margin}"
+```

data/skills/dhanhq-ruby/references/instruments.md

@@ -0,0 +1,85 @@
+# Instruments — Complete Reference (Ruby SDK)
+
+Use the security master as the primary source for `security_id`, lot size, expiry, strike, tick size, and display symbol.
+
+## Preferred SDK Entry Point
+
+In the Ruby SDK, search and load instruments segment-wise using:
+
+```ruby
+# Retrieve compact list for a single segment (returns Array of Instrument objects)
+instruments = DhanHQ::Models::Instrument.by_segment("NSE_EQ")
+```
+
+Official instrument sources (managed by the SDK internally):
+- Compact CSV: `https://images.dhan.co/api-data/api-scrip-master.csv`
+- Detailed CSV: `https://images.dhan.co/api-data/api-scrip-master-detailed.csv`
+
+---
+
+## Key Columns (Instrument Attributes)
+
+| Attribute | Meaning |
+|-----------|---------|
+| `security_id` | Security ID (String) |
+| `exchange` | Exchange ID (`NSE`, `BSE`, `MCX`) |
+| `instrument` | Instrument Type (`EQUITY`, `OPTIDX`, `OPTSTK`, etc.) |
+| `symbol_name` | Exchange trading symbol |
+| `display_name` | Dhan custom symbol |
+| `lot_size` | Lot size (Integer) |
+| `tick_size` | Tick size (Float) |
+| `expiry_date` | Expiry date (String) |
+| `strike_price` | Strike price (Float) |
+| `option_type` | Option Type (`CALL` or `PUT`) |
+
+---
+
+## Recommended Resolution Flow
+
+Use the SDK's built-in helper methods on the `Instrument` class:
+
+```ruby
+# Find specific instrument in a segment (exact match)
+inst = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+
+# Search across multiple segments (finds any match)
+inst = DhanHQ::Models::Instrument.find_anywhere("RELIANCE")
+
+# Fuzzy search across multiple segments
+results = DhanHQ::Models::Instrument.search("RELIANCE")
+```
+
+Or leverage the helper layer in `scripts/dhan_helpers.rb`:
+
+```ruby
+require_relative "../scripts/dhan_helpers"
+
+cash = resolve_symbol("RELIANCE", "NSE_EQ")
+contract = resolve_derivative("NIFTY", strike: 24000, option_type: "CE", expiry: "2025-03-27")
+lot_size = get_lot_size(underlying: "NIFTY")
+```
+
+---
+
+## Quick-Reference Fallback IDs
+
+### Index Underlyings
+
+| Underlying | security_id | Underlying Segment |
+|------------|-------------|-------------------|
+| NIFTY 50 | `13` | `IDX_I` |
+| BANK NIFTY | `25` | `IDX_I` |
+| FINNIFTY | `27` | `IDX_I` |
+| MIDCPNIFTY | `442` | `IDX_I` |
+| SENSEX | `51` | `IDX_I` |
+
+### Common NSE Equities
+
+| Symbol | security_id |
+|--------|-------------|
+| RELIANCE | `2885` |
+| HDFCBANK | `1333` |
+| TCS | `11536` |
+| INFY | `1594` |
+| ICICIBANK | `4963` |
+| SBIN | `3045` |

data/skills/dhanhq-ruby/references/live-feed.md

@@ -0,0 +1,83 @@
+# Live Feed — Complete Reference (Ruby SDK)
+
+The Ruby SDK provides three distinct WebSocket interfaces under the `DhanHQ::WS` namespace to handle live data streaming.
+
+## 1. Market Feed (`DhanHQ::WS.connect`)
+
+Real-time market ticks, last traded prices, quotes, and market depth updates.
+
+### Usage
+
+```ruby
+# Connect to market feed. Modes: :ticker, :quote, :full
+market_client = DhanHQ::WS.connect(mode: :ticker) do |tick|
+  timestamp = tick[:ts] ? Time.at(tick[:ts]) : Time.now
+  puts "Tick: #{tick[:segment]}:#{tick[:security_id]} LTP=#{tick[:ltp]} at #{timestamp}"
+end
+
+# Subscribe to segments and security IDs
+market_client.subscribe_one(segment: "NSE_EQ", security_id: "2885")
+market_client.subscribe_one(segment: "NSE_EQ", security_id: "1333")
+
+# Stop connection
+sleep(15)
+market_client.stop
+```
+
+### Modes
+- `:ticker` - LTP (Last Traded Price) only.
+- `:quote` - OHLC + Volume updates.
+- `:full` - Full quote depth (5 levels) and Open Interest (OI) updates.
+
+---
+
+## 2. Order Updates (`DhanHQ::WS::Orders.connect`)
+
+Streams real-time updates for placed, modified, executed, or rejected orders.
+
+### Usage
+
+```ruby
+orders_client = DhanHQ::WS::Orders.connect do |update|
+  puts "Order Update: #{update.order_no} status=#{update.status}"
+  puts "  Symbol: #{update.symbol}, Traded: #{update.traded_qty}/#{update.quantity}"
+end
+
+# Register event callbacks
+orders_client.on(:update) { |order| puts "📝 Order Modified: #{order.order_no}" }
+orders_client.on(:execution) { |exec| puts "✅ Executed: #{exec[:new_traded_qty]} shares" }
+orders_client.on(:order_rejected) { |order| puts "❌ Rejected: #{order.order_no}" }
+
+sleep(15)
+orders_client.stop
+```
+
+---
+
+## 3. Market Depth (`DhanHQ::WS::MarketDepth.connect`)
+
+Streams order book depth (bid/ask levels). Supports 20-level depth.
+
+### Usage
+
+```ruby
+symbols = [
+  { symbol: "RELIANCE", exchange_segment: "NSE_EQ", security_id: "2885" },
+  { symbol: "TCS", exchange_segment: "NSE_EQ", security_id: "11536" }
+]
+
+depth_client = DhanHQ::WS::MarketDepth.connect(symbols: symbols) do |depth|
+  puts "Symbol: #{depth[:symbol]} Spread: #{depth[:spread]}"
+  puts "  Best Bid: #{depth[:best_bid]} | Best Ask: #{depth[:best_ask]}"
+end
+
+sleep(15)
+depth_client.stop
+```
+
+---
+
+## Connection Limits & Cleanup
+
+- Dhan allows up to **5 concurrent WebSocket connections** per client account.
+- Always call `client.stop` or `DhanHQ::WS.disconnect_all_local!` to prevent socket leaks and rate-limit issues (`429 Too Many Requests`).

data/skills/dhanhq-ruby/references/market-data.md

@@ -0,0 +1,119 @@
+# Market Data — Complete Reference (Ruby SDK)
+
+Timestamps returned by the `HistoricalData` model are automatically normalized into Ruby `Time` objects.
+
+## Historical Daily Data
+
+Use `DhanHQ::Models::HistoricalData.daily(params)`:
+
+```ruby
+candles = DhanHQ::Models::HistoricalData.daily(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  instrument: "EQUITY",
+  from_date: "2024-01-01",
+  to_date: "2024-12-31",
+  expiry_code: 0, # Optional: 0 for current, 1 for next, 2 for far
+  oi: false       # Optional: true to include open interest
+)
+
+first_candle = candles.first
+puts "Date: #{first_candle[:timestamp]}, Close: ₹#{first_candle[:close]}"
+```
+
+Each candle in the returned array is a Hash containing:
+- `:timestamp` (Ruby `Time` object)
+- `:open` (Float)
+- `:high` (Float)
+- `:low` (Float)
+- `:close` (Float)
+- `:volume` (Integer)
+- `:open_interest` (Float, only if `oi: true` was requested)
+
+## Intraday Minute Data
+
+Use `DhanHQ::Models::HistoricalData.intraday(params)`:
+
+```ruby
+candles = DhanHQ::Models::HistoricalData.intraday(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  instrument: "EQUITY",
+  interval: "15", # Supported: "1", "5", "15", "25", "60"
+  from_date: "2024-09-11 09:30:00",
+  to_date: "2024-09-15 13:00:00",
+  oi: false
+)
+```
+
+- Max 90 days of data can be polled in a single request.
+- Returns a normalized array of candle hashes.
+
+---
+
+## Market Quote Snapshots
+
+REST quote snapshots are accessed via the `DhanHQ::Models::MarketFeed` model.
+
+### Ticker Data (LTP only)
+
+```ruby
+response = DhanHQ::Models::MarketFeed.ltp(
+  "NSE_EQ" => [2885, 1333],
+  "NSE_FNO" => [49081]
+)
+
+ltp = response[:data]["NSE_EQ"]["2885"][:last_price]
+```
+
+### OHLC Data
+
+```ruby
+response = DhanHQ::Models::MarketFeed.ohlc(
+  "NSE_EQ" => [2885]
+)
+
+ohlc = response[:data]["NSE_EQ"]["2885"][:ohlc]
+```
+
+### Quote Data (Full Quote Depth & Analytics)
+
+```ruby
+response = DhanHQ::Models::MarketFeed.quote(
+  "NSE_FNO" => [49081]
+)
+
+quote = response[:data]["NSE_FNO"]["49081"]
+puts "LTP: #{quote[:last_price]}, OI: #{quote[:oi]}, Vol: #{quote[:volume]}"
+```
+
+---
+
+## Expired Options Data
+
+Use `DhanHQ::Models::ExpiredOptionsData.fetch(params)` (or direct resource access):
+
+```ruby
+response = DhanHQ::Models::ExpiredOptionsData.fetch(
+  underlying_scrip: 13,
+  exchange_segment: "NSE_FNO",
+  expiry_flag: "MONTH",
+  expiry_code: 1,
+  strike: "ATM",
+  option_type: "CALL",
+  required_data: ["open", "high", "low", "close", "volume", "oi", "spot"],
+  from_date: "2021-08-01",
+  to_date: "2021-08-31",
+  interval: "1"
+)
+```
+
+---
+
+## Timestamp Conversion
+
+If using raw API responses where timestamps are UNIX epochs, convert them to Ruby Time:
+
+```ruby
+time = Time.at(epoch_timestamp)
+```

data/skills/dhanhq-ruby/references/option-chain.md

@@ -0,0 +1,71 @@
+# Option Chain — Complete Reference (Ruby SDK)
+
+For analysis code, use the helper layer `fetch_chain_df` from `scripts/dhan_helpers.rb`.
+
+## Expiry List
+
+Use `DhanHQ::Models::OptionChain.fetch_expiry_list(params)`:
+
+```ruby
+expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
+  underlying_scrip: 13,
+  underlying_seg: "IDX_I"
+)
+```
+
+## Option Chain
+
+Use `DhanHQ::Models::OptionChain.fetch(params)`:
+
+```ruby
+chain = DhanHQ::Models::OptionChain.fetch(
+  underlying_scrip: 13,
+  underlying_seg: "IDX_I",
+  expiry: "2025-03-27"
+)
+
+# Underlying LTP
+spot = chain[:last_price]
+
+# Strikes sorted array
+chain[:strikes].each do |strike_data|
+  puts "Strike: #{strike_data[:strike]}"
+  puts "Call LTP: #{strike_data[:call][:last_price]}"
+  puts "Put Delta: #{strike_data[:put][:greeks][:delta]}"
+end
+```
+
+### Rate Limits
+- Calls are limited to **1 request every 3 seconds**. The SDK's internal rate limiter handles this.
+
+---
+
+## Normalized Helper Layer
+
+```ruby
+require_relative "../scripts/dhan_helpers"
+
+chain_rows, spot = fetch_chain_df(
+  under_security_id: 13,
+  expiry: "2025-03-27",
+  under_exchange_segment: "IDX_I"
+)
+
+atm = find_atm_row(chain_rows, spot)
+puts "Spot: #{spot}, ATM Strike: #{atm['strike']}, Call LTP: #{atm['ce_ltp']}"
+```
+
+Normalized columns returned by `fetch_chain_df`:
+- `strike`
+- `ce_security_id`, `pe_security_id`
+- `ce_ltp`, `pe_ltp`
+- `ce_oi`, `pe_oi`
+- `ce_oi_change`, `pe_oi_change`
+- `ce_volume`, `pe_volume`
+- `ce_iv`, `pe_iv`
+- `ce_bid_price`, `pe_bid_price`
+- `ce_ask_price`, `pe_ask_price`
+- `ce_delta`, `pe_delta`
+- `ce_gamma`, `pe_gamma`
+- `ce_theta`, `pe_theta`
+- `ce_vega`, `pe_vega`

data/skills/dhanhq-ruby/references/options-analysis-patterns.md

@@ -0,0 +1,76 @@
+# Options Analysis Patterns (Ruby SDK)
+
+Use the normalized helper output from `scripts/dhan_helpers.rb` for option chain analysis:
+
+```ruby
+require_relative "../scripts/dhan_helpers"
+
+chain_rows, spot = fetch_chain_df(
+  under_security_id: 13,
+  expiry: "2025-03-27",
+  under_exchange_segment: "IDX_I"
+)
+
+atm = find_atm_row(chain_rows, spot)
+```
+
+## Put-Call Ratio (PCR)
+
+```ruby
+total_ce_oi = chain_rows.sum { |r| r["ce_oi"].to_f }
+total_pe_oi = chain_rows.sum { |r| r["pe_oi"].to_f }
+pcr = total_ce_oi > 0 ? (total_pe_oi / total_ce_oi) : 0.0
+puts "PCR: #{'%.2f' % pcr}"
+```
+
+## OI Support / Resistance
+
+Find strikes with the highest open interest for resistance (CE) and support (PE):
+
+```ruby
+# Top 3 resistance walls (highest Call OI)
+ce_walls = chain_rows.sort_by { |r| -(r["ce_oi"] || 0) }.first(3)
+
+# Top 3 support walls (highest Put OI)
+pe_walls = chain_rows.sort_by { |r| -(r["pe_oi"] || 0) }.first(3)
+```
+
+## IV Skew
+
+```ruby
+otm_puts = chain_rows.select { |r| r["strike"] < spot }.sort_by { |r| -r["strike"] }.first(3)
+otm_calls = chain_rows.select { |r| r["strike"] > spot }.sort_by { |r| r["strike"] }.first(3)
+
+put_iv_avg = otm_puts.sum { |r| r["pe_iv"].to_f } / otm_puts.size.to_f
+call_iv_avg = otm_calls.sum { |r| r["ce_iv"].to_f } / otm_calls.size.to_f
+skew = put_iv_avg - call_iv_avg
+```
+
+## Max Pain
+
+Calculate the option strike price where option buyers would experience the maximum loss:
+
+```ruby
+def calculate_max_pain(chain_rows)
+  strikes = chain_rows.map { |r| r["strike"] }
+  pain = {}
+
+  strikes.each do |test_price|
+    total = 0.0
+    chain_rows.each do |row|
+      strike = row["strike"]
+      ce_oi = row["ce_oi"].to_f
+      pe_oi = row["pe_oi"].to_f
+      
+      total += [test_price - strike, 0.0].max * ce_oi
+      total += [strike - test_price, 0.0].max * pe_oi
+    end
+    pain[test_price] = total
+  end
+
+  pain.min_by { |_strike, total_pain| total_pain }&.first
+end
+
+max_pain_strike = calculate_max_pain(chain_rows)
+puts "Max Pain Strike: #{max_pain_strike}"
+```