DhanHQ 4.0.0 → 4.1.0

data/lib/DhanHQ/rate_limiter.rb

@@ -5,11 +5,20 @@ require "concurrent"
 module DhanHQ
   # Coarse-grained in-memory throttler matching the platform rate limits.
   class RateLimiter
-    # Per-interval thresholds keyed by API type, matching the published
-    # DhanHQ rate-limit table (Order APIs: 10/sec, 100,000/day;
-    # Data APIs: 5/sec, 7,000/day; Market Quote: 1/sec; Option Chain: 1 per 3 sec).
+    # Per-interval thresholds keyed by API type.
+    #
+    # Values are deliberately conservative client-side budgets: they follow this
+    # repo's own documented operational limits (docs/DATA_API_PARAMETERS.md — market
+    # feed 1/s, option chain 1 per 3s; skills/dhanhq-ruby/references/option-chain.md),
+    # NOT the platform's published table, so the SDK stays well inside whatever
+    # per-account enforcement the broker applies. Per-minute caps are not enforced
+    # yet (all per_minute values are infinite except option chain); see the 4.1.0
+    # review notes for the open question.
+    # Global Stocks shares the order-API limits on its own tier so it can be
+    # routed independently (it always stays on the production host).
     RATE_LIMITS = {
       order_api: { per_second: 10, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: 100_000 },
+      global_stocks_api: { per_second: 10, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: 100_000 },
       data_api: { per_second: 5, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: 7_000 },
       quote_api: { per_second: 1, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: Float::INFINITY },
       option_chain: { per_second: 1.0 / 3, per_minute: 20, per_hour: 600, per_day: 4800 },
@@ -17,6 +26,9 @@ module DhanHQ
                          per_day: Float::INFINITY }
     }.freeze
 
+    # Seconds to wait between counter resets, per interval.
+    RESET_INTERVALS = { per_minute: 60, per_hour: 3600, per_day: 86_400 }.freeze
+
     # Thread-safe shared rate limiters per API type
     @shared_limiters = Concurrent::Map.new
     @mutexes = Concurrent::Map.new
@@ -56,9 +68,7 @@ module DhanHQ
 
           sleep_time = 3 - (Time.now - last_request_time)
           if sleep_time.positive?
-            if ENV["DHAN_DEBUG"] == "true"
-              puts "Sleeping for #{sleep_time.round(2)} seconds due to option_chain rate limit"
-            end
+            DhanHQ.logger&.debug("[DhanHQ::RateLimiter] Sleeping #{sleep_time.round(2)}s (option_chain limit)")
             sleep(sleep_time)
           end
 
@@ -101,6 +111,9 @@ module DhanHQ
       end
     end
 
+    # NOTE: @request_times is only touched inside #throttle!, which holds the
+    # per-tier mutex, so the plain Array needs no synchronization of its own.
+
     private
 
     # Gets or creates a mutex for this API type for thread-safe throttling
@@ -140,47 +153,28 @@ module DhanHQ
       end
     end
 
-    # Spawns background threads to reset counters after each interval elapses.
+    # Spawns one reset thread per interval whose limit is finite. Intervals whose
+    # limit is Float::INFINITY never block, so resetting them is a no-op and no
+    # thread is created (quote and non-trading tiers end up with zero threads).
+    # Threads die with the process; #shutdown exists for explicit teardown.
     def start_cleanup_threads
       @cleanup_threads = []
       @shutdown = Concurrent::AtomicBoolean.new(false)
 
-      # Don't create per_second cleanup thread - we handle it with timestamps
-      @cleanup_threads << Thread.new do
-        loop do
-          break if @shutdown.true?
-
-          sleep(60)
-          break if @shutdown.true?
+      RESET_INTERVALS.each do |interval, seconds|
+        limit = RATE_LIMITS[@api_type][interval]
+        next if limit.nil? || limit >= Float::INFINITY
 
-          mutex.synchronize do
-            @buckets[:per_minute]&.value = 0
-          end
-        end
-      end
+        @cleanup_threads << Thread.new do
+          loop do
+            break if @shutdown.true?
 
-      @cleanup_threads << Thread.new do
-        loop do
-          break if @shutdown.true?
+            sleep(seconds)
+            break if @shutdown.true?
 
