DhanHQ 3.0.0 → 3.1.0

data/lib/DhanHQ/skills/builtin/bear_call_spread.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build a bear call spread (sell OTM call, buy further OTM call).
+      #
+      # Steps: find instrument → spot price → option chain →
+      # select strikes → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("bear_call_spread",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50
+      #   )
+      #
+      class BearCallSpread < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build a bear call spread: sell an OTM call, buy a further OTM call for defined risk."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :spread_width, type: :number, default: 200
+        param :max_loss, type: :number, default: 5000
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_strikes, priority: 4
+        step :build_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_strikes(ctx)
+          spot = ctx[:spot_price].to_f
+          chain = ctx[:chain]
+          spread = ctx[:spread_width].to_f
+
+          atm_strike_price = nearest_strike(chain, spot)[:strike].to_f
+
+          short_call = find_strike(chain, atm_strike_price + spread)
+          long_call = find_strike(chain, atm_strike_price + (spread * 2))
+
+          raise ArgumentError, "Could not build bear call spread — insufficient strikes in chain" unless short_call && long_call
+
+          ctx[:legs] = [
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "CE", strike: short_call[:strike],
+              security_id: leg_security_id(short_call, "CE") },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "CE", strike: long_call[:strike],
+              security_id: leg_security_id(long_call, "CE") }
+          ]
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "BEAR_CALL_SPREAD",
+            symbol: ctx[:symbol],
+            expiry: ctx[:expiry],
+            quantity: ctx[:quantity],
+            spread_width: ctx[:spread_width],
+            max_loss: ctx[:max_loss],
+            legs: ctx[:legs],
+            note: "Bear call spread prepared. Await human confirmation before execution."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/builtin/bull_put_spread.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build a bull put spread (sell OTM put, buy further OTM put).
+      #
+      # Steps: find instrument → spot price → option chain →
+      # select strikes → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("bull_put_spread",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50
+      #   )
+      #
+      class BullPutSpread < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build a bull put spread: sell an OTM put, buy a further OTM put for defined risk."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :spread_width, type: :number, default: 200
+        param :max_loss, type: :number, default: 5000
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_strikes, priority: 4
+        step :build_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_strikes(ctx)
+          spot = ctx[:spot_price].to_f
+          chain = ctx[:chain]
+          spread = ctx[:spread_width].to_f
+
+          atm_strike_price = nearest_strike(chain, spot)[:strike].to_f
+
+          short_put = find_strike(chain, atm_strike_price - spread)
+          long_put = find_strike(chain, atm_strike_price - (spread * 2))
+
+          raise ArgumentError, "Could not build bull put spread — insufficient strikes in chain" unless short_put && long_put
+
+          ctx[:legs] = [
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "PE", strike: short_put[:strike],
+              security_id: leg_security_id(short_put, "PE") },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "PE", strike: long_put[:strike],
+              security_id: leg_security_id(long_put, "PE") }
+          ]
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "BULL_PUT_SPREAD",
+            symbol: ctx[:symbol],
+            expiry: ctx[:expiry],
+            quantity: ctx[:quantity],
+            spread_width: ctx[:spread_width],
+            max_loss: ctx[:max_loss],
+            legs: ctx[:legs],
+            note: "Bull put spread prepared. Await human confirmation before execution."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/builtin/buy_atm_call.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to buy an ATM call option on an index.
+      #
+      # Steps: find instrument → get spot price → get option chain →
+      # select ATM strike → prepare trade intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("buy_atm_call",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50
+      #   )
+      #   puts result[:intent]
+      #
+      class BuyAtmCall < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Buy an at-the-money call option on an index (e.g. NIFTY)."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :stop_loss, type: :number, default: 100
+        param :target, type: :number, default: 200
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_atm_strike, priority: 4
+        step :prepare_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_atm_strike(ctx)
+          spot = ctx[:spot_price]
+          chain = ctx[:chain]
+
+          atm = nearest_strike(chain, spot)
+          raise ArgumentError, "Could not find ATM strike" unless atm
+
+          ctx[:selected_option] = atm
+          ctx[:security_id] = leg_security_id(atm, "CE")
+          ctx[:strike] = atm[:strike]
+          ctx[:premium] = leg_premium(atm, "CE")
+          ctx
+        end
+
+        def prepare_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "OPTIONS_BUY",
+            instrument: "#{ctx[:symbol]} #{ctx[:strike]} CE",
+            security_id: ctx[:security_id],
+            strike: ctx[:strike],
+            expiry: ctx[:expiry],
+            option_type: "CE",
+            quantity: ctx[:quantity],
+            premium: ctx[:premium],
+            stop_loss: ctx[:stop_loss],
+            target: ctx[:target],
+            note: "Prepared ATM call buy. Await human confirmation."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/builtin/covered_call.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build a covered call strategy (buy 100 shares, sell 1 OTM call).
+      #
+      # Steps: find equity instrument → spot price → option chain →
+      # select OTM call strike → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("covered_call",
+      #     symbol: "RELIANCE",
+      #     expiry: "2026-01-30",
+      #     quantity: 100
+      #   )
+      #
+      class CoveredCall < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build a covered call: buy the underlying equity, sell an OTM call against it."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 100
+        param :strike_offset, type: :number, default: 2.0
+        param :stop_loss, type: :number, default: nil
+        param :target, type: :number, default: nil
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_otm_call, priority: 4
+        step :build_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::NSE_EQ, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_otm_call(ctx)
+          spot = ctx[:spot_price].to_f
+          chain = ctx[:chain]
+          offset_pct = ctx[:strike_offset] / 100.0
+
+          target_strike = spot * (1 + offset_pct)
+          otm_call = nearest_strike(chain, target_strike)
+
+          raise ArgumentError, "Could not find suitable OTM call strike near #{target_strike}" unless otm_call
+
+          ctx[:call_strike] = otm_call[:strike]
+          ctx[:call_security_id] = leg_security_id(otm_call, "CE")
+          ctx[:call_premium] = leg_premium(otm_call, "CE")
+          ctx[:equity_security_id] = ctx[:instrument].security_id
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "COVERED_CALL",
+            symbol: ctx[:symbol],
+            quantity: ctx[:quantity],
+            legs: [
+              { action: DhanHQ::Constants::TransactionType::BUY, instrument_type: DhanHQ::Constants::InstrumentType::EQUITY, security_id: ctx[:equity_security_id],
+                quantity: ctx[:quantity] },
+              { action: DhanHQ::Constants::TransactionType::SELL, option_type: "CE", strike: ctx[:call_strike], security_id: ctx[:call_security_id], quantity: ctx[:quantity], premium: ctx[:call_premium] }
+            ],
+            note: "Covered call prepared: Buy #{ctx[:quantity]} #{ctx[:symbol]}, Sell #{ctx[:quantity]} #{ctx[:call_strike]} CE. Await human confirmation."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/builtin/iron_condor.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build an iron condor strategy (sell OTM CE + PE, buy further OTM CE + PE).
+      #
+      # Steps: find instrument → spot price → option chain → select strikes → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("iron_condor",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50,
+      #     wing_width: 200
+      #   )
+      #
+      class IronCondor < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build an iron condor: sell OTM call + sell OTM put, buy further OTM call + put for protection."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :wing_width, type: :number, default: 200
+        param :max_loss, type: :number, default: 5000
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_strikes, priority: 4
+        step :build_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_strikes(ctx)
+          spot = ctx[:spot_price]
+          chain = ctx[:chain]
+          wing = ctx[:wing_width].to_f
+
+          atm_strike = nearest_strike(chain, spot)[:strike].to_f
+
+          short_ce = find_strike(chain, atm_strike + wing)
+          long_ce = find_strike(chain, atm_strike + (wing * 2))
+          short_pe = find_strike(chain, atm_strike - wing)
+          long_pe = find_strike(chain, atm_strike - (wing * 2))
+
+          raise ArgumentError, "Could not build iron condor — insufficient strikes in chain" unless short_ce && long_ce && short_pe && long_pe
+
+          ctx[:legs] = [
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "CE", strike: short_ce[:strike], security_id: leg_security_id(short_ce, "CE") },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "CE", strike: long_ce[:strike], security_id: leg_security_id(long_ce, "CE") },
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "PE", strike: short_pe[:strike], security_id: leg_security_id(short_pe, "PE") },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "PE", strike: long_pe[:strike], security_id: leg_security_id(long_pe, "PE") }
+          ]
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "IRON_CONDOR",
+            symbol: ctx[:symbol],
+            expiry: ctx[:expiry],
+            quantity: ctx[:quantity],
+            wing_width: ctx[:wing_width],
+            max_loss: ctx[:max_loss],
+            legs: ctx[:legs],
+            note: "Iron condor prepared. Await human confirmation before execution."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/builtin/market_data_summarizer.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/RescueModifier
+# rubocop:disable Naming/VariableNumber
+# rubocop:disable Style/NumericPredicate
+# rubocop:disable Lint/AmbiguousOperatorPrecedence
+
+require "date"
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Programmatic Agent Skill to process and summarize market data.
+      # Exposes computed technical indicators and options statistics rather than raw data.
+      class MarketDataSummarizer < Base
+        risk "read_only"
+        scope "market:read"
+        description "Summarize technicals and/or option chain (PCR, OI walls, ATM strikes) for a symbol."
+
+        param :underlying_symbol, type: :string, required: true, description: "Underlying ticker symbol (e.g. NIFTY, RELIANCE)"
+        param :mode, type: :string, default: "both", description: "Analysis mode: both, technicals, or option_chain"
+        param :interval, type: :string, default: DhanHQ::Constants::Validity::DAY, description: "Timeframe for technical indicators"
+        param :range_days, type: :integer, default: 30, description: "Lookback period in days for indicator calculation"
+        param :expiry, type: :string, default: "nearest", description: "Specific option expiry date (YYYY-MM-DD) or 'nearest'"
+        param :strike_range, type: :integer, default: 5, description: "Number of strikes to include above and below ATM"
+
+        step :resolve_instrument, priority: 1
+        step :fetch_technicals, priority: 2
+        step :fetch_option_chain_summary, priority: 3
+        step :prepare_final_summary, priority: 4
+
+        def resolve_instrument(ctx)
+          symbol = ctx[:underlying_symbol].to_s.upcase.strip
+          inst = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, symbol) rescue nil
+          inst ||= DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::NSE_EQ, symbol) rescue nil
+          inst ||= DhanHQ::Models::Instrument.find_anywhere(symbol) rescue nil
+
+          raise "Underlying symbol not found: #{symbol}" unless inst
+
+          ctx[:instrument] = inst
+          ctx
+        end
+
+        def fetch_technicals(ctx)
+          return ctx unless %w[both technicals].include?(ctx[:mode])
+
+          inst = ctx[:instrument]
+          to_date = Date.today.strftime("%Y-%m-%d")
+          from_date = (Date.today - [ctx[:range_days].to_i * 2, 100].max).strftime("%Y-%m-%d")
+
+          candles = DhanHQ::Models::HistoricalData.daily(
+            security_id: inst.security_id,
+            exchange_segment: inst.exchange_segment,
+            instrument: inst.instrument,
+            from_date: from_date,
+            to_date: to_date
+          ) rescue []
+
+          if candles.any?
+            closes = candles.map { |c| c[:close].to_f }
+            latest_close = closes.last
+
+            sma_20 = closes.size >= 20 ? (closes.last(20).sum / 20.0).round(2) : nil
+            sma_50 = closes.size >= 50 ? (closes.last(50).sum / 50.0).round(2) : nil
+            ret_5d = closes.size >= 6 ? (((closes.last / closes[-6]) - 1.0) * 100).round(2) : nil
+
+            # RSI (14) Calculation
+            rsi_14 = calculate_rsi(closes)
+
+            ctx[:technical_summary] = {
+              ltp: latest_close,
+              sma_20: sma_20,
+              sma_50: sma_50,
+              return_5d_pct: ret_5d,
+              rsi_14: rsi_14,
+              data_points_analyzed: closes.size
+            }
+          else
+            # Fallback to LTP quote if daily candles fail
+            quote = inst.ltp rescue {}
+            ctx[:technical_summary] = {
+              ltp: quote[:ltp] || quote["ltp"] || 0.0,
+              note: "Failed to load historical candles; loaded quote snapshot instead."
+            }
+          end
+          ctx
+        end
+
+        def fetch_option_chain_summary(ctx)
+          return ctx unless %w[both option_chain].include?(ctx[:mode])
+
+          inst = ctx[:instrument]
+          underlying_seg = inst.exchange_segment == DhanHQ::Constants::ExchangeSegment::IDX_I ? DhanHQ::Constants::ExchangeSegment::IDX_I : DhanHQ::Constants::ExchangeSegment::NSE_EQ
+
+          target_expiry = ctx[:expiry]
+          if target_expiry.to_s.empty? || target_expiry == "nearest"
+            expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
+              underlying_scrip: inst.security_id.to_i,
+              underlying_seg: underlying_seg
+            )
+            target_expiry = expiries.first
+          end
+
+          return ctx if target_expiry.nil?
+
+          chain = DhanHQ::Models::OptionChain.fetch(
+            underlying_scrip: inst.security_id.to_i,
+            underlying_seg: underlying_seg,
+            expiry: target_expiry
+          )
+
+          if chain
+            spot = chain[:last_price] || ctx[:technical_summary]&.[](:ltp)
+            strikes = chain[:strikes] || []
+
+            # Locate ATM
+            closest_strike_data = strikes.min_by { |s| (s[:strike].to_f - spot).abs }
+            closest_idx = strikes.index(closest_strike_data)
+
+            # Filter ATM +/- strike_range
+            range = ctx[:strike_range].to_i
+            start_idx = [0, closest_idx - range].max
+            end_idx = [strikes.size - 1, closest_idx + range].min
+
+            filtered_strikes = strikes[start_idx..end_idx].map do |s|
+              {
+                strike: s[:strike],
+                ce: s[:call] ? { security_id: s[:call][:security_id], ltp: s[:call][:last_price], oi: s[:call][:oi] } : nil,
+                pe: s[:put] ? { security_id: s[:put][:security_id], ltp: s[:put][:last_price], oi: s[:put][:oi] } : nil
+              }
+            end
+
+            # PCR & OI Walls
+            total_ce_oi = strikes.sum { |s| s[:call]&.[](:oi).to_f }
+            total_pe_oi = strikes.sum { |s| s[:put]&.[](:oi).to_f }
+            pcr = total_ce_oi > 0 ? (total_pe_oi / total_ce_oi).round(3) : 0.0
+
+            ce_walls = strikes.reject { |s| s[:call].nil? }.sort_by { |s| -(s[:call][:oi] || 0) }.first(3).map { |s| { strike: s[:strike], oi: s[:call][:oi] } }
+            pe_walls = strikes.reject { |s| s[:put].nil? }.sort_by { |s| -(s[:put][:oi] || 0) }.first(3).map { |s| { strike: s[:strike], oi: s[:put][:oi] } }
+
+            ctx[:option_chain_summary] = {
+              expiry: target_expiry,
+              spot: spot,
+              pcr: pcr,
+              resistance_walls: ce_walls,
+              support_walls: pe_walls,
+              strikes: filtered_strikes
+            }
+          end
+          ctx
+        end
+
+        def prepare_final_summary(ctx)
+          ctx[:summary] = {
+            symbol: ctx[:underlying_symbol],
+            timestamp: Time.now.strftime("%Y-%m-%d %H:%M:%S"),
+            technicals: ctx[:technical_summary],
+            options: ctx[:option_chain_summary]
+          }
+          ctx
+        end
+
+        private
+
+        def calculate_rsi(closes)
+          return nil if closes.size < 15
+
+          gains = []
+          losses = []
+          closes.each_cons(2) do |prev, curr|
+            diff = curr - prev
+            gains << (diff > 0 ? diff : 0.0)
+            losses << (diff < 0 ? -diff : 0.0)
+          end
+
+          avg_gain = gains.first(14).sum / 14.0
+          avg_loss = losses.first(14).sum / 14.0
+
+          gains[14..].zip(losses[14..]).each do |g, l|
+            avg_gain = (avg_gain * 13 + g) / 14.0
+            avg_loss = (avg_loss * 13 + l) / 14.0
+          end
+
+          rs = avg_loss > 0 ? (avg_gain / avg_loss) : 100.0
+          (100.0 - (100.0 / (1.0 + rs))).round(2)
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Style/RescueModifier
+# rubocop:enable Naming/VariableNumber
+# rubocop:enable Style/NumericPredicate
+# rubocop:enable Lint/AmbiguousOperatorPrecedence