DhanHQ 3.3.0 → 4.0.0

data/lib/DhanHQ/backtest/trade.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Backtest
+    # A single completed long round-trip trade produced by Runner.
+    #
+    # `fees` is the total cost charged across both legs (entry + exit), already
+    # netted into `pnl` — it is not deducted again by callers.
+    Trade = Struct.new(
+      :entry_time, :entry_price, :exit_time, :exit_price, :quantity, :exit_reason, :fees
+    ) do
+      # Net profit/loss for this trade, after fees.
+      #
+      # @return [Float]
+      def pnl
+        ((exit_price - entry_price) * quantity) - fees.to_f
+      end
+
+      # Net profit/loss as a percentage of the entry value.
+      #
+      # @return [Float]
+      def pnl_pct
+        entry_value = entry_price.to_f * quantity.to_f
+        return 0.0 if entry_value.zero?
+
+        (pnl / entry_value) * 100
+      end
+
+      # @return [Boolean] whether this trade closed profitably after fees
+      def win?
+        pnl.positive?
+      end
+    end
+  end
+end

data/lib/DhanHQ/backtest.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Backtesting engine that replays a DhanHQ::Strategy::Base against historical
+  # OHLC data and reports trades, an equity curve, and summary performance stats.
+  #
+  # @example Backtest a strategy against daily candles
+  #   data = DhanHQ::Models::HistoricalData.daily(
+  #     security_id: "1333", exchange_segment: "NSE_EQ",
+  #     instrument: "EQUITY", from_date: "2024-01-01", to_date: "2024-12-31"
+  #   )
+  #   series = DhanHQ::MarketData::OHLCSeries.from_response(data)
+  #
+  #   result = DhanHQ::Backtest::Runner.new(
+  #     strategy: MyStrategy.new,
+  #     data: series,
+  #     initial_capital: 100_000.0
+  #   ).run
+  #
+  #   result.summary #=> { total_return_pct: 12.4, num_trades: 8, win_rate: 62.5, ... }
+  #
+  module Backtest
+  end
+end

data/lib/DhanHQ/client.rb

@@ -42,42 +42,68 @@ module DhanHQ
     ].freeze
     private_constant :RETRYABLE_TRANSPORT_ERRORS
 
-    attr_reader :token_manager
+    attr_reader :config, :token_manager, :api_type
 
-    # Initializes a new DhanHQ Client.
-    #
-    # Establishes state and checks its one invariant; the HTTP connection is opened
-    # lazily on first use, so constructing a client does no network setup.
-    #
-    # @example Create a new client:
-    #   client = DhanHQ::Client.new(api_type: :order_api)
+    # Initializes a new DhanHQ Client with instance-level configuration and rate limiting.
     #
+    # @param config_or_attrs [DhanHQ::Configuration, Hash, nil] Optional configuration or attribute hash
+    # @param config [DhanHQ::Configuration, nil] Optional keyword configuration
     # @param api_type [Symbol] Type of API (`:order_api`, `:data_api`, `:non_trading_api`)
-    # @return [DhanHQ::Client] A new client instance.
-    # @raise [DhanHQ::Error] If the rate limiter cannot be resolved for this API type.
-    def initialize(api_type:)
-      DhanHQ.ensure_configuration!
-      # Shared per API type, so separate clients coordinate against one limit.
+    # @param attrs [Hash] Additional keyword configuration attributes
+    def initialize(config_or_attrs = nil, config: nil, api_type: :order_api, **attrs)
+      @config = resolve_config(config_or_attrs, config, attrs)
+      @api_type = api_type
       @rate_limiter = RateLimiter.for(api_type)
 
       raise DhanHQ::Error, "RateLimiter initialization failed" unless @rate_limiter
     end
 
     # The Faraday connection used for HTTP requests.
-    #
-    # Built on first use and rebuilt whenever the configured base URL changes — which
-    # happens when sandbox mode is toggled, or when a token endpoint hands back a
-    # different host mid-process.
+    # Built on first use and rebuilt whenever the configured base URL changes.
     #
     # @return [Faraday::Connection]
     def connection
-      current_url = DhanHQ.configuration.base_url
+      current_url = @config.base_url
       return @connection if @connection && @last_base_url == current_url
 
       @last_base_url = current_url
       @connection = build_connection(current_url)
     end
 
