DhanHQ 3.0.0 → 3.1.0

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
@@ -62,25 +63,55 @@ module DhanHQ
           exact_match = options[:exact_match] || false
           case_sensitive = options[:case_sensitive] || false
 
-          instruments = by_segment(exchange_segment)
-          return nil if instruments.empty?
+          csv_text = resource.by_segment(exchange_segment)
+          return nil unless csv_text.is_a?(String) && !csv_text.empty?
 
+          require "csv"
           search_symbol = case_sensitive ? symbol : symbol.upcase
 
-          instruments.find do |instrument|
+          # Scan raw CSV rows and instantiate only the match — building a full
+          # Instrument for every row in a large segment (NSE_EQ is ~219k rows)
+          # is minutes-slow and can use gigabytes of memory (see #by_segment).
+          row = CSV.parse(csv_text, headers: true).find do |r|
             # For equity instruments, prefer underlying_symbol over symbol_name
-            instrument_symbol = if instrument.instrument == DhanHQ::Constants::InstrumentType::EQUITY && instrument.underlying_symbol
-                                  case_sensitive ? instrument.underlying_symbol : instrument.underlying_symbol.upcase
-                                else
-                                  case_sensitive ? instrument.symbol_name : instrument.symbol_name.upcase
-                                end
-
-            if exact_match
-              instrument_symbol == search_symbol
-            else
-              instrument_symbol.include?(search_symbol)
-            end
+            row_symbol = if r["INSTRUMENT"] == DhanHQ::Constants::InstrumentType::EQUITY && !r["UNDERLYING_SYMBOL"].to_s.empty?
+                           r["UNDERLYING_SYMBOL"]
+                         else
+                           r["SYMBOL_NAME"]
+                         end
+            next false if row_symbol.nil?
+
+            comparable = case_sensitive ? row_symbol : row_symbol.upcase
+            exact_match ? comparable == search_symbol : comparable.include?(search_symbol)
           end
+
+          return nil unless row
+
+          new(normalize_csv_row(row), skip_validation: true)
+        end
+
+        # Find a specific instrument within a segment by its security ID.
+        # @param exchange_segment [String] The exchange segment (e.g., "NSE_EQ", "NSE_FNO")
+        # @param security_id [String, Integer] The Dhan security ID
+        # @return [Instrument, nil] The found instrument or nil if not found
+        # @example
+        #   instrument = DhanHQ::Models::Instrument.find_by_security_id("NSE_EQ", "2885")
+        #   puts instrument.symbol_name  # => "RELIANCE"
+        def find_by_security_id(exchange_segment, security_id)
+          validate_params!({ exchange_segment: exchange_segment }, DhanHQ::Contracts::InstrumentListContract)
+
+          csv_text = resource.by_segment(exchange_segment)
+          return nil unless csv_text.is_a?(String) && !csv_text.empty?
+
+          require "csv"
+          # Scan raw CSV rows and instantiate only the match — building a full
+          # Instrument (and its per-attribute singleton methods) for every row
+          # in a large segment (NSE_EQ is ~219k rows) is minutes-slow and can
+          # use gigabytes of memory. See #by_segment for the bulk path.
+          row = CSV.parse(csv_text, headers: true).find { |r| r["SECURITY_ID"].to_s == security_id.to_s }
+          return nil unless row
+
+          new(normalize_csv_row(row), skip_validation: true)
         end
 
         # Find a specific instrument across all exchange segments.
@@ -114,6 +145,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.

data/lib/DhanHQ/models/position.rb

@@ -44,6 +44,72 @@ module DhanHQ
                  :day_sell_value, :drv_expiry_date, :drv_option_type, :drv_strike_price,
                  :cross_currency
 
+      # Returns a concise prompt-friendly summary of the position.
+      def to_prompt
+        parts = [
+          "#{position_type} #{net_qty}x #{trading_symbol || security_id}",
+          "on #{exchange_segment}/#{product_type}"
+        ]
+        parts << "buy_avg=#{buy_avg}" if buy_avg&.positive?
+        parts << "sell_avg=#{sell_avg}" if sell_avg&.positive?
+        parts << "realized_pnl=#{realized_profit}" if realized_profit
+        parts << "unrealized_pnl=#{unrealized_profit}" if unrealized_profit
+        parts << "expiry=#{drv_expiry_date}" if drv_expiry_date
+        parts << "strike=#{drv_strike_price}" if drv_strike_price&.positive?
+        parts << "type=#{drv_option_type}" if drv_option_type
+        parts.join(", ")
+      end
+
+      # Returns true if this is a long position.
+      def long?
+        position_type == DhanHQ::Constants::PositionType::LONG
+      end
+
+      # Returns true if this is a short position.
+      def short?
+        position_type == DhanHQ::Constants::PositionType::SHORT
+      end
+
+      # Returns true if this position is closed.
+      def closed?
+        position_type == DhanHQ::Constants::OrderStatus::CLOSED || net_qty.to_i.zero?
+      end
+
+      # Returns true if this position has an open quantity.
+      def open?
+        !closed? && net_qty.to_i != 0
+      end
+
+      # Returns true if this position is profitable (unrealized).
+      def profitable?
+        unrealized_profit.to_f.positive?
+      end
+
+      # Returns true if this position is in loss (unrealized).
+      def in_loss?
+        unrealized_profit.to_f.negative?
+      end
+
+      # Returns the total unrealized P&L including realized.
+      def total_pnl
+        realized_profit.to_f + unrealized_profit.to_f
+      end
+
+      # Returns true if this is an F&O position.
+      def derivatives?
+        drv_expiry_date.present? || drv_strike_price.to_f.positive?
+      end
+
+      # Returns true if this is an options position.
+      def options?
+        derivatives? && drv_option_type.present?
+      end
+
+      # Returns true if this is a futures position.
+      def futures?
+        derivatives? && drv_option_type.nil?
+      end
+
       class << self
         ##
         # Provides a shared instance of the Positions resource.

