DhanHQ 3.2.0 → 3.3.0

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

@@ -0,0 +1,91 @@
+# 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 by symbol name (exact match)
+inst = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+
+# Find by security ID instead of symbol name — use this, not `.find`, when you
+# already have a security_id (e.g. from an order, position, or option chain leg)
+inst = DhanHQ::Models::Instrument.find_by_security_id("NSE_EQ", "2885")
+
+# 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")
+```
+
+`.find`'s second argument is always a **symbol name**, never a security ID — passing a security ID there silently returns `nil` (it searches symbol/underlying-symbol text, doesn't match on ID). Use `.find_by_security_id` when resolving by ID.
+
+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}"
+```

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

@@ -0,0 +1,203 @@
+# Orders — Complete Reference (Ruby SDK)
+
+Critical API rules:
+- Order placement, modification, cancellation, super orders, and forever orders require static IP whitelisting.
+- Dhan's current order docs say API market orders are converted to limit orders with MPP.
+- **`ENV["LIVE_TRADING"]="true"` is required for `place`/`create`/`modify`/`cancel` to actually submit anything** — the gem raises `DhanHQ::LiveTradingDisabledError` otherwise, as a safety gate against accidental order placement from a dev machine.
+- **`correlation_id` must be 25 characters or fewer.** Dhan's real API rejects the entire order with a generic `DH-905` error if exceeded — it doesn't say which field was wrong.
+
+## Regular Orders
+
+### Place Order
+
+In the Ruby SDK, prefer using the model class `DhanHQ::Models::Order.place(params)`:
+
+```ruby
+order = DhanHQ::Models::Order.place(
+  security_id: "2885",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  quantity: 10,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  price: 2450.0,
+  validity: DhanHQ::Constants::Validity::DAY,
+  correlation_id: "rebalance_001"
+)
+
+if order
+  puts "Placed Order ID: #{order.order_id}, Status: #{order.order_status}"
+end
+```
+
+Alternatively, you can use the ActiveRecord-style `new` and `save` flow:
+
+```ruby
+order = DhanHQ::Models::Order.new(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  quantity: 10,
+  order_type: "LIMIT",
+  product_type: "CNC",
+  price: 2450.0,
+  validity: "DAY"
+)
+order.save # Places the order via API
+```
+
+### Slice Order
+
+If placing a large quantity that exceeds exchange freeze limits, the SDK handles slicing automatically when using the slice API:
+
+```ruby
+order.slice_order(
+  slice_quantity: 1000
+)
+```
+
+### Modify Order
+
+Modify a pending order directly on the model instance:
+
+```ruby
+order = DhanHQ::Models::Order.find("112111182198")
+if order.pending?
+  order.modify(
+    price: 2455.0,
+    quantity: 10,
+    validity: "DAY"
+  )
+end
+```
+
+The modify request expects the full placed quantity, not the pending quantity.
+
+### Cancel Order
+
+Cancel a pending order directly on the model instance:
+
+```ruby
+order = DhanHQ::Models::Order.find("112111182198")
+order.cancel # Returns true on success
+```
+
+### Order Retrieval
+
+```ruby
+# Fetch all orders for today
+orders = DhanHQ::Models::Order.all
+
+# Find order by ID
+order = DhanHQ::Models::Order.find("112111182198")
+
+# Find order by correlation ID
+order = DhanHQ::Models::Order.find_by_correlation("rebalance_001")
+
+# Fetch today's trades
+trades = DhanHQ::Models::Trade.today
+
+# Find trades by order ID
+trade = DhanHQ::Models::Trade.find_by_order_id("112111182198")
+
+# Fetch trade history
+history = DhanHQ::Models::Trade.history(
+  from_date: "2025-01-01",
+  to_date: "2025-01-31",
+  page: 0
+)
+```
+
+---
+
+## Super Orders (Bracket/Cover Orders)
+
+### Place Super Order
+
+Use the `DhanHQ::Models::SuperOrder.create` method:
+
+```ruby
+super_order = DhanHQ::Models::SuperOrder.create(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  quantity: 1,
+  order_type: "LIMIT",
+  product_type: "INTRADAY",
+  price: 2450.0,
+  target_price: 2500.0,
+  stop_loss_price: 2420.0,
+  trailing_jump: 10.0
+)
+
+puts "Placed Super Order ID: #{super_order.order_id}"
+```
+
+### Modify Super Order
+
+```ruby
+super_order.modify(
+  leg_name: "ENTRY_LEG",
+  price: 2455.0,
+  quantity: 1,
+  target_price: 2510.0,
+  stop_loss_price: 2425.0,
+  trailing_jump: 10.0
+)
+```
+
+- `ENTRY_LEG` can modify the whole structure while the entry order is `PENDING` or `PART_TRADED`.
+- After entry is `TRADED`, only price and trailing jump of `TARGET_LEG` and `STOP_LOSS_LEG` can be modified.
+
+### Cancel Super Order
+
+```ruby
+super_order.cancel("ENTRY_LEG") # Cancels all legs
+```
+
+---
+
+## Forever Orders (GTT Orders)
+
+### Place Forever Order
+
+Use the `DhanHQ::Models::ForeverOrder.create` method:
+
+```ruby
+# Single Trigger
+gtt_order = DhanHQ::Models::ForeverOrder.create(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  product_type: "CNC",
+  order_type: "LIMIT",
+  quantity: 5,
+  price: 2300.0,
+  trigger_price: 2305.0,
+  order_flag: "SINGLE",
+  validity: "DAY"
+)
+
+# OCO (One Cancels Other) target + stop loss
+oco_order = DhanHQ::Models::ForeverOrder.create(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "SELL",
+  product_type: "CNC",
+  order_type: "LIMIT",
+  quantity: 5,
+  price: 2700.00,        # Target price (price of first leg)
+  trigger_price: 2695.00, # Target trigger price (trigger of first leg)
+  price1: 2200.00,       # Stop loss price (price of second leg)
+  trigger_price1: 2205.00, # Stop loss trigger price (trigger of second leg)
+  quantity1: 5,          # Stop loss quantity (quantity of second leg)
+  order_flag: "OCO",
+  validity: "DAY"
+)
+```
+
+### Cancel Forever Order
+
+```ruby
+gtt_order.cancel # Returns true on success
+```