-          sleep(3600)
-          break if @shutdown.true?
-
-          mutex.synchronize do
-            @buckets[:per_hour]&.value = 0
-          end
-        end
-      end
-
-      @cleanup_threads << Thread.new do
-        loop do
-          break if @shutdown.true?
-
-          sleep(86_400)
-          break if @shutdown.true?
-
-          mutex.synchronize do
-            @buckets[:per_day]&.value = 0
+            mutex.synchronize do
+              @buckets[interval]&.value = 0
+            end
           end
         end
       end

data/lib/DhanHQ/resources/global_stocks/funds.rb

@@ -10,7 +10,7 @@ module DhanHQ
       # Global Stocks funds are held in USD and are reported separately from the
       # domestic INR fund limit exposed by {DhanHQ::Resources::Funds}.
       class Funds < BaseAPI
-        API_TYPE = :order_api
+        API_TYPE = :global_stocks_api
         HTTP_PATH = "/v2/globalstocks/fundlimit"
 
         # Retrieves the authenticated user's US stock fund limit details.

data/lib/DhanHQ/resources/global_stocks/holdings.rb

@@ -7,7 +7,7 @@ module DhanHQ
       #
       #   GET /v2/globalstocks/holdings
       class Holdings < BaseAPI
-        API_TYPE = :order_api
+        API_TYPE = :global_stocks_api
         HTTP_PATH = "/v2/globalstocks/holdings"
 
         # Retrieves the authenticated user's US stock holdings.

data/lib/DhanHQ/resources/global_stocks/margin_calculator.rb

@@ -11,7 +11,7 @@ module DhanHQ
       # Both endpoints take the same request body. The API documents +price+ and
       # +quantity+ as strings, so numeric input is stringified before sending.
       class MarginCalculator < BaseAPI
-        API_TYPE = :non_trading_api
+        API_TYPE = :global_stocks_api
         HTTP_PATH = "/v2/globalstocks"
 
         # Calculates the margin required for a Global Stocks order.

data/lib/DhanHQ/resources/global_stocks/market_status.rb

@@ -7,7 +7,7 @@ module DhanHQ
       #
       #   GET /v2/globalstocks/marketstatus
       class MarketStatus < BaseAPI
-        API_TYPE = :non_trading_api
+        API_TYPE = :global_stocks_api
         HTTP_PATH = "/v2/globalstocks/marketstatus"
 
         # Retrieves the current US market status and session timings.

data/lib/DhanHQ/resources/global_stocks/orders.rb

@@ -26,7 +26,7 @@ module DhanHQ
       class Orders < BaseAPI
         include DhanHQ::Concerns::OrderAudit
 
-        API_TYPE = :order_api
+        API_TYPE = :global_stocks_api
         HTTP_PATH = "/v2/globalstocks/orders"
 
         # Places a new Global Stocks order.

data/lib/DhanHQ/resources/global_stocks/trades.rb

@@ -8,7 +8,7 @@ module DhanHQ
       #   GET /v2/globalstocks/trades
       #   GET /v2/globalstocks/trades/{security-id}
       class Trades < BaseAPI
-        API_TYPE = :order_api
+        API_TYPE = :global_stocks_api
         HTTP_PATH = "/v2/globalstocks/trades"
 
         # Retrieves the current trading day's executed Global Stocks trades.