+    # Resource accessors bound to this client instance. Each resource gets the client
+    # matching its own API_TYPE, so e.g. option chain calls throttle at 1 per 3 sec
+    # instead of borrowing the order client's 10/sec limiter.
+    def orders = @orders ||= Resources::Orders.new(client: client_for(Resources::Orders::API_TYPE))
+    def market_feed = @market_feed ||= Resources::MarketFeed.new(client: client_for(Resources::MarketFeed::API_TYPE))
+    def positions = @positions ||= Resources::Positions.new(client: client_for(Resources::Positions::API_TYPE))
+    def holdings = @holdings ||= Resources::Holdings.new(client: client_for(Resources::Holdings::API_TYPE))
+    def historical_data = @historical_data ||= Resources::HistoricalData.new(client: client_for(Resources::HistoricalData::API_TYPE))
+    def option_chain = @option_chain ||= Resources::OptionChain.new(client: client_for(Resources::OptionChain::API_TYPE))
+    def funds = @funds ||= Resources::Funds.new(client: client_for(Resources::Funds::API_TYPE))
+    def trades = @trades ||= Resources::Trades.new(client: client_for(Resources::Trades::API_TYPE))
+    def forever_orders = @forever_orders ||= Resources::ForeverOrders.new(client: client_for(Resources::ForeverOrders::API_TYPE))
+    def alert_orders = @alert_orders ||= Resources::AlertOrders.new(client: client_for(Resources::AlertOrders::API_TYPE))
+    def iceberg_orders = @iceberg_orders ||= Resources::IcebergOrders.new(client: client_for(Resources::IcebergOrders::API_TYPE))
+    def super_orders = @super_orders ||= Resources::SuperOrders.new(client: client_for(Resources::SuperOrders::API_TYPE))
+    def twap_orders = @twap_orders ||= Resources::TwapOrders.new(client: client_for(Resources::TwapOrders::API_TYPE))
+    def statements = @statements ||= Resources::Statements.new(client: client_for(Resources::Statements::API_TYPE))
+    def kill_switch = @kill_switch ||= Resources::KillSwitch.new(client: client_for(Resources::KillSwitch::API_TYPE))
+    def pnl_exit = @pnl_exit ||= Resources::PnlExit.new(client: client_for(Resources::PnlExit::API_TYPE))
+    def trader_control = @trader_control ||= Resources::TraderControl.new(client: client_for(Resources::TraderControl::API_TYPE))
+    def ip_setup = @ip_setup ||= Resources::IPSetup.new(client: client_for(Resources::IPSetup::API_TYPE))
+    def edis = @edis ||= Resources::Edis.new(client: client_for(Resources::Edis::API_TYPE))
+
+    # WebSocket streams bound to this client instance configuration
+    def ws_market_feed(mode: :ticker, url: nil, &block)
+      WS::Client.new(mode: mode, url: url, config: @config).tap do |ws|
+        ws.start if block_given?
+        ws.on(:tick, &block) if block_given?
+      end
+    end
+
+    def ws_order_update = WS::Orders::Client.new(config: @config)
+    def ws_market_depth = WS::MarketDepth::Client.new(config: @config)
+
     # Sends an HTTP request to the API with automatic retry for transient errors.
     #
     # @param method [Symbol] The HTTP method (`:get`, `:post`, `:put`, `:delete`)
@@ -93,8 +119,6 @@ module DhanHQ
       @token_manager&.ensure_valid_token!
       @rate_limiter.throttle!
 
-      # A non-idempotent write is not safely retryable: the API has no idempotency
-      # key, so a request that timed out may already have reached the exchange.
       effective_retries = retryable_write?(method, path) ? retries : 0
 
       with_auth_retry do
@@ -112,10 +136,9 @@ module DhanHQ
       yield
     rescue DhanHQ::InvalidAuthenticationError, DhanHQ::InvalidTokenError,
            DhanHQ::TokenExpiredError, DhanHQ::AuthenticationFailedError => e
-      config = DhanHQ.configuration
-      raise unless config&.access_token_provider
+      raise unless @config&.access_token_provider
 
