DhanHQ 3.4.0 → 4.1.0

data/lib/DhanHQ/client.rb

@@ -42,42 +42,82 @@ 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 mode [Symbol, nil] Optional environment override (`:live`, `:sandbox`, `:hybrid`)
+    #   for this client. When combined with +config:+ the configuration is forked,
+    #   so a shared/global configuration is never mutated.
+    # @param attrs [Hash] Additional keyword configuration attributes
+    def initialize(config_or_attrs = nil, config: nil, api_type: :order_api, mode: nil, **attrs)
+      attrs = attrs.merge(mode: mode) if mode
+      @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 base URL for this client's API
+    # tier changes — including a mid-flight mode switch.
     #
     # @return [Faraday::Connection]
     def connection
-      current_url = DhanHQ.configuration.base_url
+      current_url = @config.base_url_for(@api_type)
       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))
+    def scanx = @scanx ||= Resources::ScanX.new(client: client_for(Resources::ScanX::API_TYPE))
+
+    # The effective environment (+:live+ or +:sandbox+) for requests issued by
+    # this client, resolved from its API tier and the configured mode.
+    #
+    # @return [Symbol]
+    def environment
+      @config.environment_for(@api_type)
+    end
+
+    # 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 +133,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 +150,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 +255,58 @@ 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)
+        fork_config_with_attrs(config_or_attrs, attrs)
+      elsif config_or_attrs.is_a?(Hash)
+        DhanHQ::Configuration.new(config_or_attrs.merge(attrs))
+      elsif keyword_config
+        fork_config_with_attrs(keyword_config, attrs)
+      elsif attrs.any?
+        DhanHQ::Configuration.new(attrs)
+      else
+        DhanHQ.ensure_configuration!
+      end
+    end
+
+    # Copies a Configuration when per-instance attributes (e.g. +mode:+) are
+    # given alongside it, so an injected or global configuration is never
+    # mutated. Without extra attributes the original object is shared unchanged.
+    def fork_config_with_attrs(config, attrs)
+      return config if attrs.empty?
+
+      config.dup.tap do |forked|
+        attrs.each { |key, value| forked.public_send("#{key}=", value) }
+      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 +315,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/concerns/order_audit.rb

@@ -37,13 +37,28 @@ module DhanHQ
     module OrderAudit
       private
 
-      # Raises an error if LIVE_TRADING is not explicitly enabled.
-      # Set ENV["LIVE_TRADING"]="true" in production to allow order submission.
+      # Raises an error unless live trading is explicitly enabled OR the request
+      # targets the sandbox host, where no real money is at risk.
+      #
+      # Set ENV["LIVE_TRADING"]="true" to allow order submission against the
+      # production host. Orders routed to the sandbox host (config.mode =
+      # :sandbox, or the trading tiers under :hybrid) skip the gate because they
+      # cannot place real orders.
       def ensure_live_trading!
         return if ENV["LIVE_TRADING"] == "true"
+        return if sandbox_target?
 
         raise DhanHQ::LiveTradingDisabledError,
-              "Live trading is disabled. Set ENV[\"LIVE_TRADING\"]=\"true\" to enable order placement."
+              "Live trading is disabled. Set ENV[\"LIVE_TRADING\"]=\"true\" to enable order placement, " \
+              "or switch to the sandbox with DhanHQ.configure { |c| c.mode = :sandbox } / :hybrid."
+      end
+
+      # True when this resource's requests resolve to the sandbox host.
+      # Tolerates hosts that never got a client wired in (bare test doubles).
+      def sandbox_target?
+        return false unless respond_to?(:client) && client.respond_to?(:environment)
+
+        client.environment == :sandbox
       end
 
       # Runs the risk pipeline for the given order params.
@@ -120,6 +135,7 @@ module DhanHQ
           event: event,
           hostname: inspector.hostname,
           env: inspector.environment,
+          target: request_target,
           ipv4: inspector.public_ipv4,
           ipv6: inspector.public_ipv6,
           security_id: extract_param(params, :securityId, :security_id),
@@ -131,6 +147,13 @@ module DhanHQ
         DhanHQ.logger&.warn(JSON.generate(entry))
       end
 
+      # The host the order will be sent to, for the audit trail.
+      def request_target
+        return "sandbox" if sandbox_target?
+
+        "live"
+      end
+
       # Extracts a value from params trying both camelCase and snake_case keys,
       # as well as both symbol and string key types.
       def extract_param(params, camel_key, snake_key)