data/lib/DhanHQ/resources/scanx.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    ##
+    # Resource for the ScanX data API endpoints (POST /v2/data/*).
+    #
+    # Covers company fundamentals, market movers, live news headlines and
+    # server-side technical indicators. These are market-data endpoints, so in
+    # hybrid mode they keep hitting the production host.
+    class ScanX < BaseAPI
+      # ScanX requests hit the data API tier (5 req/sec, 7,000/day).
+      API_TYPE = :data_api
+      # Root path for the ScanX data endpoints.
+      HTTP_PATH = "/v2/data"
+
+      ##
+      # POST /v2/data/companyinfo
+      # Company overview, valuation/profitability ratios and shareholding
+      # pattern for a single equity instrument.
+      #
+      # @param params [Hash] Example:
+      #   {
+      #     security_id: "1333",
+      #     exchange_segment: "NSE_EQ",
+      #     instrument: "EQUITY",
+      #     metrics: ["CO", "RATIOS", "SHP"]
+      #   }
+      # @return [HashWithIndifferentAccess]
+      def company_info(params)
+        validate_with!(Contracts::CompanyInfoContract, params)
+        post("/companyinfo", params: params)
+      end
+
+      ##
+      # POST /v2/data/marketmovers
+      # Top options, futures and stocks ranked by open interest, volume or
+      # price movement.
+      #
+      # @param params [Hash] Example:
+      #   {
+      #     exchange_segment: "NSE_FNO",
+      #     instrument: ["OPTIDX", "OPTSTK"],
+      #     category: "HIGHEST_OI",
+      #     expiry: "2026-10-29",
+      #     limit: 10
+      #   }
+      #   For EQUITY rankings pass +universe:+ (e.g. "NIFTY_50") instead of expiry.
+      # @return [HashWithIndifferentAccess]
+      def market_movers(params)
+        validate_with!(Contracts::MarketMoversContract, params)
+        post("/marketmovers", params: params)
+      end
+
+      ##
+      # POST /v2/data/newsheadline
+      # Latest news headlines, filterable by category and stock (max 50 items).
+      # +dhanClientId+ is injected automatically from the configuration.
+      #
+      # @param params [Hash] Example:
+      #   { categories: ["ALL"], limit: 10, stock_list: ["1333"] }
+      # @return [HashWithIndifferentAccess]
+      def news_headlines(params)
+        validate_with!(Contracts::NewsHeadlineContract, params)
+        post("/newsheadline", params: params)
+      end
+
+      ##
+      # POST /v2/data/technical
+      # Server-side technical indicator values for an instrument. Only the
+      # requested indicators are computed and returned.
+      #
+      # @param params [Hash] Example:
+      #   {
+      #     security_id: "1333",
+      #     exchange_segment: "NSE_EQ",
+      #     instrument: "EQUITY",
+      #     timeframe: "D",
+      #     indicators: ["SMA_20", "RSI_14", "MACD_HIST"]
+      #   }
+      # @return [HashWithIndifferentAccess]
+      def technical_data(params)
+        validate_with!(Contracts::TechnicalDataContract, params)
+        post("/technical", params: params)
+      end
+
+      private
+
+      # Runs the given contract and raises DhanHQ::ValidationError on failure.
+      def validate_with!(contract_class, params)
+        result = contract_class.new.call(snake_case(params))
+        return if result.success?
+
+        raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}"
+      end
+    end
+  end
+end

data/lib/DhanHQ/version.rb

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

data/lib/DhanHQ/ws/client.rb

@@ -35,8 +35,10 @@ module DhanHQ
         token = @config.resolved_access_token
         raise DhanHQ::AuthenticationError, "Missing access token" if token.nil? || token.empty?
 
-        cid   = @config.client_id or raise "DhanHQ.client_id not set"
-        ver   = (@config.respond_to?(:ws_version) && @config.ws_version) || 2
+        cid = @config.client_id
+        raise DhanHQ::AuthenticationError, "client_id is not set (configure DhanHQ.client_id)" if cid.nil? || cid.to_s.empty?
+
+        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
@@ -54,7 +56,7 @@ module DhanHQ
           emit(:tick, tick) if tick
         end
         Registry.register(self)
-        install_at_exit_once!
+        self.class.install_at_exit_hook!
         @conn.start
         self
       end
@@ -295,13 +297,6 @@ module DhanHQ
       rescue StandardError => e
         DhanHQ.logger&.error("[DhanHQ::WS::Client] Error in event handler for #{event}: #{e.class} #{e.message}")
       end
-
-      def install_at_exit_once!
-        return if defined?(@at_exit_installed) && @at_exit_installed
-
-        @at_exit_installed = true
-        at_exit { Registry.stop_all }
-      end
     end
   end
 end

data/lib/DhanHQ/ws/connection.rb

@@ -9,9 +9,14 @@ module DhanHQ
     # Low-level wrapper responsible for establishing and maintaining the raw
     # WebSocket connection to the streaming API.
     class Connection
