DhanHQ 2.1.8 → 2.1.10

data/lib/DhanHQ/models/historical_data.rb

@@ -3,72 +3,189 @@
 module DhanHQ
   module Models
     ##
-    # Model class for fetching Daily & Intraday data
-    # The default response is a Hash with arrays of "open", "high", "low", etc.
+    # Model for fetching historical candle data (OHLC) for desired instruments across segments and exchanges.
+    #
+    # This API provides historical price data in the form of candlestick data with timestamp, open, high, low,
+    # close, and volume information. Data is available in two formats:
+    # - **Daily**: Daily candle data available back to the date of instrument inception
+    # - **Intraday**: Minute-level candle data (1, 5, 15, 25, 60 minutes) available for the last 5 years
+    #
+    # @example Fetch daily historical data
+    #   data = DhanHQ::Models::HistoricalData.daily(
+    #     security_id: "1333",
+    #     exchange_segment: "NSE_EQ",
+    #     instrument: "EQUITY",
+    #     from_date: "2022-01-08",
+    #     to_date: "2022-02-08"
+    #   )
+    #   puts "First day close: #{data[:close].first}"
+    #
+    # @example Fetch intraday historical data
+    #   data = DhanHQ::Models::HistoricalData.intraday(
+    #     security_id: "1333",
+    #     exchange_segment: "NSE_EQ",
+    #     instrument: "EQUITY",
+    #     interval: "15",
+    #     from_date: "2024-09-11",
+    #     to_date: "2024-09-15"
+    #   )
+    #   puts "Total candles: #{data[:open].size}"
+    #
+    # @note For intraday data, only 90 days of data can be polled at once for any time interval.
+    #   It is recommended to store this data locally for day-to-day analysis.
     #
     class HistoricalData < BaseModel
-      # Typically, we won't define a single resource path,
-      # because we call "daily" or "intraday" endpoints specifically.
-      # So let's rely on the resource call directly.
+      # Base path for historical data endpoints.
       HTTP_PATH = "/v2/charts"
 
-      # If you want typed attributes, you could define them,
-      # but the endpoints return arrays. We'll keep it raw.
-      # e.g. attributes :open, :high, :low, :close, :volume, :timestamp
-
       class << self
         ##
-        # Provide a **shared instance** of the `HistoricalData` resource
+        # Provides a shared instance of the HistoricalData resource.
         #
-        # @return [DhanHQ::Resources::HistoricalData]
+        # @return [DhanHQ::Resources::HistoricalData] The HistoricalData resource client instance
         def resource
           @resource ||= DhanHQ::Resources::HistoricalData.new
         end
 
         ##
-        # Daily historical data
-        # @param params [Hash] The request parameters, e.g.:
-        #   {
+        # Fetches daily OHLC (Open, High, Low, Close) and volume data for the desired instrument.
+        #
+        # Retrieves daily candle data for any scrip available back to the date of its inception.
+        # The data is returned as arrays where each index corresponds to a single trading day.
+        #
+        # @param params [Hash{Symbol => String, Integer, Boolean}] Request parameters
+        #   @option params [String] :security_id (required) Exchange standard ID for each scrip
+        #   @option params [String] :exchange_segment (required) Exchange and segment for which data is to be fetched.
+        #     Valid values: See {DhanHQ::Constants::EXCHANGE_SEGMENTS}
+        #   @option params [String] :instrument (required) Instrument type of the scrip.
+        #     Valid values: See {DhanHQ::Constants::INSTRUMENTS}
+        #   @option params [Integer] :expiry_code (optional) Expiry of the instruments in case of derivatives.
+        #     Valid values: 0, 1, 2
+        #   @option params [Boolean] :oi (optional) Include Open Interest data for Futures & Options.
+        #     Default: false
+        #   @option params [String] :from_date (required) Start date of the desired range in YYYY-MM-DD format
+        #   @option params [String] :to_date (required) End date of the desired range (non-inclusive) in YYYY-MM-DD format
+        #
+        # @return [HashWithIndifferentAccess{Symbol => Array<Float, Integer>}] Historical data hash containing:
+        #   - **:open** [Array<Float>] Open prices for each trading day
+        #   - **:high** [Array<Float>] High prices for each trading day
+        #   - **:low** [Array<Float>] Low prices for each trading day
+        #   - **:close** [Array<Float>] Close prices for each trading day
+        #   - **:volume** [Array<Integer>] Volume traded for each trading day
+        #   - **:timestamp** [Array<Integer>] Epoch timestamps (Unix time in seconds) for each trading day
+        #   - **:open_interest** [Array<Float>] Open interest values (only included if `oi: true` was specified)
+        #
+        # @example Fetch daily data for equity
+        #   data = DhanHQ::Models::HistoricalData.daily(
         #     security_id: "1333",
         #     exchange_segment: "NSE_EQ",
         #     instrument: "EQUITY",
