DhanHQ 2.8.0 → 3.0.1

data/lib/DhanHQ/risk/pipeline.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    # Pre-execution risk pipeline that validates orders before they reach the broker.
+    #
+    # Runs a sequence of checks against the instrument and order arguments.
+    # Raises DhanHQ::RiskViolation on the first failure.
+    #
+    # @example Run equity risk checks
+    #   DhanHQ::Risk::Pipeline.run!(
+    #     instrument: instrument,
+    #     args: args,
+    #     now: Time.now,
+    #     type: :equity
+    #   )
+    #
+    # @example Run options risk checks
+    #   DhanHQ::Risk::Pipeline.run!(
+    #     instrument: instrument,
+    #     args: args,
+    #     now: Time.now,
+    #     type: :options
+    #   )
+    #
+    class Pipeline
+      CHECKS = [
+        Checks::TradingPermission,
+        Checks::AsmGsm,
+        Checks::ProductSupport,
+        Checks::OrderType,
+        Checks::Quantity,
+        Checks::MarketHours
+      ].freeze
+
+      OPTION_CHECKS = [
+        Checks::Options
+      ].freeze
+
+      # Run all applicable risk checks.
+      #
+      # @param instrument [Object] instrument with trading metadata
+      # @param args [Hash] order arguments (string keys)
+      # @param now [Time] current time for market hours check (default: Time.now)
+      # @param type [Symbol] :equity or :options
+      # @return [true] if all checks pass
+      # @raise [DhanHQ::RiskViolation] on first failure
+      # rubocop:disable Naming/PredicateMethod
+      def self.run!(instrument:, args:, now: Time.now, type: :equity)
+        run_checks!(CHECKS, instrument, args, now)
+        run_checks!(OPTION_CHECKS, instrument, args, now) if type == :options
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      def self.run_checks!(checks, instrument, args, now)
+        checks.each do |check|
+          check.run!(instrument: instrument, args: args, now: now)
+        end
+      end
+
+      private_class_method :run_checks!
+    end
+  end
+end

