DhanHQ 2.6.1 → 2.6.3

data/lib/DhanHQ/contracts/slice_order_contract.rb

@@ -31,7 +31,7 @@ module DhanHQ
       # Parameters and validation rules for the slicing order request.
       #
       # @!attribute [r] correlationId
-      #   @return [String] Optional. Identifier for tracking, max length 25 characters.
+      #   @return [String] Optional. Identifier for tracking, max length 30 characters (per orders doc).
       # @!attribute [r] transactionType
       #   @return [String] Required. BUY or SELL.
       # @!attribute [r] exchangeSegment
@@ -39,13 +39,13 @@ module DhanHQ
       #     Must be one of: NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM.
       # @!attribute [r] productType
       #   @return [String] Required. Product type for the order.
-      #     Must be one of: CNC, INTRADAY, MARGIN, MTF, CO, BO.
+      #     Must be one of: CNC, INTRADAY, MARGIN, MTF (per orders doc).
       # @!attribute [r] orderType
       #   @return [String] Required. Type of order.
       #     Must be one of: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_MARKET.
       # @!attribute [r] validity
       #   @return [String] Required. Validity of the order.
-      #     Must be one of: DAY, IOC, GTC, GTD.
+      #     Must be one of: DAY, IOC (per orders doc).
       # @!attribute [r] securityId
       #   @return [String] Required. Security identifier for the order.
       # @!attribute [r] quantity
@@ -59,11 +59,11 @@ module DhanHQ
       # @!attribute [r] afterMarketOrder
       #   @return [Boolean] Optional. Indicates if this is an after-market order.
       # @!attribute [r] amoTime
-      #   @return [String] Optional. Time for after-market orders. Must be one of: OPEN, OPEN_30, OPEN_60.
+      #   @return [String] Optional. Time for after-market orders. Must be one of: PRE_OPEN, OPEN, OPEN_30, OPEN_60.
       # @!attribute [r] boProfitValue
-      #   @return [Float] Optional. Profit value for Bracket Orders, must be > 0 if provided.
+      #   @return [Float] Optional. Profit value for Bracket Orders (not used when productType is CNC/INTRADAY/MARGIN/MTF).
       # @!attribute [r] boStopLossValue
-      #   @return [Float] Optional. Stop-loss value for Bracket Orders, must be > 0 if provided.
+      #   @return [Float] Optional. Stop-loss value for Bracket Orders (not used when productType is CNC/INTRADAY/MARGIN/MTF).
       # @!attribute [r] drvExpiryDate
       #   @return [String] Optional. Expiry date for derivative contracts.
       # @!attribute [r] drvOptionType
@@ -71,21 +71,21 @@ module DhanHQ
       # @!attribute [r] drvStrikePrice
       #   @return [Float] Optional. Strike price for options, must be > 0 if provided.
       params do
-        optional(:correlationId).maybe(:string, max_size?: 25)
+        optional(:correlationId).maybe(:string, max_size?: 30)
         required(:transactionType).filled(:string, included_in?: %w[BUY SELL])
         required(:exchangeSegment).filled(:string,
                                           included_in?: %w[NSE_EQ NSE_FNO NSE_CURRENCY BSE_EQ BSE_FNO BSE_CURRENCY
                                                            MCX_COMM])
-        required(:productType).filled(:string, included_in?: %w[CNC INTRADAY MARGIN MTF CO BO])
+        required(:productType).filled(:string, included_in?: %w[CNC INTRADAY MARGIN MTF])
         required(:orderType).filled(:string, included_in?: %w[LIMIT MARKET STOP_LOSS STOP_LOSS_MARKET])
-        required(:validity).filled(:string, included_in?: %w[DAY IOC GTC GTD])
+        required(:validity).filled(:string, included_in?: %w[DAY IOC])
         required(:securityId).filled(:string)
         required(:quantity).filled(:integer, gt?: 0)
         optional(:disclosedQuantity).maybe(:integer, gteq?: 0)
         optional(:price).maybe(:float, gt?: 0)
         optional(:triggerPrice).maybe(:float, gt?: 0)
         optional(:afterMarketOrder).maybe(:bool)
