DhanHQ 2.1.8 → 2.1.10

data/lib/DhanHQ/models/margin.rb

@@ -2,7 +2,47 @@
 
 module DhanHQ
   module Models
-    # Model for the on-demand margin calculator response.
+    ##
+    # Model for fetching margin calculation results for orders.
+    #
+    # The Margin Calculator API provides span margin, exposure margin, VAR (variable margin),
+    # brokerage, leverage, and available margin values for any type of order and instrument
+    # you want to place. This helps you determine the margin requirements before placing an order.
+    #
+    # @example Calculate margin for a CNC order
+    #   margin = DhanHQ::Models::Margin.calculate(
+    #     dhan_client_id: "1000000132",
+    #     exchange_segment: "NSE_EQ",
+    #     transaction_type: "BUY",
+    #     quantity: 5,
+    #     product_type: "CNC",
+    #     security_id: "1333",
+    #     price: 1428.0
+    #   )
+    #   puts "Total margin required: ₹#{margin.total_margin}"
+    #   puts "Available balance: ₹#{margin.available_balance}"
+    #
+    # @example Calculate margin for stop-loss order
+    #   margin = DhanHQ::Models::Margin.calculate(
+    #     dhan_client_id: "1000000132",
+    #     exchange_segment: "NSE_EQ",
+    #     transaction_type: "BUY",
+    #     quantity: 10,
+    #     product_type: "INTRADAY",
+    #     security_id: "1333",
+    #     price: 1428.0,
+    #     trigger_price: 1427.0
+    #   )
+    #   puts "Leverage: #{margin.leverage}x"
+    #
+    # @example Check if sufficient margin is available
+    #   margin = DhanHQ::Models::Margin.calculate(params)
+    #   if margin.insufficient_balance > 0
+    #     puts "Insufficient balance: ₹#{margin.insufficient_balance}"
+    #   else
+    #     puts "Sufficient margin available"
+    #   end
+    #
     class Margin < BaseModel
       # Base path used to invoke the calculator.
       HTTP_PATH = "/v2/margincalculator"
@@ -12,18 +52,86 @@ module DhanHQ
 
       class << self
         ##
-        # Provides a **shared instance** of the `MarginCalculator` resource.
+        # Provides a shared instance of the MarginCalculator resource.
         #
-        # @return [DhanHQ::Resources::MarginCalculator]
+        # @return [DhanHQ::Resources::MarginCalculator] The MarginCalculator resource client instance
         def resource
           @resource ||= DhanHQ::Resources::MarginCalculator.new
         end
 
         ##
-        # Calculate margin requirements for an order.
+        # Calculates margin requirements for an order before placement.
         #
