DhanHQ 3.0.0 → 3.0.1

data/lib/DhanHQ/market_data/option_snapshot.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module MarketData
+    # A snapshot of option chain data for a single underlying.
+    #
+    # Wraps the raw OptionChain response into a convenient structure
+    # with typed accessors and helper methods for option analysis.
+    #
+    # @example Build a snapshot from OptionChain response
+    #   response = DhanHQ::Models::OptionChain.fetch(
+    #     underlying_scrip: 13,
+    #     underlying_seg: "IDX_I",
+    #     expiry: "2024-07-25"
+    #   )
+    #   snapshot = DhanHQ::MarketData::OptionSnapshot.from_response(response)
+    #   snapshot.calls_at(24000) #=> Array of call option data
+    #   snapshot.puts_at(24000) #=> Array of put option data
+    #
+    class OptionSnapshot
+      OptionLeg = Struct.new(:strike_price, :option_type, :ltp, :bid, :ask,
+                             :volume, :open_interest, :implied_volatility,
+                             :delta, :gamma, :theta, :vega) do
+        def call?
+          option_type == DhanHQ::Constants::OptionType::CALL
+        end
+
+        def put?
+          option_type == DhanHQ::Constants::OptionType::PUT
+        end
+
+        def itm?(spot_price)
+          return false unless spot_price
+
+          call? ? strike_price < spot_price : strike_price > spot_price
+        end
+
+        def otm?(spot_price)
+          return false unless spot_price
+
+          call? ? strike_price > spot_price : strike_price < spot_price
+        end
+
+        def atm?(spot_price)
+          return false unless spot_price
+
+          (strike_price - spot_price).abs < 1
+        end
+      end
+
+      attr_reader :underlying_scrip, :underlying_seg, :expiry, :legs, :spot_price, :fetched_at
+
+      def initialize(legs = [], metadata = {})
+        @underlying_scrip = metadata[:underlying_scrip]
+        @underlying_seg = metadata[:underlying_seg]
+        @expiry = metadata[:expiry]
+        @spot_price = metadata[:spot_price]
+        @legs = legs
+        @fetched_at = Time.now
+      end
+
+      # Build an OptionSnapshot from a raw OptionChain API response.
+      def self.from_response(response)
+        data = response.is_a?(Hash) ? (response[:data] || response["data"] || response) : response
+        return new([], {}) unless data.is_a?(Hash)
+
+        legs = parse_legs(data)
+        metadata = {
+          underlying_scrip: data[:underlyingScrip] || data["underlyingScrip"],
+          underlying_seg: data[:underlyingSeg] || data["underlyingSeg"],
+          expiry: data[:expiry] || data["expiry"],
+          spot_price: data[:spot] || data["spot"]
+        }
+
+        new(legs, metadata)
+      end
+
+      # Get all call option legs.
+      def calls
+        @legs.select(&:call?)
+      end
+
+      # Get all put option legs.
+      def puts
+        @legs.select(&:put?)
+      end
+
+      # Get all unique strike prices.
+      def strikes
+        @legs.map(&:strike_price).uniq.sort
+      end
+
+      # Get option legs at a specific strike price.
+      def at_strike(strike_price)
+        @legs.select { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get call option at a specific strike price.
+      def call_at(strike_price)
+        calls.find { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get put option at a specific strike price.
+      def put_at(strike_price)
+        puts.find { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get all ITM calls (calls with strike below spot).
+      def itm_calls
+        return [] unless @spot_price
+
+        calls.select { |leg| leg.itm?(@spot_price) }
+      end
+
+      # Get all OTM calls (calls with strike above spot).
+      def otm_calls
+        return [] unless @spot_price
+
+        calls.select { |leg| leg.otm?(@spot_price) }
+      end
+
+      # Get all ITM puts (puts with strike above spot).
+      def itm_puts
+        return [] unless @spot_price
+
+        puts.select { |leg| leg.itm?(@spot_price) }
+      end
+
+      # Get all OTM puts (puts with strike below spot).
+      def otm_puts
+        return [] unless @spot_price
+
+        puts.select { |leg| leg.otm?(@spot_price) }
+      end
+
+      # Find the ATM strike (closest to spot price).
+      def atm_strike
+        return nil unless @spot_price || strikes.any?
+
+        spot = @spot_price || strikes.first
+        strikes.min_by { |strike| (strike - spot).abs }
+      end
+
+      # Get the total open interest across all legs.
+      def total_oi
+        @legs.sum { |leg| leg.open_interest.to_i }
+      end
+
+      # Get the total volume across all legs.
+      def total_volume
+        @legs.sum { |leg| leg.volume.to_i }
+      end
+
+      # Calculate put-call ratio by open interest.
+      def pcr_by_oi
+        call_oi = calls.sum { |leg| leg.open_interest.to_i }
+        put_oi = puts.sum { |leg| leg.open_interest.to_i }
+        return 0.0 if call_oi.zero?
+
+        put_oi.to_f / call_oi
+      end
+
+      # Calculate put-call ratio by volume.
+      def pcr_by_volume
+        call_vol = calls.sum { |leg| leg.volume.to_i }
+        put_vol = puts.sum { |leg| leg.volume.to_i }
+        return 0.0 if call_vol.zero?
+
+        put_vol.to_f / call_vol
+      end
+
+      def self.parse_legs(data)
+        # Parse from the option chain structure
+        ce_data = data[:ce] || data["ce"] || {}
+        pe_data = data[:pe] || data["pe"] || {}
+
+        ce_strikes = ce_data[:strike] || ce_data["strike"] || []
+        pe_strikes = pe_data[:strike] || pe_data["strike"] || []
+
+        # Parse CE (call) and PE (put) legs
+        parse_option_legs(ce_data, DhanHQ::Constants::OptionType::CALL, ce_strikes) +
+          parse_option_legs(pe_data, DhanHQ::Constants::OptionType::PUT, pe_strikes)
+      end
+      private_class_method :parse_legs
+
+      def self.parse_option_legs(data, option_type, strikes)
+        return [] unless data.is_a?(Hash)
+
+        strikes.each_with_index.map do |strike, i|
+          build_leg(data, option_type, strike, i)
+        end
+      end
+      private_class_method :parse_option_legs
+
+      def self.build_leg(data, option_type, strike, index)
+        OptionLeg.new(
+          strike_price: strike.to_f,
+          option_type: option_type,
+          ltp: extract_value(data, :ltp, index),
+          bid: extract_value(data, :bid, index),
+          ask: extract_value(data, :ask, index),
+          volume: extract_value(data, :volume, index, as_integer: true),
+          open_interest: extract_value(data, :oi, index, as_integer: true),
+          implied_volatility: extract_value(data, :iv, index),
+          delta: extract_value(data, :delta, index),
+          gamma: extract_value(data, :gamma, index),
+          theta: extract_value(data, :theta, index),
+          vega: extract_value(data, :vega, index)
+        )
+      end
+      private_class_method :build_leg
+
+      def self.extract_value(data, key, index, as_integer: false)
+        values = data[key] || data[key.to_s] || []
+        value = values[index]
+        return nil if value.nil?
+
+        as_integer ? value.to_i : value.to_f
+      end
+      private_class_method :extract_value
+    end
+  end
+end

data/lib/DhanHQ/market_data.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "market_data/market_snapshot"
+require_relative "market_data/ohlc_series"
+require_relative "market_data/option_snapshot"
+
+module DhanHQ
+  # Higher-level abstractions for market data consumption.
+  #
+  # Provides typed wrappers around raw API responses for more convenient
+  # market data analysis and consumption.
+  #
+  # @example Quick market snapshot
+  #   response = DhanHQ::Models::MarketFeed.ltp("NSE_EQ" => [11536])
+  #   snapshot = DhanHQ::MarketData::MarketSnapshot.from_response(response)
+  #   puts snapshot.ltp("NSE_EQ", "11536")
+  #
+  # @example Historical OHLC series
+  #   response = DhanHQ::Models::HistoricalData.daily(...)
+  #   series = DhanHQ::MarketData::OHLCSeries.from_response(response)
+  #   puts series.average_close
+  #
+  module MarketData
+  end
+end

data/lib/DhanHQ/mcp/server.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../agent"
+
+module DhanHQ
+  module MCP
+    # Minimal MCP-compatible stdio JSON-RPC server for DhanHQ agent tools.
+    class Server
+      def initialize(input: $stdin, output: $stdout, policy: DhanHQ::Agent::Policy.from_env)
+        @input = input
+        @output = output
+        @policy = policy
+      end
+
+      def run
+        @input.each_line { |line| handle_line(line) }
+      end
+
+      def handle_line(line)
+        request = JSON.parse(line)
+        respond(request["id"], dispatch(request["method"], request["params"] || {}))
+      rescue StandardError => e
+        respond(nil, nil, code: -32_000, message: e.message)
+      end
+
+      private
+
+      def dispatch(method, params)
+        case method
+        when "initialize"
+          {
+            protocolVersion: "2024-11-05",
+            serverInfo: { name: "dhanhq-ruby", version: DhanHQ::VERSION },
+            capabilities: { tools: {} }
+          }
+        when "tools/list"
+          { tools: DhanHQ::Agent::ToolRegistry.list.map { |t| mcp_tool(t) } }
+        when "tools/call"
+          result = DhanHQ::Agent::ToolRegistry.execute(
+            params.fetch("name"),
+            params.fetch("arguments", {}),
+            policy: @policy
+          )
+          { content: [{ type: "text", text: JSON.pretty_generate(serialize(result)) }] }
+        else
+          raise ArgumentError, "Unsupported MCP method: #{method}"
+        end
+      end
+
+      def mcp_tool(tool)
+        { name: tool[:name], description: "[#{tool[:risk]}] #{tool[:description]}", inputSchema: tool[:input_schema] }
+      end
+
+      def serialize(value)
+        case value
+        when Array then value.map { |v| serialize(v) }
+        when Hash then value.transform_values { |v| serialize(v) }
+        else
+          value.respond_to?(:attributes) ? value.attributes : value
+        end
+      end
+
+      def respond(id, result, code: nil, message: nil)
+        payload = { jsonrpc: "2.0", id: id }
+        code ? payload[:error] = { code: code, message: message } : payload[:result] = result
+        @output.puts(JSON.generate(payload))
+        @output.flush
+      end
+    end
+  end
+end

data/lib/DhanHQ/mcp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "mcp/server"
+
+module DhanHQ
+  # MCP namespace provides Model Context Protocol server for AI agent integration.
+  # Enables stdio-based JSON-RPC communication with AI tools and agents.
+  module MCP
+  end
+end

data/lib/DhanHQ/models/funds.rb

@@ -29,6 +29,18 @@ module DhanHQ
       attributes :available_balance, :sod_limit, :collateral_amount, :receiveable_amount, :utilized_amount,
                  :blocked_payout_amount, :withdrawable_balance
 
+      # Returns a concise prompt-friendly summary of funds.
+      def to_prompt
+        parts = []
+        parts << "available=₹#{available_balance}" if available_balance
+        parts << "utilized=₹#{utilized_amount}" if utilized_amount
+        parts << "withdrawable=₹#{withdrawable_balance}" if withdrawable_balance
+        parts << "collateral=₹#{collateral_amount}" if collateral_amount&.positive?
+        parts << "sod_limit=₹#{sod_limit}" if sod_limit
+        parts << "blocked_payout=₹#{blocked_payout_amount}" if blocked_payout_amount&.positive?
+        parts.join(", ")
+      end
+
       ##
       # Normalizes the typo'd `availabelBalance` key from the API response to `available_balance`.
       #

data/lib/DhanHQ/models/holding.rb

@@ -33,6 +33,48 @@ module DhanHQ
       attributes :exchange, :trading_symbol, :security_id, :isin, :total_qty,
                  :dp_qty, :t1_qty, :available_qty, :collateral_qty, :avg_cost_price
 
+      # Returns a concise prompt-friendly summary of the holding.
+      def to_prompt
+        parts = [
+          "#{total_qty}x #{trading_symbol || security_id}",
+          "on #{exchange}"
+        ]
+        parts << "avg_cost=#{avg_cost_price}" if avg_cost_price&.positive?
+        parts << "available=#{available_qty}" if available_qty
+        parts << "dp=#{dp_qty}" if dp_qty&.positive?
+        parts << "t1=#{t1_qty}" if t1_qty&.positive?
+        parts << "collateral=#{collateral_qty}" if collateral_qty&.positive?
+        parts << "isin=#{isin}" if isin
+        parts.join(", ")
+      end
+
+      # Returns true if this holding has pending T1 delivery.
+      def pending_delivery?
+        t1_qty.to_i.positive?
+      end
+
+      # Returns true if this holding is fully delivered (no T1).
+      def delivered?
+        t1_qty.to_i.zero?
+      end
+
+      # Returns true if any quantity is pledged as collateral.
+      def pledged?
+        collateral_qty.to_i.positive?
+      end
+
+      # Returns the percentage of holding that is pledged.
+      def pledge_percentage
+        return 0.0 if total_qty.to_i.zero?
+
+        (collateral_qty.to_i.to_f / total_qty.to_i * 100).round(2)
+      end
+
+      # Returns true if this holding is partially pledged.
+      def partially_pledged?
+        pledged? && collateral_qty.to_i < total_qty.to_i
+      end
+
       class << self
         ##
         # Provides a shared instance of the Holdings resource.

data/lib/DhanHQ/models/iceberg_order.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "../contracts/iceberg_order_contract"
+
+module DhanHQ
+  module Models
+    ##
+    # Model for creating and managing Iceberg Orders.
+    #
+    # Iceberg orders allow you to place a large order while revealing only a small
+    # "visible" portion (disclosed quantity) to the market at a time. The remaining
+    # quantity is hidden and filled as prior legs execute, reducing market impact
+    # and information leakage.
+    #
+    # @note **Static IP Whitelisting**: Iceberg order creation, modification, and
+    #   cancellation APIs require Static IP whitelisting.
+    #
+    # @example Create an iceberg order
+    #   order = DhanHQ::Models::IcebergOrder.create(
+    #     dhan_client_id: "1000000003",
+    #     transaction_type: "BUY",
+    #     exchange_segment: "NSE_EQ",
+    #     product_type: "INTRADAY",
+    #     order_type: "LIMIT",
+    #     validity: "DAY",
+    #     security_id: "11536",
+    #     quantity: 1000,
+    #     price: 2450.50,
+    #     iceberg_qty: 100,
+    #     disclosed_quantity: 100
+    #   )
+    #   puts "Iceberg Order ID: #{order.order_id} - #{order.order_status}"
+    #
+    # @example Modify an iceberg order (change visible leg size)
+    #   order = DhanHQ::Models::IcebergOrder.find(order_id)
+    #   order.modify(
+    #     dhan_client_id: "1000000003",
+    #     order_id: order_id,
+    #     price: 2440.0,
+    #     iceberg_qty: 150
+    #   )
+    #
+    # @example Cancel an iceberg order
+    #   order = DhanHQ::Models::IcebergOrder.find(order_id)
+    #   order.cancel
+    #
+    # @example List all iceberg orders for the day
+    #   orders = DhanHQ::Models::IcebergOrder.all
+    #
+    class IcebergOrder < BaseModel
+      include Concerns::ApiResponseHandler
+
+      attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
+                 :transaction_type, :exchange_segment, :product_type, :order_type,
+                 :validity, :trading_symbol, :security_id, :quantity,
+                 :remaining_quantity, :price, :trigger_price, :after_market_order,
+                 :iceberg_qty, :disclosed_quantity, :leg_name,
+                 :create_time, :update_time, :exchange_time, :drv_expiry_date,
+                 :drv_option_type, :drv_strike_price,
+                 :oms_error_code, :oms_error_description, :average_traded_price, :filled_qty
+
+      class << self
+        # @return [DhanHQ::Resources::IcebergOrders]
+        def resource
+          @resource ||= DhanHQ::Resources::IcebergOrders.new
+        end
+
+        # Retrieves all iceberg orders for the day.
+        #
+        # @return [Array<IcebergOrder>]
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |o| new(o, skip_validation: true) }
+        end
+
+        # Retrieves a specific iceberg order by ID.
+        #
+        # @param order_id [String]
+        # @return [IcebergOrder, nil]
+        def find(order_id)
+          response = resource.find(order_id)
+          return nil unless response.is_a?(Hash) && response.any?
+
+          new(response, skip_validation: true)
+        end
+
+        # Creates a new iceberg order.
+        #
+        # @param params [Hash{Symbol => String, Integer, Float}]
+        # @return [IcebergOrder, nil]
+        def create(params)
+          normalized = snake_case(params)
+          config = DhanHQ.configuration
+          normalized[:dhan_client_id] ||= config.client_id if config&.client_id
+          validate_params!(normalized, DhanHQ::Contracts::IcebergOrderCreateContract)
+          formatted = camelize_keys(normalized)
+          response = resource.create(formatted)
+          return nil unless response.is_a?(Hash) && response["orderId"]
+
+          new(order_id: response["orderId"], order_status: response["orderStatus"], skip_validation: true)
+        end
+      end
+
+      # Modifies an existing iceberg order.
+      #
+      # @param new_params [Hash{Symbol => String, Integer, Float}]
+      # @return [IcebergOrder, nil]
+      def modify(new_params)
+        raise "Order ID is required to modify an iceberg order" unless order_id
+
+        DhanHQ.logger&.info("[DhanHQ::Models::IcebergOrder] Modifying order #{order_id}")
+        full_params = snake_case(new_params)
+        config = DhanHQ.configuration
+        full_params[:dhan_client_id] ||= config.client_id if config&.client_id
+        full_params[:order_id] = order_id
+        validate_params!(full_params, DhanHQ::Contracts::IcebergOrderModifyContract)
+        formatted = camelize_keys(full_params)
+        response = self.class.resource.update(order_id, formatted)
+        success = handle_api_response(response, success_key: "orderId",
+                                                context: "[DhanHQ::Models::IcebergOrder] Modification")
+        return self.class.find(order_id) if success
+
+        nil
+      end
+
+      # Cancels the iceberg order.
+      #
+      # @return [Boolean] true when cancelled successfully
+      def cancel
+        raise "Order ID is required to cancel an iceberg order" unless order_id
+
+        response = self.class.resource.cancel(order_id)
+        response.is_a?(Hash) && response["orderStatus"] == DhanHQ::Constants::OrderStatus::CANCELLED
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/instrument.rb

@@ -2,6 +2,7 @@
 
 require_relative "../contracts/instrument_list_contract"
 require_relative "instrument_helpers"
+require_relative "search_result"
 
 module DhanHQ
   module Models
@@ -114,6 +115,41 @@ module DhanHQ
           nil
         end
 
+        # Search instruments across segments and return agent-friendly search results.
+        # @param query [String] symbol/company/index text
+        # @param options [Hash] :segments, :limit, :exact_match, :case_sensitive
+        # @return [Array<DhanHQ::Models::SearchResult>]
+        def search(query, options = {})
+          raise ArgumentError, "query is required" if query.to_s.strip.empty?
+
+          limit = Integer(options.fetch(:limit, 20))
+          segments = options[:segments] || %w[NSE_EQ BSE_EQ IDX_I NSE_FNO BSE_FNO NSE_CURRENCY BSE_CURRENCY MCX_COMM]
+          exact_match = options.fetch(:exact_match, false)
+          case_sensitive = options.fetch(:case_sensitive, false)
+          needle = case_sensitive ? query.to_s : query.to_s.upcase
+
+          results = []
+          segments.each do |segment|
+            by_segment(segment).each do |instrument|
+              haystacks = [
+                instrument.symbol_name,
+                instrument.display_name,
+                instrument.underlying_symbol,
+                instrument.isin
+              ].compact
+              matched = haystacks.any? do |value|
+                comparable = case_sensitive ? value.to_s : value.to_s.upcase
+                exact_match ? comparable == needle : comparable.include?(needle)
+              end
+              next unless matched
+
+              results << DhanHQ::Models::SearchResult.new(instrument.attributes, skip_validation: true)
+              return results if results.length >= limit
+            end
+          end
+          results
+        end
+
         def normalize_csv_row(row)
           # Extract exchange and segment from CSV
           exchange_id = row["EXCH_ID"] || row["EXCHANGE"]

data/lib/DhanHQ/models/order.rb

@@ -73,6 +73,101 @@ module DhanHQ
                  :drv_strike_price, :oms_error_code, :oms_error_description, :algo_id,
                  :remaining_quantity, :average_traded_price, :filled_qty
 
+      # Returns a concise prompt-friendly summary of the order.
+      # Useful for AI agents to understand order state without raw attributes.
+      def to_prompt
+        parts = [
+          "#{transaction_type} #{quantity}x #{trading_symbol || security_id}",
+          "on #{exchange_segment}",
+          "as #{order_type}/#{product_type}",
+          "status=#{order_status}"
+        ]
+        parts << "price=#{price}" if price&.to_f&.positive?
+        parts << "trigger=#{trigger_price}" if trigger_price&.to_f&.positive?
+        parts << "filled=#{filled_qty}" if filled_qty&.positive?
+        parts << "remaining=#{remaining_quantity}" if remaining_quantity&.positive?
+        parts << "id=#{order_id}" if order_id
+        parts << "correlation=#{correlation_id}" if correlation_id
+        parts.join(", ")
+      end
+
+      # Returns true if the order has been fully filled.
+      def filled?
+        order_status == DhanHQ::Constants::OrderStatus::TRADED
+      end
+
+      # Returns true if the order is pending execution.
+      def pending?
+        order_status == DhanHQ::Constants::OrderStatus::PENDING
+      end
+
+      # Returns true if the order was rejected by the exchange.
+      def rejected?
+        order_status == DhanHQ::Constants::OrderStatus::REJECTED
+      end
+
+      # Returns true if the order was cancelled.
+      def cancelled?
+        order_status == DhanHQ::Constants::OrderStatus::CANCELLED
+      end
+
+      # Returns true if the order is in transit to the exchange.
+      def transit?
+        order_status == DhanHQ::Constants::OrderStatus::TRANSIT
+      end
+
+      # Returns true if the order is partially filled.
+      def partially_filled?
+        filled_qty.to_i.positive? && remaining_quantity.to_i.positive?
+      end
+
+      # Returns the fill percentage (0.0 to 100.0).
+      def fill_percentage
+        return 0.0 if quantity.to_i.zero?
+
+        (filled_qty.to_i.to_f / quantity.to_i * 100).round(2)
+      end
+
+      # Returns true if this is a buy order.
+      def buy?
+        transaction_type == DhanHQ::Constants::TransactionType::BUY
+      end
+
+      # Returns true if this is a sell order.
+      def sell?
+        transaction_type == DhanHQ::Constants::TransactionType::SELL
+      end
+
+      # Returns true if this is an intraday order.
+      def intraday?
+        product_type == DhanHQ::Constants::ProductType::INTRADAY
+      end
+
+      # Returns true if this is a delivery (CNC) order.
+      def delivery?
+        product_type == DhanHQ::Constants::ProductType::CNC
+      end
+
+      # Returns true if this is an MTF order.
+      def mtf?
+        product_type == DhanHQ::Constants::ProductType::MTF
+      end
+
+      # Returns true if this is a market order.
+      def market_order?
+        order_type == DhanHQ::Constants::OrderType::MARKET
+      end
+
+      # Returns true if this is a limit order.
+      def limit_order?
+        order_type == DhanHQ::Constants::OrderType::LIMIT
+      end
+
+      # Returns true if this is a stop-loss order.
+      def stop_loss_order?
+        order_type&.start_with?(DhanHQ::Constants::OrderType::STOP_LOSS)
+      end
+
       class << self
         ##
         # Provides a shared instance of the Orders resource.