-        optional(:amoTime).maybe(:string, included_in?: %w[OPEN OPEN_30 OPEN_60])
+        optional(:amoTime).maybe(:string, included_in?: %w[PRE_OPEN OPEN OPEN_30 OPEN_60])
         optional(:boProfitValue).maybe(:float, gt?: 0)
         optional(:boStopLossValue).maybe(:float, gt?: 0)
         optional(:drvExpiryDate).maybe(:string)

data/lib/DhanHQ/core/auth_api.rb

@@ -8,7 +8,7 @@ module DhanHQ
   # This class intentionally lives at the top-level namespace so it autoloads
   # cleanly from `lib/DhanHQ/core/auth_api.rb` with Zeitwerk `collapse`.
   class AuthAPI
-    BASE_URL = "https://auth.dhan.co"
+    BASE_URL = Constants::Urls::AUTH_BASE
 
     def connection
       @connection ||= Faraday.new(url: BASE_URL) do |faraday|

data/lib/DhanHQ/core/base_api.rb

@@ -86,20 +86,21 @@ module DhanHQ
       "#{self.class::HTTP_PATH}#{endpoint}"
     end
 
-    # Format parameters based on API endpoint
+    # Format parameters based on API endpoint. Uses path-based strategy (marketfeed: pass-through,
+    # optionchain: titleize, default: camelize).
     def format_params(endpoint, params)
-      return params if marketfeed_api?(endpoint) || params.empty?
+      full_path = build_path(endpoint)
+      return params if params.empty?
 
-      optionchain_api?(endpoint) ? titleize_keys(params) : camelize_keys(params)
+      param_formatter_for(full_path).call(params)
     end
 
-    # Determines if the API endpoint is for Option Chain
-    def optionchain_api?(endpoint)
-      endpoint.include?("/optionchain")
-    end
+    # Returns a callable that formats params for the given path (Strategy).
+    def param_formatter_for(full_path)
+      return ->(p) { p } if full_path.include?("/marketfeed")
+      return ->(p) { titleize_keys(p) } if full_path.include?("/optionchain")
 
-    def marketfeed_api?(endpoint)
-      endpoint.include?("/marketfeed")
+      ->(p) { camelize_keys(p) }
     end
   end
 end

data/lib/DhanHQ/core/base_model.rb

@@ -145,7 +145,10 @@ module DhanHQ
       def parse_collection_response(response)
         # Some endpoints return arrays, others might return a `[:data]` structure
         unless response.is_a?(Array) || (response.is_a?(Hash) && response[:data].is_a?(Array))
-          DhanHQ.logger&.warn("[DhanHQ::BaseModel] Unexpected response format for collection: #{response.class}. Expected Array or Hash with :data key.")
+          DhanHQ.logger&.warn(
+            "[DhanHQ::BaseModel] Unexpected response format for collection: #{response.class}. " \
+            "Expected Array or Hash with :data key."
+          )
           return []
         end
 

data/lib/DhanHQ/core/error_handler.rb

@@ -10,9 +10,9 @@ module DhanHQ
     def self.handle(error)
       case error
       when Dry::Validation::Result
-        raise "Validation Error: #{error.errors.to_h}"
+        raise DhanHQ::ValidationError, "Invalid parameters: #{error.errors.to_h}"
       else
-        raise "Error: #{error.message}"
+        raise DhanHQ::Error, error.message
       end
     end
   end

data/lib/DhanHQ/errors.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
 module DhanHQ
-  # Base error class for all DhanHQ API errors
-  class Error < StandardError; end
+  # Base error class for all DhanHQ API errors.
+  # When raised from API response handling, {#response_body} holds the parsed error payload.
+  class Error < StandardError
+    attr_reader :response_body
+
+    def initialize(message = nil, response_body: nil)
+      super(message)
+      @response_body = response_body
+    end
+  end
 
   # Authentication and access errors
   # Raised when access token cannot be resolved (missing config or provider returned nil).