-      SUB_CODES   = { ticker: 15, quote: 15, full: 15 }.freeze # All use RequestCode 15 per official API
-      # Request codes used when unsubscribing from feeds.
-      UNSUB_CODES = { ticker: 12, quote: 12, full: 12 }.freeze # Use disconnect code 12 for unsubscribe
+      # Feed request codes per the official Annexure "Feed Request Code" table
+      # (dhanhq.co/docs/v2/annexure#feed-request-code): 15/16 ticker, 17/18 quote,
+      # 21/22 full. RequestCode 12 is the whole-connection Disconnect Feed frame
+      # and is reserved for #send_disconnect.
+      SUB_CODES   = { ticker: 15, quote: 17, full: 21 }.freeze
+      # Unsubscribe codes per the same table: 16/18/22. Never 12 — that is the
+      # whole-connection disconnect, not a per-instrument unsubscribe.
+      UNSUB_CODES = { ticker: 16, quote: 18, full: 22 }.freeze
 
       COOL_OFF_429 = 60  # seconds to cool off on 429
       MAX_BACKOFF  = 90  # cap exponential backoff
@@ -219,7 +224,7 @@ module DhanHQ
         subs, unsubs = cmds.partition { |c| c.op == :sub }
 
         unless subs.empty?
-          list     = uniq(flatten(subs.map(&:payload)))
+          list     = uniq(subs.map(&:payload).flatten)
           new_only = @state.want_sub(list)
           unless new_only.empty?
             send_sub(new_only)
@@ -229,7 +234,7 @@ module DhanHQ
 
         return if unsubs.empty?
 
-        list       = uniq(flatten(unsubs.map(&:payload)))
+        list       = uniq(unsubs.map(&:payload).flatten)
         exist_only = @state.want_unsub(list)
         return if exist_only.empty?
 
@@ -267,17 +272,10 @@ module DhanHQ
         DhanHQ.logger&.debug("[DhanHQ::WS] send_disconnect error #{e.class}: #{e.message}")
       end
 
-      def flatten(a) = a.flatten
-
       def uniq(list)
-        seen = {}
-        list.each_with_object([]) do |i, out|
-          k = "#{i[:ExchangeSegment]}:#{i[:SecurityId]}"
-          next if seen[k]
-
-          out << i
-          seen[k] = true
-        end
+        # Composite key: the same instrument can arrive via repeated subscribe
+        # calls; Array#uniq with a block keeps the first occurrence.
+        list.uniq { |i| [i[:ExchangeSegment], i[:SecurityId]] }
       end
     end
   end

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

@@ -13,8 +13,12 @@ module DhanHQ
       # WebSocket client for Full Market Depth data
       # Provides real-time market depth (bid/ask levels) for specified symbols
       class Client < BaseConnection
+        # Feed request codes per the official Annexure "Feed Request Code" table
+        # (dhanhq.co/docs/v2/annexure#feed-request-code): 23 = Subscribe - Full
+        # Market Depth, 24 = Unsubscribe - Full Market Depth. Never 12 - that is
+        # the whole-connection disconnect, not a per-instrument unsubscribe.
         SUBSCRIBE_REQUEST_CODE    = 23
-        UNSUBSCRIBE_REQUEST_CODE  = 12
+        UNSUBSCRIBE_REQUEST_CODE  = 24
 
         ##
         # Initialize Market Depth WebSocket client

data/lib/DhanHQ/ws/registry.rb

@@ -9,13 +9,14 @@ module DhanHQ
     # disconnected when required.
     class Registry
       @clients = []
+      @mutex = Mutex.new
       class << self
         # Registers a client instance with the registry.
         #
         # @param client [DhanHQ::WS::Client]
         # @return [void]
         def register(client)
-          @clients << client unless @clients.include?(client)
+          @mutex.synchronize { @clients << client unless @clients.include?(client) }
         end
 
         # Removes a client from the registry.
@@ -23,18 +24,21 @@ module DhanHQ
         # @param client [DhanHQ::WS::Client]
         # @return [void]
         def unregister(client)
-          @clients.delete(client)
+          @mutex.synchronize { @clients.delete(client) }
         end
 
         # Stops and removes all registered clients.
         #
         # @return [void]
         def stop_all
