DhanHQ 3.1.0 → 3.2.1

data/lib/DhanHQ/client.rb

@@ -2,6 +2,7 @@
 
 require "faraday"
 require "json"
+require "securerandom"
 require "active_support/core_ext/hash/indifferent_access"
 require_relative "errors"
 require_relative "rate_limiter"
@@ -24,31 +25,57 @@ module DhanHQ
     include DhanHQ::RequestHelper
     include DhanHQ::ResponseHelper
 
-    # The Faraday connection object used for HTTP requests.
-    #
-    # @return [Faraday::Connection] The connection instance used for API requests.
-    attr_reader :connection
+    # Transient failures raised by this gem, worth retrying as-is.
+    RETRYABLE_SDK_ERRORS = [
+      DhanHQ::RateLimitError,
+      DhanHQ::InternalServerError,
+      DhanHQ::NetworkError
+    ].freeze
+    private_constant :RETRYABLE_SDK_ERRORS
+
+    # Transport failures raised by Faraday. Also worth retrying, but they are not part
+    # of this gem's error hierarchy, so a caller rescuing DhanHQ::Error would miss
+    # them — they are translated on the way out. See {#exhausted_error}.
+    RETRYABLE_TRANSPORT_ERRORS = [
+      Faraday::TimeoutError,
+      Faraday::ConnectionFailed
+    ].freeze
+    private_constant :RETRYABLE_TRANSPORT_ERRORS
 
     attr_reader :token_manager
 
-    # Initializes a new DhanHQ Client instance with a Faraday connection.
+    # 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)
     #
     # @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 configuration is invalid or rate limiter initialization fails
+    # @raise [DhanHQ::Error] If the rate limiter cannot be resolved for this API type.
     def initialize(api_type:)
       DhanHQ.ensure_configuration!
-      # Use shared rate limiter instance per API type to ensure proper coordination
+      # Shared per API type, so separate clients coordinate against one limit.
       @rate_limiter = RateLimiter.for(api_type)
 
       raise DhanHQ::Error, "RateLimiter initialization failed" unless @rate_limiter
+    end
 
-      # Store initial URL to detect changes
-      @last_base_url = DhanHQ.configuration.base_url
-      @connection = build_connection(@last_base_url)
+    # 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.
+    #
+    # @return [Faraday::Connection]
+    def connection
+      current_url = DhanHQ.configuration.base_url
+      return @connection if @connection && @last_base_url == current_url
+
+      @last_base_url = current_url
+      @connection = build_connection(current_url)
     end
 
     # Sends an HTTP request to the API with automatic retry for transient errors.
@@ -60,12 +87,18 @@ module DhanHQ
     # @return [HashWithIndifferentAccess, Array<HashWithIndifferentAccess>] Parsed JSON response.
     # @raise [DhanHQ::Error] If an HTTP error occurs.
     def request(method, path, payload, retries: 3)
+      payload = with_correlation_id(method, path, payload)
+      return dry_run.response_for(method, path, payload) if dry_run.simulates?(method, path)
+
       @token_manager&.ensure_valid_token!
       @rate_limiter.throttle!
-      refresh_connection!
+
+      # 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
-        with_transient_retry(retries: retries) do
+        with_transient_retry(retries: effective_retries) do
           response = connection.send(method, path) do |req|
             req.headers.merge!(build_headers(path))
             prepare_payload(req, payload, method, path)
@@ -91,23 +124,13 @@ module DhanHQ
       attempt = 0
       begin
         yield
-      rescue DhanHQ::RateLimitError, DhanHQ::InternalServerError, DhanHQ::NetworkError => e
-        attempt += 1
-        raise if attempt > retries
-
-        backoff = calculate_backoff(attempt)
-        DhanHQ.logger&.warn(
-          "[DhanHQ::Client] Transient error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
-        )
-        sleep(backoff)
-        retry
-      rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      rescue *RETRYABLE_SDK_ERRORS, *RETRYABLE_TRANSPORT_ERRORS => e
         attempt += 1
-        raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}" if attempt > retries
+        raise exhausted_error(e, retries) if attempt > retries
 
         backoff = calculate_backoff(attempt)
         DhanHQ.logger&.warn(
-          "[DhanHQ::Client] Network error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
+          "[DhanHQ::Client] Transient failure (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
         )
         sleep(backoff)
         retry