@@ -36,6 +44,10 @@ module DhanHQ
 
   # Order and market data errors
   class OrderError < Error; end
+
+  # Raised when the 25-modifications-per-order API cap would be exceeded.
+  # Count is tracked per Order instance in this process only (see Order#modify).
+  class ModificationLimitError < Error; end
   # Raised when the API signals an issue with the requested data payload.
   class DataError < Error; end
 

data/lib/DhanHQ/helpers/request_helper.rb

@@ -39,7 +39,7 @@ module DhanHQ
         "access-token" => token
       }
 
-      # Add client-id for DATA APIs
+      # Add client-id for DATA APIs (now including sandbox profile/funds)
       if data_api?(path)
         client_id = DhanHQ.configuration&.client_id
         unless client_id
@@ -70,19 +70,41 @@ module DhanHQ
     # @param req [Faraday::Request] The request object.
     # @param payload [Hash] The request payload.
     # @param method [Symbol] The HTTP method.
-    def prepare_payload(req, payload, method)
-      return if payload.nil? || payload.empty?
+    def prepare_payload(req, payload, method, path = nil)
+      return if payload.nil? || (payload.empty? && (path.nil? || !data_api?(path)))
 
       unless payload.is_a?(Hash)
         raise DhanHQ::InputExceptionError,
               "Invalid payload: Expected a Hash, got #{payload.class}"
       end
 
+      out = payload
+      if path && %i[post put patch].include?(method)
+        client_id = DhanHQ.configuration&.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
+          if out.keys.any?(String)
+            out["dhanClientId"] = client_id
+          else
+            out[:dhanClientId] = client_id
+          end
+        end
+      end
+
       case method
       when :delete then req.params = {}
-      when :get then req.params = payload
-      else req.body = payload.to_json
+      when :get then req.params = out
+      else req.body = out.to_json
       end
     end
+
+    # True when the path is one where the request body must include dhanClientId (order-api style).
+    def payload_requires_dhan_client_id?(path)
+      return false if path.nil? || path.empty?
+
+      prefixes = DhanHQ::Constants::PAYLOAD_REQUIRES_DHAN_CLIENT_ID_PREFIXES
+      prefixes.any? { |p| path.start_with?(p) }
+    end
   end
 end

data/lib/DhanHQ/helpers/response_helper.rb

@@ -3,6 +3,14 @@
 module DhanHQ
   # Helper mixin for normalising API responses and raising mapped errors.
   module ResponseHelper
+    STATUS_ERROR_FALLBACK = {
+      400 => DhanHQ::InputExceptionError,
+      401 => DhanHQ::InvalidAuthenticationError,
+      403 => DhanHQ::InvalidAccessError,
+      404 => DhanHQ::NotFoundError,
+      429 => DhanHQ::RateLimitError
+    }.freeze
+
     private
 
     # Determines if the API response indicates success.
@@ -53,31 +61,52 @@ module DhanHQ
       end
 
       error_class = DhanHQ::Constants::DHAN_ERROR_MAPPING[error_code]
-
       unless error_class
-        # Log unmapped error codes for investigation
         DhanHQ.logger&.warn("[DhanHQ] Unmapped error code: #{error_code} (status: #{response.status})")
+        error_class = status_fallback_error_class(response.status)
+      end
 
-        error_class =
-          case response.status
-          when 400 then DhanHQ::InputExceptionError
-          when 401 then DhanHQ::InvalidAuthenticationError
-          when 403 then DhanHQ::InvalidAccessError
-          when 404 then DhanHQ::NotFoundError
-          when 429 then DhanHQ::RateLimitError
-          when 500..599 then DhanHQ::InternalServerError
-          else DhanHQ::OtherError
-          end
+      message = build_error_text(error_code, error_message, body)
+      raise error_class.new(message, response_body: body)
+    end
+
+    def status_fallback_error_class(status)
+      STATUS_ERROR_FALLBACK[status] ||
+        (status.between?(500, 599) ? DhanHQ::InternalServerError : DhanHQ::OtherError)
+    end
+
+    def build_error_text(error_code, error_message, body = {})
+      text = if error_code == DhanHQ::Constants::TradingErrorCode::NO_HOLDINGS
+               "#{error_message} (error code: #{error_code})"
+             else
+               "#{error_code}: #{error_message}"
+             end
+
+      extra = extra_error_detail(body)
+      text += " | #{extra}" if extra
+
+      if error_code == DhanHQ::Constants::TradingErrorCode::INPUT_EXCEPTION
+        text += " (API does not return which field failed; check required params and value types for this endpoint.)"
       end
 