data/lib/DhanHQ/configuration.rb

@@ -15,6 +15,24 @@ module DhanHQ
     # Default Sandbox API host.
     # @return [String]
     SANDBOX_URL = Constants::Urls::SANDBOX_API_BASE
+
+    # All environments a client can run in.
+    #
+    # - +:live+ — every request hits the production host.
+    # - +:sandbox+ — every request hits the sandbox host (previous `sandbox = true` behaviour).
+    # - +:hybrid+ — market data (quotes, option chain, charts, instruments, ScanX)
+    #   hits production while trading/account requests hit the sandbox host, so a
+    #   strategy rehearses execution against real prices without risking money.
+    # @return [Array<Symbol>]
+    MODES = %i[live sandbox hybrid].freeze
+
+    # API tiers routed to the production host when {#mode} is +:hybrid+.
+    # Everything else (orders, positions, funds, statements, ...) routes to the
+    # sandbox host. Global Stocks keeps its own tier so it stays on production in
+    # hybrid mode — the sandbox host does not mirror the US-equities API.
+    # @return [Array<Symbol>]
+    HYBRID_LIVE_API_TYPES = %i[data_api quote_api option_chain global_stocks_api].freeze
+
     # The client ID for API authentication.
     # @return [String, nil] The client ID or `nil` if not set.
     attr_accessor :client_id
@@ -39,7 +57,55 @@ module DhanHQ
     attr_writer :base_url
 
     # Whether to use the sandbox environment.
-    attr_accessor :sandbox
+    #
+    # Backward-compatible facade over {#mode}: setting it to +true+ switches to
+    # full sandbox mode, +false+ back to live. Prefer {#mode} for new code — it
+    # also supports +:hybrid+ (live market data + sandbox execution).
+    #
+    # rubocop:disable Naming/PredicateMethod -- legacy attr_accessor-style API,
+    # kept as a boolean mirror of +mode+ for every caller written before :hybrid.
+    # @return [Boolean] True when every request targets the sandbox host.
+    def sandbox
+      mode == :sandbox
+    end
+    # rubocop:enable Naming/PredicateMethod
+
+    def sandbox=(value)
+      self.mode = value ? :sandbox : :live
+    end
+
+    # The environment the client runs in: +:live+, +:sandbox+, or +:hybrid+.
+    #
+    # Set via +DHAN_MODE+ or in {DhanHQ.configure}. {#sandbox=} remains as an
+    # alias for switching between +:live+ and +:sandbox+.
+    #
+    # @return [Symbol]
+    attr_reader :mode
+
+    # @param value [Symbol, String] One of {MODES} (case-insensitive).
+    # @raise [ArgumentError] When the value is not a known mode.
+    def mode=(value)
+      @mode = coerce_mode!(value)
+    end
+
+    # Per-tier environment overrides applied on top of {#mode}.
+    #
+    # Keys are API tier symbols (+:order_api+, +:data_api+, +:quote_api+,
+    # +:option_chain+, +:non_trading_api+, +:global_stocks_api+); values are
+    # +:live+ or +:sandbox+. Useful to, say, keep fund limits on production while
+    # everything else runs on the sandbox in hybrid mode:
+    #
+    #   DhanHQ.configure do |c|
+    #     c.mode = :hybrid
+    #     c.environment_overrides = { non_trading_api: :live }
+    #   end
+    #
+    # @return [Hash{Symbol => Symbol}]
+    attr_reader :environment_overrides
+
+    def environment_overrides=(value)
+      @environment_overrides = coerce_environment_overrides(value)
+    end
 
     # When true, state-changing requests (order placement, modification,
     # cancellation, position exits, trading controls) are validated and logged but
@@ -176,15 +242,54 @@ module DhanHQ
     # is nil or the default production URL, returns {SANDBOX_URL}.
     # @return [String]
     def base_url
-      if sandbox? && (@base_url.nil? || @base_url == BASE_URL)
+      base_url_for(nil)
+    end
+
+    # Returns the base URL for requests on the given API tier, honouring
+    # {#mode}, {#environment_overrides}, and an explicit {#base_url} override.
+    #
+    # In +:hybrid+ mode data tiers (see {HYBRID_LIVE_API_TYPES}) resolve to the
+    # production host while trading and account tiers resolve to the sandbox
+    # host, which is what lets a strategy read live prices while placing paper
+    # orders.
+    #
+    # @param api_type [Symbol, nil] API tier the request belongs to. +nil+ uses
+    #   the mode-level default (+:sandbox+ mode resolves to the sandbox host,
+    #   +:live+ and +:hybrid+ to production).
+    # @return [String]
+    def base_url_for(api_type)
+      if environment_for(api_type) == :sandbox && (@base_url.nil? || @base_url == BASE_URL)
         SANDBOX_URL
       else
         @base_url || BASE_URL
       end
     end
 
