DhanHQ 3.2.0 → 3.2.1

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
+```

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

@@ -0,0 +1,93 @@
+# Portfolio And Positions — Complete Reference (Ruby SDK)
+
+## Holdings
+
+Use `DhanHQ::Models::Holding.all`:
+
+```ruby
+holdings = DhanHQ::Models::Holding.all
+
+holdings.each do |holding|
+  puts "#{holding.trading_symbol} available=#{holding.available_qty}"
+end
+```
+
+Useful holding fields:
+- `exchange`
+- `trading_symbol`
+- `security_id`
+- `isin`
+- `total_qty`
+- `dp_qty`
+- `t1_qty`
+- `available_qty`
+- `collateral_qty`
+- `avg_cost_price`
+
+---
+
+## Positions
+
+Use `DhanHQ::Models::Position.all`:
+
+```ruby
+positions = DhanHQ::Models::Position.all
+open_positions = positions.select { |p| p.net_qty.to_i != 0 }
+```
+
+Useful position fields:
+- `trading_symbol`
+- `security_id`
+- `position_type` # "LONG" or "SHORT"
+- `exchange_segment`
+- `product_type`
+- `buy_avg`
+- `buy_qty`
+- `sell_avg`
+- `sell_qty`
+- `net_qty`
+- `realized_profit`
+- `unrealized_profit`
+
+---
+
+## Convert Position
+
+Convert an open position (e.g. from Intraday to CNC/Carry Forward):
+
+```ruby
+# In the Ruby SDK, call convert directly on a Position model instance
+position = DhanHQ::Models::Position.all.first
+position.convert(
+  from_product_type: "INTRADAY",
+  to_product_type: "CNC",
+  position_type: "LONG",
+  convert_qty: 1
+)
+```
+
+---
+
+## eDIS Authorization
+
+For selling delivery holdings, authorization is handled via `DhanHQ::Models::EDIS`:
+
+### Step 1: Generate TPIN
+```ruby
+DhanHQ::Models::EDIS.generate_tpin
+```
+
+### Step 2: Open Browser Authorization
+```ruby
+DhanHQ::Models::EDIS.open_browser_for_tpin(
+  isin: "INE002A01018",
+  qty: 5,
+  exchange: "NSE"
+)
+```
+
+### Step 3: Inquiry eDIS Approval
+```ruby
+inquiry = DhanHQ::Models::EDIS.inquiry(isin: "INE002A01018")
+puts "Approved Qty: #{inquiry.aprvd_qty}, Status: #{inquiry.status}"
+```

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

@@ -0,0 +1,62 @@
+# ScanX — Fundamental and Technical Data
+
+Use ScanX when Dhan APIs do not cover the needed data. Dhan provides execution, quotes, OHLC, option chain, and portfolio. ScanX provides fundamentals, technical indicators, shareholding, and screeners.
+
+## Capability Gap
+
+| Data needed | Use |
+|------------|-----|
+| PE ratio, EPS, Book Value, PB Ratio | ScanX |
+| Revenue, Net Profit, EBITDA | ScanX |
+| Debt-to-equity, Return on Equity | ScanX |
+| RSI(14), MACD(12,26), ADX(14), ATR(14) | ScanX |
+| Promoter %, FII %, DII %, Public % | ScanX |
+| Quarterly results history (2015–present) | ScanX |
+| Balance Sheet, Cash Flows | ScanX |
+| Stock screeners (fundamental/technical) | ScanX |
+| Live quotes, OHLC, option chain | Dhan |
+| Order execution, portfolio | Dhan |
+
+---
+
+## Company Page URL Pattern
+
+`https://scanx.trade/company/{slug}`
+
+Slug rules:
+- Lowercase the full registered company name.
+- Replace spaces with hyphens.
+- Include "ltd" if part of the official name.
+
+---
+
+## Combined Workflow: Analyze on ScanX → Execute on Dhan
+
+```ruby
+# Step 1: fetch ScanX page for fundamentals/technicals
+# -> https://scanx.trade/company/reliance-industries-ltd
+# -> Extract metrics: PE, RSI, etc.
+
+# Step 2: resolve security_id from Dhan security master
+require_relative "../scripts/dhan_helpers"
+get_client
+
+row = resolve_symbol("RELIANCE", "NSE_EQ")
+security_id = row["security_id"]
+
+# Step 3: Get live quotes from Dhan
+quote_resp = DhanHQ::Models::MarketFeed.ltp("NSE_EQ" => [security_id.to_i])
+ltp = quote_resp[:data]["NSE_EQ"][security_id.to_s][:last_price].to_f
+
+# Step 4: Place order via Dhan
+order = DhanHQ::Models::Order.place(
+  security_id: security_id,
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  quantity: 1,
+  order_type: "LIMIT",
+  product_type: "CNC",
+  price: ltp,
+  validity: "DAY"
+)
+```