data/lib/DhanHQ/risk.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Risk management utilities for position sizing and order risk calculation.
+  module Risk
+    # Calculate optimal position size based on risk parameters.
+    #
+    # Supports multiple sizing methods:
+    # - Fixed risk percentage of account
+    # - Kelly criterion
+    # - Volatility-based sizing
+    #
+    # @example Calculate position size with 2% risk
+    #   size = DhanHQ::Risk::PositionSizer.calculate(
+    #     account_balance: 100_000,
+    #     risk_percent: 2.0,
+    #     entry_price: 2500,
+    #     stop_loss_price: 2450
+    #   )
+    #   #=> 40
+    #
+    class PositionSizer
+      # Calculate position size based on fixed risk percentage.
+      #
+      # @param account_balance [Float] Total account balance
+      # @param risk_percent [Float] Percentage of account to risk per trade (e.g., 2.0 for 2%)
+      # @param entry_price [Float] Planned entry price
+      # @param stop_loss_price [Float] Planned stop loss price
+      # @param lot_size [Integer] Lot size for the instrument (default: 1)
+      # @return [Integer] Number of shares/lots to trade
+      def self.calculate(account_balance:, risk_percent:, entry_price:, stop_loss_price:, lot_size: 1)
+        return 0 if account_balance <= 0 || entry_price <= 0 || stop_loss_price <= 0
+        return 0 if entry_price == stop_loss_price
+
+        risk_amount = account_balance * (risk_percent / 100.0)
+        risk_per_share = (entry_price - stop_loss_price).abs
+
+        return 0 if risk_per_share.zero?
+
+        raw_shares = (risk_amount / risk_per_share).floor
+        (raw_shares / lot_size).floor * lot_size
+      end
+
+      # Calculate position size using Kelly Criterion.
+      #
+      # @param win_rate [Float] Historical win rate (0.0 to 1.0)
+      # @param avg_win [Float] Average winning trade amount
+      # @param avg_loss [Float] Average losing trade amount (positive number)
+      # @param account_balance [Float] Total account balance
+      # @param entry_price [Float] Planned entry price
+      # @param fraction [Float] Kelly fraction to use (default: 0.5 for half-Kelly)
+      # @return [Integer] Number of shares to trade
+      def self.kelly(win_rate:, avg_win:, avg_loss:, account_balance:, entry_price:, fraction: 0.5)
+        return 0 if account_balance <= 0 || entry_price <= 0
+        return 0 if avg_loss.zero? || win_rate <= 0 || win_rate >= 1
+
+        # Kelly formula: f = (bp - q) / b
+        # where b = avg_win/avg_loss, p = win_rate, q = 1 - win_rate
+        b = avg_win / avg_loss
+        kelly_fraction = ((b * win_rate) - (1 - win_rate)) / b
+
+        return 0 if kelly_fraction <= 0
+
+        # Apply fractional Kelly
+        adjusted_fraction = kelly_fraction * fraction
+        risk_amount = account_balance * adjusted_fraction
+        shares = (risk_amount / entry_price).floor
+
+        [shares, 0].max
+      end
+
+      # Calculate position size based on volatility (ATR-based).
+      #
+      # @param account_balance [Float] Total account balance
+      # @param risk_percent [Float] Percentage of account to risk per trade
+      # @param entry_price [Float] Planned entry price
+      # @param atr [Float] Current ATR value
+      # @param atr_multiplier [Float] Multiplier for ATR-based stop (default: 2.0)
+      # @param lot_size [Integer] Lot size for the instrument (default: 1)
+      # @return [Integer] Number of shares/lots to trade
+      def self.volatility_based(account_balance:, risk_percent:, entry_price:, atr:, atr_multiplier: 2.0, lot_size: 1)
+        return 0 if account_balance <= 0 || entry_price <= 0 || atr <= 0
+
+        stop_distance = atr * atr_multiplier
+        stop_loss_price = entry_price - stop_distance
+
+        calculate(
+          account_balance: account_balance,
+          risk_percent: risk_percent,
+          entry_price: entry_price,
+          stop_loss_price: stop_loss_price,
+          lot_size: lot_size
+        )
+      end
+    end
+
+    # Calculate stop loss and take profit levels.
+    #
+    # @example Calculate stop loss
+    #   levels = DhanHQ::Risk::SLCalculator.stop_loss(
+    #     entry_price: 2500,
+    #     risk_percent: 2.0,
+    #     atr: 50
+    #   )
+    #   #=> { fixed: 2450, atr_based: 2400 }
+    #
+    class SLCalculator
+      # Calculate fixed percentage stop loss.
+      #
+      # @param entry_price [Float] Entry price
+      # @param risk_percent [Float] Risk percentage (e.g., 2.0 for 2%)
+      # @return [Float] Stop loss price
+      def self.percentage(entry_price:, risk_percent:)
+        return 0.0 if entry_price <= 0 || risk_percent <= 0
+
+        entry_price * (1 - (risk_percent / 100.0))
+      end
+
+      # Calculate ATR-based stop loss.
+      #
+      # @param entry_price [Float] Entry price
+      # @param atr [Float] Current ATR value
+      # @param multiplier [Float] ATR multiplier (default: 2.0)
+      # @return [Float] Stop loss price
+      def self.atr_based(entry_price:, atr:, multiplier: 2.0)
+        return 0.0 if entry_price <= 0 || atr <= 0
+
+        entry_price - (atr * multiplier)
+      end
+
+      # Calculate support-based stop loss.
+      #
+      # @param entry_price [Float] Entry price
+      # @param support_levels [Array<Float>] Array of support levels
+      # @param buffer [Float] Buffer below support (default: 0.5%)
+      # @return [Float] Stop loss price (below nearest support)
+      def self.support_based(entry_price:, support_levels:, buffer: 0.005)
+        return 0.0 if entry_price <= 0 || support_levels.nil? || support_levels.empty?
+
+        # Find nearest support below entry price
+        valid_supports = support_levels.select { |s| s < entry_price }
+        return 0.0 if valid_supports.empty?
+
+        nearest_support = valid_supports.max
+        nearest_support * (1 - buffer)
+      end
+
+      # Calculate take profit based on risk-reward ratio.
+      #
+      # @param entry_price [Float] Entry price
+      # @param stop_loss_price [Float] Stop loss price
+      # @param risk_reward_ratio [Float] Desired risk:reward ratio (e.g., 2.0 for 1:2)
+      # @return [Float] Take profit price
+      def self.take_profit(entry_price:, stop_loss_price:, risk_reward_ratio: 2.0)
+        return 0.0 if entry_price <= 0 || stop_loss_price <= 0
+
+        risk = (entry_price - stop_loss_price).abs
+        entry_price + (risk * risk_reward_ratio)
+      end
+
+      # Calculate trailing stop level.
+      #
+      # @param highest_price [Float] Highest price since entry
+      # @param atr [Float] Current ATR value
+      # @param multiplier [Float] ATR multiplier (default: 2.0)
+      # @return [Float] Trailing stop price
+      def self.trailing_stop(highest_price:, atr:, multiplier: 2.0)
+        return 0.0 if highest_price <= 0 || atr <= 0
+
+        highest_price - (atr * multiplier)
+      end
+    end
+
+    # Manage trailing stop updates.
+    #
+    # @example Create trail manager
+    #   trail = DhanHQ::Risk::TrailManager.new(
+    #     entry_price: 2500,
+    #     initial_stop: 2450,
+    #     atr: 50,
+    #     trail_multiplier: 2.0
+    #   )
+    #   trail.update(2600) #=> { stop: 2500, triggered: false }
+    #
+    class TrailManager
+      attr_reader :entry_price, :initial_stop, :current_stop, :highest_price, :atr, :trail_multiplier
+
+      def initialize(entry_price:, initial_stop:, atr:, trail_multiplier: 2.0)
+        @entry_price = entry_price
+        @initial_stop = initial_stop
+        @current_stop = initial_stop
+        @highest_price = entry_price
+        @atr = atr
+        @trail_multiplier = trail_multiplier
+      end
+
+      # Update trail with new price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Hash] Hash with :stop, :highest, :triggered
+      def update(current_price)
+        return { stop: @current_stop, highest: @highest_price, triggered: false } if current_price <= 0
+
+        # Update highest price
+        @highest_price = current_price if current_price > @highest_price
+
+        # Calculate new trailing stop
+        new_stop = @highest_price - (@atr * @trail_multiplier)
+
+        # Stop can only move up, never down
+        @current_stop = new_stop if new_stop > @current_stop
+
+        # Check if stop is triggered
+        triggered = current_price <= @current_stop
+
+        {
+          stop: @current_stop,
+          highest: @highest_price,
+          triggered: triggered
+        }
+      end
+
+      # Check if stop is triggered at current price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Boolean]
+      def triggered?(current_price)
+        current_price <= @current_stop
+      end
+
+      # Calculate profit from entry to current price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Float] Profit per share
+      def profit(current_price)
+        current_price - entry_price
+      end
+
+      # Calculate profit percentage from entry to current price.
+      #
+      # @param current_price [Float] Current market price
+      # @return [Float] Profit percentage
+      def profit_percent(current_price)
+        return 0.0 if entry_price.zero?
+
+        (profit(current_price) / entry_price * 100).round(2)
+      end
+    end
+  end
+end