-      error_text =
-        if error_code == DhanHQ::Constants::TradingErrorCode::NO_HOLDINGS
-          "#{error_message} (error code: #{error_code})"
-        else
-          "#{error_code}: #{error_message}"
-        end
+      text
+    end
 
-      raise error_class, error_text
+    # Returns any additional error detail from the response body (errors array, details, etc.).
+    def extra_error_detail(body)
+      return nil unless body.is_a?(Hash)
+
+      parts = []
+      if body[:errors].is_a?(Array) && body[:errors].any?
+        parts << body[:errors].join("; ")
+      end
+      if body[:details].is_a?(String) && body[:details].to_s.strip != ""
+        parts << body[:details].to_s
+      end
+      if body[:validationErrors].is_a?(Array) && body[:validationErrors].any?
+        parts << body[:validationErrors].map { |e| e.is_a?(Hash) ? e[:message] || e[:field] : e }.join("; ")
+      end
+      parts.empty? ? nil : parts.join(" ")
     end
 
     # Parses JSON response safely. Converts response body to a hash or array with indifferent access.

data/lib/DhanHQ/helpers/validation_helper.rb

@@ -11,7 +11,9 @@ module DhanHQ
       contract = contract_class.new
       result = contract.call(params)
 
-      raise DhanHQ::Error, "Validation Error: #{result.errors.to_h}" unless result.success?
+      raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}" unless result.success?
+
+      result.to_h
     end
 
     # Validate instance attributes using the defined validation contract
@@ -23,7 +25,7 @@ module DhanHQ
 
       result = contract.call(@attributes)
       @errors = result.errors.to_h unless result.success?
-      raise DhanHQ::Error, "Validation Error: #{@errors}" unless valid?
+      raise DhanHQ::ValidationError, "Invalid parameters: #{@errors}" unless valid?
     end
 
     # Checks if the current instance is valid

data/lib/DhanHQ/models/alert_order.rb

@@ -8,7 +8,7 @@ module DhanHQ
     class AlertOrder < BaseModel
       include Concerns::ApiResponseHandler
 
-      HTTP_PATH = "/alerts/orders"
+      HTTP_PATH = "/v2/alerts/orders"
 
       attributes :alert_id, :exchange_segment, :security_id, :condition,
                  :trigger_price, :order_type, :transaction_type, :quantity,
@@ -37,6 +37,8 @@ module DhanHQ
           return nil unless response.is_a?(Hash) || (response.is_a?(Array) && response.any?)
 
           payload = response.is_a?(Array) ? response.first : response
+          return nil if payload.is_a?(Hash) && payload.empty?
+
           new(payload, skip_validation: true)
         end
 
@@ -65,7 +67,9 @@ module DhanHQ
         #
         def modify(alert_id, params)
           normalized = snake_case(params)
-          response = resource.update(alert_id, camelize_keys(normalized))
+          validate_params!(normalized, DhanHQ::Contracts::AlertOrderContract)
+          payload = normalized.merge(alert_id: alert_id)
+          response = resource.update(alert_id, camelize_keys(payload))
           return nil unless success_response?(response)
 
           find(alert_id)

data/lib/DhanHQ/models/edis.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../contracts/edis_contract"
+
 module DhanHQ
   module Models
     ##
@@ -16,15 +18,15 @@ module DhanHQ
     #     isin: "INE155A01022",
     #     qty: 10,
     #     exchange: "NSE",
-    #     segment: "E",
+    #     segment: "EQ",
     #     bulk: false
     #   )
     #