-        #     expiry_code: 0,
         #     from_date: "2022-01-08",
         #     to_date: "2022-02-08"
-        #   }
-        # @return [HashWithIndifferentAccess]
-        #   {
-        #     open: [...], high: [...], low: [...], close: [...],
-        #     volume: [...], timestamp: [...]
-        #   }
+        #   )
+        #   data[:open].size  # => Number of trading days
+        #   data[:close].first  # => First day's close price
+        #
+        # @example Fetch daily data with open interest for futures
+        #   data = DhanHQ::Models::HistoricalData.daily(
+        #     security_id: "13",
+        #     exchange_segment: "NSE_FNO",
+        #     instrument: "FUTIDX",
+        #     expiry_code: 0,
+        #     oi: true,
+        #     from_date: "2024-01-01",
+        #     to_date: "2024-01-31"
+        #   )
+        #   puts "OI data available: #{data.key?(:open_interest)}"
+        #
+        # @raise [DhanHQ::ValidationError] If validation fails for any parameter
         def daily(params)
           validate_params!(params, DhanHQ::Contracts::HistoricalDataContract)
-          # You can rename the keys from snake_case to something if needed
           resource.daily(params)
-          # return as a raw hash or transform further
         end
 
         ##
-        # Intraday historical data
-        # @param params [Hash], e.g.:
-        #   {
+        # Fetches intraday OHLC (Open, High, Low, Close) and volume data for minute-level timeframes.
+        #
+        # Retrieves minute-level candle data (1, 5, 15, 25, or 60 minutes) for desired instruments.
+        # Data is available for the last 5 years for all exchanges and segments for all active instruments.
+        #
+        # **Important**: Only 90 days of data can be polled at once for any of the time intervals.
+        # It is recommended that you store this data locally for day-to-day analysis.
+        #
+        # @param params [Hash{Symbol => String, Integer, Boolean}] Request parameters
+        #   @option params [String] :security_id (required) Exchange standard ID for each scrip
+        #   @option params [String] :exchange_segment (required) Exchange and segment for which data is to be fetched.
+        #     Valid values: See {DhanHQ::Constants::EXCHANGE_SEGMENTS}
+        #   @option params [String] :instrument (required) Instrument type of the scrip.
+        #     Valid values: See {DhanHQ::Constants::INSTRUMENTS}
+        #   @option params [String] :interval (required) Minute intervals for the timeframe.
+        #     Valid values: "1", "5", "15", "25", "60"
+        #   @option params [Integer] :expiry_code (optional) Expiry of the instruments in case of derivatives.
+        #     Valid values: 0, 1, 2
+        #   @option params [Boolean] :oi (optional) Include Open Interest data for Futures & Options.
+        #     Default: false
+        #   @option params [String] :from_date (required) Start date of the desired range.
+        #     Format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS (e.g., "2024-09-11" or "2024-09-11 09:30:00")
+        #   @option params [String] :to_date (required) End date of the desired range.
+        #     Format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS (e.g., "2024-09-15" or "2024-09-15 13:00:00")
+        #
+        # @return [HashWithIndifferentAccess{Symbol => Array<Float, Integer>}] Historical data hash containing:
+        #   - **:open** [Array<Float>] Open prices for each timeframe
+        #   - **:high** [Array<Float>] High prices for each timeframe
+        #   - **:low** [Array<Float>] Low prices for each timeframe
+        #   - **:close** [Array<Float>] Close prices for each timeframe
+        #   - **:volume** [Array<Integer>] Volume traded for each timeframe
+        #   - **:timestamp** [Array<Integer>] Epoch timestamps (Unix time in seconds) for each timeframe
+        #   - **:open_interest** [Array<Float>] Open interest values (only included if `oi: true` was specified)
+        #
+        # @example Fetch 15-minute intraday data
+        #   data = DhanHQ::Models::HistoricalData.intraday(
         #     security_id: "1333",
         #     exchange_segment: "NSE_EQ",
         #     instrument: "EQUITY",
         #     interval: "15",
         #     from_date: "2024-09-11",
         #     to_date: "2024-09-15"