data/lib/DhanHQ/skills/base.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    # Base class for all trading skills.
+    #
+    # Provides a DSL for defining parameters, steps, and execution logic.
+    # Skills are stateless — context is passed through and returned.
+    #
+    # @example
+    #   class BuyAtmCall < DhanHQ::Skills::Base
+    #     param :symbol, type: :string, required: true
+    #     param :expiry, type: :string, required: true
+    #     param :quantity, type: :integer, default: 50
+    #
+    #     step :find_instrument
+    #     step :get_spot_price
+    #     step :prepare_intent
+    #
+    #     def find_instrument(ctx)
+    #       ctx[:instrument] = DhanHQ::Models::Instrument.find("IDX_I", ctx[:symbol])
+    #       ctx
+    #     end
+    #
+    #     def get_spot_price(ctx)
+    #       ctx[:spot_price] = ctx[:instrument].ltp[:ltp]
+    #       ctx
+    #     end
+    #
+    #     def prepare_intent(ctx)
+    #       ctx[:intent] = { symbol: ctx[:symbol], spot: ctx[:spot_price] }
+    #       ctx
+    #     end
+    #   end
+    #
+    class Base
+      class << self
+        # Define a parameter for this skill.
+        #
+        # @param name [Symbol] parameter name
+        # @param type [Symbol] :string, :integer, :number, :boolean
+        # @param required [Boolean] whether the parameter is required
+        # @param default [Object] default value if not provided
+        def param(name, type: :string, required: false, default: nil, description: nil)
+          @params ||= {}
+          @params[name] = { type: type, required: required, default: default, description: description }
+        end
+
+        # Define a step in the skill execution sequence.
+        #
+        # @param name [Symbol] method name to call
+        # @param priority [Integer] execution order (lower = earlier)
+        def step(name, priority: 10)
+          @steps ||= []
+          @steps << { name: name, priority: priority }
+          @steps.sort_by! { |s| s[:priority] }
+        end
+
+        # Accessor for defined parameters.
+        def params
+          @params || {}
+        end
+
+        # Accessor for defined steps.
+        def steps
+          @steps || []
+        end
+
+        # Validate that all required parameters are present.
+        #
+        # @param args [Hash] provided parameters
+        # @raise [ArgumentError] if required parameters are missing
+        def validate_params!(args)
+          params.each do |name, config|
+            next unless config[:required]
+
+            value = args[name] || args[name.to_s]
+            next unless value.nil?
+
+            raise ArgumentError, "Missing required parameter: #{name}"
+          end
+        end
+      end
+
+      # Execute the skill with the given arguments.
+      #
+      # @param args [Hash] skill parameters (symbol or string keys)
+      # @return [Hash] context with all accumulated state
+      # @raise [ArgumentError] if required parameters are missing
+      def call(args = {})
+        ctx = build_context(args)
+        self.class.validate_params!(ctx)
+
+        self.class.steps.each do |step|
+          result = send(step[:name], ctx)
+          ctx = result if result.is_a?(Hash)
+        end
+
+        ctx
+      end
+
+      # Skill name (defaults to class name).
+      def name
+        self.class.name || self.class.to_s
+      end
+
+      # Skill description (override in subclasses).
+      def description
+        self.class.to_s
+      end
+
+      # List of parameter definitions for this skill.
+      def param_definitions
+        self.class.params
+      end
+
+      private
+
+      def build_context(args)
+        ctx = {}
+
+        self.class.params.each do |name, config|
+          value = args[name] || args[name.to_s]
+          value = config[:default] if value.nil? && config[:default]
+          ctx[name] = value
+        end
+
+        ctx
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# 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
+        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)
+          ltp = ctx[:instrument].ltp
+          ctx[:spot_price] = ltp[:ltp] || ltp["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]
+
+          ce_options = chain.select do |opt|
+            opt[:option_type] == "CE" || opt["optionType"] == "CE"
+          end
+
+          atm = ce_options.min_by do |opt|
+            strike = opt[:strike] || opt["strike"]
+            (strike.to_f - spot).abs
+          end
+
+          ctx[:selected_option] = atm
+          ctx[:security_id] = atm[:security_id] || atm["securityId"]
+          ctx[:strike] = atm[:strike] || atm["strike"]
+          ctx[:premium] = atm[:last_price] || atm["lastPrice"] || atm[:ltp] || atm["ltp"]
+          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/iron_condor.rb

@@ -0,0 +1,93 @@
+# 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
+        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)
+          ltp = ctx[:instrument].ltp
+          ctx[:spot_price] = ltp[:ltp] || ltp["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]
+
+          ce_options = chain.select { |o| (o[:option_type] || o["optionType"]) == "CE" }
+                            .sort_by { |o| (o[:strike] || o["strike"]).to_f }
+          pe_options = chain.select { |o| (o[:option_type] || o["optionType"]) == "PE" }
+                            .sort_by { |o| (o[:strike] || o["strike"]).to_f }
+
+          atm = ce_options.min_by { |o| (o[:strike] || o["strike"]).to_f - spot.to_f }
+
+          atm_strike = (atm[:strike] || atm["strike"]).to_f
+
+          short_ce = ce_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike + wing)).abs < 0.001 }
+          long_ce = ce_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike + (wing * 2))).abs < 0.001 }
+          short_pe = pe_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike - wing)).abs < 0.001 }
+          long_pe = pe_options.find { |o| ((o[:strike] || o["strike"]).to_f - (atm_strike - (wing * 2))).abs < 0.001 }
+
+          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: atm_strike + wing, security_id: short_ce[:security_id] || short_ce["securityId"] },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "CE", strike: atm_strike + (wing * 2), security_id: long_ce[:security_id] || long_ce["securityId"] },
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "PE", strike: atm_strike - wing, security_id: short_pe[:security_id] || short_pe["securityId"] },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "PE", strike: atm_strike - (wing * 2), security_id: long_pe[:security_id] || long_pe["securityId"] }
+          ]
+          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/square_off_all.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to exit all open positions at market price.
+      #
+      # Steps: fetch positions → exit each position → summarize results.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("square_off_all")
+      #   puts result[:exited_count]
+      #
+      class SquareOffAll < Base
+        step :fetch_positions, priority: 1
+        step :exit_positions, priority: 2
+
+        def fetch_positions(ctx)
+          ctx[:positions] = DhanHQ::Models::Position.all.reject do |p|
+            qty = begin
+              p[:net_quantity] || p["netQuantity"] || p.net_quantity
+            rescue StandardError
+              0
+            end
+            qty.to_i.zero?
+          end
+          ctx
+        end
+
+        def exit_positions(ctx)
+          results = ctx[:positions].map do
+            DhanHQ::Models::Position.exit_all!
+          rescue StandardError => e
+            { error: e.message }
+          end
+
+          ctx[:exit_results] = results
+          ctx[:exited_count] = results.count { |r| !(r.is_a?(Hash) && r.key?(:error)) }
+          ctx[:failed_count] = results.count { |r| r.is_a?(Hash) && r.key?(:error) }
+          ctx
+        end
+      end
+    end
+  end
+end