@@ -197,12 +220,64 @@ module DhanHQ
 
     private
 
-    def refresh_connection!
-      current_url = DhanHQ.configuration.base_url
-      return if @last_base_url == current_url
+    # 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
+    end
 
-      @last_base_url = current_url
-      @connection = build_connection(current_url)
+    # 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
+    end
+
+    # Fills in a +correlationId+ on order placements that lack one, so a caller who
+    # hits a timeout can still discover whether the order reached the exchange via
+    # GET /v2/orders/external/{correlation-id}.
+    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 if correlation_id?(payload)
+
+      inject_correlation_id(payload)
+    end
+
+    # Keys a caller may already have used for the correlation id, in either casing.
+    CORRELATION_ID_KEYS = %i[correlationId correlation_id].flat_map { |key| [key, key.to_s] }.freeze
+    private_constant :CORRELATION_ID_KEYS
+
+    # @return [Boolean] True when the caller supplied their own correlation id.
+    def correlation_id?(payload)
+      CORRELATION_ID_KEYS.any? { |key| payload.key?(key) }
+    end
+
+    # Returns a copy of the payload carrying a generated correlation id, matching the
+    # key type the payload already uses.
+    def inject_correlation_id(payload)
+      correlation_id = "dhq-#{SecureRandom.hex(8)}"
+      out = payload.dup
+      out.keys.any?(String) ? out["correlationId"] = correlation_id : out[:correlationId] = correlation_id
+      out
+    end
+
+    # The exception to raise once the retries are spent.
+    #
+    # Faraday's transport errors are translated to {DhanHQ::NetworkError}, so a caller
+    # rescuing DhanHQ::Error sees every failure this client can produce. This gem's own
+    # errors already belong to that hierarchy and are re-raised unchanged.
+    #
+    # @param error [StandardError] The failure that exhausted the retries.
+    # @param retries [Integer] How many retries were allowed.
+    # @return [StandardError] The exception to raise.
+    def exhausted_error(error, retries)
+      return error unless RETRYABLE_TRANSPORT_ERRORS.any? { |klass| error.is_a?(klass) }
+
+      attempts = retries.zero? ? "" : " after #{retries} retries"
+      DhanHQ::NetworkError.new("Request failed#{attempts}: #{error.message}")
     end
 
     def build_connection(url)

data/lib/DhanHQ/concerns/order_audit.rb

@@ -50,14 +50,21 @@ module DhanHQ
       #
       # Extracts +security_id+ and +exchange_segment+ from the params,
       # resolves the instrument, and calls {DhanHQ::Risk::Pipeline.run!}.
-      # If the instrument cannot be resolved the check is skipped silently
-      # rather than blocking the order.
+      # If the instrument cannot be resolved the check is skipped rather than
+      # blocking the order, since a transient scrip-master lookup failure should not
+      # stop a valid trade.
+      #
+      # Anything other than a lookup failure is logged before being swallowed. This
+      # method used to rescue StandardError silently, which is how a wrong-arity call
+      # to `Instrument.find` went unnoticed long enough for the risk pipeline to never
+      # run for any real order (see CHANGELOG 3.1.0). A skipped check is tolerable; a
+      # skipped check nobody can see is not.
       def run_risk_checks!(params)
         security_id = extract_param(params, :securityId, :security_id)
         exchange_segment = extract_param(params, :exchangeSegment, :exchange_segment)
         return unless security_id && exchange_segment
 
-        instrument = DhanHQ::Models::Instrument.find_by_security_id(exchange_segment, security_id)
+        instrument = resolve_instrument_for_risk(exchange_segment, security_id)
         return unless instrument
 
         DhanHQ::Risk::Pipeline.run!(
@@ -68,10 +75,34 @@ module DhanHQ
         )
       rescue DhanHQ::RiskViolation
         raise