+    # The effective environment (+:live+ or +:sandbox+) for requests on the
+    # given API tier. Explicit {#environment_overrides} win over the {#mode}
+    # defaults.
+    #
+    # @param api_type [Symbol, nil]
+    # @return [Symbol]
+    def environment_for(api_type)
+      key = api_type&.to_sym
+      return @environment_overrides[key] if key && @environment_overrides.key?(key)
+
+      case mode
+      when :sandbox then :sandbox
+      when :hybrid then HYBRID_LIVE_API_TYPES.include?(key) ? :live : :sandbox
+      else :live
+      end
+    end
+
     def sandbox?
-      @sandbox == true
+      mode == :sandbox
+    end
+
+    # True when {#mode} is +:hybrid+ — live market data, sandbox execution.
+    # @return [Boolean]
+    def hybrid?
+      mode == :hybrid
     end
 
     # @return [Boolean] True when state-changing requests should be simulated.
@@ -212,34 +317,80 @@ 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)
+      @environment_overrides = coerce_environment_overrides(
+        attrs[:environment_overrides] || ENV.fetch("DHAN_ENV_OVERRIDES", nil)
+      )
+      @mode = resolve_mode(attrs)
+      @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
 
+    # Resolves the initial mode from attributes and ENV.
+    #
+    # Precedence: an explicit +:mode+ attribute wins, then +DHAN_MODE+, then the
+    # legacy +sandbox+ attribute / +DHAN_SANDBOX+ flag, then +:live+.
+    def resolve_mode(attrs)
+      raw_mode = attrs.key?(:mode) ? attrs[:mode] : ENV.fetch("DHAN_MODE", nil)
+      return coerce_mode!(raw_mode) if raw_mode
+
+      sandbox_flag = attrs.key?(:sandbox) ? attrs[:sandbox] : env_flag("DHAN_SANDBOX", default: false)
+      sandbox_flag ? :sandbox : :live
+    end
+
+    # Normalises a mode value, raising on anything outside {MODES}.
+    def coerce_mode!(value)
+      mode = value.to_s.strip.downcase.to_sym
+      raise ArgumentError, "unknown mode #{value.inspect}: expected one of #{MODES.join(", ")}" unless MODES.include?(mode)
+
+      mode
+    end
+
+    # Valid targets for an environment override.
+    OVERRIDE_TARGETS = %i[live sandbox].freeze
+    private_constant :OVERRIDE_TARGETS
+
+    # Normalises an environment-overrides hash: symbol keys, :live/:sandbox values.
+    def coerce_environment_overrides(value)
+      return {} if value.nil? || value == ""
+
+      value = value.split(",").to_h { |pair| pair.split("=") } if value.is_a?(String)
+      raise ArgumentError, "environment_overrides must be a Hash (tier => :live/:sandbox)" unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(tier, env), out|
+        key = tier.to_s.strip.to_sym
+        target = env.to_s.strip.downcase.to_sym
+        raise ArgumentError, "environment override for #{key} must be :live or :sandbox (got #{env.inspect})" unless OVERRIDE_TARGETS.include?(target)
+
+        out[key] = target
+      end
+    end
+
     # Reads a boolean-ish environment variable, falling back to +default+ when unset.
     def env_flag(name, default:)
       raw = ENV.fetch(name, nil)

data/lib/DhanHQ/constants.rb

@@ -130,6 +130,63 @@ module DhanHQ
     # Backward-compatible alias kept for existing SDK usage.
     Instrument = InstrumentType
 