-        # @param params [Hash] Request parameters for margin calculation.
-        # @return [Margin]
+        # Fetches span margin, exposure margin, VAR (variable margin), brokerage, leverage,
+        # and available margin values for the specified order parameters. This allows you to
+        # check margin requirements and availability before actually placing the order.
+        #
+        # @param params [Hash{Symbol => String, Integer, Float}] Request parameters for margin calculation
+        #   @option params [String] :dhan_client_id (required) User-specific identification generated by Dhan.
+        #     Must be explicitly provided in the params hash
+        #   @option params [String] :exchange_segment (required) Exchange and segment identifier.
+        #     Valid values: "NSE_EQ", "NSE_FNO", "BSE_EQ", "BSE_FNO", "MCX_COMM"
+        #   @option params [String] :transaction_type (required) The trading side of transaction.
+        #     Valid values: "BUY", "SELL"
+        #   @option params [Integer] :quantity (required) Number of shares for the order. Must be greater than 0
+        #   @option params [String] :product_type (required) Product type.
+        #     Valid values: "CNC", "INTRADAY", "MARGIN", "MTF", "CO", "BO"
+        #   @option params [String] :security_id (required) Exchange standard ID for each scrip
+        #   @option params [Float] :price (required) Price at which order is placed. Must be greater than 0
+        #   @option params [Float] :trigger_price (conditionally required) Price at which the order is triggered.
+        #     Required for STOP_LOSS and STOP_LOSS_MARKET order types
+        #
+        # @return [Margin] Margin object containing margin calculation results.
+        #   Response structure (keys normalized to snake_case):
+        #   - **:total_margin** [Float] Total margin required for placing the order successfully
+        #   - **:span_margin** [Float] SPAN margin required
+        #   - **:exposure_margin** [Float] Exposure margin required
+        #   - **:available_balance** [Float] Available amount in trading account
+        #   - **:variable_margin** [Float] VAR or Variable margin required
+        #   - **:insufficient_balance** [Float] Insufficient amount in trading account
+        #     (Available Balance - Total Margin). Negative or zero indicates sufficient margin
+        #   - **:brokerage** [Float] Brokerage charges for executing the order
+        #   - **:leverage** [String] Margin leverage provided for the order as per product type
+        #
+        # @example Calculate margin for CNC equity order
+        #   margin = DhanHQ::Models::Margin.calculate(
+        #     dhan_client_id: "1000000132",
+        #     exchange_segment: "NSE_EQ",
+        #     transaction_type: "BUY",
+        #     quantity: 5,
+        #     product_type: "CNC",
+        #     security_id: "1333",
+        #     price: 1428.0
+        #   )
+        #   puts "Total Margin: ₹#{margin.total_margin}"
+        #   puts "Brokerage: ₹#{margin.brokerage}"
+        #
+        # @example Calculate margin for intraday order
+        #   margin = DhanHQ::Models::Margin.calculate(
+        #     dhan_client_id: "1000000132",
+        #     exchange_segment: "NSE_EQ",
+        #     transaction_type: "SELL",
+        #     quantity: 10,
+        #     product_type: "INTRADAY",
+        #     security_id: "1333",
+        #     price: 1500.0
+        #   )
+        #   puts "Leverage: #{margin.leverage}x"
+        #   puts "SPAN Margin: ₹#{margin.span_margin}"
+        #
+        # @example Calculate margin for stop-loss order
+        #   margin = DhanHQ::Models::Margin.calculate(
+        #     dhan_client_id: "1000000132",
+        #     exchange_segment: "NSE_EQ",
+        #     transaction_type: "BUY",
+        #     quantity: 5,
+        #     product_type: "INTRADAY",
+        #     security_id: "1333",
+        #     price: 1428.0,
+        #     trigger_price: 1427.0
+        #   )
+        #
+        # @raise [DhanHQ::ValidationError] If validation fails for any parameter
         def calculate(params)
           formatted_params = camelize_keys(params)
           validate_params!(formatted_params, DhanHQ::Contracts::MarginCalculatorContract)
@@ -34,9 +142,26 @@ module DhanHQ
       end
 
       ##
-      # Convert model attributes to a hash.
+      # Converts the Margin model attributes to a hash representation.
+      #
+      # Useful for serialization, logging, or passing margin data to other methods.
+      #
+      # @return [Hash{Symbol => Float, String}] Hash representation of the Margin model containing:
+      #   - **:total_margin** [Float] Total margin required
+      #   - **:span_margin** [Float] SPAN margin
+      #   - **:exposure_margin** [Float] Exposure margin
+      #   - **:available_balance** [Float] Available balance
+      #   - **:variable_margin** [Float] Variable margin
+      #   - **:insufficient_balance** [Float] Insufficient balance amount
+      #   - **:brokerage** [Float] Brokerage charges
+      #   - **:leverage** [String] Leverage as string
+      #
+      # @example Convert margin to hash
+      #   margin = DhanHQ::Models::Margin.calculate(params)
+      #   margin_hash = margin.to_h
+      #   puts margin_hash[:total_margin]  # => 2800.00
+      #   puts margin_hash[:leverage]       # => "4.00"
       #
