DhanHQ 2.1.7 → 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/instrument_helpers.rb

@@ -8,13 +8,26 @@ module DhanHQ
       ##
       # Fetches last traded price (LTP) for this instrument.
       #
-      # @return [Hash] Market feed LTP response
+      # @return [Float, nil] Last traded price value, or nil if not available
       # @example
       #   instrument = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
-      #   instrument.ltp
+      #   instrument.ltp  # => 26053.9
       def ltp
         params = build_market_feed_params
-        DhanHQ::Models::MarketFeed.ltp(params)
+        response = DhanHQ::Models::MarketFeed.ltp(params)
+
+        # Extract last_price from nested response structure
+        # Response format: {"data" => {"EXCHANGE_SEGMENT" => {"security_id" => {"last_price" => value}}}, "status" => "success"}
+        data = response[:data] || response["data"]
+        return nil unless data
+
+        segment_data = data[exchange_segment] || data[exchange_segment.to_sym]
+        return nil unless segment_data
+
+        security_data = segment_data[security_id] || segment_data[security_id.to_s]
+        return nil unless security_data
+
+        security_data[:last_price] || security_data["last_price"]
       end
 
       ##
@@ -82,7 +95,7 @@ module DhanHQ
       def expiry_list
         params = {
           underlying_scrip: security_id.to_i,
-          underlying_seg: exchange_segment
+          underlying_seg: underlying_segment_for_options
         }
         DhanHQ::Models::OptionChain.fetch_expiry_list(params)
       end
@@ -98,7 +111,7 @@ module DhanHQ
       def option_chain(expiry:)
         params = {
           underlying_scrip: security_id.to_i,
-          underlying_seg: exchange_segment,
+          underlying_seg: underlying_segment_for_options,
           expiry: expiry
         }
         DhanHQ::Models::OptionChain.fetch(params)
@@ -136,6 +149,27 @@ module DhanHQ
 
         params
       end
+
+      ##
+      # Determines the correct underlying segment for option chain APIs.
+      # Index uses IDX_I; stocks map to NSE_FNO or BSE_FNO by exchange.
+      def underlying_segment_for_options
+        seg = exchange_segment.to_s
+        ins = instrument.to_s
+
+        # If already a valid underlying seg, return as-is
+        return seg if %w[IDX_I NSE_FNO BSE_FNO MCX_FO].include?(seg)
+
+        # Index detection by instrument kind or segment
+        return "IDX_I" if ins == "INDEX" || seg == "IDX_I"
+
+        # Map equities/stock-related segments to respective FNO
+        return "NSE_FNO" if seg.start_with?("NSE")
+        return "BSE_FNO" if seg.start_with?("BSE")
+
+        # Fallback to IDX_I to avoid contract rejection
+        "IDX_I"
+      end
     end
   end
 end

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