+    # ScanX data API enums (POST /v2/data/* — company info, market movers,
+    # news headlines, technical indicators).
+    module ScanX
+      # Exchange segments accepted by POST /v2/data/companyinfo.
+      COMPANY_INFO_SEGMENTS = %w[NSE_EQ BSE_EQ].freeze
+      # Metric sections returned by POST /v2/data/companyinfo (CO = company
+      # overview, RATIOS = valuation/profitability + industry benchmarks,
+      # SHP = shareholding pattern).
+      COMPANY_INFO_METRICS = %w[CO RATIOS SHP].freeze
+      # Instrument kinds accepted by POST /v2/data/companyinfo.
+      COMPANY_INFO_INSTRUMENTS = %w[EQUITY].freeze
+
+      # Exchange segments accepted by POST /v2/data/marketmovers.
+      MARKET_MOVERS_SEGMENTS = %w[NSE_FNO BSE_FNO NSE_COMM MCX_COMM NSE_EQ BSE_EQ].freeze
+      # Instrument kinds ranked by POST /v2/data/marketmovers.
+      MARKET_MOVERS_INSTRUMENTS = %w[OPTIDX OPTSTK OPTFUT FUTIDX FUTSTK FUTCOM EQUITY].freeze
+      # Ranking categories for POST /v2/data/marketmovers.
+      MARKET_MOVERS_CATEGORIES =
+        %w[HIGHEST_OI OI_GAINERS OI_LOSERS TOP_VOLUME PRICE_GAINERS PRICE_LOSERS].freeze
+      # Equity universes accepted by POST /v2/data/marketmovers (required when
+      # instrument is EQUITY).
+      MARKET_MOVERS_UNIVERSES = %w[
+        ALL FNO_STOCKS NIFTY_50 NIFTY_BANK FINNIFTY INDIA_VIX NIFTY_MIDCAP NIFTY_NEXT_50
+        NIFTY_SMALLCAP_50 NIFTY_MID_CAP_50 NIFTY_100 NIFTY_200 NIFTY_500 NIFTY_MIDCAP_100
+        NIFTY_MIDCAP_150 NIFTY_SMALLCAP_100 NIFTY_SMALLCAP_250 NIFTY_MICROCAP_250 NIFTY_AUTO
+        NIFTY_PRIVATE_BANK NIFTY_FMCG NIFTY_ENERGY NIFTY_INFRA NIFTY_IT NIFTY_MEDIA NIFTY_METAL
+        NIFTY_MNC NIFTY_PHARMA NIFTY_PSU_BANK NIFTY_REALTY NIFTY_SERVICE_SECTOR NIFTY_CUNSUMPTION
+        GIFT_NIFTY SENSEX BSE_100 BSE_200 BSE_500 BSE_150_MIDCAP BSE_250_SMALLCAP
+        BSE_250_LARGE_MID BSE_400_MID_SMALL BSE_BANKEX BSE_AUTO BSE_CAPITAL_GOODS
+        BSE_CONSUMER_DURABLES BSE_ENERGY BSE_FINANCE BSE_FMCG BSE_HEALTHCARE BSE_INDIA_MFG
+        BSE_INDUSTRIALS BSE_IPO BSE_IT BSE_METALS BSE_OIL_AND_GAS BSE_POWER BSE_PSU BSE_TELECOM
+      ].freeze
+
+      # News categories accepted by POST /v2/data/newsheadline.
+      NEWS_CATEGORIES = %w[
+        ALL COMPANIES EQUITY_MARKETS DEBT_MARKETS IPO GLOBAL INDIAN_ECONOMY GLOBAL_ECONOMY
+        CURRENCY COMMODITIES CRYPTOCURRENCIES GOVERNMENT_POLICY_AND_REGULATION INFRASTRUCTURE
+        INTERNATIONAL_TRADE INVESTMENT_IDEAS REAL_ESTATE STARTUPS TECHNOLOGY MUTUAL_FUNDS
+      ].freeze
+      # News scoping options (portfolio/watchlist) for POST /v2/data/newsheadline.
+      NEWS_UNIVERSES = %w[PORTFOLIO WATCHLIST].freeze
+
+      # Exchange segments accepted by POST /v2/data/technical.
+      TECHNICAL_SEGMENTS = %w[NSE_EQ IDX_I].freeze
+      # Instrument kinds accepted by POST /v2/data/technical.
+      TECHNICAL_INSTRUMENTS = %w[INDEX EQUITY].freeze
+      # Candle timeframes for POST /v2/data/technical (1/5/15 minute, D = daily).
+      TECHNICAL_TIMEFRAMES = %w[1 5 15 D].freeze
+      # Indicator identifiers computed by POST /v2/data/technical.
+      TECHNICAL_INDICATORS = %w[
+        SMA_5 SMA_10 SMA_20 SMA_50 SMA_100 SMA_200
+        EMA_5 EMA_10 EMA_20 EMA_50 EMA_100 EMA_200
+        RSI_14 MACD_HIST STOCH STOCHRSI_14 ATR_14 ADX_14 UO ROC WILLR
+        PIVOT_CLASSIC PIVOT_FIBONACCI PIVOT_CAMARILLA
+      ].freeze
+    end
+
     # Minute intervals allowed by POST /v2/charts/intraday (charts annexure).
     module ChartInterval
       ONE = "1"