data/lib/DhanHQ/models/search_result.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    # Lightweight result returned by Instrument.search for agent-friendly security resolution.
+    class SearchResult < BaseModel
+      attributes :security_id, :symbol_name, :display_name, :exchange_segment, :instrument,
+                 :instrument_type, :lot_size, :tick_size, :expiry_date, :strike_price,
+                 :option_type, :underlying_symbol, :isin
+    end
+  end
+end

data/lib/DhanHQ/models/trade.rb

@@ -44,6 +44,19 @@ module DhanHQ
                  :create_time, :update_time, :exchange_time, :drv_expiry_date,
                  :drv_option_type, :drv_strike_price
 
+      # Returns a concise prompt-friendly summary of the trade.
+      def to_prompt
+        parts = [
+          "#{transaction_type} #{traded_quantity}x #{trading_symbol || security_id}",
+          "@ ₹#{traded_price}",
+          "on #{exchange_segment}/#{product_type}"
+        ]
+        parts << "order=#{order_id}" if order_id
+        parts << "charges=₹#{total_charges}" if respond_to?(:total_charges) && total_charges
+        parts << "time=#{create_time}" if create_time
+        parts.join(", ")
+      end
+
       class << self
         ##
         # Provides a shared instance of the Trades resource for current day tradebook APIs.

data/lib/DhanHQ/models/twap_order.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "../contracts/twap_order_contract"
+
+module DhanHQ
+  module Models
+    ##
+    # Model for creating and managing TWAP Orders.
+    #
+    # TWAP (Time-Weighted Average Price) orders split a large order into smaller
+    # slices distributed evenly across a defined time window. This minimizes market
+    # impact and achieves execution closer to the period's average price.
+    #
+    # @note **Static IP Whitelisting**: TWAP order creation, modification, and
+    #   cancellation APIs require Static IP whitelisting.
+    #
+    # @example Create a TWAP order
+    #   order = DhanHQ::Models::TwapOrder.create(
+    #     dhan_client_id: "1000000003",
+    #     transaction_type: "SELL",
+    #     exchange_segment: "NSE_EQ",
+    #     product_type: "INTRADAY",
+    #     order_type: "MARKET",
+    #     validity: "DAY",
+    #     security_id: "11536",
+    #     quantity: 500,
+    #     price: 0,                    # MARKET order
+    #     slice_interval: 300,         # 5 minutes
+    #     start_time: "09:30:00",
+    #     end_time: "15:00:00"
+    #   )
+    #   puts "TWAP Order ID: #{order.order_id} - #{order.order_status}"
+    #
+    # @example Modify a TWAP order (extend window)
+    #   order = DhanHQ::Models::TwapOrder.find(order_id)
+    #   order.modify(
+    #     dhan_client_id: "1000000003",
+    #     order_id: order_id,
+    #     end_time: "15:30:00",
+    #     slice_interval: 600
+    #   )
+    #
+    # @example Cancel a TWAP order
+    #   order = DhanHQ::Models::TwapOrder.find(order_id)
+    #   order.cancel
+    #
+    class TwapOrder < 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,
+                 :slice_interval, :start_time, :end_time, :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::TwapOrders]
+        def resource
+          @resource ||= DhanHQ::Resources::TwapOrders.new
+        end
+
+        # Retrieves all TWAP orders for the day.
+        #
+        # @return [Array<TwapOrder>]
+        def all
+          response = resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |o| new(o, skip_validation: true) }
+        end
+
+        # Retrieves a specific TWAP order by ID.
+        #
+        # @param order_id [String]
+        # @return [TwapOrder, 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 TWAP order.
+        #
+        # @param params [Hash{Symbol => String, Integer, Float}]
+        # @return [TwapOrder, 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::TwapOrderCreateContract)
+          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 TWAP order.
+      #
+      # @param new_params [Hash{Symbol => String, Integer, Float}]
+      # @return [TwapOrder, nil]
+      def modify(new_params)
+        raise "Order ID is required to modify a TWAP order" unless order_id
+
+        DhanHQ.logger&.info("[DhanHQ::Models::TwapOrder] 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::TwapOrderModifyContract)
+        formatted = camelize_keys(full_params)
+        response = self.class.resource.update(order_id, formatted)
+        success = handle_api_response(response, success_key: "orderId",
+                                                context: "[DhanHQ::Models::TwapOrder] Modification")
+        return self.class.find(order_id) if success
+
+        nil
+      end
+
+      # Cancels the TWAP order.
+      #
+      # @return [Boolean] true when cancelled successfully
+      def cancel
+        raise "Order ID is required to cancel a TWAP 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