-      config.on_token_expired&.call(e)
+      @config.on_token_expired&.call(e)
       DhanHQ.logger&.warn("[DhanHQ::Client] Auth failure (#{e.class}), retrying once with fresh token")
       yield
     end
@@ -218,20 +241,47 @@ module DhanHQ
       @token_manager.generate!
     end
 
+    # A client sharing this one's config but rate-limited for a different API tier.
+    # RateLimiter.for(api_type) is a shared instance per type, so sibling clients still
+    # throttle against the same counters as any other client using that tier.
+    #
+    # @param api_type [Symbol] Target API tier (:order_api, :data_api, :non_trading_api, :option_chain)
+    # @return [DhanHQ::Client]
+    def client_for(api_type)
+      return self if api_type == @api_type
+
+      @sibling_clients ||= {}
+      @sibling_clients[api_type] ||= self.class.new(config: @config, api_type: api_type)
+    end
+
     private
 
+    def resolve_config(config_or_attrs, keyword_config, attrs = {})
+      if config_or_attrs.is_a?(DhanHQ::Configuration)
+        config_or_attrs
+      elsif config_or_attrs.is_a?(Hash)
+        DhanHQ::Configuration.new(config_or_attrs.merge(attrs))
+      elsif keyword_config
+        keyword_config
+      elsif attrs.any?
+        DhanHQ::Configuration.new(attrs)
+      else
+        DhanHQ.ensure_configuration!
+      end
+    end
+
     # Simulator that answers state-changing requests locally when dry run is on.
     #
     # @return [DhanHQ::DryRun::Simulator]
     def dry_run
-      @dry_run ||= DhanHQ::DryRun::Simulator.new
+      @dry_run ||= DhanHQ::DryRun::Simulator.new(config: @config)
     end
 
     # A write may be auto-retried only when the user has explicitly opted in.
     def retryable_write?(method, path)
       return true unless WritePaths.mutating?(method, path)
 
-      DhanHQ.configuration&.retry_non_idempotent_writes? || false
+      @config&.retry_non_idempotent_writes? || false
     end
 
     # Fills in a +correlationId+ on order placements that lack one, so a caller who
@@ -240,7 +290,7 @@ module DhanHQ
     def with_correlation_id(method, path, payload)
       return payload unless WritePaths.order_placement?(method, path)
       return payload unless payload.is_a?(Hash)
-      return payload unless DhanHQ.configuration&.auto_correlation_id?
+      return payload unless @config&.auto_correlation_id?
       return payload if correlation_id?(payload)
 
       inject_correlation_id(payload)

data/lib/DhanHQ/configuration.rb

@@ -132,6 +132,15 @@ module DhanHQ
     # @return [Integer]
     attr_accessor :market_depth_level
 
+    # When true, every raw inbound WebSocket frame (market feed, order updates,
+    # market depth) is logged as a hex dump at debug level before it's parsed.
+    # Off by default -- high volume, and the check happens before any hex
+    # encoding work so there's no cost when disabled.
+    #
+    # Set via +DHAN_WS_DEBUG=true+ or in {DhanHQ.configure}.
+    # @return [Boolean]
+    attr_accessor :ws_debug
+
     # Setters for websocket URLs
     attr_writer :ws_order_url, :ws_market_feed_url, :ws_market_depth_url
 
@@ -198,29 +207,37 @@ module DhanHQ
       @auto_correlation_id == true
     end
 
