ollama-client 0.2.1 → 0.2.3

data/examples/dhanhq_tools.rb

@@ -10,6 +10,7 @@
 require "json"
 require "date"
 require "dhan_hq"
+require_relative "dhanhq/indicators/technical_indicators"
 
 # Helper to get valid exchange segments from DhanHQ constants
 def valid_exchange_segments
@@ -53,6 +54,45 @@ rescue StandardError
   nil
 end
 
+# Helper to validate security_id is numeric (integer or numeric string), not a symbol string
+# Returns [is_valid, result_or_error_message]
+# If valid: [true, integer_value]
+# If invalid: [false, error_message_string]
+def validate_security_id_numeric(security_id)
+  return [false, "security_id cannot be nil"] if security_id.nil?
+
+  # If it's already an integer, it's valid
+  return [true, security_id.to_i] if security_id.is_a?(Integer)
+
+  # If it's a string, check if it's numeric
+  if security_id.is_a?(String)
+    # Remove whitespace
+    cleaned = security_id.strip
+
+    # Check if it's a numeric string (all digits, possibly with leading/trailing spaces)
+    return [true, cleaned.to_i] if cleaned.match?(/^\d+$/)
+
+    # It's a non-numeric string (likely a symbol like "NIFTY")
+    message = "security_id must be numeric (integer or numeric string like '13'), " \
+              "not a symbol string like '#{cleaned}'. Use symbol parameter for symbols."
+    return [false, message]
+
+  end
+
+  # Try to convert to integer
+  begin
+    int_value = security_id.to_i
+    # Check if conversion was successful (to_i returns 0 for non-numeric strings)
+    if int_value.zero? && security_id.to_s.strip != "0"
+      return [false, "security_id must be numeric (integer or numeric string), got: #{security_id.inspect}"]
+    end
+
+    [true, int_value]
+  rescue StandardError
+    [false, "security_id must be numeric (integer or numeric string), got: #{security_id.inspect}"]
+  end
+end
+
 # Debug logging helper (if needed)
 def debug_log(location, message, data = {}, hypothesis_id = nil)
   log_entry = {
@@ -79,6 +119,13 @@ end
 # 4. Historical Data
 # 5. Expired Options Data
 # 6. Option Chain
+#
+# NOTE: These tools are callable functions. For use with Ollama::Agent::Executor,
+# you can either:
+# 1. Use them directly as callables (auto-inferred schema)
+# 2. Wrap them with structured Ollama::Tool classes for explicit schemas
+#    See examples/dhanhq/technical_analysis_agentic_runner.rb for examples
+#    of structured Tool definitions with type safety and better LLM understanding.
 class DhanHQDataTools
   class << self
     # Rate limiting: MarketFeed APIs have a limit of 1 request per second
@@ -98,145 +145,221 @@ class DhanHQDataTools
       end
     end
 
-    # 1. Market Quote API - Get market quote using Instrument convenience method
-    # Uses instrument.quote which automatically uses instrument's security_id,
-    # exchange_segment, and instrument attributes
-    # Note: Instrument.find(exchange_segment, symbol) expects symbol
-    # (e.g., "NIFTY", "RELIANCE"), not security_id
-    # Rate limit: 1 request per second
-    def get_market_quote(exchange_segment:, security_id: nil, symbol: nil)
-      # Instrument.find expects symbol, support both for backward compatibility
-      instrument_symbol = symbol || security_id
-      unless instrument_symbol
+    # 0. Find Instrument - Search for instrument by symbol across common exchange segments
+    #
+    # REQUIRED PARAMETERS:
+    #   - symbol [String]: Trading symbol to search for (e.g., "NIFTY", "RELIANCE", "TCS")
+    #
+    # Returns: Instrument details including:
+    #   - exchange_segment: Exchange and segment identifier (e.g., "IDX_I", "NSE_EQ")
+    #   - security_id: Numeric security ID (use this for subsequent API calls)
+    #   - trading_symbol: Trading symbol
+    #   - instrument_type: Type of instrument (EQUITY, INDEX, etc.)
+    #   - name: Full name of the instrument
+    #   - isin: ISIN code if available
+    #
+    # This is useful when you only have a symbol and need to resolve it to proper parameters
+    # Searches across common segments: NSE_EQ, BSE_EQ, NSE_FNO, BSE_FNO, IDX_I, NSE_CURRENCY, BSE_CURRENCY, MCX_COMM
+    def find_instrument(symbol:)
+      unless symbol
         return {
-          action: "get_market_quote",
-          error: "Either symbol or security_id must be provided",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          action: "find_instrument",
+          error: "Symbol is required",
+          params: { symbol: symbol }
         }
       end
 
-      rate_limit_marketfeed # Enforce rate limiting
-      instrument_symbol = instrument_symbol.to_s
-      exchange_segment = exchange_segment.to_s
+      symbol_str = symbol.to_s.upcase
+      common_index_symbols = %w[NIFTY BANKNIFTY FINNIFTY MIDCPNIFTY SENSEX BANKEX]
 
-      # Find instrument first
-      instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
+      if common_index_symbols.include?(symbol_str)
+        instrument = DhanHQ::Models::Instrument.find("IDX_I", symbol_str)
+        if instrument
+          return {
+            action: "find_instrument",
+            params: { symbol: symbol_str },
+            result: {
+              symbol: symbol_str,
+              exchange_segment: "IDX_I",
+              security_id: safe_instrument_attr(instrument, :security_id),
+              trading_symbol: safe_instrument_attr(instrument, :trading_symbol),
+              instrument_type: safe_instrument_attr(instrument, :instrument_type),
+              name: safe_instrument_attr(instrument, :name),
+              isin: safe_instrument_attr(instrument, :isin)
+            }
+          }
+        end
+      end
 
-      if instrument
-        # Use instrument convenience method - automatically uses instrument's attributes
-        # Returns nested structure: {"data"=>{"NSE_EQ"=>{"2885"=>{...}}}, "status"=>"success"}
-        quote_response = instrument.quote
+      common_segments = %w[NSE_EQ BSE_EQ NSE_FNO BSE_FNO IDX_I NSE_CURRENCY BSE_CURRENCY MCX_COMM]
 
-        # Extract actual quote data from nested structure
-        security_id_str = safe_instrument_attr(instrument, :security_id)&.to_s || security_id.to_s
-        if quote_response.is_a?(Hash) && quote_response["data"]
-          quote_data = quote_response.dig("data", exchange_segment,
-                                          security_id_str)
-        end
+      common_segments.each do |segment|
+        instrument = DhanHQ::Models::Instrument.find(segment, symbol_str)
+        next unless instrument
 
-        {
-          action: "get_market_quote",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment },
+        return {
+          action: "find_instrument",
+          params: { symbol: symbol_str },
           result: {
-            security_id: safe_instrument_attr(instrument, :security_id) || security_id,
-            symbol: instrument_symbol,
-            exchange_segment: exchange_segment,
-            quote: quote_data || quote_response
+            symbol: symbol_str,
+            exchange_segment: segment,
+            security_id: safe_instrument_attr(instrument, :security_id),
+            trading_symbol: safe_instrument_attr(instrument, :trading_symbol),
+            instrument_type: safe_instrument_attr(instrument, :instrument_type),
+            name: safe_instrument_attr(instrument, :name),
+            isin: safe_instrument_attr(instrument, :isin)
           }
         }
-      else
-        {
-          action: "get_market_quote",
-          error: "Instrument not found",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
-        }
       end
+
+      {
+        action: "find_instrument",
+        error: "Instrument not found in any common exchange segment",
+        params: { symbol: symbol_str },
+        suggestions: "Try specifying exchange_segment explicitly (NSE_EQ, BSE_EQ, etc.)"
+      }
     rescue StandardError => e
       {
-        action: "get_market_quote",
+        action: "find_instrument",
         error: e.message,
-        params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+        params: { symbol: symbol }
       }
     end
 
-    # 2. Live Market Feed API - Get LTP (Last Traded Price) using Instrument convenience method
-    # Uses instrument.ltp which automatically uses instrument's security_id, exchange_segment, and instrument attributes
+    # 1. Market Quote API - Get market quote using Instrument convenience method
+    #
+    # REQUIRED PARAMETERS:
+    #   - exchange_segment [String]: Exchange and segment identifier
+    #     Valid values: NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM, IDX_I
+    #   - symbol [String] OR security_id [Integer]: Must provide one
+    #     symbol: Trading symbol (e.g., "NIFTY", "RELIANCE")
+    #     security_id: Numeric security ID
+    #
+    # Returns: Full market quote with OHLC, depth, volume, and other market data
+    #
+    # Rate limit: 1 request per second
+    # Up to 1000 instruments per request
+    #
     # Note: Instrument.find(exchange_segment, symbol) expects symbol (e.g., "NIFTY", "RELIANCE"), not security_id
+    def get_market_quote(exchange_segment:, security_id: nil, symbol: nil)
+      error = require_symbol_or_security_id(action: "get_market_quote",
+                                            exchange_segment: exchange_segment,
+                                            security_id: security_id,
+                                            symbol: symbol)
+      return error if error
+
+      rate_limit_marketfeed
+      exchange_segment = exchange_segment.to_s
+
+      if security_id && !symbol
+        error, security_id_int = validated_security_id_for_marketfeed(
+          action: "get_market_quote",
+          exchange_segment: exchange_segment,
+          security_id: security_id,
+          symbol: symbol
+        )
+        return error if error
+
+        return market_quote_from_security_id(exchange_segment: exchange_segment,
+                                             security_id_int: security_id_int,
+                                             symbol: symbol)
+      end
+
+      market_quote_from_symbol(exchange_segment: exchange_segment, security_id: security_id, symbol: symbol)
+    rescue StandardError => e
+      action_error(action: "get_market_quote",
+                   message: e.message,
+                   exchange_segment: exchange_segment,
+                   security_id: security_id,
+                   symbol: symbol)
+    end
+
+    # 2. Live Market Feed API - Get LTP (Last Traded Price) using Instrument convenience method
+    #
+    # REQUIRED PARAMETERS:
+    #   - exchange_segment [String]: Exchange and segment identifier
+    #     Valid values: NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM, IDX_I
+    #   - symbol [String] OR security_id [Integer]: Must provide one
+    #     symbol: Trading symbol (e.g., "NIFTY", "RELIANCE")
+    #     security_id: Numeric security ID
+    #
+    # Returns: Last Traded Price (LTP) - fastest API for current price
+    #
     # Rate limit: 1 request per second
+    # Up to 1000 instruments per request
+    #
+    # Note: Instrument.find(exchange_segment, symbol) expects symbol (e.g., "NIFTY", "RELIANCE"), not security_id
     def get_live_ltp(exchange_segment:, security_id: nil, symbol: nil)
-      # Instrument.find expects symbol, support both for backward compatibility
-      instrument_symbol = symbol || security_id
-      unless instrument_symbol
-        return {
-          action: "get_live_ltp",
-          error: "Either symbol or security_id must be provided",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
-        }
-      end
+      error = require_symbol_or_security_id(action: "get_live_ltp",
+                                            exchange_segment: exchange_segment,
+                                            security_id: security_id,
+                                            symbol: symbol)
+      return error if error
 
-      rate_limit_marketfeed # Enforce rate limiting
-      instrument_symbol = instrument_symbol.to_s
+      rate_limit_marketfeed
       exchange_segment = exchange_segment.to_s
 
-      # Find instrument first
-      instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
+      if security_id && !symbol
+        error, security_id_int = validated_security_id_for_marketfeed(
+          action: "get_live_ltp",
+          exchange_segment: exchange_segment,
+          security_id: security_id,
+          symbol: symbol
+        )
+        return error if error
 
-      if instrument
-        # Use instrument convenience method - automatically uses instrument's attributes
-        # Returns nested structure: {"data"=>{"NSE_EQ"=>{"2885"=>{"last_price"=>1578.1}}}, "status"=>"success"}
-        # OR direct value: 1578.1 (after retry/rate limit handling)
-        ltp_response = instrument.ltp
-
-        # Extract LTP from nested structure or use direct value
-        if ltp_response.is_a?(Hash) && ltp_response["data"]
-          security_id_str = safe_instrument_attr(instrument, :security_id)&.to_s || security_id.to_s
-          ltp_data = ltp_response.dig("data", exchange_segment, security_id_str)
-          ltp = extract_value(ltp_data, [:last_price, "last_price"]) if ltp_data
-        elsif ltp_response.is_a?(Numeric)
-          ltp = ltp_response
-          ltp_data = { last_price: ltp }
-        else
-          ltp = extract_value(ltp_response, [:last_price, "last_price", :ltp, "ltp"]) || ltp_response
-          ltp_data = ltp_response
-        end
+        ltp, ltp_data = ltp_from_marketfeed(exchange_segment: exchange_segment, security_id: security_id_int)
+        return live_ltp_response(exchange_segment: exchange_segment,
+                                 security_id: security_id_int,
+                                 symbol: symbol,
+                                 ltp_payload: { ltp: ltp, ltp_data: ltp_data })
+      end
 
-        {
-          action: "get_live_ltp",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment },
-          result: {
-            security_id: safe_instrument_attr(instrument, :security_id) || security_id,
-            symbol: instrument_symbol,
-            exchange_segment: exchange_segment,
-            ltp: ltp,
-            ltp_data: ltp_data
-          }
-        }
-      else
-        {
-          action: "get_live_ltp",
-          error: "Instrument not found",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
-        }
+      instrument_symbol = symbol.to_s
+      instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
+      unless instrument
+        return action_error(action: "get_live_ltp",
+                            message: "Instrument not found",
+                            exchange_segment: exchange_segment,
+                            security_id: security_id,
+                            symbol: symbol)
       end
