DhanHQ 4.1.0 → 4.1.1

data/lib/DhanHQ/helpers/request_helper.rb

@@ -40,7 +40,7 @@ module DhanHQ
       # Public CSV endpoint for segment-wise instruments requires no auth
       return { "Accept" => "text/csv" } if path.start_with?("/v2/instrument/")
 
-      token = resolved_access_token
+      token = request_access_token
       raise DhanHQ::AuthenticationError, "Missing access token" if token.nil? || token.empty?
 
       headers = {
@@ -51,7 +51,7 @@ module DhanHQ
 
       # Add client-id for DATA APIs (now including sandbox profile/funds)
       if data_api?(path)
-        client_id = current_config&.client_id
+        client_id = request_client_id
         unless client_id
           raise DhanHQ::InvalidAuthenticationError,
                 "client_id is required for DATA APIs but not set. Please configure DhanHQ with DHAN_CLIENT_ID."
@@ -66,6 +66,18 @@ module DhanHQ
       current_config&.resolved_access_token
     end
 
+    # Access token for the request being built. Overridden by {DhanHQ::Client}
+    # to pick the sandbox or production token for its API tier.
+    def request_access_token
+      resolved_access_token
+    end
+
+    # Client ID for the request being built. Overridden by {DhanHQ::Client}
+    # to pick the sandbox or production client ID for its API tier.
+    def request_client_id
+      current_config&.client_id
+    end
+
     # Determines if the API path requires a `client-id` header.
     #
     # @param path [String] The API endpoint path.
@@ -88,12 +100,12 @@ module DhanHQ
               "Invalid payload: Expected a Hash, got #{payload.class}"
       end
 
-      out = payload
+      out = rebind_dhan_client_id(payload)
       if path && %i[post put patch].include?(method)
-        client_id = current_config&.client_id
+        client_id = request_client_id
         needs_client_id = data_api?(path) || payload_requires_dhan_client_id?(path)
-        if client_id && needs_client_id && !payload.key?(:dhanClientId) && !payload.key?("dhanClientId")
-          out = payload.dup
+        if client_id && needs_client_id && !out.key?(:dhanClientId) && !out.key?("dhanClientId")
+          out = out.dup
           if out.keys.any?(String)
             out["dhanClientId"] = client_id
           else
@@ -109,6 +121,23 @@ module DhanHQ
       end
     end
 
+    # Models fill +dhanClientId+ from the production {Configuration#client_id}.
+    # When this request authenticates with a different client ID (the sandbox
+    # one, in +:hybrid+ mode) the body must name the same account as the
+    # token, so a production ID is swapped for the request's ID. Only a value
+    # equal to the production ID is rewritten; an explicitly different ID is
+    # left alone.
+    def rebind_dhan_client_id(payload)
+      production_id = current_config&.client_id
+      request_id = request_client_id
+      return payload if production_id.nil? || request_id.nil? || production_id.to_s == request_id.to_s
+
+      key = [:dhanClientId, "dhanClientId"].find { |k| payload.key?(k) }
+      return payload unless key && payload[key].to_s == production_id.to_s
+
+      payload.merge(key => request_id)
+    end
+
     # True when the path is one where the request body must include dhanClientId (order-api style).
     def payload_requires_dhan_client_id?(path)
       return false if path.nil? || path.empty?

data/lib/DhanHQ/helpers/response_helper.rb

@@ -54,7 +54,7 @@ module DhanHQ
     def handle_error(response)
       body = parse_json(response.body)
 
-      error_code = body[:errorCode] || response.status.to_s
+      error_code = (body[:errorCode] || response.status).to_s
       error_message = body[:errorMessage] || body[:message] || "Unknown error"
       if error_code == DhanHQ::Constants::TradingErrorCode::NO_HOLDINGS
         error_message = "No holdings found for this account. Add holdings or wait for them to settle before retrying."

data/lib/DhanHQ/models/iceberg_order.rb

@@ -108,7 +108,7 @@ module DhanHQ
           response = resource.create(formatted)
           return nil unless response.is_a?(Hash) && response["orderId"]
 
-          new(order_id: response["orderId"], order_status: response["orderStatus"], skip_validation: true)
+          new({ order_id: response["orderId"], order_status: response["orderStatus"] }, skip_validation: true)
         end
       end
 

data/lib/DhanHQ/models/super_order.rb

@@ -222,7 +222,7 @@ module DhanHQ
           response = resource.create(normalized_params)
           return nil unless response.is_a?(Hash) && response["orderId"]
 
-          new(order_id: response["orderId"], order_status: response["orderStatus"], skip_validation: true)
+          new({ order_id: response["orderId"], order_status: response["orderStatus"] }, skip_validation: true)
         end
       end
 

data/lib/DhanHQ/models/twap_order.rb

@@ -105,7 +105,7 @@ module DhanHQ
           response = resource.create(formatted)
           return nil unless response.is_a?(Hash) && response["orderId"]
 
-          new(order_id: response["orderId"], order_status: response["orderStatus"], skip_validation: true)
+          new({ order_id: response["orderId"], order_status: response["orderStatus"] }, skip_validation: true)
         end
       end
 

data/lib/DhanHQ/resources/instruments.rb

@@ -14,6 +14,7 @@ module DhanHQ
       #
       # @param exchange_segment [String] e.g. "NSE_EQ", "NSE_FNO", "IDX_I"
       # @return [String] CSV content
+      # @raise [DhanHQ::Error] When the API answers with an HTTP error.
       def by_segment(exchange_segment)
         path = "#{HTTP_PATH}/#{exchange_segment}"
         resp = client.connection.get(path)
@@ -21,9 +22,38 @@ module DhanHQ
           redirect_url = resp.headers["location"]
           Faraday.get(redirect_url).body
         else
+          raise_for_failure!(resp) if resp.status >= 400
+
           resp.body
         end
       end
+
+      private
+
+      # Raises the error class mapped to the response status, so this non-JSON
+      # endpoint fails like every other resource instead of handing the caller a
+      # raw error body dressed up as CSV.
+      #
+      # @param resp [Faraday::Response]
+      # @raise [DhanHQ::Error]
+      def raise_for_failure!(resp)
+        body = parse_error_body(resp.body)
+        message = "#{body[:errorCode] || resp.status}: #{body[:errorMessage] || "Unknown error"}"
+        klass = DhanHQ::ResponseHelper::STATUS_ERROR_FALLBACK.fetch(resp.status) do
+          resp.status.between?(500, 599) ? DhanHQ::InternalServerError : DhanHQ::OtherError
+        end
+        raise klass, message
+      end
+
+      # Best-effort parse of a JSON error body; non-JSON bodies degrade to the raw text.
+      #
+      # @param raw [String]
+      # @return [Hash]
+      def parse_error_body(raw)
+        JSON.parse(raw.to_s, symbolize_names: true)
+      rescue JSON::ParserError
+        {}
+      end
     end
   end
 end

data/lib/DhanHQ/resources/margin_calculator.rb

@@ -24,7 +24,10 @@ module DhanHQ
       # @param params [Hash] Request parameters including scripList, includePosition, includeOrder.
       # @return [Hash] API response containing combined margin details with hedge benefit.
       def calculate_multi(params)
-        post("/multi", params: params)
+        # Deep-camelize: the scripList entries are hashes, and the API expects
+        # camelCase keys inside them (securityId, exchangeSegment, ...), which the
+        # shallow top-level camelize would leave in snake_case.
+        post("/multi", params: deep_camelize_keys(params))
       end
     end
   end

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

@@ -5,7 +5,10 @@ module DhanHQ
     module Checks
       # Blocks trading on ASM/GSM restricted instruments.
       class AsmGsm
-        def self.run!(instrument:, **_unused)
+        # Exits are allowed: a position held before the instrument entered ASM/GSM
+        # must still be closable.
+        def self.run!(instrument:, reducing: false, **_unused)
+          return if reducing
           return unless instrument.asm_gsm_flag == "Y"
 
           raise DhanHQ::RiskViolation,

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

@@ -7,30 +7,99 @@ module DhanHQ
       class Concentration
         MAX_CONCENTRATION_PCT = 25.0
 
-        def self.run!(args:, **_unused)
-          symbol = args["trading_symbol"] || args["security_id"]
-          return unless symbol
+        # Exposure in one instrument — open positions plus this order's notional —
+        # as a share of available funds. Positions match on security id (and segment
+        # when given) or, when the order names one, on trading symbol. Order params
+        # usually carry only a security id, and comparing that against a position's
+        # trading symbol never matched, which left this check inert for orders.
+        #
+        # A MARKET entry carries no price, so its notional is estimated from the
+        # trigger price or the instrument's LTP; an entry that cannot be priced is
+        # refused rather than counted as zero exposure.
+        def self.run!(args:, positions: nil, reducing: false, instrument: nil, **_unused)
+          security_id = args["security_id"].to_s
+          symbol = args["trading_symbol"].to_s
+          return if reducing || (security_id.empty? && symbol.empty?)
 
           funds = DhanHQ::Models::Funds.fetch
           available = funds.available_balance.to_f
           return if available <= 0
 
-          positions = DhanHQ::Models::Position.all
-          symbol_positions = positions.select do |p|
-            sym = p.trading_symbol || p.security_id
-            sym.to_s == symbol.to_s
-          end
+          positions ||= DhanHQ::Models::Position.all
+          symbol_positions = positions.select { |p| same_instrument?(p, args, security_id, symbol) }
 
           current_exposure = symbol_positions.sum do |p|
             p.net_qty.to_i.abs * p.cost_price.to_f
           end
+          order_notional = order_notional(args, instrument)
+          limit = Limits.value(:max_concentration_pct, MAX_CONCENTRATION_PCT)
 
-          concentration_pct = (current_exposure / available) * 100.0
-          return if concentration_pct <= MAX_CONCENTRATION_PCT
+          concentration_pct = ((current_exposure + order_notional) / available) * 100.0
+          return if concentration_pct <= limit
 
           raise DhanHQ::RiskViolation,
-                "Concentration #{concentration_pct.round(1)}% exceeds #{MAX_CONCENTRATION_PCT}% limit for #{symbol}"
+                "Concentration #{concentration_pct.round(1)}% exceeds #{limit}% limit for #{symbol.empty? ? security_id : symbol}"
+        end
+
+        def self.order_notional(args, instrument)
+          quantity = args["quantity"].to_i
+          return 0.0 unless quantity.positive?
+
+          quantity * order_price!(args, instrument)
         end
+
+        def self.order_price!(args, instrument)
+          price = [args["price"], args["trigger_price"]].map(&:to_f).find(&:positive?)
+          return price if price
+          return unpriced_paper_order(args) if paper_order_without_quotes?
+
+          price = live_price(instrument)
+          return price if price&.positive?
+
+          raise DhanHQ::RiskViolation,
+                "Cannot price #{args["security_id"] || args["trading_symbol"]} for the concentration check " \
+                "(no price, trigger price or LTP)"
+        end
+
+        # Full sandbox: the order is a paper order and the sandbox serves no quotes
+        # (GET /marketfeed/ltp is refused there), so a MARKET entry cannot be
+        # priced. Refusing it would block every paper market order for no money at
+        # risk; count only existing exposure instead. A real order is never let
+        # through this way: it needs the order tier on the sandbox too.
+        def self.paper_order_without_quotes?
+          config = DhanHQ.configuration
+          return false unless config
+
+          config.environment_for(:order_api) == :sandbox && config.environment_for(:data_api) == :sandbox
+        end
+
+        def self.unpriced_paper_order(args)
+          DhanHQ.logger&.info(
+            "[DhanHQ::Risk::Concentration] Sandbox has no quotes; #{args["security_id"]} order notional not counted"
+          )
+          0.0
+        end
+
+        # A failed LTP fetch must refuse the entry, not escape as a generic error:
+        # OrderAudit treats unexpected errors as "skip every check".
+        def self.live_price(instrument)
+          return nil unless instrument.respond_to?(:ltp)
+
+          instrument.ltp.to_f
+        rescue StandardError => e
+          DhanHQ.logger&.warn("[DhanHQ::Risk::Concentration] LTP fetch failed: #{e.class} #{e.message}")
+          nil
+        end
+
+        def self.same_instrument?(position, args, security_id, symbol)
+          return position.trading_symbol.to_s == symbol unless symbol.empty?
+
+          position.security_id.to_s == security_id &&
+            (args["exchange_segment"].nil? || position.exchange_segment.to_s == args["exchange_segment"].to_s)
+        end
+
+        private_class_method :order_notional, :order_price!, :paper_order_without_quotes?, :unpriced_paper_order,
+                             :live_price, :same_instrument?
       end
     end
   end

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

@@ -7,16 +7,21 @@ module DhanHQ
       class MaxLoss
         DAILY_MAX_LOSS = 50_000
 
-        def self.run!(**_unused)
-          positions = DhanHQ::Models::Position.all
-          total_unrealized_loss = positions.sum do |p|
-            p.unrealized_profit.to_f
+        # Day P&L is realized plus unrealized: a loss booked earlier in the day
+        # counts against the limit just as an open one does.
+        def self.run!(positions: nil, reducing: false, **_unused)
+          return if reducing
+
+          positions ||= DhanHQ::Models::Position.all
+          day_pnl = positions.sum do |p|
+            p.realized_profit.to_f + p.unrealized_profit.to_f
           end
+          limit = Limits.value(:daily_max_loss, DAILY_MAX_LOSS)
 
-          return if total_unrealized_loss >= -DAILY_MAX_LOSS
+          return if day_pnl >= -limit
 
           raise DhanHQ::RiskViolation,
-                "Daily loss limit of ₹#{DAILY_MAX_LOSS} exceeded (current: ₹#{total_unrealized_loss.round(0)})"
+                "Daily loss limit of ₹#{limit} exceeded (current: ₹#{day_pnl.round(0)})"
         end
       end
     end

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

@@ -5,7 +5,10 @@ module DhanHQ
     module Checks
       # Enforces option-specific risk rules (index-only, stop loss, target, risk-reward).
       class Options
-        def self.run!(args:, instrument:, **_unused)
+        # Entry rules only: closing an option position needs no stop loss or target.
+        def self.run!(args:, instrument:, reducing: false, **_unused)
+          return if reducing
+
           enforce_index!(instrument)
           enforce_stop_loss!(args)
           enforce_target!(args)

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

@@ -5,7 +5,9 @@ module DhanHQ
     module Checks
       # Restricts order types to MARKET and LIMIT only.
       class OrderType
-        VALID_TYPES = %w[MARKET LIMIT].freeze
+        # Every order type the Dhan order APIs accept. STOP_LOSS / STOP_LOSS_MARKET
+        # must pass: they are how a stop-loss is placed.
+        VALID_TYPES = DhanHQ::Constants::OrderType::ALL
 
         def self.run!(args:, **_unused)
           order_type = args["order_type"]

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

@@ -7,16 +7,19 @@ module DhanHQ
       class PositionLimits
         MAX_OPEN_POSITIONS = 20
 
-        def self.run!(**_unused)
-          positions = DhanHQ::Models::Position.all
+        def self.run!(positions: nil, reducing: false, **_unused)
+          return if reducing
+
+          positions ||= DhanHQ::Models::Position.all
           open_count = positions.count do |p|
             p.net_qty.to_i != 0
           end
+          limit = Limits.value(:max_open_positions, MAX_OPEN_POSITIONS)
 
-          return if open_count < MAX_OPEN_POSITIONS
+          return if open_count < limit
 
           raise DhanHQ::RiskViolation,
-                "Maximum #{MAX_OPEN_POSITIONS} open positions exceeded (#{open_count} open)"
+                "Maximum #{limit} open positions exceeded (#{open_count} open)"
         end
       end
     end

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

@@ -8,10 +8,13 @@ module DhanHQ
         MAX_QUANTITY = 10
         MAX_NOTIONAL = 100_000
 
-        def self.run!(args:, **_unused)
+        # Size caps apply to new exposure only; an exit of any size that does not
+        # exceed the open position is allowed.
+        def self.run!(args:, reducing: false, **_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
+          return if reducing
+          raise DhanHQ::RiskViolation, "Quantity exceeds limit" if quantity > Limits.value(:max_quantity, MAX_QUANTITY)
 
           enforce_notional_limit!(quantity, args["price"])
         end
@@ -20,7 +23,7 @@ module DhanHQ
           return unless price
 
           notional = quantity * price.to_f
-          return if notional <= MAX_NOTIONAL
+          return if notional <= Limits.value(:max_notional, MAX_NOTIONAL)
 
           raise DhanHQ::RiskViolation, "Notional exceeds limit"
         end

data/lib/DhanHQ/risk/exposure.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    # Classifies an order against the account's open positions.
+    #
+    # A risk-reducing order — the opposite side of an open position in the same
+    # instrument and product, for no more than that position's size — only shrinks
+    # exposure. Limit checks (position count, daily loss, concentration, size caps,
+    # ASM/GSM) must never block it: refusing a stop-out because the account is
+    # already over a limit turns a capped loss into an uncapped one.
+    module Exposure
+      # @param args [Hash] Order arguments with snake_case String keys.
+      # @param positions [Array<#security_id, #exchange_segment, #product_type, #net_qty>]
+      # @return [Boolean] True when the order only reduces an existing position.
+      def self.reducing?(args, positions)
+        quantity = args["quantity"].to_i
+        side = args["transaction_type"].to_s.upcase
+        return false unless quantity.positive? && Constants::TransactionType::ALL.include?(side)
+
+        position = matching_position(args, positions)
+        return false unless position
+
+        net = position.net_qty.to_i
+        closes = side == Constants::TransactionType::SELL ? net.positive? : net.negative?
+        closes && quantity <= net.abs
+      end
+
+      def self.matching_position(args, positions)
+        security_id = args["security_id"].to_s
+        return nil if security_id.empty?
+
+        Array(positions).find do |position|
+          position.net_qty.to_i != 0 &&
+            position.security_id.to_s == security_id &&
+            same_or_unspecified?(args["exchange_segment"], position.exchange_segment) &&
+            same_or_unspecified?(args["product_type"], position.product_type)
+        end
+      end
+
+      def self.same_or_unspecified?(wanted, actual)
+        wanted.nil? || wanted.to_s.empty? || wanted.to_s == actual.to_s
+      end
+
+      private_class_method :matching_position, :same_or_unspecified?
+    end
+  end
+end

data/lib/DhanHQ/risk/limits.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    # Configurable thresholds for the pre-trade risk checks.
+    #
+    # Each check keeps its historical constant as the default, so an unconfigured
+    # client behaves exactly as before. Override per process with
+    # {DhanHQ::Configuration#risk_limits} or the matching +DHAN_RISK_*+ variable:
+    #
+    #   DhanHQ.configure do |c|
+    #     c.risk_limits = { max_quantity: 1_800, max_notional: 250_000 }
+    #   end
+    #
+    # +max_quantity+ is in units as sent to the API (one NIFTY lot is 75 units),
+    # not in lots.
+    module Limits
+      # Limit name => environment variable that sets it.
+      ENV_KEYS = {
+        max_quantity: "DHAN_RISK_MAX_QUANTITY",
+        max_notional: "DHAN_RISK_MAX_NOTIONAL",
+        max_open_positions: "DHAN_RISK_MAX_OPEN_POSITIONS",
+        daily_max_loss: "DHAN_RISK_DAILY_MAX_LOSS",
+        max_concentration_pct: "DHAN_RISK_MAX_CONCENTRATION_PCT"
+      }.freeze
+
+      # Every limit name {DhanHQ::Configuration#risk_limits} accepts.
+      NAMES = ENV_KEYS.keys.freeze
+
+      # @param name [Symbol] One of {NAMES}.
+      # @param default [Numeric] The check's built-in threshold.
+      # @return [Numeric] The configured threshold, or +default+.
+      def self.value(name, default)
+        DhanHQ.configuration&.risk_limits&.fetch(name, nil) || default
+      end
+
+      # Validates and normalises a limits hash (String or Symbol keys, numeric values).
+      #
+      # @param raw [Hash, nil]
+      # @return [Hash{Symbol => Numeric}]
+      # @raise [ArgumentError] On an unknown name or a non-positive / non-numeric value.
+      def self.coerce(raw)
+        return {} if raw.nil?
+        raise ArgumentError, "risk_limits must be a Hash of #{NAMES.join(", ")}" unless raw.is_a?(Hash)
+
+        raw.each_with_object({}) do |(name, value), out|
+          key = name.to_s.strip.to_sym
+          raise ArgumentError, "unknown risk limit #{name.inspect}: expected one of #{NAMES.join(", ")}" unless NAMES.include?(key)
+
+          out[key] = positive_number!(key, value)
+        end
+      end
+
+      # Limits set through +DHAN_RISK_*+ environment variables.
+      #
+      # @return [Hash{Symbol => Numeric}]
+      def self.from_env
+        coerce(ENV_KEYS.each_with_object({}) do |(name, env), out|
+          raw = ENV.fetch(env, "").strip
+          out[name] = raw unless raw.empty?
+        end)
+      end
+
+      def self.positive_number!(key, value)
+        number = Float(value.to_s, exception: false)
+        raise ArgumentError, "risk limit #{key} must be a number (got #{value.inspect})" if number.nil?
+        raise ArgumentError, "risk limit #{key} must be positive (got #{value.inspect})" unless number.positive?
+
+        (number % 1).zero? ? number.to_i : number
+      end
+
+      private_class_method :positive_number!
+    end
+  end
+end

data/lib/DhanHQ/risk/pipeline.rb

@@ -7,6 +7,11 @@ module DhanHQ
     # Runs a sequence of checks against the instrument and order arguments.
     # Raises DhanHQ::RiskViolation on the first failure.
     #
+    # Open positions are fetched once per run and shared by every check. Orders that
+    # only reduce an open position (see {Exposure.reducing?}) skip the limit checks
+    # but still get the validity checks (trading permission, product support, order
+    # type, quantity > 0, market hours).
+    #
     # @example Run equity risk checks
     #   DhanHQ::Risk::Pipeline.run!(
     #     instrument: instrument,
@@ -46,22 +51,25 @@ module DhanHQ
       # Run all applicable risk checks.
       #
       # @param instrument [Object] instrument with trading metadata
-      # @param args [Hash] order arguments (string keys)
+      # @param args [Hash] order arguments (snake_case string keys)
       # @param now [Time] current time for market hours check (default: Time.now)
       # @param type [Symbol] :equity or :options
+      # @param positions [Array, nil] open positions; fetched once when nil
       # @return [true] if all checks pass
       # @raise [DhanHQ::RiskViolation] on first failure
-      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
-        run_checks!(DAILY_CHECKS, instrument, args, now)
+      def self.run!(instrument:, args:, now: Time.now, type: :equity, positions: nil)
+        positions ||= DhanHQ::Models::Position.all
+        context = { instrument: instrument, args: args, now: now, positions: positions,
+                    reducing: Exposure.reducing?(args, positions) }
+
+        run_checks!(CHECKS, context)
+        run_checks!(OPTION_CHECKS, context) if type == :options
+        run_checks!(DAILY_CHECKS, context)
         true
       end
 
-      def self.run_checks!(checks, instrument, args, now)
-        checks.each do |check|
-          check.run!(instrument: instrument, args: args, now: now)
-        end
+      def self.run_checks!(checks, context)
+        checks.each { |check| check.run!(**context) }
       end
 
       private_class_method :run_checks!

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "4.1.0"
+  VERSION = "4.1.1"
 end