-    # Initializes a new configuration instance with default values.
-    #
-    # @example
-    #   config = DhanHQ::Configuration.new
-    #   config.client_id = "your_client_id"
-    #   config.access_token = "your_access_token"
-    def initialize
-      @client_id = ENV.fetch("DHAN_CLIENT_ID", nil)
-      @access_token = ENV.fetch("DHAN_ACCESS_TOKEN", nil)
-      @sandbox        = env_flag("DHAN_SANDBOX", default: false)
-      @dry_run        = env_flag("DHAN_DRY_RUN", default: false)
-      @retry_non_idempotent_writes = env_flag("DHAN_RETRY_WRITES", default: false)
-      @auto_correlation_id = env_flag("DHAN_AUTO_CORRELATION_ID", default: false)
-      @warn_on_ambiguous_write_failure = env_flag("DHAN_WARN_AMBIGUOUS_WRITE_FAILURE", default: true)
-      @base_url       = ENV.fetch("DHAN_BASE_URL", nil)
-      @ws_version     = ENV.fetch("DHAN_WS_VERSION", 2).to_i
-      @ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", nil)
-      @ws_market_feed_url = ENV.fetch("DHAN_WS_MARKET_FEED_URL", nil)
-      @ws_market_depth_url = ENV.fetch("DHAN_WS_MARKET_DEPTH_URL", nil)
-      @market_depth_level = ENV.fetch("DHAN_MARKET_DEPTH_LEVEL", "20").to_i
-      @ws_user_type   = ENV.fetch("DHAN_WS_USER_TYPE", "SELF")
-      @partner_id     = ENV.fetch("DHAN_PARTNER_ID", nil)
-      @partner_secret = ENV.fetch("DHAN_PARTNER_SECRET", nil)
+    # @return [Boolean] True when raw WebSocket frames should be hex-logged.
+    def ws_debug?
+      @ws_debug == true
+    end
+
+    def initialize(attrs = {})
+      @client_id = attrs[:client_id] || ENV.fetch("DHAN_CLIENT_ID", nil)
+      @access_token = attrs[:access_token] || ENV.fetch("DHAN_ACCESS_TOKEN", nil)
+      @access_token_provider = attrs[:access_token_provider]
+      @on_token_expired = attrs[:on_token_expired]
+      @sandbox = attrs.key?(:sandbox) ? attrs[:sandbox] : env_flag("DHAN_SANDBOX", default: false)
+      @dry_run = attrs.key?(:dry_run) ? attrs[:dry_run] : env_flag("DHAN_DRY_RUN", default: false)
+      @retry_non_idempotent_writes = attrs.key?(:retry_non_idempotent_writes) ? attrs[:retry_non_idempotent_writes] : env_flag("DHAN_RETRY_WRITES", default: false)
+      @auto_correlation_id = attrs.key?(:auto_correlation_id) ? attrs[:auto_correlation_id] : env_flag("DHAN_AUTO_CORRELATION_ID", default: false)
+      @warn_on_ambiguous_write_failure = if attrs.key?(:warn_on_ambiguous_write_failure)
+                                           attrs[:warn_on_ambiguous_write_failure]
+                                         else
+                                           env_flag("DHAN_WARN_AMBIGUOUS_WRITE_FAILURE",
+                                                    default: true)
+                                         end
+      @base_url = attrs[:base_url] || ENV.fetch("DHAN_BASE_URL", nil)
+      @ws_version = (attrs[:ws_version] || ENV.fetch("DHAN_WS_VERSION", 2)).to_i
+      @ws_order_url = attrs[:ws_order_url] || ENV.fetch("DHAN_WS_ORDER_URL", nil)
+      @ws_market_feed_url = attrs[:ws_market_feed_url] || ENV.fetch("DHAN_WS_MARKET_FEED_URL", nil)
+      @ws_market_depth_url = attrs[:ws_market_depth_url] || ENV.fetch("DHAN_WS_MARKET_DEPTH_URL", nil)
+      @market_depth_level = (attrs[:market_depth_level] || ENV.fetch("DHAN_MARKET_DEPTH_LEVEL", "20")).to_i
+      @ws_debug = attrs.key?(:ws_debug) ? attrs[:ws_debug] : env_flag("DHAN_WS_DEBUG", default: false)
+      @ws_user_type = attrs[:ws_user_type] || ENV.fetch("DHAN_WS_USER_TYPE", "SELF")
+      @partner_id = attrs[:partner_id] || ENV.fetch("DHAN_PARTNER_ID", nil)
+      @partner_secret = attrs[:partner_secret] || ENV.fetch("DHAN_PARTNER_SECRET", nil)
+      yield(self) if block_given?
     end
 
     private

data/lib/DhanHQ/core/base_api.rb

@@ -17,9 +17,10 @@ module DhanHQ
 
     # Initializes the BaseAPI with the appropriate Client instance
     #
+    # @param client [DhanHQ::Client, nil] Optional injected client instance
     # @param api_type [Symbol] API type (`:order_api`, `:data_api`, `:non_trading_api`)