-      # @return [Hash] Hash representation of the Margin model.
       def to_h
         {
           total_margin: total_margin,

data/lib/DhanHQ/models/market_feed.rb

@@ -2,39 +2,203 @@
 
 module DhanHQ
   module Models
-    # Lightweight wrapper exposing market feed resources.
+    ##
+    # Model for fetching real-time market snapshots for multiple instruments.
+    #
+    # The Market Feed API provides snapshots of multiple instruments at once. You can fetch
+    # LTP (Last Traded Price), OHLC (Open, High, Low, Close), or Market Depth (quote) data
+    # for instruments via a single API request. Data is returned in real-time at the time
+    # of the API request.
+    #
+    # @note **Rate Limits**: You can fetch up to 1000 instruments in a single API request
+    #   with a rate limit of 1 request per second. The client's internal rate limiter
+    #   automatically throttles calls to prevent exceeding limits.
+    #
+    # @example Fetch LTP for multiple instruments
+    #   payload = {
+    #     "NSE_EQ" => [11536, 3456],
+    #     "NSE_FNO" => [49081, 49082]
+    #   }
+    #   response = DhanHQ::Models::MarketFeed.ltp(payload)
+    #   nse_eq_data = response[:data]["NSE_EQ"]
+    #   puts "TCS LTP: ₹#{nse_eq_data["11536"][:last_price]}"
+    #
+    # @example Fetch OHLC data for equity instruments
+    #   payload = {
+    #     "NSE_EQ" => [11536]
+    #   }
+    #   response = DhanHQ::Models::MarketFeed.ohlc(payload)
+    #   tcs_data = response[:data]["NSE_EQ"]["11536"]
+    #   puts "Open: ₹#{tcs_data[:ohlc][:open]}"
+    #   puts "High: ₹#{tcs_data[:ohlc][:high]}"
+    #
+    # @example Fetch full market depth quote
+    #   payload = {
+    #     "NSE_FNO" => [49081]
+    #   }
+    #   response = DhanHQ::Models::MarketFeed.quote(payload)
+    #   quote_data = response[:data]["NSE_FNO"]["49081"]
+    #   puts "Volume: #{quote_data[:volume]}"
+    #   puts "Open Interest: #{quote_data[:oi]}"
+    #
     class MarketFeed < BaseModel
       class << self
-        # Fetches last traded price snapshots.
+        ##
+        # Provides a shared instance of the MarketFeed resource.
+        #
+        # @return [DhanHQ::Resources::MarketFeed] The MarketFeed resource client instance
+        def resource
+          @resource ||= DhanHQ::Resources::MarketFeed.new
+        end
+
+        ##
+        # Fetches Last Traded Price (LTP) snapshots for multiple instruments.
+        #
+        # Retrieves the last traded price for a list of instruments with a single API request.
+        # Supports up to 1000 instruments per request, organized by exchange segment.
+        #
+        # @param params [Hash{String => Array<Integer>}] Request payload mapping exchange segments
+        #   to arrays of security IDs. Exchange segments are keys (e.g., "NSE_EQ", "NSE_FNO", "BSE_EQ").
+        #   Values are arrays of security IDs (integer identifiers for each scrip).
+        #   Valid exchange segment values: "NSE_EQ", "NSE_FNO", "BSE_EQ", "BSE_FNO", etc.
+        #
+        # @return [HashWithIndifferentAccess] Response hash containing market data.
+        #   Response structure:
+        #   - **:data** [Hash{String => Hash{String => Hash}}] Market data organized by exchange segment
+        #     and security ID. Each instrument's data contains:
+        #     - **:last_price** [Float] Last traded price of the instrument
+        #   - **:status** [String] Response status (typically "success")
+        #
+        # @example Fetch LTP for equity and F&O instruments
+        #   payload = {
+        #     "NSE_EQ" => [11536],
+        #     "NSE_FNO" => [49081, 49082]
+        #   }
+        #   response = DhanHQ::Models::MarketFeed.ltp(payload)
+        #   tcs_ltp = response[:data]["NSE_EQ"]["11536"][:last_price]
+        #   puts "TCS LTP: ₹#{tcs_ltp}"
+        #
+        # @example Access data from response
+        #   response = DhanHQ::Models::MarketFeed.ltp("NSE_EQ" => [11536])
+        #   data = response[:data]["NSE_EQ"]["11536"]
+        #   puts "Last Price: ₹#{data[:last_price]}"
         #
-        # @param params [Hash]
-        # @return [Hash]
         def ltp(params)
           resource.ltp(params)
         end
 
-        # Fetches OHLC data for the requested instruments.
+        ##
+        # Fetches OHLC (Open, High, Low, Close) data along with LTP for specified instruments.
+        #
+        # Retrieves the open, high, low, and close prices along with the last traded price
+        # for a list of instruments. Supports up to 1000 instruments per request.
+        #
+        # @param params [Hash{String => Array<Integer>}] Request payload mapping exchange segments
+        #   to arrays of security IDs. Exchange segments are keys (e.g., "NSE_EQ", "NSE_FNO", "BSE_EQ").
+        #   Values are arrays of security IDs (integer identifiers for each scrip).
+        #   Valid exchange segment values: "NSE_EQ", "NSE_FNO", "BSE_EQ", "BSE_FNO", etc.
+        #
+        # @return [HashWithIndifferentAccess] Response hash containing OHLC market data.
+        #   Response structure:
+        #   - **:data** [Hash{String => Hash{String => Hash}}] Market data organized by exchange segment
+        #     and security ID. Each instrument's data contains:
+        #     - **:last_price** [Float] Last traded price of the instrument
+        #     - **:ohlc** [Hash{Symbol => Float}] OHLC data:
+        #       - **:open** [Float] Market opening price of the day
+        #       - **:close** [Float] Market closing price of the day (previous day close for current session)
+        #       - **:high** [Float] Day high price
+        #       - **:low** [Float] Day low price
+        #   - **:status** [String] Response status (typically "success")
+        #
+        # @note For newly listed instruments or instruments without trading activity,
+        #   OHLC values may be 0. The close price typically represents the previous day's
+        #   closing price during the current trading session.
+        #
+        # @example Fetch OHLC for equity instruments
+        #   payload = {
+        #     "NSE_EQ" => [11536]
+        #   }
+        #   response = DhanHQ::Models::MarketFeed.ohlc(payload)
+        #   tcs_data = response[:data]["NSE_EQ"]["11536"]
+        #   puts "Open: ₹#{tcs_data[:ohlc][:open]}"
+        #   puts "High: ₹#{tcs_data[:ohlc][:high]}"
+        #   puts "Low: ₹#{tcs_data[:ohlc][:low]}"
+        #   puts "Close: ₹#{tcs_data[:ohlc][:close]}"
+        #   puts "LTP: ₹#{tcs_data[:last_price]}"
         #
-        # @param params [Hash]
-        # @return [Hash]
         def ohlc(params)
           resource.ohlc(params)
         end
 
-        # Fetches full quote depth and analytics.
+        ##
+        # Fetches full market depth data including OHLC, Open Interest, Volume, and order book depth.
+        #
+        # Retrieves comprehensive market data including market depth (buy/sell orders), OHLC data,
+        # Open Interest (for derivatives), Volume, circuit limits, and other trading analytics
+        # for specified instruments. Supports up to 1000 instruments per request.
+        #
+        # @param params [Hash{String => Array<Integer>}] Request payload mapping exchange segments
+        #   to arrays of security IDs. Exchange segments are keys (e.g., "NSE_EQ", "NSE_FNO", "BSE_EQ").
+        #   Values are arrays of security IDs (integer identifiers for each scrip).
+        #   Valid exchange segment values: "NSE_EQ", "NSE_FNO", "BSE_EQ", "BSE_FNO", etc.
+        #
+        # @return [HashWithIndifferentAccess] Response hash containing full quote market data.
+        #   Response structure:
+        #   - **:data** [Hash{String => Hash{String => Hash}}] Market data organized by exchange segment
+        #     and security ID. Each instrument's data contains:
+        #     - **:last_price** [Float] Last traded price of the instrument
+        #     - **:last_quantity** [Integer] Last traded quantity
+        #     - **:last_trade_time** [String] Timestamp of last trade in "DD/MM/YYYY HH:MM:SS" format
+        #     - **:average_price** [Float] Volume weighted average price (VWAP) of the day
+        #     - **:buy_quantity** [Integer] Total buy order quantity pending at the exchange
+        #     - **:sell_quantity** [Integer] Total sell order quantity pending at the exchange
+        #     - **:volume** [Integer] Total traded volume for the day
+        #     - **:oi** [Integer] Open Interest in the contract (for derivatives)
+        #     - **:oi_day_high** [Integer] Highest Open Interest for the day (only for NSE_FNO)
+        #     - **:oi_day_low** [Integer] Lowest Open Interest for the day (only for NSE_FNO)
+        #     - **:net_change** [Float] Absolute change in LTP from previous day closing price
+        #     - **:upper_circuit_limit** [Float] Current upper circuit limit
+        #     - **:lower_circuit_limit** [Float] Current lower circuit limit
+        #     - **:ohlc** [Hash{Symbol => Float}] OHLC data:
+        #       - **:open** [Float] Market opening price of the day
+        #       - **:close** [Float] Market closing price of the day
+        #       - **:high** [Float] Day high price
+        #       - **:low** [Float] Day low price
+        #     - **:depth** [Hash{Symbol => Array<Hash>}] Market depth (order book) data:
+        #       - **:buy** [Array<Hash{Symbol => Integer, Float}>] Buy side depth levels (up to 5 levels):
+        #         - **:quantity** [Integer] Number of quantity at this price depth
+        #         - **:orders** [Integer] Number of open BUY orders at this price depth
+        #         - **:price** [Float] Price at which the BUY depth stands
+        #       - **:sell** [Array<Hash{Symbol => Integer, Float}>] Sell side depth levels (up to 5 levels):
+        #         - **:quantity** [Integer] Number of quantity at this price depth
+        #         - **:orders** [Integer] Number of open SELL orders at this price depth
+        #         - **:price** [Float] Price at which the SELL depth stands
+        #   - **:status** [String] Response status (typically "success")
+        #
+        # @note This endpoint uses a separate quote API with stricter rate limits (1 request per second).
+        #   The client automatically handles rate limiting for quote requests.
+        #
+        # @example Fetch full quote for futures contract
+        #   payload = {
+        #     "NSE_FNO" => [49081]
+        #   }
+        #   response = DhanHQ::Models::MarketFeed.quote(payload)
+        #   quote = response[:data]["NSE_FNO"]["49081"]
+        #   puts "LTP: ₹#{quote[:last_price]}"
+        #   puts "Volume: #{quote[:volume]}"
+        #   puts "Open Interest: #{quote[:oi]}"
+        #   puts "Day High OI: #{quote[:oi_day_high]}"
+        #
+        # @example Access market depth (order book)
+        #   response = DhanHQ::Models::MarketFeed.quote("NSE_FNO" => [49081])
+        #   quote = response[:data]["NSE_FNO"]["49081"]
+        #   buy_depth = quote[:depth][:buy]
+        #   puts "Best Buy Price: ₹#{buy_depth[0][:price]}"
+        #   puts "Best Buy Quantity: #{buy_depth[0][:quantity]}"
         #
-        # @param params [Hash]
-        # @return [Hash]
         def quote(params)
           resource.quote(params)
         end
-
-        # Shared market feed resource instance.
-        #
-        # @return [DhanHQ::Resources::MarketFeed]
-        def resource
-          @resource ||= DhanHQ::Resources::MarketFeed.new
-        end
       end
     end
   end

data/lib/DhanHQ/models/option_chain.rb

@@ -4,22 +4,151 @@ require_relative "../contracts/option_chain_contract"
 
 module DhanHQ
   module Models
-    # Model for fetching and filtering option chain snapshots.
+    ##
+    # Model for fetching option chain data for any option instrument across exchanges.
+    #
+    # The Option Chain API provides the entire option chain for any underlying instrument
+    # across NSE, BSE, and MCX exchanges. For each strike price, you get Open Interest (OI),
+    # Greeks (Delta, Theta, Gamma, Vega), Volume, Last Traded Price, Best Bid/Ask prices,
+    # Implied Volatility (IV), and other option analytics.
+    #
+    # @note **Rate Limits**: You can call the Option Chain API once every 3 seconds.
+    #   This rate limit is enforced because OI data updates slowly compared to LTP or
+    #   other data parameters. The client's internal rate limiter automatically throttles
+    #   calls to prevent exceeding limits.
+    #
+    # @note **Data Filtering**: The model automatically filters out strikes where both
+    #   Call (CE) and Put (PE) options have zero `last_price`, keeping the payload compact
+    #   and focused on actively traded strikes.
+    #
+    # @example Fetch option chain for NIFTY index options
+    #   chain = DhanHQ::Models::OptionChain.fetch(
+    #     underlying_scrip: 13,
+    #     underlying_seg: "IDX_I",
+    #     expiry: "2024-10-31"
+    #   )
+    #   puts "Underlying LTP: ₹#{chain[:last_price]}"
+    #   nifty_25000 = chain[:oc]["25000.000000"]
+    #   puts "CE LTP: ₹#{nifty_25000['ce'][:last_price]}"
+    #   puts "CE OI: #{nifty_25000['ce'][:oi]}"
+    #
+    # @example Fetch expiry list for an underlying
+    #   expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
+    #     underlying_scrip: 13,
+    #     underlying_seg: "IDX_I"
+    #   )
+    #   expiries.each { |expiry| puts expiry }
+    #
+    # @example Access Greeks for a strike
+    #   chain = DhanHQ::Models::OptionChain.fetch(
+    #     underlying_scrip: 1333,
+    #     underlying_seg: "NSE_FNO",
+    #     expiry: "2024-12-26"
+    #   )
+    #   strike_data = chain[:oc]["25000.000000"]
+    #   ce_greeks = strike_data['ce'][:greeks]
+    #   puts "Delta: #{ce_greeks[:delta]}"
+    #   puts "Gamma: #{ce_greeks[:gamma]}"
+    #   puts "Theta: #{ce_greeks[:theta]}"
+    #   puts "Vega: #{ce_greeks[:vega]}"
+    #
     class OptionChain < BaseModel
       attr_reader :underlying_scrip, :underlying_seg, :expiry, :last_price, :option_data
 
       class << self
-        # Shared resource for option chain operations.
+        ##
+        # Provides a shared instance of the OptionChain resource.
         #
-        # @return [DhanHQ::Resources::OptionChain]
+        # @return [DhanHQ::Resources::OptionChain] The OptionChain resource client instance
         def resource
           @resource ||= DhanHQ::Resources::OptionChain.new
         end
 
-        # Fetch the entire option chain for an instrument
+        ##
+        # Fetches the entire option chain for a specified underlying instrument and expiry.
         #
-        # @param params [Hash] The request parameters (snake_case format)
-        # @return [HashWithIndifferentAccess] The filtered option chain data
+        # Retrieves real-time option chain data across all strikes for the given underlying.
+        # The response includes Open Interest (OI), Greeks, Volume, Last Traded Price,
+        # Best Bid/Ask prices, Implied Volatility (IV), and other option analytics for
+        # both Call (CE) and Put (PE) options at each strike price.
+        #
+        # @param params [Hash{Symbol => Integer, String}] Request parameters for option chain
+        #   @option params [Integer] :underlying_scrip (required) Security ID of the underlying
+        #     instrument. Can be found via the Instruments API.
+        #   @option params [String] :underlying_seg (required) Exchange and segment of underlying
+        #     for which data is to be fetched.
+        #     Valid values: "IDX_I" (Index), "NSE_FNO" (NSE F&O), "BSE_FNO" (BSE F&O), "MCX_FO" (MCX)
+        #   @option params [String] :expiry (required) Expiry date of the option contract for
+        #     which the option chain is requested. Must be in "YYYY-MM-DD" format.
+        #     List of active expiries can be fetched using {fetch_expiry_list}.
+        #
+        # @return [HashWithIndifferentAccess] Filtered option chain data.
+        #   Response structure:
+        #   - **:last_price** [Float] Last Traded Price (LTP) of the underlying instrument
+        #   - **:oc** [Hash{String => Hash}] Option chain data organized by strike price.
+        #     Strike prices are stored as string keys (e.g., "25000.000000").
+        #     Each strike contains:
+        #     - **"ce"** [Hash{Symbol => Float, Integer, Hash}] Call Option data for this strike:
+        #       - **:greeks** [Hash{Symbol => Float}] Option Greeks:
+        #         - **:delta** [Float] Measures the change of option's premium based on
+        #           every 1 rupee change in underlying
+        #         - **:theta** [Float] Measures how quickly an option's value decreases over time
+        #         - **:gamma** [Float] Rate of change in an option's delta in relation to the
+        #           price of the underlying asset
+        #         - **:vega** [Float] Measures the change of option's premium in response to
+        #           a 1% change in implied volatility
+        #       - **:implied_volatility** [Float] Value of expected volatility of a stock
+        #         over the life of the option
+        #       - **:last_price** [Float] Last Traded Price of the Call Option Instrument
+        #       - **:oi** [Integer] Open Interest of the Call Option Instrument
+        #       - **:previous_close_price** [Float] Previous day close price
+        #       - **:previous_oi** [Integer] Previous day Open Interest
+        #       - **:previous_volume** [Integer] Previous day volume
+        #       - **:top_ask_price** [Float] Current best ask price available
+        #       - **:top_ask_quantity** [Integer] Quantity available at current best ask price
+        #       - **:top_bid_price** [Float] Current best bid price available
+        #       - **:top_bid_quantity** [Integer] Quantity available at current best bid price
+        #       - **:volume** [Integer] Day volume for Call Option Instrument
+        #     - **"pe"** [Hash{Symbol => Float, Integer, Hash}] Put Option data for this strike.
+        #       Contains the same fields as "ce" (Call Option data).
+        #
+        # @note Strikes where both CE and PE have zero `last_price` are automatically filtered out.
+        #   This keeps the payload compact and focused on actively traded strikes.
+        #
+        # @example Fetch option chain for NIFTY index options
+        #   chain = DhanHQ::Models::OptionChain.fetch(
+        #     underlying_scrip: 13,
+        #     underlying_seg: "IDX_I",
+        #     expiry: "2024-10-31"
+        #   )
+        #   puts "NIFTY LTP: ₹#{chain[:last_price]}"
+        #
+        # @example Access Call and Put data for a specific strike
+        #   chain = DhanHQ::Models::OptionChain.fetch(
+        #     underlying_scrip: 13,
+        #     underlying_seg: "IDX_I",
+        #     expiry: "2024-10-31"
+        #   )
+        #   strike_25000 = chain[:oc]["25000.000000"]
+        #   ce_data = strike_25000["ce"]
+        #   pe_data = strike_25000["pe"]
+        #   puts "CE LTP: ₹#{ce_data[:last_price]}, OI: #{ce_data[:oi]}"
+        #   puts "PE LTP: ₹#{pe_data[:last_price]}, OI: #{pe_data[:oi]}"
+        #
+        # @example Calculate OI change and analyze Greeks
+        #   chain = DhanHQ::Models::OptionChain.fetch(
+        #     underlying_scrip: 1333,
+        #     underlying_seg: "NSE_FNO",
+        #     expiry: "2024-12-26"
+        #   )
+        #   strike_data = chain[:oc]["25000.000000"]
+        #   ce = strike_data["ce"]
+        #   oi_change = ce[:oi] - ce[:previous_oi]
+        #   puts "OI Change: #{oi_change}"
+        #   puts "Delta: #{ce[:greeks][:delta]}"
+        #   puts "IV: #{ce[:implied_volatility]}%"
+        #
+        # @raise [DhanHQ::ValidationError] If validation fails for any parameter or date format
         def fetch(params)
           validate_params!(params, DhanHQ::Contracts::OptionChainContract)
 
@@ -29,10 +158,44 @@ module DhanHQ
           filter_valid_strikes(response[:data]).with_indifferent_access
         end
 
-        # Fetch the expiry list of an underlying security
+        ##
+        # Fetches the list of active expiry dates for an underlying instrument.
         #
-        # @param params [Hash] The request parameters (snake_case format)
-        # @return [Array<String>] The list of expiry dates
+        # Retrieves all expiry dates for which option instruments are active for the given
+        # underlying. This list is useful for selecting valid expiry dates when fetching
+        # option chains.
+        #
+        # @param params [Hash{Symbol => Integer, String}] Request parameters for expiry list
+        #   @option params [Integer] :underlying_scrip (required) Security ID of the underlying
+        #     instrument. Can be found via the Instruments API.
+        #   @option params [String] :underlying_seg (required) Exchange and segment of underlying
+        #     for which expiry list is to be fetched.
+        #     Valid values: "IDX_I" (Index), "NSE_FNO" (NSE F&O), "BSE_FNO" (BSE F&O), "MCX_FO" (MCX)
+        #
+        # @return [Array<String>] Array of expiry dates in "YYYY-MM-DD" format.
+        #   Returns empty array if the API response status is not "success" or if no expiries are found.
+        #
+        # @example Fetch expiry list for NIFTY index
+        #   expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
+        #     underlying_scrip: 13,
+        #     underlying_seg: "IDX_I"
+        #   )
+        #   puts "Available expiries:"
+        #   expiries.each { |expiry| puts "  #{expiry}" }
+        #
+        # @example Use expiry list to fetch option chains
+        #   expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
+        #     underlying_scrip: 1333,
+        #     underlying_seg: "NSE_FNO"
+        #   )
+        #   nearest_expiry = expiries.first
+        #   chain = DhanHQ::Models::OptionChain.fetch(
+        #     underlying_scrip: 1333,
+        #     underlying_seg: "NSE_FNO",
+        #     expiry: nearest_expiry
+        #   )
+        #
+        # @raise [DhanHQ::ValidationError] If validation fails for any parameter
         def fetch_expiry_list(params)
           validate_params!(params, DhanHQ::Contracts::OptionChainExpiryListContract)
 
@@ -42,10 +205,17 @@ module DhanHQ
 
         private
 
-        # **Filters valid strikes where `ce` or `pe` has `last_price > 0` and keeps strike prices as-is**
+        ##
+        # Filters valid strikes where at least one of CE or PE has a non-zero last_price.
+        #
+        # Removes strikes from the option chain where both Call (CE) and Put (PE) options
+        # have zero `last_price`, keeping only actively traded strikes. This keeps the
+        # payload compact and focused on relevant data.
+        #
+        # @param data [Hash] The API response data containing option chain information
+        # @return [Hash] The filtered option chain data with original strike price keys preserved
         #
-        # @param data [Hash] The API response data
-        # @return [Hash] The filtered option chain data with original strike price keys
+        # @api private
         def filter_valid_strikes(data)
           return {} unless data.is_a?(Hash) && data.key?(:oc)
 
@@ -63,6 +233,7 @@ module DhanHQ
         # Validation contract for option chain
         #
         # @return [DhanHQ::Contracts::OptionChainContract]
+        # @api private
         def validation_contract
           DhanHQ::Contracts::OptionChainContract.new
         end
@@ -73,6 +244,7 @@ module DhanHQ
       # Validation contract for option chain
       #
       # @return [DhanHQ::Contracts::OptionChainContract]
+      # @api private
       def validation_contract
         DhanHQ::Contracts::OptionChainContract.new
       end