DhanHQ 2.8.0 → 3.0.1

data/lib/DhanHQ/option_analytics/black_scholes.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Option analytics calculations for derivatives trading.
+  module OptionAnalytics
+    # Black-Scholes option pricing model for calculating theoretical option prices and Greeks.
+    #
+    # @example Calculate option price
+    #   price = DhanHQ::OptionAnalytics::BlackScholes.price(
+    #     spot: 24000,
+    #     strike: 24200,
+    #     time_to_expiry: 0.038, # ~10 days
+    #     risk_free_rate: 0.065,
+    #     volatility: 0.15,
+    #     option_type: :call
+    #   )
+    #
+    class BlackScholes
+      # Calculate theoretical option price using Black-Scholes model.
+      #
+      # @param spot [Float] Current spot price
+      # @param strike [Float] Strike price
+      # @param time_to_expiry [Float] Time to expiry in years
+      # @param risk_free_rate [Float] Risk-free interest rate (annualized)
+      # @param volatility [Float] Implied volatility (annualized)
+      # @param option_type [Symbol] :call or :put
+      # @return [Float] Theoretical option price
+      def self.price(spot:, strike:, time_to_expiry:, risk_free_rate:, volatility:, option_type:)
+        return 0.0 if time_to_expiry <= 0
+
+        d1 = calculate_d1(spot, strike, time_to_expiry, risk_free_rate, volatility)
+        d2 = calculate_d2(d1, time_to_expiry, volatility)
+
+        if option_type == :call
+          (spot * normal_cdf(d1)) - (strike * Math.exp(-risk_free_rate * time_to_expiry) * normal_cdf(d2))
+        else
+          (strike * Math.exp(-risk_free_rate * time_to_expiry) * normal_cdf(-d2)) - (spot * normal_cdf(-d1))
+        end
+      end
+
+      # Calculate option Greeks (Delta, Gamma, Theta, Vega, Rho).
+      #
+      # @param spot [Float] Current spot price
+      # @param strike [Float] Strike price
+      # @param time_to_expiry [Float] Time to expiry in years
+      # @param risk_free_rate [Float] Risk-free interest rate (annualized)
+      # @param volatility [Float] Implied volatility (annualized)
+      # @param option_type [Symbol] :call or :put
+      # @return [Hash] Hash with :delta, :gamma, :theta, :vega, :rho
+      def self.greeks(spot:, strike:, time_to_expiry:, risk_free_rate:, volatility:, option_type:)
+        return empty_greeks if time_to_expiry <= 0
+
+        d1 = calculate_d1(spot, strike, time_to_expiry, risk_free_rate, volatility)
+        d2 = calculate_d2(d1, time_to_expiry, volatility)
+
+        gamma = normal_pdf(d1) / (spot * volatility * Math.sqrt(time_to_expiry))
+
+        theta = if option_type == :call
+                  calculate_call_theta(spot, strike, time_to_expiry, risk_free_rate, volatility, d1, d2)
+                else
+                  calculate_put_theta(spot, strike, time_to_expiry, risk_free_rate, volatility, d1, d2)
+                end
+
+        vega = spot * normal_pdf(d1) * Math.sqrt(time_to_expiry) / 100
+
+        rho = if option_type == :call
+                calculate_call_rho(spot, strike, time_to_expiry, risk_free_rate, d2)
+              else
+                calculate_put_rho(spot, strike, time_to_expiry, risk_free_rate, d2)
+              end
+
+        {
+          delta: calculate_delta(spot, strike, time_to_expiry, risk_free_rate, volatility, option_type),
+          gamma: gamma,
+          theta: theta / 365.0, # Daily theta
+          vega: vega,
+          rho: rho / 100.0
+        }
+      end
+
+      # Calculate implied volatility using Newton-Raphson method.
+      #
+      # @param market_price [Float] Observed market price of the option
+      # @param spot [Float] Current spot price
+      # @param strike [Float] Strike price
+      # @param time_to_expiry [Float] Time to expiry in years
+      # @param risk_free_rate [Float] Risk-free interest rate (annualized)
+      # @param option_type [Symbol] :call or :put
+      # @param tolerance [Float] Convergence tolerance (default: 0.0001)
+      # @param max_iterations [Integer] Maximum iterations (default: 100)
+      # @return [Float] Implied volatility
+      # rubocop:disable Metrics/ParameterLists
+      def self.implied_volatility(market_price:, spot:, strike:, time_to_expiry:, risk_free_rate:, option_type:,
+                                  tolerance: 0.0001, max_iterations: 100)
+        # rubocop:enable Metrics/ParameterLists
+        return 0.0 if time_to_expiry <= 0 || market_price <= 0
+
+        # Initial guess
+        iv = 0.2
+        max_iterations.times do
+          theoretical_price = price(
+            spot: spot, strike: strike, time_to_expiry: time_to_expiry,
+            risk_free_rate: risk_free_rate, volatility: iv, option_type: option_type
+          )
+
+          diff = theoretical_price - market_price
+          return iv if diff.abs < tolerance
+
+          # Vega for Newton-Raphson
+          vega = spot * normal_pdf(calculate_d1(spot, strike, time_to_expiry, risk_free_rate, iv)) *
+                 Math.sqrt(time_to_expiry)
+
+          return iv if vega < 1e-10
+
+          iv -= diff / vega
+          iv = [iv, 0.001].max # Prevent negative volatility
+        end
+
+        iv
+      end
+
+      class << self
+        private
+
+        def calculate_d1(spot, strike, time_to_expiry, risk_free_rate, volatility)
+          (Math.log(spot / strike) + ((risk_free_rate + ((volatility**2) / 2)) * time_to_expiry)) /
+            (volatility * Math.sqrt(time_to_expiry))
+        end
+
+        def calculate_d2(d1_val, time_to_expiry, volatility)
+          d1_val - (volatility * Math.sqrt(time_to_expiry))
+        end
+
+        def calculate_delta(spot, strike, time_to_expiry, risk_free_rate, volatility, option_type)
+          d1_val = calculate_d1(spot, strike, time_to_expiry, risk_free_rate, volatility)
+
+          if option_type == :call
+            normal_cdf(d1_val)
+          else
+            normal_cdf(d1_val) - 1
+          end
+        end
+
+        def calculate_call_theta(spot, strike, time_to_expiry, risk_free_rate, volatility, d1_val, d2_val)
+          term1 = -(spot * normal_pdf(d1_val) * volatility) / (2 * Math.sqrt(time_to_expiry))
+          term2 = risk_free_rate * strike * Math.exp(-risk_free_rate * time_to_expiry) * normal_cdf(d2_val)
+          term1 - term2
+        end
+
+        def calculate_put_theta(spot, strike, time_to_expiry, risk_free_rate, volatility, d1_val, d2_val)
+          term1 = -(spot * normal_pdf(d1_val) * volatility) / (2 * Math.sqrt(time_to_expiry))
+          term2 = -risk_free_rate * strike * Math.exp(-risk_free_rate * time_to_expiry) * normal_cdf(-d2_val)
+          term1 - term2
+        end
+
+        def calculate_call_rho(_spot, strike, time_to_expiry, risk_free_rate, d2_val)
+          strike * time_to_expiry * Math.exp(-risk_free_rate * time_to_expiry) * normal_cdf(d2_val)
+        end
+
+        def calculate_put_rho(_spot, strike, time_to_expiry, risk_free_rate, d2_val)
+          -strike * time_to_expiry * Math.exp(-risk_free_rate * time_to_expiry) * normal_cdf(-d2_val)
+        end
+
+        def empty_greeks
+          { delta: 0.0, gamma: 0.0, theta: 0.0, vega: 0.0, rho: 0.0 }
+        end
+
+        # rubocop:disable Naming/MethodParameterName
+        # Standard normal cumulative distribution function
+        def normal_cdf(x)
+          0.5 * (1 + erf(x / Math.sqrt(2)))
+        end
+
+        # Standard normal probability density function
+        def normal_pdf(x)
+          Math.exp(-0.5 * (x**2)) / Math.sqrt(2 * Math::PI)
+        end
+
+        # Error function approximation (Abramowitz and Stegun)
+        def erf(x)
+          sign = x.negative? ? -1 : 1
+          x = x.abs
+
+          t = 1.0 / (1.0 + (0.327_591_1 * x))
+          y = 1.0 - (((((((((1.061_40_5429 * t) - 1.453_152_027) * t) + 1.421_413_741) * t) -
+                      0.284_496_736) * t) + 0.254_829_592) * t * Math.exp(-x * x))
+
+          sign * y
+        end
+        # rubocop:enable Naming/MethodParameterName
+      end
+    end
+  end
+end