-      rescue StandardError
+      rescue StandardError => e
+        log_risk_check_skipped(e, security_id, exchange_segment)
+        nil
+      end
+
+      # Resolves the instrument the risk pipeline needs, tolerating a lookup failure.
+      #
+      # @return [DhanHQ::Models::Instrument, nil]
+      def resolve_instrument_for_risk(exchange_segment, security_id)
+        DhanHQ::Models::Instrument.find_by_security_id(exchange_segment, security_id)
+      rescue StandardError => e
+        log_risk_check_skipped(e, security_id, exchange_segment)
         nil
       end
 
+      # Records that pre-trade risk checks did not run, and why.
+      def log_risk_check_skipped(error, security_id, exchange_segment)
+        DhanHQ.logger&.error(
+          JSON.generate(
+            event: "DHAN_RISK_CHECK_SKIPPED",
+            security_id: security_id,
+            exchange_segment: exchange_segment,
+            error: error.class.name,
+            message: error.message
+          )
+        )
+      end
+
       # Maps an exchange segment string to a pipeline trade type.
       def trade_type_for(exchange_segment)
         case exchange_segment.to_s

data/lib/DhanHQ/configuration.rb

@@ -41,6 +41,47 @@ module DhanHQ
     # Whether to use the sandbox environment.
     attr_accessor :sandbox
 
+    # When true, state-changing requests (order placement, modification,
+    # cancellation, position exits, trading controls) are validated and logged but
+    # never sent to the API — the client answers with a simulated response instead.
+    #
+    # Read-only requests still hit the API, so market data, the option chain,
+    # positions and holdings remain live. That makes dry-run usable for a full
+    # strategy rehearsal against real prices.
+    #
+    # Set via +DHAN_DRY_RUN=true+ or in {DhanHQ.configure}.
+    # @return [Boolean]
+    attr_accessor :dry_run
+
+    # Whether to auto-retry non-idempotent writes (order placement, modification,
+    # cancellation) after a transient failure — a 429, a 5xx, or a network timeout.
+    #
+    # Defaults to +false+, because the DhanHQ API has no idempotency key: a POST
+    # /v2/orders that times out may well have reached the exchange, and retrying it
+    # can place a second, duplicate order. With this off, the transient error is
+    # raised to the caller, who can reconcile using the correlation id (see
+    # {#auto_correlation_id} and +DhanHQ::Models::Order.find_by_correlation_id+)
+    # before deciding to resubmit.
+    #
+    # Read requests are always retried regardless of this setting.
+    #
+    # Set via +DHAN_RETRY_WRITES=true+ or in {DhanHQ.configure}.
+    # @return [Boolean]
+    attr_accessor :retry_non_idempotent_writes
+
+    # Whether to generate a +correlationId+ for order placements that do not carry
+    # one. The correlation id is the only way to answer "did my order actually go
+    # through?" after a timeout, via GET /v2/orders/external/{correlation-id}.
+    #
+    # Defaults to +false+ because it changes the request body, which would break
+    # callers matching recorded fixtures on the exact payload. Turn it on to get
+    # timeout-reconcilable orders for free. Only fills the field when absent; an
+    # explicit correlation id is always preserved.
+    #
+    # Set via +DHAN_AUTO_CORRELATION_ID=true+ or in {DhanHQ.configure}.
+    # @return [Boolean]
+    attr_accessor :auto_correlation_id
+
     # URL for the compact CSV format of instruments.
     # @return [String] URL for compact CSV.
     attr_accessor :compact_csv_url
@@ -124,6 +165,21 @@ module DhanHQ
       @sandbox == true
     end
 
+    # @return [Boolean] True when state-changing requests should be simulated.
+    def dry_run?
+      @dry_run == true
+    end
+
+    # @return [Boolean] True when non-idempotent writes may be auto-retried.
+    def retry_non_idempotent_writes?
+      @retry_non_idempotent_writes == true
+    end
+
+    # @return [Boolean] True when a correlation id should be generated for orders.
+    def auto_correlation_id?
+      @auto_correlation_id == true
+    end
+
     # Initializes a new configuration instance with default values.
     #
     # @example
@@ -133,7 +189,10 @@ module DhanHQ
     def initialize
       @client_id = ENV.fetch("DHAN_CLIENT_ID", nil)
       @access_token = ENV.fetch("DHAN_ACCESS_TOKEN", nil)
-      @sandbox        = ENV.fetch("DHAN_SANDBOX", "false").to_s.casecmp("true").zero?
+      @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)
       @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)