-    def initialize(api_type: self.class::API_TYPE)
-      @client = DhanHQ::Client.new(api_type: api_type)
+    def initialize(client: nil, api_type: self.class::API_TYPE)
+      @client = client || DhanHQ::Client.new(api_type: api_type)
     end
 
     # Perform a GET request via `Client`

data/lib/DhanHQ/dry_run/simulator.rb

@@ -25,8 +25,9 @@ module DhanHQ
       # Extracts a fabricated id out of a request path.
       ID_PATTERN = /#{Regexp.escape(ID_PREFIX)}[A-Za-z0-9]+/
 
-      def initialize(ledger: Ledger.instance)
+      def initialize(ledger: Ledger.instance, config: nil)
         @ledger = ledger
+        @config = config
       end
 
       # Whether this request should be answered locally.
@@ -35,7 +36,7 @@ module DhanHQ
       # @param path [String, nil] Request path
       # @return [Boolean]
       def simulates?(method, path)
-        return false unless DhanHQ.configuration&.dry_run?
+        return false unless (@config || DhanHQ.configuration)&.dry_run?
 
         WritePaths.mutating?(method, path) || replayable_read?(method, path)
       end

data/lib/DhanHQ/helpers/request_helper.rb

@@ -21,6 +21,16 @@ module DhanHQ
 
     private
 
+    def current_config
+      if respond_to?(:config) && config
+        config
+      elsif respond_to?(:client) && client.respond_to?(:config) && client.config
+        client.config
+      else
+        DhanHQ.configuration
+      end
+    end
+
     # Dynamically builds headers for each request.
     #
     # @param path [String] The API endpoint path.
@@ -41,7 +51,7 @@ module DhanHQ
 
       # Add client-id for DATA APIs (now including sandbox profile/funds)
       if data_api?(path)
-        client_id = DhanHQ.configuration&.client_id
+        client_id = current_config&.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."
@@ -53,7 +63,7 @@ module DhanHQ
     end
 
     def resolved_access_token
-      DhanHQ.configuration&.resolved_access_token
+      current_config&.resolved_access_token
     end
 
     # Determines if the API path requires a `client-id` header.
@@ -80,7 +90,7 @@ module DhanHQ
 
       out = payload
       if path && %i[post put patch].include?(method)
-        client_id = DhanHQ.configuration&.client_id
+        client_id = current_config&.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