+
+      ltp, ltp_data, resolved_security_id = ltp_from_instrument(exchange_segment: exchange_segment,
+                                                                instrument: instrument,
+                                                                security_id: security_id)
+      live_ltp_response(exchange_segment: exchange_segment,
+                        security_id: resolved_security_id,
+                        symbol: symbol,
+                        ltp_payload: { ltp: ltp, ltp_data: ltp_data },
+                        instrument_symbol: instrument_symbol)
     rescue StandardError => e
-      {
-        action: "get_live_ltp",
-        error: e.message,
-        params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
-      }
+      action_error(action: "get_live_ltp",
+                   message: e.message,
+                   exchange_segment: exchange_segment,
+                   security_id: security_id,
+                   symbol: symbol)
     end
 
     # 3. Full Market Depth API - Get full market depth (bid/ask levels)
-    # Uses instrument.quote which automatically uses instrument's security_id,
-    # exchange_segment, and instrument attributes
-    # Note: Instrument.find(exchange_segment, symbol) expects symbol
-    # (e.g., "NIFTY", "RELIANCE"), not security_id
+    #
+    # REQUIRED PARAMETERS:
+    #   - exchange_segment [String]: Exchange and segment identifier
+    #     Valid values: NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM, IDX_I
+    #   - symbol [String] OR security_id [Integer]: Must provide one
+    #     symbol: Trading symbol (e.g., "NIFTY", "RELIANCE")
+    #     security_id: Numeric security ID
+    #
+    # Returns: Full market depth with order book (bid/ask levels), OHLC, volume, OI
+    #
     # Rate limit: 1 request per second (uses quote API which has stricter limits)