@@ -144,5 +203,15 @@ module DhanHQ
       @partner_id     = ENV.fetch("DHAN_PARTNER_ID", nil)
       @partner_secret = ENV.fetch("DHAN_PARTNER_SECRET", nil)
     end
+
+    private
+
+    # Reads a boolean-ish environment variable, falling back to +default+ when unset.
+    def env_flag(name, default:)
+      raw = ENV.fetch(name, nil)
+      return default if raw.nil? || raw.to_s.strip.empty?
+
+      raw.to_s.casecmp("true").zero?
+    end
   end
 end

data/lib/DhanHQ/constants.rb

@@ -16,8 +16,14 @@ module DhanHQ
       MCX_COMM = "MCX_COMM"
       BSE_CURRENCY = "BSE_CURRENCY"
       BSE_FNO = "BSE_FNO"
+      # US / international equities, traded through the Global Stocks APIs
+      # (`/v2/globalstocks/*`). Deliberately excluded from {ALL} so it can never
+      # satisfy the domestic order contracts.
+      INX_EQ = "INX_EQ"
 
       ALL = [IDX_I, NSE_EQ, NSE_FNO, NSE_CURRENCY, NSE_COMM, BSE_EQ, MCX_COMM, BSE_CURRENCY, BSE_FNO].freeze
+      # Segments served by the Global Stocks APIs.
+      GLOBAL_ALL = [INX_EQ].freeze
       # Segments allowed by POST /v2/margincalculator (single and multi).
       MARGIN_CALC_ALL = [NSE_EQ, NSE_FNO, BSE_EQ, BSE_FNO, MCX_COMM].freeze
       # Segments allowed by POST /v2/forever/orders (create).
@@ -218,6 +224,64 @@ module DhanHQ
       ].freeze
     end
 
+    # Enumerations specific to the Global Stocks (US equities) APIs served under
+    # `/v2/globalstocks/*`. These orders carry no exchange segment, product type
+    # or validity — the domestic {ProductType}/{Validity} enums do not apply.
+    #
+    # @see https://dhanhq.co/docs/v2/ Global Stocks section
+    module GlobalStocks
+      # The only exchange segment currently supported by the Global Stocks feed.
+      EXCHANGE_SEGMENT = ExchangeSegment::INX_EQ
+      # Numeric exchange-segment code used in the binary WebSocket header.
+      EXCHANGE_SEGMENT_CODE = 14
+      # Maximum instruments accepted per Global Stocks feed subscription frame.
+      MAX_INSTRUMENTS_PER_REQUEST = 100
+      # Maximum concurrent subscriptions on a single Global Stocks connection.
+      MAX_SUBSCRIPTIONS_PER_CONNECTION = 5_000
+      # Maximum concurrent Global Stocks feed connections per client.
+      MAX_CONNECTIONS_PER_CLIENT = 5
+
+      # Order types accepted by POST /v2/globalstocks/orders. Adds +AMOUNT+
+      # (notional/dollar-value orders) on top of the domestic order types.
+      module OrderType
+        MARKET = "MARKET"
+        LIMIT = "LIMIT"
+        STOP_LOSS = "STOP_LOSS"
+        STOP_LOSS_MARKET = "STOP_LOSS_MARKET"
+        AMOUNT = "AMOUNT"
+
+        ALL = [MARKET, LIMIT, STOP_LOSS, STOP_LOSS_MARKET, AMOUNT].freeze
+      end
+
+      # Leg names accepted when modifying a Global Stocks super order.
+      module LegName
+        ENTRY_LEG = "ENTRY_LEG"
+        STOP_LOSS_LEG = "STOP_LOSS_LEG"
+        TARGET_LEG = "TARGET_LEG"
+        NA = "NA"
+
+        ALL = [ENTRY_LEG, STOP_LOSS_LEG, TARGET_LEG, NA].freeze
+      end
+
+      # Values returned by GET /v2/globalstocks/marketstatus.
+      module MarketStatus
+        OPEN = "open"
+        CLOSED = "closed"
+
+        ALL = [OPEN, CLOSED].freeze
+      end
+
+      # Message codes on the Global Stocks binary feed.
+      module MsgCode
+        TRADE = 1
+        PREV_CLOSE = 32
+        CIRCUIT_LIMIT = 33
+        FIFTY_TWO_WEEK = 36
+
+        ALL = [TRADE, PREV_CLOSE, CIRCUIT_LIMIT, FIFTY_TWO_WEEK].freeze
+      end
+    end
+
     # Comparison types for conditional trigger alerts.
     module ComparisonType
       TECHNICAL_WITH_VALUE = "TECHNICAL_WITH_VALUE"