-    # @example Check EDIS status for a security
+    # @example Check EDIS status for a security (or "ALL" for all holdings)
     #   status = DhanHQ::Models::Edis.inquire(isin: "INE155A01022")
     #
     class Edis < BaseModel
-      HTTP_PATH = "/edis"
+      HTTP_PATH = "/v2/edis"
 
       class << self
         ##
@@ -52,24 +54,26 @@ module DhanHQ
         ##
         # Generate an eDIS form for authorizing sale of holdings.
         #
-        # @param isin [String] ISIN of the security (e.g., "INE155A01022")
+        # @param isin [String] ISIN of the security (e.g. "INE733E01010")
         # @param qty [Integer] Quantity to authorize for sale
-        # @param exchange [String] Exchange name (e.g., "NSE", "BSE")
-        # @param segment [String] Segment identifier (e.g., "E")
-        # @param bulk [Boolean] Whether this is a bulk authorization (default: false)
+        # @param exchange [String] Exchange: "NSE" or "BSE"
+        # @param segment [String] Segment: "EQ", "COMM", or "FNO"
+        # @param bulk [Boolean] If true, mark eDIS for all stocks in portfolio (default: false)
         #
-        # @return [Hash] API response containing the eDIS form data
+        # @return [Hash] API response with dhanClientId and edisFormHtml (escaped HTML to render)
         #
         # @example Authorize sale of 10 shares
         #   DhanHQ::Models::Edis.generate_form(
         #     isin: "INE155A01022",
         #     qty: 10,
         #     exchange: "NSE",
-        #     segment: "E"
+        #     segment: "EQ"
         #   )
         #
         def generate_form(isin:, qty:, exchange:, segment:, bulk: false)
-          resource.form({ isin: isin, qty: qty, exchange: exchange, segment: segment, bulk: bulk })
+          params = { isin: isin, qty: qty, exchange: exchange, segment: segment, bulk: bulk }
+          validate_params!(params, DhanHQ::Contracts::EdisFormContract)
+          resource.form(params)
         end
 
         ##
@@ -85,13 +89,16 @@ module DhanHQ
         ##
         # Check EDIS authorization status for a security.
         #
-        # @param isin [String] ISIN of the security to check
+        # @param isin [String] ISIN of the security, or "ALL" for all holdings
         #
-        # @return [Hash] API response containing authorization status
+        # @return [Hash] API response with clientId, isin, totalQty, aprvdQty, status, remarks
         #
-        # @example Check if EDIS is authorized
+        # @example Check if EDIS is authorized for one security
         #   status = DhanHQ::Models::Edis.inquire(isin: "INE155A01022")
         #
+        # @example Check EDIS status for all holdings
+        #   status = DhanHQ::Models::Edis.inquire(isin: "ALL")
+        #
         def inquire(isin:)
           resource.inquire(isin)
         end

data/lib/DhanHQ/models/expired_options_data.rb

@@ -42,7 +42,12 @@ module DhanHQ
     #   call_data = data.call_data
     #   put_data = data.put_data
     #
+    # @example Normalize to candles
+    #   candles = data.to_candles
+    #
     class ExpiredOptionsData < BaseModel
+      OHLC_FIELDS = %i[open high low close iv volume strike spot oi open_interest].freeze
+
       # All expired options data attributes
       attributes :exchange_segment, :interval, :security_id, :instrument,
                  :expiry_flag, :expiry_code, :strike, :drv_option_type,
@@ -56,63 +61,29 @@ module DhanHQ
         # 31 days in a single request. Historical data is available for up to the last 5 years.
         #
         # @param params [Hash{Symbol => String, Integer, Array<String>}] Request parameters
+        #   @option params [String, Integer] :security_id (required) Underlying exchange standard ID for each scrip
         #   @option params [String] :exchange_segment (required) Exchange and segment identifier.
