DhanHQ 3.0.0 → 3.0.1

data/lib/DhanHQ/resources/twap_orders.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/order_audit"
+
+module DhanHQ
+  module Resources
+    # Resource client for TWAP order management.
+    class TwapOrders < BaseAPI
+      include DhanHQ::Concerns::OrderAudit
+
+      API_TYPE = :order_api
+      HTTP_PATH = "/v2/orders/twap"
+
+      # Lists all TWAP orders for the account.
+      #
+      # @return [Array<Hash>]
+      def all
+        get("")
+      end
+
+      # Creates a new TWAP order.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def create(params)
+        ensure_live_trading!
+        log_order_context("DHAN_TWAP_ORDER_ATTEMPT", params)
+        post("", params: params)
+      end
+
+      # Fetches a specific TWAP order by ID.
+      #
+      # @param order_id [String]
+      # @return [Hash]
+      def find(order_id)
+        get("/#{order_id}")
+      end
+
+      # Updates an existing TWAP order.
+      #
+      # @param order_id [String]
+      # @param params [Hash]
+      # @return [Hash]
+      def update(order_id, params)
+        ensure_live_trading!
+        log_order_context("DHAN_TWAP_ORDER_MODIFY_ATTEMPT", params.merge(order_id: order_id))
+        put("/#{order_id}", params: params)
+      end
+
+      # Cancels a TWAP order.
+      #
+      # @param order_id [String]
+      # @return [Hash]
+      def cancel(order_id)
+        ensure_live_trading!
+        log_order_context("DHAN_TWAP_ORDER_CANCEL_ATTEMPT", { order_id: order_id })
+        delete("/#{order_id}")
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/asm_gsm.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Blocks trading on ASM/GSM restricted instruments.
+      class AsmGsm
+        def self.run!(instrument:, **_unused)
+          return unless instrument.asm_gsm_flag == "Y"
+
+          raise DhanHQ::RiskViolation,
+                "ASM/GSM restricted instrument (#{instrument.asm_gsm_category})"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/market_hours.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Blocks orders outside Indian market hours (9:15 AM - 3:30 PM IST).
+      class MarketHours
+        TIMEZONE_OFFSET = "+05:30"
+        OPEN_HOUR = 9
+        OPEN_MINUTE = 15
+        CLOSE_HOUR = 15
+        CLOSE_MINUTE = 30
+
+        def self.run!(now: Time.now, **_unused)
+          market_now = now.getlocal(TIMEZONE_OFFSET)
+          return if market_open?(market_now)
+
+          raise DhanHQ::RiskViolation, "Market is closed"
+        end
+
+        def self.market_open?(now)
+          now.between?(market_open(now), market_close(now))
+        end
+
+        def self.market_open(now)
+          Time.new(now.year, now.month, now.day, OPEN_HOUR, OPEN_MINUTE, 0, TIMEZONE_OFFSET)
+        end
+
+        def self.market_close(now)
+          Time.new(now.year, now.month, now.day, CLOSE_HOUR, CLOSE_MINUTE, 0, TIMEZONE_OFFSET)
+        end
+
+        private_class_method :market_open?, :market_open, :market_close
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/options.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces option-specific risk rules (index-only, stop loss, target, risk-reward).
+      class Options
+        def self.run!(args:, instrument:, **_unused)
+          enforce_index!(instrument)
+          enforce_stop_loss!(args)
+          enforce_target!(args)
+          enforce_risk_reward!(args)
+        end
+
+        def self.enforce_index!(instrument)
+          return if instrument.instrument_type == "INDEX"
+
+          raise DhanHQ::RiskViolation, "Options only allowed on index"
+        end
+
+        def self.enforce_stop_loss!(args)
+          return if args["stop_loss"]
+
+          raise DhanHQ::RiskViolation, "Stop loss required"
+        end
+
+        def self.enforce_target!(args)
+          return if args["target"]
+
+          raise DhanHQ::RiskViolation, "Target required"
+        end
+
+        def self.enforce_risk_reward!(args)
+          stop_loss = args["stop_loss"].to_f
+          target = args["target"].to_f
+          return if target > stop_loss
+
+          raise DhanHQ::RiskViolation, "Invalid risk-reward"
+        end
+
+        private_class_method :enforce_index!, :enforce_stop_loss!,
+                             :enforce_target!, :enforce_risk_reward!
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/order_type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Restricts order types to MARKET and LIMIT only.
+      class OrderType
+        VALID_TYPES = %w[MARKET LIMIT].freeze
+
+        def self.run!(args:, **_unused)
+          order_type = args["order_type"]
+          return unless order_type
+          return if VALID_TYPES.include?(order_type)
+
+          raise DhanHQ::RiskViolation, "Invalid order type"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/product_support.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Validates that the instrument supports the requested product type (BO/CO).
+      class ProductSupport
+        def self.run!(args:, instrument:, **_unused)
+          product_type = args["product_type"]
+          return unless product_type
+
+          enforce_bracket_support!(product_type, instrument)
+          enforce_cover_support!(product_type, instrument)
+        end
+
+        def self.enforce_bracket_support!(product_type, instrument)
+          return unless product_type == DhanHQ::Constants::ProductType::BO
+          return if instrument.bracket_flag == "Y"
+
+          raise DhanHQ::RiskViolation, "Bracket orders not supported"
+        end
+
+        def self.enforce_cover_support!(product_type, instrument)
+          return unless product_type == DhanHQ::Constants::ProductType::CO
+          return if instrument.cover_flag == "Y"
+
+          raise DhanHQ::RiskViolation, "Cover orders not supported"
+        end
+
+        private_class_method :enforce_bracket_support!, :enforce_cover_support!
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/quantity.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces quantity and notional limits for MCP tool safety.
+      class Quantity
+        MAX_QUANTITY = 10
+        MAX_NOTIONAL = 100_000
+
+        def self.run!(args:, **_unused)
+          quantity = args["quantity"].to_i
+          raise DhanHQ::RiskViolation, "Quantity must be > 0" unless quantity.positive?
+          raise DhanHQ::RiskViolation, "Quantity exceeds limit" if quantity > MAX_QUANTITY
+
+          enforce_notional_limit!(quantity, args["price"])
+        end
+
+        def self.enforce_notional_limit!(quantity, price)
+          return unless price
+
+          notional = quantity * price.to_f
+          return if notional <= MAX_NOTIONAL
+
+          raise DhanHQ::RiskViolation, "Notional exceeds limit"
+        end
+
+        private_class_method :enforce_notional_limit!
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/trading_permission.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Blocks trading on instruments where buy_sell_indicator is not "A".
+      class TradingPermission
+        def self.run!(instrument:, **_unused)
+          return if instrument.buy_sell_indicator == "A"
+
+          raise DhanHQ::RiskViolation, "Trading disabled for instrument"
+        end
+      end
+    end
+  end
+end

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