@@ -399,6 +463,7 @@ module DhanHQ
       WS_ORDER_UPDATE = "wss://api-order-update.dhan.co"
       WS_DEPTH_20 = "wss://depth-api-feed.dhan.co/twentydepth"
       WS_DEPTH_200 = "wss://full-depth-api.dhan.co/twohundreddepth"
+      WS_GLOBAL_STOCKS_FEED = "wss://global-stocks-api-feed.dhan.co"
       INSTRUMENT_CSV_COMPACT = "https://images.dhan.co/api-data/api-scrip-master.csv"
       INSTRUMENT_CSV_DETAILED = "https://images.dhan.co/api-data/api-scrip-master-detailed.csv"
       DOCS = "https://dhanhq.co/docs/v2"
@@ -424,6 +489,9 @@ module DhanHQ
     COMPARISON_TYPES = ComparisonType::ALL
     OPERATORS = Operator::ALL
     ALERT_CONDITION_SEGMENTS = ExchangeSegment::ALERT_CONDITION_ALL
+    GLOBAL_STOCKS_SEGMENTS = ExchangeSegment::GLOBAL_ALL
+    GLOBAL_STOCKS_ORDER_TYPES = GlobalStocks::OrderType::ALL
+    GLOBAL_STOCKS_LEG_NAMES = GlobalStocks::LegName::ALL
     ALERT_TIMEFRAMES = %w[DATE ONE_MIN FIVE_MIN FIFTEEN_MIN DAY].freeze
 
     # Exchange aliases used when building subscription payloads.
@@ -475,6 +543,7 @@ module DhanHQ
     # Injection is done in the client layer when building the payload.
     PAYLOAD_REQUIRES_DHAN_CLIENT_ID_PREFIXES = %w[
       /alerts/orders
+      /v2/alerts
       /v2/orders
       /v2/orders/iceberg
       /v2/orders/twap
@@ -485,6 +554,38 @@ module DhanHQ
       /v2/margincalculator
       /v2/killswitch
       /v2/ip
+      /v2/globalstocks
+    ].freeze
+
+    # Path prefixes whose non-GET requests change real account state — they place,
+    # modify or cancel orders, exit positions, or alter trading controls.
+    #
+    # Note that a POST is not automatically a mutation on this API: option chain,
+    # market feed, historical charts and the margin calculators are all read-only
+    # POSTs. Dry-run mode and non-idempotent retry protection consult this list so
+    # they act on real writes only and leave data fetches alone.
+    MUTATING_PATH_PREFIXES = %w[
+      /v2/orders
+      /v2/super/orders
+      /v2/forever
+      /v2/alerts
+      /v2/globalstocks/orders
+      /v2/positions
+      /v2/killswitch
+      /v2/pnlExit
+      /v2/edis
+      /v2/ip
+    ].freeze
+
+    # Subset of {MUTATING_PATH_PREFIXES} that create orders. A retried POST to one
+    # of these can produce a duplicate order, and dry-run mode answers these with a
+    # simulated order id so caller code paths still complete.
+    ORDER_PLACEMENT_PATH_PREFIXES = %w[
+      /v2/orders
+      /v2/super/orders
+      /v2/forever
+      /v2/alerts
+      /v2/globalstocks/orders
     ].freeze
 
     # Mapping of exchange and segment combinations to canonical exchange segment names.

data/lib/DhanHQ/contracts/expired_options_data_contract.rb

@@ -71,8 +71,7 @@ module DhanHQ
             from_date = Date.parse(values[:from_date])
             to_date = Date.parse(values[:to_date])
 