-        #     Valid values: "NSE_FNO", "BSE_FNO", "NSE_EQ", "BSE_EQ"
-        #   @option params [String] :interval (required) Minute intervals for the timeframe.
-        #     Valid values: "1", "5", "15", "25", "60"
-        #   @option params [Integer] :security_id (required) Underlying exchange standard ID for each scrip
+        #     Valid values: "NSE_FNO", "IDX_I", "NSE_EQ", "BSE_EQ"
         #   @option params [String] :instrument (required) Instrument type of the scrip.
         #     Valid values: "OPTIDX" (Index Options), "OPTSTK" (Stock Options)
+        #   @option params [String, Integer] :interval (required) Minute intervals for the timeframe.
+        #     Valid values: "1", "5", "15", "25", "60"
         #   @option params [String] :expiry_flag (required) Expiry interval of the instrument.
         #     Valid values: "WEEK", "MONTH"
         #   @option params [Integer] :expiry_code (required) Expiry code for the instrument
         #   @option params [String] :strike (required) Strike price specification.
         #     Format: "ATM" for At The Money, "ATM+X" or "ATM-X" for offset strikes.
-        #     For Index Options (near expiry): Up to ATM+10 / ATM-10
-        #     For all other contracts: Up to ATM+3 / ATM-3
-        #   @option params [String] :drv_option_type (required) Option type.
-        #     Valid values: "CALL", "PUT"
+        #   @option params [String] :option_type (required) Option type ("CALL" or "PUT").
         #   @option params [Array<String>] :required_data (required) Array of required data fields.
-        #     Valid values: "open", "high", "low", "close", "iv", "volume", "strike", "oi", "spot"
-        #   @option params [String] :from_date (required) Start date of the desired range in YYYY-MM-DD format.
-        #     Cannot be more than 5 years ago. Same-day ranges are allowed.
-        #   @option params [String] :to_date (required) End date of the desired range (non-inclusive) in YYYY-MM-DD format.
-        #     Date range cannot exceed 31 days from from_date (to_date is non-inclusive). Same-day `from_date`/`to_date` is valid.
+        #   @option params [String] :from_date (required) Start date in YYYY-MM-DD format.
+        #   @option params [String] :to_date (required) End date in YYYY-MM-DD format.
         #
         # @return [ExpiredOptionsData] Expired options data object with fetched data
-        #
-        # @example Fetch NIFTY index options data
-        #   data = DhanHQ::Models::ExpiredOptionsData.fetch(
-        #     exchange_segment: "NSE_FNO",
-        #     interval: "1",
-        #     security_id: 13,
-        #     instrument: "OPTIDX",
-        #     expiry_flag: "MONTH",
-        #     expiry_code: 1,
-        #     strike: "ATM",
-        #     drv_option_type: "CALL",
-        #     required_data: ["open", "high", "low", "close", "volume", "iv", "oi", "spot"],
-        #     from_date: "2021-08-01",
-        #     to_date: "2021-09-01"
-        #   )
-        #
-        # @example Fetch stock options data for ATM+2 strike
-        #   data = DhanHQ::Models::ExpiredOptionsData.fetch(
-        #     exchange_segment: "NSE_FNO",
-        #     interval: "15",
-        #     security_id: 11536,
-        #     instrument: "OPTSTK",
-        #     expiry_flag: "WEEK",
-        #     expiry_code: 0,
-        #     strike: "ATM+2",
-        #     drv_option_type: "PUT",
-        #     required_data: ["open", "high", "low", "close", "volume"],
-        #     from_date: "2024-01-01",
-        #     to_date: "2024-01-31"
-        #   )
-        #
         # @raise [DhanHQ::ValidationError] If validation fails for any parameter
         def fetch(params)
+          # Map option_type to drv_option_type if provided
+          params[:drv_option_type] ||= params[:option_type] if params.key?(:option_type)
+
           normalized = normalize_params(params)
           validate_params(normalized)
 
@@ -120,6 +91,8 @@ module DhanHQ
           new(response.merge(normalized), skip_validation: true)
         end
 
+        alias rolling fetch
+
         private
 
         def expired_options_resource
@@ -180,6 +153,43 @@ module DhanHQ
         end
       end
 