-          @clients.dup.each do |c|
-            c.stop
-          rescue StandardError
+          @mutex.synchronize do
+            @clients.dup.each do |c|
+              c.stop
+            rescue StandardError => e
+              DhanHQ.logger&.debug("[DhanHQ::WS::Registry] stop failed: #{e.class} #{e.message}")
+            end
+            @clients.clear
           end
-          @clients.clear
         end
       end
     end

data/lib/dhan_hq.rb

@@ -44,6 +44,9 @@ module DhanHQ
     # "dhan_hq"` — it only worked via exe/dhanhq-mcp and lib/dhan_hq/mcp.rb, which
     # require_relative the file directly instead of going through the autoloader.
     "mcp" => "MCP",
+    # resources/scanx.rb defines DhanHQ::Resources::ScanX; without this Zeitwerk
+    # looks for DhanHQ::Resources::Scanx and fails on the first reference.
+    "scanx" => "ScanX",
     "ws" => "WS"
   )
   LOADER.push_dir(File.join(__dir__, "DhanHQ"), namespace: self)
@@ -84,8 +87,6 @@ module DhanHQ
   require_relative "DhanHQ/skills/builtin/market_data_summarizer"
   DhanHQ::Skills::Registry.load_builtins
 
-  class Error < StandardError; end
-
   class << self
     # Default REST API host used when no custom base URL is provided.
     #
@@ -244,6 +245,10 @@ module DhanHQ
     def fetch_token_endpoint(url, bearer_token, label)
       conn = ::Faraday.new(url: url) do |c|
         c.request :url_encoded
+        # Bounded timeouts, same defaults as Client#build_connection; without
+        # them a stalled token endpoint would hang the caller forever.
+        c.options.timeout = ENV.fetch("DHAN_READ_TIMEOUT", 30).to_i
+        c.options.open_timeout = ENV.fetch("DHAN_CONNECT_TIMEOUT", 10).to_i
         c.adapter ::Faraday.default_adapter
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Shubham Taywade
@@ -241,6 +241,7 @@ files:
 - lib/DhanHQ/constants.rb
 - lib/DhanHQ/contracts/alert_order_contract.rb
 - lib/DhanHQ/contracts/base_contract.rb
+- lib/DhanHQ/contracts/company_info_contract.rb
 - lib/DhanHQ/contracts/edis_contract.rb
 - lib/DhanHQ/contracts/expired_options_data_contract.rb
 - lib/DhanHQ/contracts/forever_order_contract.rb
@@ -254,15 +255,18 @@ files:
 - lib/DhanHQ/contracts/intraday_historical_data_contract.rb
 - lib/DhanHQ/contracts/margin_calculator_contract.rb
 - lib/DhanHQ/contracts/market_feed_contract.rb
+- lib/DhanHQ/contracts/market_movers_contract.rb
 - lib/DhanHQ/contracts/modify_order_contract.rb
 - lib/DhanHQ/contracts/multi_order_contract.rb
 - lib/DhanHQ/contracts/multi_scrip_margin_calc_request_contract.rb
+- lib/DhanHQ/contracts/news_headline_contract.rb
 - lib/DhanHQ/contracts/option_chain_contract.rb
 - lib/DhanHQ/contracts/order_contract.rb
 - lib/DhanHQ/contracts/place_order_contract.rb
 - lib/DhanHQ/contracts/pnl_based_exit_contract.rb
 - lib/DhanHQ/contracts/position_conversion_contract.rb
 - lib/DhanHQ/contracts/slice_order_contract.rb
+- lib/DhanHQ/contracts/technical_data_contract.rb
 - lib/DhanHQ/contracts/trade_by_order_id_contract.rb
 - lib/DhanHQ/contracts/trade_contract.rb
 - lib/DhanHQ/contracts/trade_history_contract.rb
@@ -363,6 +367,7 @@ files:
 - lib/DhanHQ/resources/pnl_exit.rb
 - lib/DhanHQ/resources/positions.rb
 - lib/DhanHQ/resources/profile.rb
+- lib/DhanHQ/resources/scanx.rb
 - lib/DhanHQ/resources/statements.rb
 - lib/DhanHQ/resources/super_orders.rb
 - lib/DhanHQ/resources/trader_control.rb