DhanHQ 3.4.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d97f7473f5bb7c4968750c3e21e5721a9c9ba1261e6e00d450818613edb74ec
-  data.tar.gz: 49464e4909ac0f52947fc86735b6b43bef6877f8ba0a1f796eb3b1c58c60bfde
+  metadata.gz: 8c2f0784210b7f48ccb056b8cc486ce5c3ef655f69a4bd2834a150b1d04a8bc7
+  data.tar.gz: a6628fc83e8ec61bd4ca4b0eb6147a67232156f98ab49196c0a81850f9b4ac59
 SHA512:
-  metadata.gz: 5a70be1d7aa2af222df63e8188af1b60e110431d73ae36317244693d974e46a3fcb84a9a49d9276fbadeea105c1124753129aa1c057d089924f0b71c7075f481
-  data.tar.gz: cb8a910ad46ae08b570eb9b19ac3a553de9a050e1b2a409d1414f3eb18d7eb762cb2fc62d6f2a5a72ad9014f726a1195541fa29ea80d749ba4c1dc21d6b0903f
+  metadata.gz: d0a4147017f7722d9a74cec3105fb57e9b8710142abda6c04d5948caa7500b21ce8c31958cc501e99643a31afffe5e64846b5a73ff239f1a8fb87074e57a6856
+  data.tar.gz: 508f55621273349e9060e941cc9bf8b7cef7fb28befb8026b57b977ba0954760f783eb5dbb26c19593ac113232c12fa74884fcd57a81b61dd21dbc3d66c7b9e9

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## [4.0.0] - 2026-08-31
+
+### Added
+
+- **Multi-Instance Client Isolation (`DhanHQ::Client.new`)** — run multiple isolated client instances in the same process with separate configurations, credentials, sandbox environments, and rate limiters. Ideal for multi-tenant applications, managing multiple trading accounts concurrently, or comparing sandbox vs. production environments side-by-side.
+  ```ruby
+  client_a = DhanHQ::Client.new(client_id: "ACC_A", access_token: "TOKEN_A")
+  client_b = DhanHQ::Client.new(client_id: "ACC_B", access_token: "TOKEN_B", sandbox: true)
+
+  orders_a = client_a.orders.all
+  orders_b = client_b.orders.all
+  ```
+- **Instance-bound Resource Accessors** — direct accessors on `DhanHQ::Client` instances (`client.orders`, `client.positions`, `client.holdings`, `client.funds`, `client.trades`, `client.market_feed`, `client.option_chain`, `client.historical_data`, `client.forever_orders`, `client.alert_orders`, `client.iceberg_orders`, `client.super_orders`, `client.twap_orders`, `client.statements`, `client.kill_switch`, `client.pnl_exit`, `client.trader_control`, `client.ip_setup`, `client.edis`) bound to that client's configuration and routed to matching rate-limiting tiers (`client_for(API_TYPE)`).
+- **Instance-bound WebSocket Helpers** — `client.ws_market_feed`, `client.ws_order_update`, and `client.ws_market_depth` configured automatically with the client instance's credentials and URLs.
+- **Keyword Argument Initialization** — `DhanHQ::Client.new` accepts keyword configuration parameters (`dry_run: true`, `sandbox: true`, `client_id: "..."`, `access_token: "..."`) or a `Configuration` instance.
+- **Per-Instance Dry-Run Mode** — `DhanHQ::Client.new(dry_run: true)` simulates state-changing writes locally for that instance regardless of the global configuration.
+- **Dynamic Model Resource Invalidation** — `DhanHQ.reset_model_resources!` automatically refreshes class-level model caches (`Models::Order.resource`, etc.) whenever `DhanHQ.configure`, `configure_with_env`, `configuration=`, or `reset_configuration!` is invoked.
+- **Per-Client Auto Token Management** — `client.enable_auto_token_management!(dhan_client_id: ..., pin: ..., totp_secret: ...)` for automated TOTP-based token lifecycle management per client instance.
+
 ## [3.4.0] - 2026-08-15
 
 ### Added