-        #   }
-        # @return [HashWithIndifferentAccess]
-        #   { open: [...], high: [...], low: [...], close: [...],
-        #     volume: [...], timestamp: [...] }
+        #   )
+        #   puts "Total 15-min candles: #{data[:open].size}"
+        #
+        # @example Fetch 1-minute data with specific time range
+        #   data = DhanHQ::Models::HistoricalData.intraday(
+        #     security_id: "1333",
+        #     exchange_segment: "NSE_EQ",
+        #     instrument: "EQUITY",
+        #     interval: "1",
+        #     from_date: "2024-09-11 09:30:00",
+        #     to_date: "2024-09-11 15:30:00"
+        #   )
+        #   # Returns 1-minute candles for the specified time range
+        #
+        # @example Fetch intraday data for futures with open interest
+        #   data = DhanHQ::Models::HistoricalData.intraday(
+        #     security_id: "13",
+        #     exchange_segment: "NSE_FNO",
+        #     instrument: "FUTIDX",
+        #     interval: "5",
+        #     expiry_code: 0,
+        #     oi: true,
+        #     from_date: "2024-01-01",
+        #     to_date: "2024-01-31"
+        #   )
+        #
+        # @note Maximum 90 days of data can be fetched in a single request. For longer periods,
+        #   make multiple requests or store data locally for analysis.
+        # @raise [DhanHQ::ValidationError] If validation fails for any parameter
         def intraday(params)
           validate_params!(params, DhanHQ::Contracts::HistoricalDataContract)
           resource.intraday(params)
         end
       end
 
-      # For a read-only type of data, we might skip validations or specify a contract if needed
+      ##
+      # HistoricalData objects are read-only, so no validation contract is applied.
+      #
+      # @return [nil] No validation contract needed for read-only data
       def validation_contract
         nil
       end

data/lib/DhanHQ/models/holding.rb

@@ -2,7 +2,30 @@
 
 module DhanHQ
   module Models
+    ##
     # Model representing a single portfolio holding.
+    #
+    # Holdings represent all stocks/securities bought or sold in previous trading sessions.
+    # This includes both T1 (pending delivery) and delivered quantities in your demat account.
+    # Each holding provides information about quantities, average cost price, and availability
+    # for transactions.
+    #
+    # @example Fetch all holdings
+    #   holdings = DhanHQ::Models::Holding.all
+    #   holdings.each do |holding|
+    #     puts "#{holding.trading_symbol}: #{holding.total_qty} shares @ ₹#{holding.avg_cost_price}"
+    #   end
+    #
+    # @example Find a specific holding by symbol
+    #   holdings = DhanHQ::Models::Holding.all
+    #   hdfc = holdings.find { |h| h.trading_symbol == "HDFC" }
+    #   puts "Available quantity: #{hdfc.available_qty}" if hdfc
+    #
+    # @example Calculate portfolio value
+    #   holdings = DhanHQ::Models::Holding.all
+    #   total_value = holdings.sum { |h| h.total_qty * h.avg_cost_price }
+    #   puts "Portfolio value: ₹#{total_value}"
+    #
     class Holding < BaseModel
       # Base path used when retrieving holdings.
       HTTP_PATH = "/v2/holdings"
@@ -12,17 +35,51 @@ module DhanHQ
 
       class << self
         ##