+      ##
+      # Normalizes the columnar response into an array of candle hashes.
+      #
+      # @param option_type [String, nil] Option type to retrieve ("CALL" or "PUT").
+      #   If nil, uses the {#drv_option_type} from the request.
+      # @return [Array<Hash>] Normalized array of candles.
+      def to_candles(option_type = nil)
+        option_type ||= drv_option_type
+        opt_data = data_for_type(option_type)
+        return [] unless opt_data.is_a?(Hash)
+
+        # Standardize keys to symbols
+        opt_data = opt_data.transform_keys(&:to_sym)
+        ts_arr = opt_data[:timestamp]
+        return [] unless ts_arr.is_a?(Array)
+
+        type_sym = option_type.to_s.downcase.to_sym
+
+        ts_arr.each_with_index.map do |ts, i|
+          candle = {
+            option_type: type_sym,
+            timestamp: ts.is_a?(Numeric) ? Time.at(ts) : ts
+          }
+
+          # Map requested fields
+          OHLC_FIELDS.each do |field|
+            val_arr = opt_data[field]
+            next unless val_arr.is_a?(Array)
+
+            # Map 'oi' to 'open_interest' if requested
+            target_field = field == :oi ? :open_interest : field
+            candle[target_field] = val_arr[i]
+          end
+          candle
+        end
+      end
+
       ##
       # Gets call option data from the response.
       #

data/lib/DhanHQ/models/forever_order.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../contracts/forever_order_contract"
+
 module DhanHQ
   module Models
     ##
@@ -154,9 +156,9 @@ module DhanHQ
         #   @option params [String] :transaction_type (required) The trading side of transaction.
         #     Valid values: "BUY", "SELL"
         #   @option params [String] :exchange_segment (required) Exchange and segment identifier.
-        #     Valid values: "NSE_EQ", "NSE_FNO", "BSE_EQ", "BSE_FNO"
+        #     Valid values: See {DhanHQ::Constants::FOREVER_ORDER_SEGMENTS} (NSE_EQ, NSE_FNO, BSE_EQ, BSE_FNO, MCX_COMM)
         #   @option params [String] :product_type (required) Product type.
-        #     Valid values: "CNC", "MTF"
+        #     Valid values: See {DhanHQ::Constants::FOREVER_ORDER_PRODUCT_TYPES} (CNC, MTF)
         #   @option params [String] :order_type (required) Order type.
         #     Valid values: "LIMIT", "MARKET"
         #   @option params [String] :validity (required) Validity of order for execution.
@@ -216,10 +218,12 @@ module DhanHQ
         #
         # @note Order placement APIs require Static IP whitelisting
         def create(params)
-          # Normalize params and auto-inject dhan_client_id from configuration if not provided
-          normalized_params = snake_case(params)
-          normalized_params[:dhan_client_id] ||= DhanHQ.configuration.client_id if DhanHQ.configuration.client_id
-          response = resource.create(normalized_params)
+          normalized = snake_case(params)
+          config = DhanHQ.configuration
+          normalized[:dhan_client_id] ||= config.client_id if config&.client_id
+          validate_params!(normalized, DhanHQ::Contracts::ForeverOrderCreateContract)
+          formatted = camelize_keys(normalized)
+          response = resource.create(formatted)
           return nil unless response.is_a?(Hash) && response["orderId"]
 
           find(response["orderId"])
@@ -291,7 +295,13 @@ module DhanHQ
         raise "Order ID is required to modify a forever order" unless order_id
 
         DhanHQ.logger&.info("[DhanHQ::Models::ForeverOrder] Modifying order #{order_id}")
-        response = self.class.resource.update(order_id, new_params)
+        full_params = snake_case(new_params)
+        config = DhanHQ.configuration
+        full_params[:dhan_client_id] ||= config.client_id if config&.client_id
+        full_params[:order_id] = order_id
+        validate_params!(full_params, DhanHQ::Contracts::ForeverOrderModifyContract)
+        formatted = camelize_keys(full_params)
+        response = self.class.resource.update(order_id, formatted)
         ctx = "[DhanHQ::Models::ForeverOrder] Modification"
         success = handle_api_response(response, success_key: "orderId", context: ctx)
         return self.class.find(order_id) if success