data/lib/DhanHQ/option_analytics/max_pain.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module OptionAnalytics
+    # Max Pain calculator for option chain analysis.
+    #
+    # Max Pain is the strike price at which the maximum number of options
+    # (both calls and puts) would expire worthless. It is believed that
+    # the underlying asset tends to gravitate towards this price at expiry.
+    #
+    # @example Calculate Max Pain
+    #   option_data = [
+    #     { strike: 24000, call_oi: 1000, put_oi: 500 },
+    #     { strike: 24100, call_oi: 800, put_oi: 700 },
+    #     { strike: 24200, call_oi: 600, put_oi: 900 },
+    #     ...
+    #   ]
+    #   max_pain = DhanHQ::OptionAnalytics::MaxPain.calculate(option_data)
+    #   #=> 24100
+    #
+    class MaxPain
+      # Calculate Max Pain strike price.
+      #
+      # @param option_data [Array<Hash>] Array of option data with :strike, :call_oi, :put_oi
+      # @return [Integer, Float] Strike price with maximum pain
+      def self.calculate(option_data)
+        return nil if option_data.nil? || option_data.empty?
+
+        strikes = option_data.map { |d| d[:strike] || d["strike"] }
+
+        # Calculate total pain for each possible strike
+        pain_values = strikes.map do |strike|
+          total_pain = option_data.sum do |data|
+            s = data[:strike] || data["strike"]
+            call_oi = (data[:call_oi] || data["call_oi"] || 0).to_i
+            put_oi = (data[:put_oi] || data["put_oi"] || 0).to_i
+
+            calculate_pain_at_strike(s, strike, call_oi, put_oi)
+          end
+
+          { strike: strike, pain: total_pain }
+        end
+
+        # Find strike with minimum pain (Max Pain)
+        pain_values.min_by { |v| v[:pain] }[:strike]
+      end
+
+      # Calculate Max Pain with detailed breakdown.
+      #
+      # @param option_data [Array<Hash>] Array of option data with :strike, :call_oi, :put_oi
+      # @return [Hash] Hash with :max_pain_strike, :total_pain, and :pain_distribution
+      def self.detailed(option_data)
+        return nil if option_data.nil? || option_data.empty?
+
+        strikes = option_data.map { |d| d[:strike] || d["strike"] }
+
+        pain_distribution = strikes.map do |strike|
+          total_pain = option_data.sum do |data|
+            s = data[:strike] || data["strike"]
+            call_oi = (data[:call_oi] || data["call_oi"] || 0).to_i
+            put_oi = (data[:put_oi] || data["put_oi"] || 0).to_i
+
+            calculate_pain_at_strike(s, strike, call_oi, put_oi)
+          end
+
+          { strike: strike, pain: total_pain }
+        end
+
+        max_pain_entry = pain_distribution.min_by { |v| v[:pain] }
+
+        {
+          max_pain_strike: max_pain_entry[:strike],
+          total_pain: max_pain_entry[:pain],
+          pain_distribution: pain_distribution
+        }
+      end
+
+      # Calculate Put-Call Ratio from option data.
+      #
+      # @param option_data [Array<Hash>] Array of option data with :call_oi, :put_oi
+      # @return [Float] Put-Call Ratio
+      def self.put_call_ratio(option_data)
+        return 0.0 if option_data.nil? || option_data.empty?
+
+        total_call_oi = option_data.sum { |d| (d[:call_oi] || d["call_oi"] || 0).to_i }
+        total_put_oi = option_data.sum { |d| (d[:put_oi] || d["put_oi"] || 0).to_i }
+
+        return 0.0 if total_call_oi.zero?
+
+        total_put_oi.to_f / total_call_oi
+      end
+
+      class << self
+        private
+
+        # Calculate total pain at a given strike price.
+        # Pain is the loss that option writers would incur if the underlying
+        # expires at that strike.
+        def calculate_pain_at_strike(current_strike, expiry_strike, call_oi, put_oi)
+          # Call writers lose when price goes above strike
+          call_pain = if expiry_strike > current_strike
+                        (expiry_strike - current_strike) * call_oi
+                      else
+                        0
+                      end
+
+          # Put writers lose when price goes below strike
+          put_pain = if expiry_strike < current_strike
+                       (current_strike - expiry_strike) * put_oi
+                     else
+                       0
+                     end
+
+          call_pain + put_pain
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/option_analytics.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "option_analytics/black_scholes"
+require_relative "option_analytics/max_pain"
+
+module DhanHQ
+  # Option analytics calculations for derivatives trading.
+  #
+  # Provides Black-Scholes pricing, Greeks calculation, implied volatility,
+  # and Max Pain analysis for option chain data.
+  #
+  # @example Calculate option price and Greeks
+  #   price = DhanHQ::OptionAnalytics::BlackScholes.price(
+  #     spot: 24000,
+  #     strike: 24200,
+  #     time_to_expiry: 0.038,
+  #     risk_free_rate: 0.065,
+  #     volatility: 0.15,
+  #     option_type: :call
+  #   )
+  #
+  #   greeks = DhanHQ::OptionAnalytics::BlackScholes.greeks(
+  #     spot: 24000,
+  #     strike: 24200,
+  #     time_to_expiry: 0.038,
+  #     risk_free_rate: 0.065,
+  #     volatility: 0.15,
+  #     option_type: :call
+  #   )
+  #
+  # @example Calculate Max Pain
+  #   max_pain = DhanHQ::OptionAnalytics::MaxPain.calculate(option_data)
+  #
+  module OptionAnalytics
+  end
+end

data/lib/DhanHQ/resources/iceberg_orders.rb

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

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