@@ -536,7 +593,8 @@ module DhanHQ
       "/v2/marketfeed/",
       "/v2/optionchain",
       "/v2/instrument/",
-      "/v2/charts"
+      "/v2/charts",
+      "/v2/data"
     ].freeze
 
     # Path prefixes for which the request body (POST/PUT/PATCH) must include dhanClientId.
@@ -555,6 +613,7 @@ module DhanHQ
       /v2/killswitch
       /v2/ip
       /v2/globalstocks
+      /v2/data/newsheadline
     ].freeze
 
     # Path prefixes whose non-GET requests change real account state — they place,

data/lib/DhanHQ/contracts/company_info_contract.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Contracts
+    # Validates request for POST /v2/data/companyinfo (ScanX company fundamentals).
+    #
+    # securityId (digits), exchangeSegment (NSE_EQ/BSE_EQ), instrument (EQUITY),
+    # metrics (one or more of CO / RATIOS / SHP).
+    class CompanyInfoContract < BaseContract
+      params do
+        required(:security_id).filled(:string)
+        required(:exchange_segment).filled(:string, included_in?: Constants::ScanX::COMPANY_INFO_SEGMENTS)
+        required(:instrument).filled(:string, included_in?: Constants::ScanX::COMPANY_INFO_INSTRUMENTS)
+        required(:metrics).filled(:array, min_size?: 1) do
+          each(:str?, included_in?: Constants::ScanX::COMPANY_INFO_METRICS)
+        end
+      end
+
+      rule(:security_id) do
+        key.failure("must be a numeric security id string") unless value.to_s.match?(/\A\d+\z/)
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/market_movers_contract.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "date"
+
+module DhanHQ
+  module Contracts
+    # Validates request for POST /v2/data/marketmovers (ScanX ranked instruments).
+    #
+    # exchangeSegment, instrument[] (options / futures / equity kinds, no mixing
+    # groups), category, limit (1-100). Expiry is required for options/futures;
+    # universe is required for EQUITY and ignored otherwise.
+    class MarketMoversContract < BaseContract
+      DERIVATIVE_INSTRUMENTS = %w[OPTIDX OPTSTK OPTFUT FUTIDX FUTSTK FUTCOM].freeze
+      private_constant :DERIVATIVE_INSTRUMENTS
+
+      params do
+        required(:exchange_segment).filled(:string, included_in?: Constants::ScanX::MARKET_MOVERS_SEGMENTS)
+        required(:instrument).filled(:array, min_size?: 1) do
+          each(:str?, included_in?: Constants::ScanX::MARKET_MOVERS_INSTRUMENTS)
+        end
+        required(:category).filled(:string, included_in?: Constants::ScanX::MARKET_MOVERS_CATEGORIES)
+        required(:limit).filled(:integer, included_in?: 1..100)
+        optional(:expiry).filled(:string)
+        optional(:universe).filled(:string, included_in?: Constants::ScanX::MARKET_MOVERS_UNIVERSES)
+      end
+
+      rule(:expiry) do
+        next unless value.is_a?(String)
+
+        unless value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          key.failure("must be in YYYY-MM-DD format")
+          next
+        end
+
+        Date.parse(value)
+      rescue StandardError
+        key.failure("must be a valid date")
+      end
+
+      # Expiry is required when ranking derivatives; universe is required for EQUITY.
+      rule(:instrument, :expiry) do
+        instruments = Array(values[:instrument]).map(&:to_s)
+        key(:expiry).failure("is required when instrument includes options or futures") if derivative?(instruments) && values[:expiry].to_s.empty?
+      end
+
+      rule(:instrument, :universe) do
+        instruments = Array(values[:instrument]).map(&:to_s)
+        key(:universe).failure("is required when instrument is EQUITY") if instruments.include?(Constants::InstrumentType::EQUITY) && values[:universe].to_s.empty?
+      end
+
+      # True when any requested instrument is an option or future.
+      def derivative?(instruments)
+        instruments.any? { |i| DERIVATIVE_INSTRUMENTS.include?(i) }
+      end
+    end
+  end
+end