data/lib/DhanHQ/jobs/place_order_job.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Jobs
+    # Places a Dhan order via ActiveJob, without ever letting a queue adapter
+    # (Sidekiq, Resque, ...) retry it.
+    #
+    # DhanHQ order writes are not idempotent -- a timed-out POST /v2/orders may
+    # already have reached the exchange, so retrying it can place a duplicate
+    # order (see the README's "Order Retries and Duplicate Protection"). Most
+    # adapters retry unhandled exceptions at the backend level by default
+    # (Sidekiq's own retry, independent of ActiveJob's opt-in `retry_on`), so
+    # the only adapter-agnostic way to guarantee this write is never silently
+    # retried is to make sure the exception never reaches the adapter at all.
+    # `discard_on` does exactly that: it's handled inside ActiveJob's own
+    # `execute`, so from the adapter's point of view the job completed, not
+    # failed -- there is nothing left for the adapter's own retry logic to
+    # act on.
+    #
+    # @example
+    #   DhanHQ::Jobs::PlaceOrderJob.perform_later(
+    #     transaction_type: DhanHQ::Constants::TransactionType::BUY,
+    #     exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+    #     product_type:     DhanHQ::Constants::ProductType::INTRADAY,
+    #     order_type:       DhanHQ::Constants::OrderType::LIMIT,
+    #     validity:         DhanHQ::Constants::Validity::DAY,
+    #     security_id:      "11536",
+    #     quantity:         5,
+    #     price:            1500.0
+    #   )
+    class PlaceOrderJob < ActiveJob::Base
+      discard_on DhanHQ::OrderError do |_job, error|
+        DhanHQ.logger&.error("[DhanHQ::Jobs::PlaceOrderJob] order rejected: #{error.message}")
+      end
+
+      discard_on DhanHQ::RiskViolation do |_job, error|
+        DhanHQ.logger&.warn("[DhanHQ::Jobs::PlaceOrderJob] risk check blocked the order: #{error.message}")
+      end
+
+      # @param params [Hash] Same params accepted by DhanHQ::Models::Order.place.
+      # @return [DhanHQ::Models::Order]
+      def perform(params)
+        DhanHQ::Models::Order.place!(params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/market_feed.rb

@@ -49,7 +49,7 @@ module DhanHQ
       #
       # @return [MarketFeed]
       def quote_resource
-        @quote_resource ||= self.class.new(api_type: :quote_api)
+        @quote_resource ||= self.class.new(client: DhanHQ::Client.new(config: client.config, api_type: :quote_api))
       end
     end
   end

data/lib/DhanHQ/version.rb

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

data/lib/DhanHQ/ws/base_connection.rb

@@ -23,8 +23,9 @@ module DhanHQ
       # @param options [Hash] Connection options
       # @option options [Integer] :max_backoff Maximum backoff time (default: 90)
       # @option options [Integer] :cool_off_429 Cool off time for 429 errors (default: 60)
-      def initialize(url:, **options)
+      def initialize(url:, config: nil, **options)
         @url = url
+        @config = config || DhanHQ.configuration || DhanHQ.ensure_configuration!
         @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
         @started = Concurrent::AtomicBoolean.new(false)
         @stop = false
@@ -212,6 +213,7 @@ module DhanHQ
       # Handle WebSocket message event
       # @param ev [Event] WebSocket message event
       def handle_message(ev)
+        WS.debug_frame(self.class.name, ev.data)
         emit(:raw, ev.data)
         process_message(ev.data) if respond_to?(:process_message, true)
       end

data/lib/DhanHQ/ws/client.rb

@@ -20,7 +20,8 @@ module DhanHQ
     class Client
       # @param mode [Symbol] Feed mode (:ticker, :quote, :full).
       # @param url [String, nil] Optional custom WebSocket endpoint.
-      def initialize(mode: :ticker, url: nil)
+      # @param config [DhanHQ::Configuration, nil] Optional configuration instance.
+      def initialize(mode: :ticker, url: nil, config: nil)
         @mode  = mode # :ticker, :quote, :full (adjust to your API)
         @bus   = CmdBus.new
         @state = SubState.new
@@ -29,13 +30,14 @@ module DhanHQ
         @last_message_at = Concurrent::AtomicReference.new(nil)
         @connected_at = Concurrent::AtomicReference.new(nil)
         @reconnects = Concurrent::AtomicFixnum.new(0)
+        @config = config || DhanHQ.configuration || DhanHQ.ensure_configuration!
 
-        token = DhanHQ.configuration.resolved_access_token
+        token = @config.resolved_access_token
         raise DhanHQ::AuthenticationError, "Missing access token" if token.nil? || token.empty?
 
-        cid   = DhanHQ.configuration.client_id or raise "DhanHQ.client_id not set"
-        ver   = (DhanHQ.configuration.respond_to?(:ws_version) && DhanHQ.configuration.ws_version) || 2
-        base  = url || DhanHQ.configuration.ws_market_feed_url
+        cid   = @config.client_id or raise "DhanHQ.client_id not set"
+        ver   = (@config.respond_to?(:ws_version) && @config.ws_version) || 2
+        base  = url || @config.ws_market_feed_url
         @url  = base.include?("?") ? base : "#{base}?version=#{ver}&token=#{token}&clientId=#{cid}&authType=2"
       end
 

data/lib/DhanHQ/ws/connection.rb

@@ -141,6 +141,7 @@ module DhanHQ
               @ws.on(:open) { |_| handle_open(sessions) }
 
               @ws.on :message do |ev|
+                WS.debug_frame(self.class.name, ev.data)
                 notify(:message, nil)
                 @on_binary&.call(ev.data) # raw frames to decoder
               end

data/lib/DhanHQ/ws/market_depth/client.rb

@@ -19,11 +19,12 @@ module DhanHQ
         ##
         # Initialize Market Depth WebSocket client
         # @param symbols [Array<String, Hash>] List of symbols (or metadata hashes) to subscribe to
+        # @param config [DhanHQ::Configuration, nil] Optional configuration instance
         # @param options [Hash] Connection options
-        def initialize(symbols: [], **options)
-          cfg = DhanHQ.configuration
+        def initialize(symbols: [], config: nil, **options)
+          cfg = config || DhanHQ.configuration || DhanHQ.ensure_configuration!
           url = options[:url] || build_market_depth_url(cfg)
-          super(url: url, **options)
+          super(url: url, config: cfg, **options)
 
           @symbols = Array(symbols)
           @subscriptions = Concurrent::Map.new

data/lib/DhanHQ/ws/orders/client.rb

@@ -16,15 +16,15 @@ module DhanHQ
         # Maximum age of orders in tracker in seconds (default: 7 days)
         MAX_ORDER_AGE = ENV.fetch("DHAN_WS_MAX_ORDER_AGE", 604_800).to_i
 
-        def initialize(url: nil, **options)
+        def initialize(url: nil, config: nil, **options)
           @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
           @started = Concurrent::AtomicBoolean.new(false)
           @order_tracker = Concurrent::Map.new
           @order_timestamps = Concurrent::Map.new
           @cleanup_mutex = Mutex.new
           @cleanup_thread = nil
-          cfg = DhanHQ.configuration
-          @url = url || cfg.ws_order_url
+          @config = config || DhanHQ.configuration || DhanHQ.ensure_configuration!
+          @url = url || @config.ws_order_url
           @connection_options = options
         end
 
@@ -35,7 +35,7 @@ module DhanHQ
           return self if @started.true?
 
           @started.make_true
-          @conn = Connection.new(url: @url, **@connection_options)
+          @conn = Connection.new(url: @url, config: @config, **@connection_options)
           @conn.on(:open) { emit(:open, true) }
           @conn.on(:close) { |payload| emit(:close, payload) }
           @conn.on(:error) { |error| emit(:error, error) }

data/lib/DhanHQ/ws/orders/connection.rb

@@ -63,6 +63,7 @@ module DhanHQ
         # Process incoming WebSocket message
         # @param ev [Event] WebSocket message event
         def handle_message(ev)
+          WS.debug_frame(self.class.name, ev.data)
           msg = JSON.parse(ev.data, symbolize_names: true)
           emit(:raw, msg)
           emit(:message, msg)
@@ -77,7 +78,7 @@ module DhanHQ
         ##
         # Authenticate with DhanHQ Orders WebSocket
         def authenticate
-          cfg = DhanHQ.configuration
+          cfg = @config || DhanHQ.configuration
 
           if cfg.ws_user_type.to_s.upcase == "PARTNER"
             payload = {

data/lib/DhanHQ/ws.rb

@@ -34,5 +34,30 @@ module DhanHQ
     def self.disconnect_all_local!
       Registry.stop_all
     end
+
+    # Cap on how many bytes of a frame get hex-dumped by {debug_frame}. A full
+    # depth packet can run several KB; at tick frequency that floods the log
+    # long before it adds diagnostic value beyond the first couple hundred
+    # bytes (header + the first few fields is normally enough to spot a
+    # parsing bug). The full frame size is always logged regardless of the cap.
+    DEBUG_FRAME_MAX_BYTES = 256
+
+    # Logs a raw inbound WebSocket frame as a hex dump when
+    # +config.ws_debug+ (+DHAN_WS_DEBUG=true+) is enabled. A no-op otherwise --
+    # the flag is checked before any hex encoding work, so there's no cost
+    # when debug logging is off. Frames longer than {DEBUG_FRAME_MAX_BYTES}
+    # are truncated in the dump, but the logged byte count is always the full
+    # frame size.
+    #
+    # @param source [String] short tag identifying which connection the frame came from
+    # @param data [String] raw frame bytes
+    # @return [void]
+    def self.debug_frame(source, data)
+      return unless DhanHQ.configuration&.ws_debug?
+
+      hex = data.byteslice(0, DEBUG_FRAME_MAX_BYTES).unpack1("H*")
+      hex += "...truncated" if data.bytesize > DEBUG_FRAME_MAX_BYTES
+      DhanHQ.logger&.debug("[DhanHQ::WS::#{source}] frame (#{data.bytesize} bytes): #{hex}")
+    end
   end
 end