-        # Provides a **shared instance** of the `Holdings` resource.
+        # Provides a shared instance of the Holdings resource.
         #
-        # @return [DhanHQ::Resources::Holdings]
+        # @return [DhanHQ::Resources::Holdings] The Holdings resource client instance
         def resource
           @resource ||= DhanHQ::Resources::Holdings.new
         end
 
         ##
-        # Fetch all holdings.
+        # Retrieves all holdings bought/sold in previous trading sessions.
         #
-        # @return [Array<Holding>]
+        # Fetches all T1 (pending delivery) and delivered quantities from your portfolio.
+        # Includes information about available quantities for transaction, collateral quantities,
+        # and average cost prices for each holding.
+        #
+        # @return [Array<Holding>] Array of Holding objects. Returns empty array if no holdings exist.
+        #   Each Holding object contains (keys normalized to snake_case):
+        #   - **:exchange** [String] Exchange identifier (e.g., "ALL", "NSE", "BSE")
+        #   - **:trading_symbol** [String] Trading symbol of the security
+        #   - **:security_id** [String] Exchange standard ID for each scrip
+        #   - **:isin** [String] Universal standard ID for each scrip (International Securities Identification Number)
+        #   - **:total_qty** [Integer] Total quantity of the holding
+        #   - **:dp_qty** [Integer] Quantity delivered in demat account
+        #   - **:t1_qty** [Integer] Quantity pending delivery in demat account (T+1 settlement)
+        #   - **:available_qty** [Integer] Quantity available for transaction
+        #   - **:collateral_qty** [Integer] Quantity placed as collateral with broker
+        #   - **:avg_cost_price** [Float] Average buy price of total quantity
+        #
+        # @example Fetch all holdings
+        #   holdings = DhanHQ::Models::Holding.all
+        #   holdings.each do |holding|
+        #     puts "#{holding.trading_symbol}: #{holding.total_qty} @ ₹#{holding.avg_cost_price}"
+        #   end
+        #
+        # @example Filter holdings by available quantity
+        #   holdings = DhanHQ::Models::Holding.all
+        #   sellable = holdings.select { |h| h.available_qty > 0 }
+        #   puts "You can sell #{sellable.size} holdings"
+        #
+        # @example Calculate total investment
+        #   holdings = DhanHQ::Models::Holding.all
+        #   total_investment = holdings.sum { |h| h.total_qty * h.avg_cost_price }
+        #   puts "Total investment: ₹#{total_investment}"
+        #
+        # @note This is a GET request with no body parameters required
+        # @note Returns empty array if no holdings exist or if {DhanHQ::NoHoldingsError} is raised
         def all
           response = resource.all
           return [] unless response.is_a?(Array)
@@ -34,9 +91,28 @@ module DhanHQ
       end
 
       ##
-      # Convert model attributes to a hash.
+      # Converts the Holding model attributes to a hash representation.
+      #
+      # Useful for serialization, logging, or passing holding data to other methods.
+      #
+      # @return [Hash{Symbol => String, Integer, Float}] Hash representation of the Holding model containing:
+      #   - **:exchange** [String] Exchange identifier
+      #   - **:trading_symbol** [String] Trading symbol
+      #   - **:security_id** [String] Security ID
+      #   - **:isin** [String] ISIN code
+      #   - **:total_qty** [Integer] Total quantity
+      #   - **:dp_qty** [Integer] Delivered quantity in demat
+      #   - **:t1_qty** [Integer] T+1 pending delivery quantity
+      #   - **:available_qty** [Integer] Available quantity for transaction
+      #   - **:collateral_qty** [Integer] Quantity placed as collateral
+      #   - **:avg_cost_price** [Float] Average cost price
+      #
+      # @example Convert holding to hash
+      #   holding = DhanHQ::Models::Holding.all.first
+      #   holding_hash = holding.to_h
+      #   puts holding_hash[:trading_symbol]  # => "HDFC"
+      #   puts holding_hash[:avg_cost_price]   # => 2655.0
       #