@@ -19,7 +38,9 @@
 ### Fixed
 
 - **`docs/RAILS_INTEGRATION.md`'s Sidekiq examples (§5, §6) called `client.wait!`, `client.subscribe(array)`, and `DhanHQ::WS::Client.new(kind: :order_updates)`** — none of which exist. `DhanHQ::WS::Client`/`DhanHQ::WS::Orders::Client` have no blocking wait method at all; `Client#start` spawns a background thread and returns immediately. Replaced with the real API (`DhanHQ::WS.connect`/`DhanHQ::WS::Orders.connect` plus a `connected?`-based liveness loop), guarded by a new spec that locks down the method names these examples call by name.
-- **`dry-validation` had no version floor in the gemspec.** A fresh `bundle install` could resolve it to `0.4.1` — a 2016-era, pre-`Dry::Validation::Contract` API generation every contract in `lib/DhanHQ/contracts/` is incompatible with. Pinned to `~> 1.11`. Found while investigating whether the Ruby floor could drop to 3.1 (it can't — see below); confirmed by forcing an actual fresh resolve under Ruby 3.1.6, which hit exactly this.
+- **Every runtime dependency except `faraday` had no version floor at all** (`add_dependency "x"`, equivalent to `>= 0` — satisfied by any version ever published). Found while investigating whether the Ruby floor could drop to 3.1 (it can't — see below): forcing a fresh `bundle install` under Ruby 3.1.6 resolved `dry-validation` to `0.4.1`, a 2016-era, pre-`Dry::Validation::Contract` API generation every contract in `lib/DhanHQ/contracts/` is incompatible with — every contract spec failed at `require`-time. Pinning that alone wasn't enough: with `dry-validation` fixed, the same fresh resolve then pulled `activesupport` down to `7.2.3.2` (ActiveSupport 8.x itself requires Ruby ≥ 3.2), and AS 7-vs-8 behavioral differences broke `Agent::ToolRegistry`, `MCP::Server`, and `Risk::Pipeline` — 63 failures with no connection to Ruby version syntax at all.
+
+  All ten now have an explicit floor matching their currently locked major (`activesupport >= 8.0`, `dry-validation ~> 1.0`, and so on) — closing the class of bug, not just the two instances that happened to surface. The `dry-validation` constraint went through two attempts: the first pass in this same release pinned it to `~> 1.11`, which — because `~>` locks to the *last* segment given — actually meant `>= 1.11, < 1.12` and would have silently blocked every future 1.12+ release. Corrected to `~> 1.0`, which excludes the ancient `0.x` line (the actual problem) without capping legitimate 1.x updates.
 - **`spec/dhan_hq/contracts/expired_options_data_contract_spec.rb` and `expired_options_data_spec.rb` hardcoded `from_date: "2021-08-02"`**, which is itself now more than 5 years in the past and so failed the contract's own "cannot be more than 5 years ago" rule — the shared fixture failed the exact rule it existed to exercise, cascading into every test merged onto it. Replaced every literal 2021 date with one computed relative to `Date.today`, preserving each test's original intent (span length, ordering, the exact-31-day boundary).
 
 ### Investigated, not changed

data/GUIDE.md

@@ -77,6 +77,22 @@ For token rotation without restarting the app, set `access_token_provider` (Proc
 
 See [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) and README “Dynamic access token”.
 
+**Multi-instance clients (multi-account support)**
+
+When you need to trade across multiple accounts, run multi-tenant setups, or isolate sandbox/testing environments in a single process, use `DhanHQ::Client.new`:
+
+```ruby
+# Account 1
+client1 = DhanHQ::Client.new(client_id: "ACC_1", access_token: "TOKEN_1")
+
+# Account 2 (Sandbox)
+client2 = DhanHQ::Client.new(client_id: "ACC_2", access_token: "TOKEN_2", sandbox: true)
+
+# Resource accessors directly bound to client instance:
+orders1 = client1.orders.all
+orders2 = client2.orders.all
+```
+
 ---
 
 ## Working With Models

data/README.md

@@ -218,6 +218,34 @@ end
 
 When the API returns 401, the client retries **once** with a fresh token from your provider.
 
+### Multi-Instance Clients (Multi-Account / Multi-Tenant)
+
+For multi-tenant applications, managing multiple trading accounts concurrently, or isolating sandbox from production within the same process, construct explicit `DhanHQ::Client` instances:
+
+```ruby
+# Account 1 (Live Trading)
+client1 = DhanHQ::Client.new(
+  client_id: "ACC_1_ID",
+  access_token: "ACC_1_TOKEN"
+)
+
+# Account 2 (Sandbox / Testing)
+client2 = DhanHQ::Client.new(
+  client_id: "ACC_2_ID",
+  access_token: "ACC_2_TOKEN",
+  sandbox: true,
+  dry_run: true
+)
+
+# Resource accessors are bound to the client instance:
+positions = client1.positions.all
+orders    = client2.orders.all
+
+# Instance-bound WebSocket streams:
+ws_stream = client1.ws_market_feed(mode: :ticker) { |tick| puts tick[:ltp] }
+ws_orders = client1.ws_order_update
+```
+
 > **Full details**: TOTP flows, partner mode, token endpoint bootstrap, auto-management — see [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md).
 
 ---

data/docs/CONFIGURATION.md

@@ -106,6 +106,31 @@ end
 - **`access_token_provider`**: Callable (Proc/lambda) returning the token string. Called on every request (no memoization). When set, the gem uses it instead of `access_token`.
 - **`on_token_expired`**: Optional callable invoked when a 401/token-expired triggers a **single retry** (only when `access_token_provider` is set).
 
+## Multi-Instance Client Configuration
+
+For multi-account or multi-tenant architectures, construct explicit `DhanHQ::Client` instances without depending on global singleton state:
+
+```ruby
+# Direct configuration via keyword arguments
+client = DhanHQ::Client.new(
+  client_id: "YOUR_CLIENT_ID",
+  access_token: "YOUR_ACCESS_TOKEN",
+  sandbox: false,
+  dry_run: false
+)
+
+# Or via an explicit Configuration object
+custom_config = DhanHQ::Configuration.new do |c|
+  c.client_id = "TENANT_CLIENT_ID"
+  c.access_token = "TENANT_ACCESS_TOKEN"
+  c.dry_run = true
+end
+
+client = DhanHQ::Client.new(config: custom_config)
+```
+
+Each client instance manages its own Faraday connection, isolated configuration, dry-run state, and instance-bound resource accessors (`client.orders`, `client.positions`, `client.market_feed`, etc.).
+
 For detailed authentication flows, see [AUTHENTICATION.md](AUTHENTICATION.md).
 
 ## Available Resources

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

@@ -212,30 +212,32 @@ module DhanHQ
       @ws_debug == 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_debug       = env_flag("DHAN_WS_DEBUG", default: false)
-      @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)
+    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/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.4.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

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/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

@@ -78,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/dhan_hq.rb

@@ -3,7 +3,11 @@
 require "json"
 require "logger"
 require "zeitwerk"
-require "dotenv/load"
+begin
+  require "dotenv/load"
+rescue LoadError
+  # Dotenv is optional in host applications
+end
 require "faraday"
 # Minimal eager requires for backward-compatible constants.
 # These are widely referenced (e.g. `DhanHQ::BaseAPI`) and should not depend on
@@ -88,9 +92,13 @@ module DhanHQ
     # @return [String]
     BASE_URL = Constants::Urls::REST_API_BASE
     # The current configuration instance.
-    #
-    # @return [DhanHQ::Configuration, nil] The current configuration or `nil` if not set.
-    attr_accessor :configuration
+    attr_reader :configuration
+
+    def configuration=(config)
+      @configuration = config
+      @default_client = nil
+      reset_model_resources!
+    end
 
     attr_writer :logger
 
@@ -106,8 +114,10 @@ module DhanHQ
     # @return [void]
     def configure
       self.configuration ||= Configuration.new
-      yield(configuration)
+      yield(configuration) if block_given?
       self.logger ||= Logger.new($stdout, level: Logger::INFO)
+      @default_client = Client.new(config: configuration)
+      reset_model_resources!
     end
 
     # default logger so calls like DhanHQ.logger&.info never explode
@@ -118,6 +128,18 @@ module DhanHQ
       @logger ||= Logger.new($stdout, level: Logger::INFO)
     end
 
+    # Global default client (used for backward compatibility with class-level APIs)
+    #
+    # @return [DhanHQ::Client]
+    def default_client
+      @default_client ||= Client.new(config: ensure_configuration!)
+    end
+
+    # Resets the global default client
+    def reset_default_client!
+      @default_client = nil
+    end
+
     # Configures the DhanHQ client using environment variables.
     #
     # When credentials are injected via `DHAN_ACCESS_TOKEN` and `DHAN_CLIENT_ID` this helper
@@ -129,6 +151,8 @@ module DhanHQ
     # @return [void]
     def configure_with_env
       self.configuration = Configuration.new
+      @default_client = Client.new(config: configuration)
+      reset_model_resources!
     end
 
     # Ensures configuration exists, bootstrapping from ENV when nil.
@@ -140,9 +164,32 @@ module DhanHQ
       self.configuration ||= Configuration.new
     end
 
-    # Resets the configuration to nil.
+    # Resets the configuration and default client to nil.
     def reset_configuration!
       self.configuration = nil
+      @default_client = nil
+      reset_model_resources!
+    end
+
+    # Clears memoized class-level resource and API instances across all models.
+    def reset_model_resources!
+      models = [
+        BaseModel,
+        Models::Order, Models::Holding, Models::Position, Models::HistoricalData,
+        Models::Trade, Models::OptionChain, Models::Funds, Models::AlertOrder,
+        Models::ForeverOrder, Models::IcebergOrder, Models::SuperOrder, Models::TwapOrder,
+        Models::LedgerEntry, Models::Instrument, Models::Edis, Models::Profile,
+        Models::Margin, Models::MultiOrder, Models::KillSwitch, Models::PnlExit,
+        Models::MarketFeed, Models::ExpiredOptionsData
+      ]
+
+      models.each do |klass|
+        next unless klass.is_a?(Class)
+
+        klass.instance_variables.each do |var|
+          klass.instance_variable_set(var, nil) if var.to_s.end_with?("resource", "api")
+        end
+      end
     end
 
     # Configures the DhanHQ client by fetching credentials from a token endpoint.
@@ -164,39 +211,14 @@ module DhanHQ
     def configure_from_token_endpoint(base_url: nil, bearer_token: nil)
       base_url ||= ENV.fetch("DHAN_TOKEN_ENDPOINT_BASE_URL", nil)
       bearer_token ||= ENV.fetch("DHAN_TOKEN_ENDPOINT_BEARER", nil)
-
       raise DhanHQ::TokenEndpointError, "base_url and bearer_token (or ENV DHAN_TOKEN_ENDPOINT_*) are required" if base_url.to_s.empty? || bearer_token.to_s.empty?
 
-      url = "#{base_url.to_s.chomp("/")}/auth/dhan/token"
-      conn = ::Faraday.new(url: url) do |c|
-        c.request :url_encoded
-        c.adapter ::Faraday.default_adapter
-      end
-
-      response = conn.get("") do |req|
-        req.headers["Authorization"] = "Bearer #{bearer_token}"
-        req.headers["Accept"] = "application/json"
-      end
-
-      unless response.success?
-        body = parse_json_body(response.body)
-        msg = body["error"] || body["message"] || body["errorMessage"] || response.body.to_s
-        raise DhanHQ::TokenEndpointError, "Token endpoint returned #{response.status}: #{msg}"
-      end
-
-      data = parse_json_body(response.body)
-      data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-
-      access_token = data["access_token"] || data[:access_token]
-      client_id = data["client_id"] || data[:client_id]
+      data = fetch_token_endpoint("#{base_url.to_s.chomp("/")}/auth/dhan/token", bearer_token, "Token endpoint")
+      access_token = data["access_token"]
+      client_id = data["client_id"]
       raise DhanHQ::TokenEndpointError, "Token endpoint response missing access_token or client_id" if access_token.to_s.empty? || client_id.to_s.empty?
 
-      self.configuration ||= Configuration.new
-      configuration.access_token = access_token.to_s
-      configuration.client_id = client_id.to_s
-      dhan_base = data["base_url"] || data[:base_url]
-      configuration.base_url = dhan_base.to_s if dhan_base.to_s != ""
-      configuration
+      apply_token_config(access_token, client_id, data["base_url"])
     end
 
     # Configures the DhanHQ client by fetching credentials from a dashboard API.
@@ -208,6 +230,18 @@ module DhanHQ
     def configure_from_dashboard(bearer_token:, url: "http://localhost:3011/api/dhan_access_token")
       raise DhanHQ::TokenEndpointError, "bearer_token is required" if bearer_token.to_s.empty?
 
+      data = fetch_token_endpoint(url, bearer_token, "Dashboard")
+      access_token = data["access_token"] || data["accessToken"] || data["dhan_access_token"] || data["dhanaccesstoken"]
+      client_id = data["client_id"] || data["clientId"] || data["dhan_client_id"] || data["dhanClientId"]
+      client_id ||= configuration&.client_id || ENV.fetch("DHAN_CLIENT_ID", nil)
+
+      raise DhanHQ::TokenEndpointError, "Dashboard response missing access_token (tried access_token, dhan_access_token, dhanaccesstoken)" if access_token.to_s.empty?
+      raise DhanHQ::TokenEndpointError, "Dashboard response missing client_id, and no fallback client_id was found in config or ENV['DHAN_CLIENT_ID']" if client_id.to_s.empty?
+
+      apply_token_config(access_token, client_id, data["base_url"] || data["baseUrl"])
+    end
+
+    def fetch_token_endpoint(url, bearer_token, label)
       conn = ::Faraday.new(url: url) do |c|
         c.request :url_encoded
         c.adapter ::Faraday.default_adapter
@@ -221,24 +255,18 @@ module DhanHQ
       unless response.success?
         body = parse_json_body(response.body)
         msg = body["error"] || body["message"] || body["errorMessage"] || response.body.to_s
-        raise DhanHQ::TokenEndpointError, "Dashboard returned #{response.status}: #{msg}"
+        raise DhanHQ::TokenEndpointError, "#{label} returned #{response.status}: #{msg}"
       end
 
       data = parse_json_body(response.body)
-      data = data.transform_keys(&:to_s) if data.is_a?(Hash)
-
-      access_token = data["access_token"] || data["accessToken"] || data["dhan_access_token"] || data["dhanaccesstoken"]
-      client_id = data["client_id"] || data["clientId"] || data["dhan_client_id"] || data["dhanClientId"]
-      client_id ||= self.configuration&.client_id || ENV.fetch("DHAN_CLIENT_ID", nil)
-
-      raise DhanHQ::TokenEndpointError, "Dashboard response missing access_token (tried access_token, dhan_access_token, dhanaccesstoken)" if access_token.to_s.empty?
-      raise DhanHQ::TokenEndpointError, "Dashboard response missing client_id, and no fallback client_id was found in config or ENV['DHAN_CLIENT_ID']" if client_id.to_s.empty?
+      data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+    end
 
+    def apply_token_config(access_token, client_id, base_url)
       self.configuration ||= Configuration.new
       configuration.access_token = access_token.to_s
       configuration.client_id = client_id.to_s
-      dhan_base = data["base_url"] || data["baseUrl"]
-      configuration.base_url = dhan_base.to_s if dhan_base.to_s != ""
+      configuration.base_url = base_url.to_s if base_url.to_s != ""
       configuration
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Shubham Taywade
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-15 00:00:00.000000000 Z
+date: 2026-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -16,98 +16,98 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: base64
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: bindata
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: dry-validation
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: eventmachine
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -128,42 +128,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.11'
 - !ruby/object:Gem::Dependency
   name: rotp
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.6'
 description: A production-grade Ruby SDK and Ruby client for Dhan API v2 built for
   algorithmic trading, portfolio monitoring, and live trading systems on NSE, BSE
   and MCX. Provides typed models, token lifecycle management, dry-validation contracts,