-            key.failure("from_date must be before to_date") if from_date >= to_date
-            key.failure("from_date must be a valid trading date (no weekend dates)") unless trading_day?(from_date)
+            key.failure("from_date must be before or equal to to_date") if from_date > to_date
 
             # Check if date range is not too large (max 31 days; to_date is non-inclusive)
             key.failure("date range cannot exceed 31 days") if (to_date - from_date).to_i > 31
@@ -101,13 +100,6 @@ module DhanHQ
           false
         end
       end
-
-      def trading_day?(date)
-        return false unless date.is_a?(Date)
-
-        # Sunday = 0, Saturday = 6; trading days are Monday (1) through Friday (5)
-        (1..5).cover?(date.wday)
-      end
     end
   end
 end

data/lib/DhanHQ/contracts/global_stocks_estimator_contract.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base_contract"
+
+module DhanHQ
+  module Contracts
+    # Validation contract shared by POST /v2/globalstocks/transEstimate
+    # (order charge estimate) and POST /v2/globalstocks/margincalculator.
+    #
+    # Both endpoints accept the same +InxEstimatorRequest+ body. The API documents
+    # +price+ and +quantity+ as strings on the wire; this contract validates them
+    # as numbers and the resource stringifies them before sending.
+    class GlobalStocksEstimatorContract < BaseContract
+      TRANSACTION_TYPES = DhanHQ::Constants::TransactionType::ALL
+
+      params do
+        required(:security_id).filled(:string, max_size?: 50)
+        required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
+        required(:price).filled(:float, gteq?: 0)
+        required(:quantity).filled(:float, gt?: 0)
+      end
+
+      rule(:price) do
+        key.failure("must be a finite number") if value.is_a?(Float) && (value.nan? || value.infinite?)
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/global_stocks_modify_order_contract.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "global_stocks_order_contract"
+
+module DhanHQ
+  module Contracts
+    # Validation contract for PUT /v2/globalstocks/orders/{order-id}.
+    class GlobalStocksModifyOrderContract < GlobalStocksOrderContract
+      params do
+        required(:order_id).filled(:string)
+        required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
+        required(:order_type).filled(:string, included_in?: ORDER_TYPES)
+        required(:security_id).filled(:string, max_size?: 50)
+
+        optional(:quantity).maybe(:float, gt?: 0)
+        optional(:price).maybe(:float, gteq?: 0)
+        optional(:leg_name).maybe(:string, included_in?: LEG_NAMES)
+        optional(:dhan_client_id).maybe(:string)
+      end
+
+      rule(:order_type, :price) do
+        key(:price).failure("must be greater than 0 for LIMIT orders") if PRICED_ORDER_TYPES.include?(values[:order_type]) && !values[:price]&.positive?
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/global_stocks_order_contract.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "dry-validation"
+require_relative "base_contract"
+
+module DhanHQ
+  module Contracts
+    # Base contract shared by the Global Stocks (US equities) order contracts.
+    #
+    # Global Stocks orders differ from domestic orders in three ways that make the
+    # domestic {OrderContract} unusable here:
+    #
+    # 1. There is no +exchange_segment+, +product_type+ or +validity+ field.
+    # 2. +quantity+ is a float — fractional shares are supported.
+    # 3. +order_type+ adds +AMOUNT+, a notional (dollar-value) order which carries
+    #    an +amount+ instead of a +quantity+.
+    #
+    # @see https://dhanhq.co/docs/v2/ Global Stocks section
+    class GlobalStocksOrderContract < BaseContract
+      TRANSACTION_TYPES = DhanHQ::Constants::TransactionType::ALL
+      ORDER_TYPES       = DhanHQ::Constants::GlobalStocks::OrderType::ALL
+      LEG_NAMES         = DhanHQ::Constants::GlobalStocks::LegName::ALL
+
+      # Order types that require a limit price.
+      PRICED_ORDER_TYPES = [DhanHQ::Constants::GlobalStocks::OrderType::LIMIT].freeze
+      # Order types that require a trigger price.
+      TRIGGERED_ORDER_TYPES = [
+        DhanHQ::Constants::GlobalStocks::OrderType::STOP_LOSS,
+        DhanHQ::Constants::GlobalStocks::OrderType::STOP_LOSS_MARKET
+      ].freeze
+    end
+  end
+end