-      # @return [Hash] Hash representation of the Holding model.
       def to_h
         {
           exchange: exchange,

data/lib/DhanHQ/models/kill_switch.rb

@@ -2,45 +2,147 @@
 
 module DhanHQ
   module Models
-    # Model helper to toggle the trading kill switch.
+    ##
+    # Model for managing the trading kill switch feature.
+    #
+    # The Kill Switch API lets you activate or deactivate the kill switch for your account,
+    # which will disable trading for the current trading day. This is a safety feature that
+    # can be used to prevent further trading activity when needed.
+    #
+    # @note **Important**: Before activating the kill switch, you must ensure that all your
+    #   positions are closed and there are no pending orders in your account. The kill switch
+    #   will not activate if there are open positions or pending orders.
+    #
+    # @example Activate kill switch
+    #   response = DhanHQ::Models::KillSwitch.activate
+    #   puts response[:kill_switch_status]
+    #   # => "Kill Switch has been successfully activated"
+    #
+    # @example Deactivate kill switch
+    #   response = DhanHQ::Models::KillSwitch.deactivate
+    #   puts response[:kill_switch_status]
+    #
+    # @example Update kill switch with custom status
+    #   response = DhanHQ::Models::KillSwitch.update("ACTIVATE")
+    #   if response[:kill_switch_status].include?("successfully")
+    #     puts "Kill switch activated"
+    #   end
+    #
     class KillSwitch < BaseModel
       # Base path used by the kill switch resource.
       HTTP_PATH = "/v2/killswitch"
 
       class << self
-        # Shared resource for kill switch operations.
+        ##
+        # Provides a shared instance of the KillSwitch resource.
         #
-        # @return [DhanHQ::Resources::KillSwitch]
+        # @return [DhanHQ::Resources::KillSwitch] The KillSwitch resource client instance
         def resource
           @resource ||= DhanHQ::Resources::KillSwitch.new
         end
 
-        # Updates the kill switch status.
+        ##
+        # Updates the kill switch status with the specified action.
+        #
+        # Allows you to set the kill switch to either "ACTIVATE" or "DEACTIVATE" state.
+        # The status is passed as a query parameter to the API endpoint.
+        #
+        # @param status [String] Kill switch action to perform.
+        #   Valid values: "ACTIVATE", "DEACTIVATE"
+        #
+        # @return [Hash{Symbol => String}] Response hash containing kill switch operation result.
+        #   Response structure (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:kill_switch_status** [String] Status message indicating the result of the operation.
+        #     For activation: "Kill Switch has been successfully activated"
+        #     For deactivation: Status message for deactivation
+        #
+        # @example Update kill switch status
+        #   response = DhanHQ::Models::KillSwitch.update("ACTIVATE")
+        #   puts response[:kill_switch_status]
+        #
+        # @example Check if activation was successful
+        #   response = DhanHQ::Models::KillSwitch.update("ACTIVATE")
+        #   if response[:kill_switch_status].include?("successfully")
+        #     puts "Kill switch is now active"
+        #   end
         #
-        # @param status [String]
-        # @return [Hash]
         def update(status)
           resource.update(kill_switch_status: status)
         end
 
-        # Activates the kill switch for the account.
+        ##
+        # Activates the kill switch for your trading account.
+        #
+        # Disables trading for the current trading day. All trading operations will be blocked
+        # until the kill switch is deactivated. This is a safety feature to prevent further
+        # trading activity.
+        #
+        # @note **Prerequisites**: All positions must be closed and there must be no pending
+        #   orders in your account before activation. The API will reject the activation request
+        #   if these conditions are not met.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing kill switch activation result.
+        #   Response structure (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:kill_switch_status** [String] Status message, typically:
+        #     "Kill Switch has been successfully activated"
+        #
+        # @example Activate kill switch
+        #   response = DhanHQ::Models::KillSwitch.activate
+        #   puts response[:kill_switch_status]
+        #   # => "Kill Switch has been successfully activated"
+        #
+        # @example Activate with error handling
+        #   begin
+        #     response = DhanHQ::Models::KillSwitch.activate
+        #     if response[:kill_switch_status].include?("successfully")
+        #       puts "✓ Kill switch activated - trading disabled"
+        #     end
+        #   rescue => e
+        #     puts "Failed to activate kill switch: #{e.message}"
+        #     puts "Ensure all positions are closed and no orders are pending"
+        #   end
         #
-        # @return [Hash]
         def activate
           update("ACTIVATE")
         end
 
-        # Deactivates the kill switch for the account.
+        ##
+        # Deactivates the kill switch for your trading account.
+        #
+        # Re-enables trading for your account. After deactivation, you can resume placing
+        # orders and executing trades normally.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing kill switch deactivation result.
+        #   Response structure (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:kill_switch_status** [String] Status message indicating deactivation result
+        #
+        # @example Deactivate kill switch
+        #   response = DhanHQ::Models::KillSwitch.deactivate
+        #   puts response[:kill_switch_status]
+        #
+        # @example Re-enable trading
+        #   response = DhanHQ::Models::KillSwitch.deactivate
+        #   if response[:kill_switch_status].include?("successfully")
+        #     puts "✓ Trading re-enabled"
+        #   end
         #
-        # @return [Hash]
         def deactivate
           update("DEACTIVATE")
         end
       end
 
+      ##
       # No explicit validation contract is required for kill switch updates.
       #
-      # @return [nil]
+      # Kill switch operations are simple status updates that don't require complex validation.
+      # The API handles validation server-side.
+      #
+      # @return [nil] Always returns nil as no validation contract is needed
+      #
+      # @api private
       def validation_contract
         nil
       end

data/lib/DhanHQ/models/ledger_entry.rb

@@ -3,34 +3,98 @@
 module DhanHQ
   module Models
     ##
-    # Represents a single row/entry in the Ledger.
-    # Ledger data typically returns an array of these objects.
+    # Model representing a single ledger entry in the Trading Account Ledger Report.
+    #
+    # The Ledger Report contains all credit and debit transaction details for a particular time interval.
+    # Each entry represents a single transaction with details such as narration, voucher information,
+    # debit/credit amounts, and running balance.
+    #
+    # @example Fetch ledger entries for a date range
+    #   entries = DhanHQ::Models::LedgerEntry.all(
+    #     from_date: "2024-04-01",
+    #     to_date: "2024-04-30"
+    #   )
+    #   entries.each do |entry|
+    #     puts "#{entry.voucherdate}: #{entry.narration} - #{entry.debit} / #{entry.credit}"
+    #   end
+    #
+    # @example Calculate total credits and debits
+    #   entries = DhanHQ::Models::LedgerEntry.all(
+    #     from_date: "2024-04-01",
+    #     to_date: "2024-04-30"
+    #   )
+    #   total_debits = entries.sum { |e| e.debit.to_f }
+    #   total_credits = entries.sum { |e| e.credit.to_f }
+    #
     class LedgerEntry < BaseModel
-      # The endpoint is /v2/ledger?from-date=...&to-date=...
-      # So we may define a resource path or rely on the Statements resource.
+      # Base path for ledger endpoint.
       HTTP_PATH = "/v2/ledger"
 
-      # Typical fields from API docs
       attributes :dhan_client_id, :narration, :voucherdate, :exchange,
                  :voucherdesc, :vouchernumber, :debit, :credit, :runbal
 
       class << self
         ##
-        # Provides a **shared instance** of the `Statements` resource.
+        # Provides a shared instance of the Statements resource.
         #
-        # @return [DhanHQ::Resources::Statements]
+        # @return [DhanHQ::Resources::Statements] The Statements resource client instance
         def resource
           @resource ||= DhanHQ::Resources::Statements.new
         end
 
         ##
-        # Fetch ledger entries for the given date range.
+        # Retrieves Trading Account Ledger Report entries for the specified date range.
         #
-        # @param from_date [String] e.g. "2023-01-01"
-        # @param to_date   [String] e.g. "2023-01-31"
-        # @return [Array<LedgerEntry>]
+        # Fetches all credit and debit transaction details for the given time interval.
+        # The ledger entries include transaction descriptions, voucher information, amounts,
+        # and running balances.
+        #
+        # @param from_date [String] Start date of the ledger report in YYYY-MM-DD format.
+        #   Example: "2024-04-01"
+        # @param to_date [String] End date of the ledger report in YYYY-MM-DD format.
+        #   Example: "2024-04-30"
+        #
+        # @return [Array<LedgerEntry>] Array of LedgerEntry objects. Returns empty array if no entries exist.
+        #   Each LedgerEntry object contains (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:narration** [String] Description of the ledger transaction (e.g., "FUNDS WITHDRAWAL", "CLOSING BALANCE")
+        #   - **:voucherdate** [String] Transaction date in format "Mon DD, YYYY" (e.g., "Jun 22, 2022")
+        #   - **:exchange** [String] Exchange information for the transaction (e.g., "NSE-CAPITAL", "NSE_CASH")
+        #   - **:voucherdesc** [String] Nature of transaction (e.g., "PAYBNK", "CLOSING BALANCE", "OPENING BALANCE")
+        #   - **:vouchernumber** [String] System generated transaction number. May be empty string for balance entries
+        #   - **:debit** [String] Debit amount as string. Only populated when credit returns "0.00"
+        #   - **:credit** [String] Credit amount as string. Only populated when debit returns "0.00"
+        #   - **:runbal** [String] Running balance post transaction as string
+        #
+        # @example Fetch ledger entries for a month
+        #   entries = DhanHQ::Models::LedgerEntry.all(
+        #     from_date: "2024-04-01",
+        #     to_date: "2024-04-30"
+        #   )
+        #   entries.each do |entry|
+        #     puts "#{entry.voucherdate}: #{entry.narration} - Balance: #{entry.runbal}"
+        #   end
+        #
+        # @example Filter entries by transaction type
+        #   entries = DhanHQ::Models::LedgerEntry.all(
+        #     from_date: "2024-04-01",
+        #     to_date: "2024-04-30"
+        #   )
+        #   withdrawals = entries.select { |e| e.voucherdesc == "PAYBNK" }
+        #   puts "Total withdrawals: #{withdrawals.size}"
+        #
+        # @example Calculate net balance change
+        #   entries = DhanHQ::Models::LedgerEntry.all(
+        #     from_date: "2024-04-01",
+        #     to_date: "2024-04-30"
+        #   )
+        #   net_change = entries.sum { |e| e.credit.to_f - e.debit.to_f }
+        #   puts "Net change: ₹#{net_change}"
+        #
+        # @note This is a GET request with query parameters. No body required.
+        # @note The ledger report represents historical data dumps and entries are returned as-is
+        #   without additional validation.
         def all(from_date:, to_date:)
-          # The resource call returns an Array<Hash>, according to the docs.
           response = resource.ledger(from_date: from_date, to_date: to_date)
 
           return [] unless response.is_a?(Array)
@@ -41,7 +105,31 @@ module DhanHQ
         end
       end
 
-      # Optional: you can override #to_h or #inspect if you want a custom representation
+      ##
+      # Converts the LedgerEntry model attributes to a hash representation.
+      #
+      # Useful for serialization, logging, or passing ledger entry data to other methods.
+      #
+      # @return [Hash{Symbol => String}] Hash representation of the LedgerEntry model containing:
+      #   - **:dhan_client_id** [String] User-specific identification
+      #   - **:narration** [String] Transaction description
+      #   - **:voucherdate** [String] Transaction date
+      #   - **:exchange** [String] Exchange information
+      #   - **:voucherdesc** [String] Nature of transaction
+      #   - **:vouchernumber** [String] Transaction number
+      #   - **:debit** [String] Debit amount
+      #   - **:credit** [String] Credit amount
+      #   - **:runbal** [String] Running balance
+      #
+      # @example Convert entry to hash
+      #   entry = DhanHQ::Models::LedgerEntry.all(
+      #     from_date: "2024-04-01",
+      #     to_date: "2024-04-30"
+      #   ).first
+      #   entry_hash = entry.to_h
+      #   puts entry_hash[:narration]  # => "FUNDS WITHDRAWAL"
+      #   puts entry_hash[:runbal]      # => "957.29"
+      #
       def to_h
         {
           dhan_client_id: dhan_client_id,