+    # Up to 1000 instruments per request
+    #
+    # Note: Instrument.find(exchange_segment, symbol) expects symbol (e.g., "NIFTY", "RELIANCE"), not security_id
     # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def get_market_depth(exchange_segment:, security_id: nil, symbol: nil)
-      # Instrument.find expects symbol, support both for backward compatibility
-      instrument_symbol = symbol || security_id
-      unless instrument_symbol
+      # CRITICAL: security_id must be an integer, not a symbol string
+      unless symbol || security_id
         return {
           action: "get_market_depth",
           error: "Either symbol or security_id must be provided",
@@ -245,10 +368,58 @@ class DhanHQDataTools
       end
 
       rate_limit_marketfeed # Enforce rate limiting
-      instrument_symbol = instrument_symbol.to_s
       exchange_segment = exchange_segment.to_s
 
-      # Find instrument first
+      # If security_id is provided, use it directly - it must be numeric (integer or numeric string), not a symbol
+      if security_id && !symbol
+        is_valid, result = validate_security_id_numeric(security_id)
+        unless is_valid
+          return {
+            action: "get_market_depth",
+            error: result,
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
+        security_id_int = result
+        unless security_id_int.positive?
+          return {
+            action: "get_market_depth",
+            error: "security_id must be a positive integer, got: #{security_id.inspect}",
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
+
+        # Use MarketFeed.quote directly with security_id
+        payload = { exchange_segment => [security_id_int] }
+        quote_response = DhanHQ::Models::MarketFeed.quote(payload)
+
+        if quote_response.is_a?(Hash) && quote_response["data"]
+          quote_data = quote_response.dig("data", exchange_segment, security_id_int.to_s)
+        end
+
+        depth = extract_value(quote_data, [:depth, "depth"]) if quote_data
+        buy_depth = extract_value(depth, [:buy, "buy"]) if depth
+        sell_depth = extract_value(depth, [:sell, "sell"]) if depth
+
+        return {
+          action: "get_market_depth",
+          params: { security_id: security_id_int, symbol: symbol, exchange_segment: exchange_segment },
+          result: {
+            security_id: security_id_int,
+            exchange_segment: exchange_segment,
+            market_depth: quote_data || quote_response,
+            buy_depth: buy_depth,
+            sell_depth: sell_depth,
+            ltp: quote_data ? extract_value(quote_data, [:last_price, "last_price"]) : nil,
+            volume: quote_data ? extract_value(quote_data, [:volume, "volume"]) : nil,
+            oi: quote_data ? extract_value(quote_data, [:oi, "oi"]) : nil,
+            ohlc: quote_data ? extract_value(quote_data, [:ohlc, "ohlc"]) : nil
+          }
+        }
+      end
+
+      # Find instrument using symbol (Instrument.find expects symbol, not security_id)
+      instrument_symbol = symbol.to_s
       instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
 
       if instrument
@@ -303,14 +474,38 @@ class DhanHQDataTools
     # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     # 4. Historical Data API - Get historical data using HistoricalData class directly
-    # Requires: security_id, exchange_segment, instrument (type), from_date, to_date
-    # Optional: interval (for intraday), expiry_code (for futures/options)
+    #
+    # REQUIRED PARAMETERS:
+    #   - exchange_segment [String]: Exchange and segment identifier
+    #     Valid values: NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM, IDX_I
+    #   - from_date [String]: Start date in YYYY-MM-DD format (e.g., "2024-01-08")
+    #   - to_date [String]: End date (non-inclusive) in YYYY-MM-DD format (e.g., "2024-02-08")
+    #   - symbol [String] OR security_id [Integer]: Must provide one
+    #     symbol: Trading symbol (e.g., "NIFTY", "RELIANCE")
+    #     security_id: Numeric security ID
+    #
+    # OPTIONAL PARAMETERS:
+    #   - interval [String]: Minute intervals for intraday data
+    #     Valid values: "1", "5", "15", "25", "60"
+    #     If provided, returns intraday data; if omitted, returns daily data
+    #   - expiry_code [Integer]: Expiry code for derivatives
+    #     Valid values: 0 (far month), 1 (near month), 2 (current month)
+    #   - instrument [String]: Instrument type
+    #     Valid values: EQUITY, INDEX, FUTIDX, FUTSTK, OPTIDX, OPTSTK, FUTCOM, OPTFUT, FUTCUR, OPTCUR
+    #     Auto-detected from exchange_segment if not provided
+    #
+    # Returns: Historical OHLCV data (arrays of open, high, low, close, volume, timestamp)
+    #
+    # Notes:
+    #   - Maximum 90 days of data for intraday requests
+    #   - Historical data available for the last 5 years
+    #   - to_date is NON-INCLUSIVE (end date is not included in results)
+    #
     # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def get_historical_data(exchange_segment:, from_date:, to_date:, security_id: nil, symbol: nil, interval: nil,
-                            expiry_code: nil, instrument: nil)
-      # Need security_id - get it from instrument if we only have symbol
-      instrument_symbol = symbol || security_id
-      unless instrument_symbol
+                            expiry_code: nil, instrument: nil, calculate_indicators: false)
+      # CRITICAL: security_id must be an integer, not a symbol string
+      unless symbol || security_id
         return {
           action: "get_historical_data",
           error: "Either symbol or security_id must be provided",
@@ -318,27 +513,51 @@ class DhanHQDataTools
         }
       end
 
-      instrument_symbol = instrument_symbol.to_s
       exchange_segment = exchange_segment.to_s
 
-      # Find instrument to get security_id and instrument type if not provided
-      found_instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
-      unless found_instrument
-        return {
-          action: "get_historical_data",
-          error: "Instrument not found",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
-        }
-      end
+      # If security_id is provided, use it directly - it must be numeric (integer or numeric string), not a symbol
+      # If symbol is provided, find instrument first to get security_id and instrument type
+      if security_id && !symbol
+        is_valid, result = validate_security_id_numeric(security_id)
+        unless is_valid
+          return {
+            action: "get_historical_data",
+            error: result,
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
+        security_id_int = result
+        unless security_id_int.positive?
+          return {
+            action: "get_historical_data",
+            error: "security_id must be a positive integer, got: #{security_id.inspect}",
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
+        resolved_security_id = security_id_int.to_s
+        found_instrument = nil
+      else
+        # Find instrument using symbol (Instrument.find expects symbol, not security_id)
+        instrument_symbol = symbol.to_s
+        found_instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
+        unless found_instrument
+          return {
+            action: "get_historical_data",
+            error: "Instrument not found",
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
 
-      # Get security_id from instrument if not provided
-      resolved_security_id = security_id || safe_instrument_attr(found_instrument, :security_id)
-      unless resolved_security_id
-        return {
-          action: "get_historical_data",
-          error: "security_id is required and could not be determined from instrument",
-          params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
-        }
+        # Get security_id from instrument
+        resolved_security_id = safe_instrument_attr(found_instrument, :security_id)
+        unless resolved_security_id
+          return {
+            action: "get_historical_data",
+            error: "security_id is required and could not be determined from instrument",
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
+        resolved_security_id = resolved_security_id.to_s
       end
 
       # Determine instrument type if not provided
@@ -350,23 +569,11 @@ class DhanHQDataTools
       instrument_type_from_obj = instrument_type_from_obj.to_s.upcase if instrument_type_from_obj
       instrument_type_from_obj = nil unless valid_instruments.include?(instrument_type_from_obj)
 
-      # Use provided instrument, or validated instrument from object, or map from exchange_segment
-      resolved_instrument = if instrument
-                              instrument.to_s.upcase
-                            elsif instrument_type_from_obj
-                              instrument_type_from_obj
+      # Determine instrument type if not provided
+      resolved_instrument = if found_instrument
+                              instrument_type_from_obj || default_instrument_for(exchange_segment)
                             else
-                              case exchange_segment
-                              when "IDX_I" then "INDEX"
-                              when "NSE_EQ", "BSE_EQ" then "EQUITY"
-                              # For FNO, default to FUTIDX (can be overridden with expiry_code for options)
-                              when "NSE_FNO", "BSE_FNO" then "FUTIDX"
-                              # For currency, default to FUTCUR
-                              when "NSE_CURRENCY", "BSE_CURRENCY" then "FUTCUR"
-                              # For commodity, default to FUTCOM
-                              when "MCX_COMM" then "FUTCOM"
-                              else "EQUITY"
-                              end
+                              instrument&.to_s&.upcase || default_instrument_for(exchange_segment)
                             end
 
       # Final validation - ensure the resolved instrument type is valid
@@ -377,8 +584,6 @@ class DhanHQDataTools
                               "EQUITY"
                             end
 
-      resolved_security_id = resolved_security_id.to_s
-
       if interval
         # Intraday data using HistoricalData.intraday
         # Returns hash with :open, :high, :low, :close, :volume, :timestamp arrays
@@ -400,21 +605,57 @@ class DhanHQDataTools
                   0
                 end
 
-        {
-          action: "get_historical_data",
-          type: "intraday",
-          params: { security_id: resolved_security_id, symbol: symbol, exchange_segment: exchange_segment,
-                    instrument: resolved_instrument, from_date: from_date, to_date: to_date, interval: interval },
-          result: {
-            data: data,
-            count: count,
-            instrument_info: {
+        # If calculate_indicators is true, calculate technical indicators and return only those
+        if calculate_indicators && data.is_a?(Hash) && count.positive?
+          indicators = calculate_technical_indicators(data)
+          {
+            action: "get_historical_data",
+            type: "intraday",
+            params: {
               security_id: resolved_security_id,
-              trading_symbol: safe_instrument_attr(found_instrument, :trading_symbol),
-              instrument_type: resolved_instrument
+              symbol: symbol,
+              exchange_segment: exchange_segment,
+              instrument: resolved_instrument,
+              from_date: from_date,
+              to_date: to_date,
+              interval: interval
+            },
+            result: {
+              indicators: indicators,
+              data_points: count,
+              note: "Technical indicators calculated from historical data. " \
+                    "Raw data not included to reduce response size.",
+              instrument_info: {
+                security_id: resolved_security_id,
+                trading_symbol: safe_instrument_attr(found_instrument, :trading_symbol),
+                instrument_type: resolved_instrument
+              }
             }
           }
-        }
+        else
+          {
+            action: "get_historical_data",
+            type: "intraday",
+            params: {
+              security_id: resolved_security_id,
+              symbol: symbol,
+              exchange_segment: exchange_segment,
+              instrument: resolved_instrument,
+              from_date: from_date,
+              to_date: to_date,
+              interval: interval
+            },
+            result: {
+              data: data,
+              count: count,
+              instrument_info: {
+                security_id: resolved_security_id,
+                trading_symbol: safe_instrument_attr(found_instrument, :trading_symbol),
+                instrument_type: resolved_instrument
+              }
+            }
+          }
+        end
       else
         # Daily data using HistoricalData.daily
         # Returns hash with :open, :high, :low, :close, :volume, :timestamp arrays
@@ -435,21 +676,57 @@ class DhanHQDataTools
                   0
                 end
 
-        {
-          action: "get_historical_data",
-          type: "daily",
-          params: { security_id: resolved_security_id, symbol: symbol, exchange_segment: exchange_segment,
-                    instrument: resolved_instrument, from_date: from_date, to_date: to_date, expiry_code: expiry_code },
-          result: {
-            data: data,
-            count: count,
-            instrument_info: {
+        # If calculate_indicators is true, calculate technical indicators and return only those
+        if calculate_indicators && data.is_a?(Hash) && count.positive?
+          indicators = calculate_technical_indicators(data)
+          {
+            action: "get_historical_data",
+            type: "daily",
+            params: {
               security_id: resolved_security_id,
-              trading_symbol: safe_instrument_attr(found_instrument, :trading_symbol),
-              instrument_type: resolved_instrument
+              symbol: symbol,
+              exchange_segment: exchange_segment,
+              instrument: resolved_instrument,
+              from_date: from_date,
+              to_date: to_date,
+              expiry_code: expiry_code
+            },
+            result: {
+              indicators: indicators,
+              data_points: count,
+              note: "Technical indicators calculated from historical data. " \
+                    "Raw data not included to reduce response size.",
+              instrument_info: {
+                security_id: resolved_security_id,
+                trading_symbol: safe_instrument_attr(found_instrument, :trading_symbol),
+                instrument_type: resolved_instrument
+              }
             }
           }
-        }
+        else
+          {
+            action: "get_historical_data",
+            type: "daily",
+            params: {
+              security_id: resolved_security_id,
+              symbol: symbol,
+              exchange_segment: exchange_segment,
+              instrument: resolved_instrument,
+              from_date: from_date,
+              to_date: to_date,
+              expiry_code: expiry_code
+            },
+            result: {
+              data: data,
+              count: count,
+              instrument_info: {
+                security_id: resolved_security_id,
+                trading_symbol: safe_instrument_attr(found_instrument, :trading_symbol),
+                instrument_type: resolved_instrument
+              }
+            }
+          }
+        end
       end
     rescue StandardError => e
       {
@@ -458,115 +735,523 @@ class DhanHQDataTools
         params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
       }
     end
+
+    def default_instrument_for(exchange_segment)
+      defaults = {
+        "IDX_I" => "INDEX",
+        "NSE_FNO" => "FUTIDX",
+        "BSE_FNO" => "FUTIDX",
+        "NSE_CURRENCY" => "FUTCUR",
+        "BSE_CURRENCY" => "FUTCUR",
+        "MCX_COMM" => "FUTCOM"
+      }
+
+      defaults.fetch(exchange_segment, "EQUITY")
+    end
+
+    # Calculate technical indicators from historical data
+    # Returns only indicator values, not raw data
+    def calculate_technical_indicators(data)
+      return {} unless data.is_a?(Hash)
+
+      # Extract OHLCV arrays (handle both symbol and string keys)
+      highs = data[:high] || data["high"] || []
+      lows = data[:low] || data["low"] || []
+      closes = data[:close] || data["close"] || []
+      volumes = data[:volume] || data["volume"] || []
+      timestamps = data[:timestamp] || data["timestamp"] || []
+
+      return {} if closes.empty?
+
+      # Convert to arrays of floats
+      closes_f = closes.map(&:to_f)
+      highs_f = highs.map(&:to_f)
+      lows_f = lows.map(&:to_f)
+      volumes_f = volumes.map(&:to_f)
+
+      # Calculate indicators
+      sma20 = DhanHQ::Indicators::TechnicalIndicators.sma(closes_f, 20)
+      sma50 = DhanHQ::Indicators::TechnicalIndicators.sma(closes_f, 50)
+      ema12 = DhanHQ::Indicators::TechnicalIndicators.ema(closes_f, 12)
+      ema26 = DhanHQ::Indicators::TechnicalIndicators.ema(closes_f, 26)
+      rsi = DhanHQ::Indicators::TechnicalIndicators.rsi(closes_f, 14)
+      macd = DhanHQ::Indicators::TechnicalIndicators.macd(closes_f)
+      bollinger = DhanHQ::Indicators::TechnicalIndicators.bollinger_bands(closes_f, 20, 2)
+      atr = DhanHQ::Indicators::TechnicalIndicators.atr(highs_f, lows_f, closes_f, 14)
+
+      # Get latest values
+      {
+        current_price: closes_f.last,
+        sma20: sma20.last,
+        sma50: sma50.last,
+        ema12: ema12.last,
+        ema26: ema26.last,
+        rsi: rsi.last,
+        macd: {
+          macd: macd[:macd].last,
+          signal: macd[:signal].last,
+          histogram: macd[:histogram].last
+        },
+        bollinger_bands: {
+          upper: bollinger[:upper].last,
+          middle: bollinger[:middle].last,
+          lower: bollinger[:lower].last
+        },
+        atr: atr.last,
+        price_range: {
+          high: highs_f.max,
+          low: lows_f.min,
+          current: closes_f.last
+        },
+        volume: {
+          current: volumes_f.last,
+          average: volumes_f.any? ? (volumes_f.sum.to_f / volumes_f.length) : nil
+        },
+        data_points: closes_f.length,
+        last_timestamp: timestamps.last
+      }
+    rescue StandardError => e
+      {
+        error: "Failed to calculate indicators: #{e.message}"
+      }
+    end
     # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
-    # 6. Option Chain API - Get option chain using OptionChain.fetch
-    # Requires: underlying_scrip (security_id), underlying_seg (exchange_segment), expiry (optional)
+    # 6a. Option Expiry List API - Get list of available expiry dates for an underlying instrument
+    #
+    # REQUIRED PARAMETERS:
+    #   - exchange_segment [String]: Exchange and segment of underlying
+    #     For indices (NIFTY, BANKNIFTY): Use "IDX_I"
+    #     For stocks: Use "NSE_FNO" or "BSE_FNO"
+    #     Valid values: IDX_I (Index), NSE_FNO (NSE F&O), BSE_FNO (BSE F&O), MCX_FO (MCX)
+    #   - symbol [String] OR security_id [Integer]: Must provide one
+    #     symbol: Trading symbol (e.g., "NIFTY", "BANKNIFTY")
+    #     security_id: Numeric security ID of underlying (use value from find_instrument)
+    #
+    # Returns: Array of available expiry dates in "YYYY-MM-DD" format
+    #
+    # Rate limit: 1 request per 3 seconds
+    #
     # Note: For index options, underlying_seg should be "IDX_I", not "NSE_FNO"
-    def get_option_chain(exchange_segment:, security_id: nil, symbol: nil, expiry: nil)
-      # Need security_id - get it from instrument if we only have symbol
-      instrument_symbol = symbol || security_id
-      unless instrument_symbol
+    def get_expiry_list(exchange_segment:, security_id: nil, symbol: nil)
+      # CRITICAL: security_id must be an integer, not a symbol string
+      unless symbol || security_id
         return {
-          action: "get_option_chain",
+          action: "get_expiry_list",
           error: "Either symbol or security_id must be provided",
           params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
         }
       end
 
-      instrument_symbol = instrument_symbol.to_s
       exchange_segment = exchange_segment.to_s
 
-      # For option chains, we need the underlying security_id
-      # If exchange_segment is NSE_FNO/BSE_FNO, try to find the underlying in IDX_I or NSE_EQ
-      underlying_seg = exchange_segment
-      found_instrument = nil
+      # If security_id is provided, use it directly - it must be numeric (integer or numeric string), not a symbol
+      if security_id
+        is_valid, result = validate_security_id_numeric(security_id)
+        unless is_valid
+          return {
+            action: "get_expiry_list",
+            error: result,
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
+        security_id_int = result
+        unless security_id_int.positive?
+          return {
+            action: "get_expiry_list",
+            error: "security_id must be a positive integer, got: #{security_id.inspect}",
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+          }
+        end
 
-      # Try to find instrument to get security_id
-      found_instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
-      # If not found and exchange_segment is NSE_FNO/BSE_FNO, try IDX_I for index options
-      if !found_instrument && %w[NSE_FNO BSE_FNO].include?(exchange_segment)
-        found_instrument = DhanHQ::Models::Instrument.find("IDX_I", instrument_symbol)
-        underlying_seg = "IDX_I" if found_instrument
+        underlying_seg = if exchange_segment == "IDX_I"
+                           "IDX_I"
+                         else
+                           exchange_segment
+                         end
+        resolved_security_id = security_id_int
+        found_instrument = nil
+      elsif symbol
+        instrument_symbol = symbol.to_s
+        underlying_seg, found_instrument = find_underlying_instrument(exchange_segment, instrument_symbol)
+        resolved_security_id = resolve_security_id_for_option_chain(nil, found_instrument)
       end
 
-      # Get security_id from instrument if not provided
-      resolved_security_id = if security_id
-                               security_id.to_i
-                             elsif found_instrument
-                               safe_instrument_attr(found_instrument, :security_id)&.to_i
-                             else
-                               nil
-                             end
-
       unless resolved_security_id
         return {
-          action: "get_option_chain",
+          action: "get_expiry_list",
           error: "security_id is required and could not be determined from instrument",
           params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
         }
       end
 
-      if expiry
-        # Get option chain for specific expiry using OptionChain.fetch
-        chain = DhanHQ::Models::OptionChain.fetch(
-          underlying_scrip: resolved_security_id,
-          underlying_seg: underlying_seg,
-          expiry: expiry.to_s
-        )
-        {
-          action: "get_option_chain",
-          params: { security_id: resolved_security_id, symbol: symbol, exchange_segment: exchange_segment,
-                    expiry: expiry },
-          result: {
-            expiry: expiry,
-            underlying_last_price: chain[:last_price],
-            chain: chain[:oc], # oc contains strike prices as keys
-            instrument_info: {
-              underlying_security_id: resolved_security_id,
-              underlying_seg: underlying_seg,
-              trading_symbol: found_instrument ? safe_instrument_attr(found_instrument, :trading_symbol) : symbol
-            }
+      expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
+        underlying_scrip: resolved_security_id,
+        underlying_seg: underlying_seg
+      )
+
+      {
+        action: "get_expiry_list",
+        params: {
+          security_id: resolved_security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment
+        }.compact,
+        result: {
+          expiries: expiries,
+          count: expiries.is_a?(Array) ? expiries.length : 0,
+          instrument_info: {
+            underlying_security_id: resolved_security_id,
+            underlying_seg: underlying_seg,
+            trading_symbol: found_instrument ? safe_instrument_attr(found_instrument, :trading_symbol) : symbol
           }
         }
+      }
+    rescue StandardError => e
+      {
+        action: "get_expiry_list",
+        error: e.message,
+        params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+      }
+    end
+
+    # 6. Option Chain API - Get option chain using OptionChain.fetch
+    #
+    # REQUIRED PARAMETERS:
+    #   - exchange_segment [String]: Exchange and segment of underlying
+    #     For indices (NIFTY, BANKNIFTY): Use "IDX_I"
+    #     For stocks: Use "NSE_FNO" or "BSE_FNO"
+    #     Valid values: IDX_I (Index), NSE_FNO (NSE F&O), BSE_FNO (BSE F&O), MCX_FO (MCX)
+    #   - symbol [String] OR security_id [Integer]: Must provide one
+    #     symbol: Trading symbol (e.g., "NIFTY", "BANKNIFTY")
+    #     security_id: Numeric security ID of underlying (use value from find_instrument)
+    #   - expiry [String]: Expiry date in YYYY-MM-DD format (REQUIRED)
+    #
+    # Returns: Option chain with CE/PE data for all strikes
+    #
+    # Rate limit: 1 request per 3 seconds
+    # Automatically filters out strikes where both CE and PE have zero last_price
+    #
+    # Note: For index options, underlying_seg should be "IDX_I", not "NSE_FNO"
+    # Note: Use get_expiry_list first to get available expiry dates if you don't know the expiry
+    # Note: Chain is automatically filtered to show strikes around ATM (default: 5 strikes = 2 ITM, ATM, 2 OTM)
+    def get_option_chain(exchange_segment:, security_id: nil, symbol: nil, expiry: nil, strikes_count: 5)
+      # CRITICAL: security_id must be an integer, not a symbol string
+      unless symbol || security_id
+        return option_chain_error(
+          "Either symbol or security_id must be provided",
+          security_id: security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment
+        )
+      end
+
+      exchange_segment = exchange_segment.to_s
+
+      # If security_id is provided, use it directly - it must be numeric (integer or numeric string), not a symbol
+      # CRITICAL: Prefer security_id over symbol when both are provided, since security_id is more reliable
+      if security_id
+        is_valid, result = validate_security_id_numeric(security_id)
+        unless is_valid
+          return option_chain_error(
+            result,
+            security_id: security_id,
+            symbol: symbol,
+            exchange_segment: exchange_segment
+          )
+        end
+        security_id_int = result
+        unless security_id_int.positive?
+          return option_chain_error(
+            "security_id must be a positive integer, got: #{security_id.inspect}",
+            security_id: security_id,
+            symbol: symbol,
+            exchange_segment: exchange_segment
+          )
+        end
+
+        # For option chain, underlying_seg should be IDX_I for indices, or match exchange_segment
+        # For indices like NIFTY (IDX_I), underlying_seg must be IDX_I
+        underlying_seg = if exchange_segment == "IDX_I"
+                           "IDX_I"
+                         else
+                           exchange_segment
+                         end
+        resolved_security_id = security_id_int
+        found_instrument = nil
+      elsif symbol
+        # Find instrument using symbol (Instrument.find expects symbol, not security_id)
+        instrument_symbol = symbol.to_s
+        underlying_seg, found_instrument = find_underlying_instrument(exchange_segment, instrument_symbol)
+
+        # Get security_id from instrument
+        resolved_security_id = resolve_security_id_for_option_chain(nil, found_instrument)
       else
-        # Get list of available expiries using OptionChain.fetch_expiry_list
-        expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
-          underlying_scrip: resolved_security_id,
-          underlying_seg: underlying_seg
+        return option_chain_error(
+          "Either symbol or security_id must be provided",
+          security_id: security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment
         )
+      end
+
+      unless resolved_security_id
+        return option_chain_error(
+          "security_id is required and could not be determined from instrument",
+          security_id: security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment
+        )
+      end
+
+      # Validate expiry is provided and not empty
+      expiry_str = expiry.to_s.strip if expiry
+      if expiry_str.nil? || expiry_str.empty?
+        return option_chain_error(
+          "expiry is required. Use get_expiry_list to get available expiry dates first.",
+          security_id: security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment,
+          expiry: expiry
+        )
+      end
+
+      option_chain_for_expiry(
         {
-          action: "get_option_chain",
-          params: { security_id: resolved_security_id, symbol: symbol, exchange_segment: exchange_segment },
-          result: {
-            expiries: expiries,
-            count: expiries.is_a?(Array) ? expiries.length : 0,
-            instrument_info: {
-              underlying_security_id: resolved_security_id,
-              underlying_seg: underlying_seg,
-              trading_symbol: found_instrument ? safe_instrument_attr(found_instrument, :trading_symbol) : symbol
-            }
-          }
+          resolved_security_id: resolved_security_id,
+          underlying_seg: underlying_seg,
+          exchange_segment: exchange_segment,
+          symbol: symbol,
+          expiry: expiry,
+          found_instrument: found_instrument,
+          strikes_count: strikes_count
         }
-      end
+      )
     rescue StandardError => e
       {
         action: "get_option_chain",
         error: e.message,
-        params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+        params: {
+          security_id: security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment,
+          expiry: expiry
+        }.compact
+      }
+    end
+
+    def find_underlying_instrument(exchange_segment, instrument_symbol)
+      found_instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
+      return [exchange_segment, found_instrument] if found_instrument
+      return [exchange_segment, nil] unless %w[NSE_FNO BSE_FNO].include?(exchange_segment)
+
+      fallback_instrument = DhanHQ::Models::Instrument.find("IDX_I", instrument_symbol)
+      return ["IDX_I", fallback_instrument] if fallback_instrument
+
+      [exchange_segment, nil]
+    end
+
+    def resolve_security_id_for_option_chain(security_id, found_instrument)
+      return security_id.to_i if security_id
+
+      safe_instrument_attr(found_instrument, :security_id)&.to_i
+    end
+
+    def option_chain_for_expiry(params)
+      resolved_security_id = params.fetch(:resolved_security_id)
+      underlying_seg = params.fetch(:underlying_seg)
+      exchange_segment = params.fetch(:exchange_segment)
+      symbol = params.fetch(:symbol)
+      expiry = params.fetch(:expiry)
+      found_instrument = params[:found_instrument]
+      strikes_count = params.fetch(:strikes_count, 5) # Default: 5 strikes (2 ITM, ATM, 2 OTM)
+
+      # Ensure expiry is a string in YYYY-MM-DD format
+      expiry_str = expiry.to_s.strip
+
+      # Validate expiry format (basic check)
+      unless expiry_str.match?(/^\d{4}-\d{2}-\d{2}$/)
+        return option_chain_error(
+          "expiry must be in YYYY-MM-DD format, got: #{expiry.inspect}",
+          security_id: resolved_security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment,
+          expiry: expiry
+        )
+      end
+
+      # Ensure underlying_scrip is an integer (as per API docs)
+      underlying_scrip_int = resolved_security_id.to_i
+      unless underlying_scrip_int.positive?
+        return option_chain_error(
+          "underlying_scrip (security_id) must be a positive integer, got: #{resolved_security_id.inspect}",
+          security_id: resolved_security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment,
+          expiry: expiry
+        )
+      end
+
+      # Validate underlying_seg (as per API docs: IDX_I, NSE_FNO, BSE_FNO, MCX_FO)
+      valid_underlying_segs = %w[IDX_I NSE_FNO BSE_FNO MCX_FO]
+      unless valid_underlying_segs.include?(underlying_seg)
+        return option_chain_error(
+          "underlying_seg must be one of: #{valid_underlying_segs.join(', ')}, got: #{underlying_seg.inspect}",
+          security_id: resolved_security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment,
+          expiry: expiry
+        )
+      end
+
+      chain = DhanHQ::Models::OptionChain.fetch(
+        underlying_scrip: underlying_scrip_int,
+        underlying_seg: underlying_seg,
+        expiry: expiry_str
+      )
+
+      # Extract last_price and filter chain to only relevant strikes around ATM
+      last_price = chain[:last_price] || chain["last_price"]
+      full_chain = chain[:oc] || chain["oc"] || {}
+
+      # Filter chain to include strikes around ATM (default: 5 strikes = 2 ITM, ATM, 2 OTM)
+      filtered_chain = filter_option_chain(full_chain, last_price, strikes_count)
+
+      {
+        action: "get_option_chain",
+        params: option_chain_params(
+          resolved_security_id: resolved_security_id,
+          exchange_segment: exchange_segment,
+          symbol: symbol,
+          expiry: expiry
+        ),
+        result: {
+          expiry: expiry,
+          underlying_last_price: last_price,
+          chain: filtered_chain,
+          chain_count: filtered_chain.is_a?(Hash) ? filtered_chain.keys.length : 0,
+          note: "Chain filtered to show #{strikes_count} strikes around ATM (ITM, ATM, OTM)",
+          instrument_info: option_chain_instrument_info(
+            resolved_security_id: resolved_security_id,
+            underlying_seg: underlying_seg,
+            found_instrument: found_instrument,
+            symbol: symbol
+          )
+        }
+      }
+    end
+
+    def option_chain_expiry_list(resolved_security_id:, underlying_seg:, exchange_segment:, symbol:, found_instrument:)
+      expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
+        underlying_scrip: resolved_security_id,
+        underlying_seg: underlying_seg
+      )
+
+      {
+        action: "get_option_chain",
+        params: option_chain_params(
+          resolved_security_id: resolved_security_id,
+          exchange_segment: exchange_segment,
+          symbol: symbol
+        ),
+        result: {
+          expiries: expiries,
+          count: expiries.is_a?(Array) ? expiries.length : 0,
+          instrument_info: option_chain_instrument_info(
+            resolved_security_id: resolved_security_id,
+            underlying_seg: underlying_seg,
+            found_instrument: found_instrument,
+            symbol: symbol
+          )
+        }
+      }
+    end
+
+    def filter_option_chain(full_chain, last_price, strikes_count = 5)
+      return {} unless valid_option_chain_inputs?(full_chain, last_price)
+
+      strikes = extract_chain_strikes(full_chain)
+      return {} if strikes.empty?
+
+      selected_strikes = select_strike_keys(strikes, last_price.to_f, strikes_count)
+      return {} if selected_strikes.empty?
+
+      build_filtered_chain(full_chain, selected_strikes)
+    end
+
+    def option_chain_instrument_info(resolved_security_id:, underlying_seg:, found_instrument:, symbol:)
+      {
+        underlying_security_id: resolved_security_id,
+        underlying_seg: underlying_seg,
+        trading_symbol: found_instrument ? safe_instrument_attr(found_instrument, :trading_symbol) : symbol
+      }
+    end
+
+    def option_chain_params(resolved_security_id:, exchange_segment:, symbol:, expiry: nil)
+      {
+        security_id: resolved_security_id,
+        symbol: symbol,
+        exchange_segment: exchange_segment,
+        expiry: expiry
+      }.compact
+    end
+
+    def option_chain_error(message, security_id:, symbol:, exchange_segment:, expiry: nil)
+      {
+        action: "get_option_chain",
+        error: message,
+        params: {
+          security_id: security_id,
+          symbol: symbol,
+          exchange_segment: exchange_segment,
+          expiry: expiry
+        }.compact
       }
     end
 
     # 5. Expired Options Data API - Get historical expired options data using ExpiredOptionsData.fetch
-    # Requires: exchange_segment, interval, security_id, instrument (OPTIDX/OPTSTK), expiry_flag, expiry_code,
-    #           strike, drv_option_type, required_data, from_date, to_date
+    #
+    # REQUIRED PARAMETERS:
+    #   - exchange_segment [String]: Exchange and segment identifier
+    #     Valid values: NSE_FNO, BSE_FNO, NSE_EQ, BSE_EQ
+    #   - expiry_date [String]: Expiry date in YYYY-MM-DD format
+    #   - symbol [String] OR security_id [Integer]: Must provide one
+    #     symbol: Trading symbol of underlying
+    #     security_id: Numeric security ID of underlying
+    #
+    # OPTIONAL PARAMETERS (with defaults):
+    #   - interval [String]: Minute intervals for timeframe (default: "1")
+    #     Valid values: "1", "5", "15", "25", "60"
+    #   - instrument [String]: Instrument type (default: auto-detected)
+    #     Valid values: "OPTIDX" (Index Options), "OPTSTK" (Stock Options)
+    #     Default: "OPTIDX" for IDX_I, "OPTSTK" for others
+    #   - expiry_flag [String]: Expiry interval (default: "MONTH")
+    #     Valid values: "WEEK", "MONTH"
+    #   - expiry_code [Integer]: Expiry code (default: 1 - near month)
+    #     Valid values: 0 (far month), 1 (near month), 2 (current month)
+    #   - strike [String]: Strike price specification (default: "ATM")
+    #     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
+    #   - drv_option_type [String]: Option type (default: "CALL")
+    #     Valid values: "CALL", "PUT"
+    #   - required_data [Array<String>]: Array of required data fields (default: all fields)
+    #     Valid values: "open", "high", "low", "close", "iv", "volume", "strike", "oi", "spot"
+    #
+    # Returns: Historical expired options data organized by strike price relative to spot
+    #
+    # Notes:
+    #   - Up to 31 days of data can be fetched in a single request
+    #   - Historical data available for up to the last 5 years
+    #   - Data is organized by strike price relative to spot
+    #   - from_date is calculated from expiry_date, to_date is expiry_date + 1 day
+    #
     # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def get_expired_options_data(exchange_segment:, expiry_date:, security_id: nil, symbol: nil, expiry_code: nil,
                                  interval: "1", instrument: nil, expiry_flag: "MONTH", strike: "ATM",
                                  drv_option_type: "CALL", required_data: nil)
-      # Need security_id - get it from instrument if we only have symbol
-      instrument_symbol = symbol || security_id
-      unless instrument_symbol
+      # CRITICAL: security_id must be an integer, not a symbol string
+      unless symbol || security_id
         return {
           action: "get_expired_options_data",
           error: "Either symbol or security_id must be provided",
@@ -575,15 +1260,34 @@ class DhanHQDataTools
         }
       end
 
-      instrument_symbol = instrument_symbol.to_s
       exchange_segment = exchange_segment.to_s
 
-      # If security_id is provided directly, use it; otherwise find instrument
-      if security_id
-        resolved_security_id = security_id.to_s
-        found_instrument = nil # Don't need to find instrument if we have security_id
+      # If security_id is provided, use it directly - it must be numeric (integer or numeric string), not a symbol
+      if security_id && !symbol
+        is_valid, result = validate_security_id_numeric(security_id)
+        unless is_valid
+          return {
+            action: "get_expired_options_data",
+            error: result,
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment,
+                      expiry_date: expiry_date }
+          }
+        end
+        security_id_int = result
+        unless security_id_int.positive?
+          return {
+            action: "get_expired_options_data",
+            error: "security_id must be a positive integer, got: #{security_id.inspect}",
+            params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment,
+                      expiry_date: expiry_date }
+          }
+        end
+        resolved_security_id = security_id_int
+        found_instrument = nil
       else
-        # Find instrument to get security_id - try original exchange_segment first, then try IDX_I for indices
+        # Find instrument using symbol (Instrument.find expects symbol, not security_id)
+        instrument_symbol = symbol.to_s
+        # Try original exchange_segment first, then try IDX_I for indices
         found_instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
         # If not found and exchange_segment is NSE_FNO/BSE_FNO, try IDX_I for index options
         if !found_instrument && %w[NSE_FNO BSE_FNO].include?(exchange_segment)
@@ -609,7 +1313,7 @@ class DhanHQDataTools
                       expiry_date: expiry_date }
           }
         end
-        resolved_security_id = resolved_security_id.to_s
+        resolved_security_id = resolved_security_id.to_i
       end
 
       # Determine instrument type - must be OPTIDX or OPTSTK
@@ -652,7 +1356,7 @@ class DhanHQDataTools
       expired_data = DhanHQ::Models::ExpiredOptionsData.fetch(
         exchange_segment: exchange_segment,
         interval: interval.to_s,
-        security_id: resolved_security_id.to_i,
+        security_id: resolved_security_id,
         instrument: resolved_instrument,
         expiry_flag: expiry_flag.to_s.upcase,
         expiry_code: resolved_expiry_code.to_i,
@@ -694,6 +1398,209 @@ class DhanHQDataTools
       }
     end
     # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    private
+
+    def action_error(action:, message:, exchange_segment:, security_id:, symbol:)
+      {
+        action: action,
+        error: message,
+        params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment }
+      }
+    end
+
+    def require_symbol_or_security_id(action:, exchange_segment:, security_id:, symbol:)
+      return nil if symbol || security_id
+
+      action_error(action: action,
+                   message: "Either symbol or security_id must be provided",
+                   exchange_segment: exchange_segment,
+                   security_id: security_id,
+                   symbol: symbol)
+    end
+
+    def validated_security_id_for_marketfeed(action:, exchange_segment:, security_id:, symbol:)
+      is_valid, result = validate_security_id_numeric(security_id)
+      unless is_valid
+        return [action_error(action: action,
+                             message: result,
+                             exchange_segment: exchange_segment,
+                             security_id: security_id,
+                             symbol: symbol), nil]
+      end
+
+      return [nil, result] if result.positive?
+
+      [action_error(action: action,
+                    message: "security_id must be a positive integer, got: #{security_id.inspect}",
+                    exchange_segment: exchange_segment,
+                    security_id: security_id,
+                    symbol: symbol), nil]
+    end
+
+    def extract_quote_data(quote_response, exchange_segment:, security_id:)
+      return unless quote_response.is_a?(Hash) && quote_response["data"]
+
+      quote_response.dig("data", exchange_segment, security_id.to_s)
+    end
+
+    def market_quote_response(exchange_segment:, security_id:, symbol:, quote:, instrument_symbol: nil)
+      result = {
+        security_id: security_id,
+        exchange_segment: exchange_segment,
+        quote: quote
+      }
+      result[:symbol] = instrument_symbol if instrument_symbol
+
+      {
+        action: "get_market_quote",
+        params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment },
+        result: result
+      }
+    end
+
+    def market_quote_from_security_id(exchange_segment:, security_id_int:, symbol:)
+      payload = { exchange_segment => [security_id_int] }
+      quote_response = DhanHQ::Models::MarketFeed.quote(payload)
+      quote_data = extract_quote_data(quote_response, exchange_segment: exchange_segment, security_id: security_id_int)
+
+      market_quote_response(exchange_segment: exchange_segment,
+                            security_id: security_id_int,
+                            symbol: symbol,
+                            quote: quote_data || quote_response)
+    end
+
+    def market_quote_from_symbol(exchange_segment:, security_id:, symbol:)
+      instrument_symbol = symbol.to_s
+      instrument = DhanHQ::Models::Instrument.find(exchange_segment, instrument_symbol)
+      unless instrument
+        return action_error(action: "get_market_quote",
+                            message: "Instrument not found",
+                            exchange_segment: exchange_segment,
+                            security_id: security_id,
+                            symbol: symbol)
+      end
+
+      quote_response = instrument.quote
+      resolved_security_id = safe_instrument_attr(instrument, :security_id) || security_id
+      quote_data = extract_quote_data(quote_response,
+                                      exchange_segment: exchange_segment,
+                                      security_id: resolved_security_id || security_id)
+
+      market_quote_response(exchange_segment: exchange_segment,
+                            security_id: resolved_security_id,
+                            symbol: symbol,
+                            quote: quote_data || quote_response,
+                            instrument_symbol: instrument_symbol)
+    end
+
+    def live_ltp_response(exchange_segment:, security_id:, symbol:, ltp_payload:, instrument_symbol: nil)
+      result = {
+        security_id: security_id,
+        exchange_segment: exchange_segment,
+        ltp: ltp_payload[:ltp],
+        ltp_data: ltp_payload[:ltp_data]
+      }
+      result[:symbol] = instrument_symbol if instrument_symbol
+
+      {
+        action: "get_live_ltp",
+        params: { security_id: security_id, symbol: symbol, exchange_segment: exchange_segment },
+        result: result
+      }
+    end
+
+    def ltp_from_marketfeed(exchange_segment:, security_id:)
+      payload = { exchange_segment => [security_id] }
+      ltp_response = DhanHQ::Models::MarketFeed.ltp(payload)
+      parse_ltp_response(ltp_response, exchange_segment: exchange_segment, security_id: security_id)
+    end
+
+    def ltp_from_instrument(exchange_segment:, instrument:, security_id:)
+      ltp_response = instrument.ltp
+      resolved_security_id = safe_instrument_attr(instrument, :security_id) || security_id
+      ltp, ltp_data = parse_ltp_response(ltp_response,
+                                         exchange_segment: exchange_segment,
+                                         security_id: resolved_security_id || security_id)
+
+      [ltp, ltp_data, resolved_security_id]
+    end
+
+    def parse_ltp_response(ltp_response, exchange_segment:, security_id:)
+      if ltp_response.is_a?(Hash) && ltp_response["data"]
+        security_id_str = security_id.to_s
+        ltp_data = ltp_response.dig("data", exchange_segment, security_id_str)
+        ltp = extract_value(ltp_data, [:last_price, "last_price"]) if ltp_data
+        return [ltp, ltp_data]
+      end
+
+      if ltp_response.is_a?(Numeric)
+        ltp = ltp_response
+        return [ltp, { last_price: ltp }]
+      end
+
+      ltp = extract_value(ltp_response, [:last_price, "last_price", :ltp, "ltp"]) || ltp_response
+      [ltp, ltp_response]
+    end
+
+    def valid_option_chain_inputs?(full_chain, last_price)
+      return false unless full_chain.is_a?(Hash)
+      return false if last_price.nil?
+
+      last_price.to_f.nonzero?
+    end
+
+    def extract_chain_strikes(full_chain)
+      strikes = full_chain.filter_map do |strike_key, strike_data|
+        next unless strike_data.is_a?(Hash)
+        next unless strike_has_both_sides?(strike_data)
+
+        strike_float = strike_key.to_f
+        next unless strike_float.positive?
+
+        [strike_key, strike_float]
+      end
+      strikes.sort_by { |(_, price)| price }
+    end
+
+    def strike_has_both_sides?(strike_data)
+      (strike_data.key?(:ce) || strike_data.key?("ce")) &&
+        (strike_data.key?(:pe) || strike_data.key?("pe"))
+    end
+
+    def select_strike_keys(strikes, last_price, strikes_count)
+      atm_strike = strikes.min_by { |_, price| (price - last_price).abs }
+      return [] unless atm_strike
+
+      atm_index = strikes.index(atm_strike)
+      return [] unless atm_index
+
+      total_strikes = [strikes_count.to_i, 1].max
+      itm_count = (total_strikes - 1) / 2
+      otm_count = total_strikes - 1 - itm_count
+
+      selected = []
+      selected.concat(collect_strike_keys(strikes, atm_index - itm_count, atm_index - 1))
+      selected << atm_strike[0]
+      selected.concat(collect_strike_keys(strikes, atm_index + 1, atm_index + otm_count))
+      selected
+    end
+
+    def collect_strike_keys(strikes, start_idx, end_idx)
+      return [] if start_idx > end_idx
+
+      bounded_start = [start_idx, 0].max
+      bounded_end = [end_idx, strikes.length - 1].min
+      return [] if bounded_start > bounded_end
+
+      strikes[bounded_start..bounded_end].map { |strike| strike[0] }
+    end
+
+    def build_filtered_chain(full_chain, selected_strikes)
+      selected_strikes.each_with_object({}) do |strike_key, filtered|
+        filtered[strike_key] = full_chain[strike_key] if full_chain.key?(strike_key)
+      end
+    end
   end
 end