DhanHQ 2.8.0 → 3.0.1

data/lib/DhanHQ/ai/prompt_helpers.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module AI
+    # Helper methods for generating prompts for AI trading assistants.
+    #
+    # Provides methods to create system prompts, user prompts,
+    # and context summaries for AI models.
+    module PromptHelpers
+      # Generate a system prompt for an AI trading assistant.
+      #
+      # @param capabilities [Array<String>] List of capabilities
+      # @return [String] System prompt
+      def self.system_prompt(capabilities: [])
+        <<~PROMPT.strip
+          You are an AI trading assistant for Indian stock markets (NSE, BSE, MCX).
+
+          Your capabilities:
+          - Fetch market data (LTP, OHLC, quotes)
+          - Place, modify, and cancel orders
+          - View portfolio holdings, positions, and orders
+          - Calculate option Greeks and implied volatility
+          - Analyze option chains and Max Pain
+          - Apply risk management rules
+
+          #{"Additional capabilities:\n#{capabilities.map { |c| "- #{c}" }.join("\n")}" unless capabilities.empty?}
+
+          Rules:
+          - Always confirm before placing live orders
+          - Use correlation_id for all agent-originated orders
+          - Never expose access tokens or secrets
+          - Prefer read-only operations unless explicitly asked to trade
+          - Validate instruments before trading using search
+        PROMPT
+      end
+
+      # Generate a portfolio summary prompt.
+      #
+      # @param holdings [Array<DhanHQ::Models::Holding>] Holdings data
+      # @param positions [Array<DhanHQ::Models::Position>] Positions data
+      # @param funds [DhanHQ::Models::Funds] Funds data
+      # @return [String] Portfolio summary
+      def self.portfolio_summary(holdings:, positions:, funds:)
+        lines = ["=== Portfolio Summary ==="]
+        lines << "Funds: #{funds.to_prompt}" if funds
+        lines << ""
+        lines << "Holdings (#{holdings.size}):"
+        holdings.each { |h| lines << "  #{h.to_prompt}" }
+        lines << ""
+        lines << "Open Positions (#{positions.count(&:open?)}):"
+        positions.select(&:open?).each { |p| lines << "  #{p.to_prompt}" }
+        lines.join("\n")
+      end
+
+      # Generate a market analysis prompt.
+      #
+      # @param snapshot [DhanHQ::MarketData::MarketSnapshot] Market snapshot
+      # @param series [DhanHQ::MarketData::OHLCSeries] OHLC series
+      # @return [String] Market analysis prompt
+      def self.market_analysis(snapshot:, series: nil)
+        lines = ["=== Market Analysis ==="]
+        lines << "Snapshot: #{snapshot.size} instruments"
+        lines << "Series: #{series&.size || 0} candles"
+
+        if series&.any?
+          lines << "Latest close: ₹#{series.last.close}"
+          lines << "Average close: ₹#{series.average_close&.round(2)}"
+          lines << "Price range: ₹#{series.price_range&.round(2)}"
+        end
+
+        lines.join("\n")
+      end
+
+      # Generate an order confirmation prompt.
+      #
+      # @param order_params [Hash] Order parameters
+      # @return [String] Order confirmation prompt
+      def self.order_confirmation(order_params)
+        <<~PROMPT.strip
+          === Order Confirmation Required ===
+          #{order_params[:transaction_type]} #{order_params[:quantity]}x #{order_params[:security_id]}
+          Exchange: #{order_params[:exchange_segment]}
+          Product: #{order_params[:product_type]}
+          Type: #{order_params[:order_type]}
+          #{order_params[:price] ? "Price: ₹#{order_params[:price]}" : "Market Price"}
+          #{"Trigger: ₹#{order_params[:trigger_price]}" if order_params[:trigger_price]}
+
+          Please confirm this order.
+        PROMPT
+      end
+
+      # Generate a risk report prompt.
+      #
+      # @param positions [Array<DhanHQ::Models::Position>] Current positions
+      # @param risk_params [Hash] Risk parameters
+      # @return [String] Risk report
+      def self.risk_report(positions:, risk_params: {})
+        lines = ["=== Risk Report ==="]
+        total_unrealized = positions.sum { |p| p.unrealized_profit.to_f }
+        total_realized = positions.sum { |p| p.realized_profit.to_f }
+
+        lines << "Total Unrealized P&L: ₹#{total_unrealized.round(2)}"
+        lines << "Total Realized P&L: ₹#{total_realized.round(2)}"
+        lines << "Open Positions: #{positions.count(&:open?)}"
+
+        lines << "Max Drawdown: #{risk_params[:max_drawdown]}%" if risk_params[:max_drawdown]
+
+        lines << "Daily Loss Limit: ₹#{risk_params[:daily_loss_limit]}" if risk_params[:daily_loss_limit]
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/DhanHQ/ai.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "ai/context_builder"
+require_relative "ai/prompt_helpers"
+
+module DhanHQ
+  # AI integration layer for building AI-powered trading assistants.
+  #
+  # Provides workflow orchestration, prompt helpers, and context
+  # serialization for AI agents.
+  #
+  # @example Build context for AI
+  #   context = DhanHQ::AI::ContextBuilder.build do |ctx|
+  #     ctx.add_portfolio
+  #     ctx.add_positions
+  #     ctx.add_recent_orders(limit: 10)
+  #   end
+  #   puts context.to_prompt
+  #
+  # @example Generate system prompt
+  #   prompt = DhanHQ::AI::PromptHelpers.system_prompt(
+  #     capabilities: ["Option chain analysis", "Greeks calculation"]
+  #   )
+  #
+  module AI
+  end
+end

data/lib/DhanHQ/auth.rb

@@ -91,7 +91,6 @@ module DhanHQ
     def self.build_connection(base_url)
       Faraday.new(url: base_url) do |c|
         c.request :url_encoded
-        c.response :json, content_type: /\bjson$/
         c.adapter Faraday.default_adapter
       end
     end

data/lib/DhanHQ/client.rb

@@ -212,9 +212,7 @@ module DhanHQ
       write_timeout = ENV.fetch("DHAN_WRITE_TIMEOUT", 30).to_i
 
       Faraday.new(url: url) do |conn|
-        conn.request :json, parser_options: { symbolize_names: true }
-        conn.response :json, content_type: /\bjson$/
-        conn.response :logger if ENV["DHAN_DEBUG"] == "true"
+        conn.request :url_encoded
         conn.options.timeout = read_timeout
         conn.options.open_timeout = connect_timeout
         conn.options.write_timeout = write_timeout

data/lib/DhanHQ/constants.rb

@@ -475,6 +475,8 @@ module DhanHQ
     PAYLOAD_REQUIRES_DHAN_CLIENT_ID_PREFIXES = %w[
       /alerts/orders
       /v2/orders
+      /v2/orders/iceberg
+      /v2/orders/twap
       /v2/forever
       /v2/super/orders
       /v2/positions

data/lib/DhanHQ/contracts/iceberg_order_contract.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "base_contract"
+
+module DhanHQ
+  module Contracts
+    # Validates request for POST /v2/orders/iceberg (create Iceberg order).
+    #
+    # Iceberg orders split a large order into multiple visible legs of a fixed
+    # disclosed quantity, reducing market impact.
+    class IcebergOrderCreateContract < BaseContract
+      params do
+        required(:dhan_client_id).filled(:string)
+        required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
+        required(:exchange_segment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
+        required(:product_type).filled(:string, included_in?: PRODUCT_TYPES)
+        required(:order_type).filled(:string, included_in?: ORDER_TYPES)
+        required(:validity).filled(:string, included_in?: VALIDITY_TYPES)
+        required(:security_id).filled(:string)
+        required(:quantity).filled(:integer, gt?: 0)
+        required(:price).filled(:float, gt?: 0)
+        required(:iceberg_qty).filled(:integer, gt?: 0)
+        required(:disclosed_quantity).filled(:integer, gteq?: 0)
+        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:trigger_price).maybe(:float, gteq?: 0)
+        optional(:after_market_order).maybe(:bool)
+        optional(:amo_time).maybe(:string, included_in?: AMO_TIMINGS)
+        optional(:drv_expiry_date).maybe(:string)
+        optional(:drv_option_type).maybe(:string, included_in?: %w[CALL PUT NA])
+        optional(:drv_strike_price).maybe(:float, gt?: 0)
+      end
+
+      rule(:iceberg_qty) do
+        key.failure("must not exceed total quantity") if value && values[:quantity] && value > values[:quantity]
+      end
+    end
+
+    # Validates request for PUT /v2/orders/iceberg/{order-id} (modify Iceberg order).
+    class IcebergOrderModifyContract < BaseContract
+      params do
+        required(:dhan_client_id).filled(:string)
+        required(:order_id).filled(:string)
+
+        optional(:transaction_type).maybe(:string, included_in?: TRANSACTION_TYPES)
+        optional(:exchange_segment).maybe(:string, included_in?: EXCHANGE_SEGMENTS)
+        optional(:product_type).maybe(:string, included_in?: PRODUCT_TYPES)
+        optional(:order_type).maybe(:string, included_in?: ORDER_TYPES)
+        optional(:validity).maybe(:string, included_in?: VALIDITY_TYPES)
+        optional(:security_id).maybe(:string, max_size?: 20)
+        optional(:quantity).maybe(:integer, gt?: 0)
+        optional(:price).maybe(:float, gt?: 0)
+        optional(:iceberg_qty).maybe(:integer, gt?: 0)
+        optional(:disclosed_quantity).maybe(:integer, gteq?: 0)
+        optional(:trigger_price).maybe(:float, gteq?: 0)
+        optional(:after_market_order).maybe(:bool)
+        optional(:amo_time).maybe(:string, included_in?: AMO_TIMINGS)
+      end
+
+      rule do
+        modifiable_fields = %i[
+          quantity price iceberg_qty disclosed_quantity
+          trigger_price validity order_type product_type
+        ]
+        changed = modifiable_fields.any? { |field| values.key?(field) && !values[field].nil? }
+        base.failure("at least one modifiable field must be provided") unless changed
+      end
+
+      rule(:order_type, :price) do
+        key(:price).failure("cannot modify price for MARKET orders") if values[:order_type] == DhanHQ::Constants::OrderType::MARKET && values[:price]
+      end
+
+      rule(:order_type, :trigger_price) do
+        if %w[STOP_LOSS STOP_LOSS_MARKET].include?(values[:order_type]) && (values[:trigger_price].nil? || values[:trigger_price].to_f <= 0)
+          key(:trigger_price).failure("must be present and greater than zero for STOP_LOSS orders")
+        end
+      end
+
+      rule(:iceberg_qty) do
+        key.failure("must not exceed total quantity") if value && values[:quantity] && value > values[:quantity]
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/twap_order_contract.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "base_contract"
+
+module DhanHQ
+  module Contracts
+    # Validates request for POST /v2/orders/twap (create TWAP order).
+    #
+    # TWAP orders slice the total quantity across the trading window at a fixed
+    # interval to minimize market impact and achieve time-weighted execution.
+    class TwapOrderCreateContract < BaseContract
+      params do
+        required(:dhan_client_id).filled(:string)
+        required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
+        required(:exchange_segment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
+        required(:product_type).filled(:string, included_in?: PRODUCT_TYPES)
+        required(:order_type).filled(:string, included_in?: ORDER_TYPES)
+        required(:validity).filled(:string, included_in?: VALIDITY_TYPES)
+        required(:security_id).filled(:string)
+        required(:quantity).filled(:integer, gt?: 0)
+        required(:price).filled(:float, gt?: 0)
+        required(:slice_interval).filled(:integer, gt?: 0)
+        required(:start_time).filled(:string, format?: /\A([01]?\d|2[0-3]):([0-5]?\d):([0-5]?\d)\z/)
+        required(:end_time).filled(:string, format?: /\A([01]?\d|2[0-3]):([0-5]?\d):([0-5]?\d)\z/)
+        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:trigger_price).maybe(:float, gteq?: 0)
+        optional(:after_market_order).maybe(:bool)
+        optional(:amo_time).maybe(:string, included_in?: AMO_TIMINGS)
+        optional(:drv_expiry_date).maybe(:string)
+        optional(:drv_option_type).maybe(:string, included_in?: %w[CALL PUT NA])
+        optional(:drv_strike_price).maybe(:float, gt?: 0)
+      end
+
+      rule(:start_time, :end_time) do
+        next unless values[:start_time] && values[:end_time]
+
+        start_minutes = time_to_minutes(values[:start_time])
+        end_minutes = time_to_minutes(values[:end_time])
+        key.failure("must be after start_time") if end_minutes <= start_minutes
+      end
+
+      rule(:slice_interval) do
+        next unless value&.positive?
+
+        start_minutes = time_to_minutes(values[:start_time])
+        end_minutes = time_to_minutes(values[:end_time])
+        window_minutes = end_minutes - start_minutes
+        key.failure("slice interval must fit within the execution window") if value > (window_minutes * 60)
+      end
+
+      def time_to_minutes(time_str)
+        parts = time_str.split(":").map(&:to_i)
+        (parts[0] * 60) + parts[1]
+      end
+    end
+
+    # Validates request for PUT /v2/orders/twap/{order-id} (modify TWAP order).
+    class TwapOrderModifyContract < BaseContract
+      params do
+        required(:dhan_client_id).filled(:string)
+        required(:order_id).filled(:string)
+
+        optional(:transaction_type).maybe(:string, included_in?: TRANSACTION_TYPES)
+        optional(:exchange_segment).maybe(:string, included_in?: EXCHANGE_SEGMENTS)
+        optional(:product_type).maybe(:string, included_in?: PRODUCT_TYPES)
+        optional(:order_type).maybe(:string, included_in?: ORDER_TYPES)
+        optional(:validity).maybe(:string, included_in?: VALIDITY_TYPES)
+        optional(:security_id).maybe(:string, max_size?: 20)
+        optional(:quantity).maybe(:integer, gt?: 0)
+        optional(:price).maybe(:float, gt?: 0)
+        optional(:slice_interval).maybe(:integer, gt?: 0)
+        optional(:start_time).maybe(:string, format?: /\A([01]?\d|2[0-3]):([0-5]?\d):([0-5]?\d)\z/)
+        optional(:end_time).maybe(:string, format?: /\A([01]?\d|2[0-3]):([0-5]?\d):([0-5]?\d)\z/)
+        optional(:trigger_price).maybe(:float, gteq?: 0)
+        optional(:after_market_order).maybe(:bool)
+        optional(:amo_time).maybe(:string, included_in?: AMO_TIMINGS)
+      end
+
+      rule do
+        modifiable_fields = %i[
+          quantity price slice_interval start_time end_time
+          trigger_price validity order_type product_type
+        ]
+        changed = modifiable_fields.any? { |field| values.key?(field) && !values[field].nil? }
+        base.failure("at least one modifiable field must be provided") unless changed
+      end
+
+      rule(:order_type, :price) do
+        key(:price).failure("cannot modify price for MARKET orders") if values[:order_type] == DhanHQ::Constants::OrderType::MARKET && values[:price]
+      end
+
+      rule(:start_time, :end_time) do
+        next unless values[:start_time] && values[:end_time]
+
+        start_minutes = time_to_minutes(values[:start_time])
+        end_minutes = time_to_minutes(values[:end_time])
+        key.failure("must be after start_time") if end_minutes <= start_minutes
+      end
+
+      def time_to_minutes(time_str)
+        parts = time_str.split(":").map(&:to_i)
+        (parts[0] * 60) + parts[1]
+      end
+    end
+  end
+end

data/lib/DhanHQ/core/auth_api.rb

@@ -13,7 +13,6 @@ module DhanHQ
     def connection
       @connection ||= Faraday.new(url: BASE_URL) do |faraday|
         faraday.request :url_encoded
-        faraday.response :json, content_type: /\bjson$/
         faraday.adapter Faraday.default_adapter
       end
     end

data/lib/DhanHQ/errors.rb

@@ -53,6 +53,10 @@ module DhanHQ
   # Raised when the API signals an issue with the requested data payload.
   class DataError < Error; end
 
+  # Risk management errors
+  # Raised when a pre-execution risk check fails (ASM/GSM, quantity, market hours, etc.)
+  class RiskViolation < Error; end
+
   # Server and network-related errors
   # DH-908, 800
   class InternalServerError < Error; end

data/lib/DhanHQ/events/base.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Event types for the trading system.
+  #
+  # Provides typed event classes for order lifecycle, market data,
+  # position updates, and strategy signals.
+  #
+  # @example Subscribe to order events
+  #   DhanHQ::Events.on(:order_filled) do |event|
+  #     puts "Order filled: #{event.order_id}"
+  #   end
+  #
+  module Events
+    # Base event class with common attributes.
+    class Base
+      attr_reader :timestamp, :data
+
+      def initialize(data = {})
+        @timestamp = Time.now
+        @data = data
+      end
+
+      def to_h
+        {
+          event_type: self.class.name.split("::").last.downcase.to_sym,
+          timestamp: timestamp,
+          data: data
+        }
+      end
+
+      def to_prompt
+        "#{self.class.name.split("::").last}: #{data.inspect}"
+      end
+    end
+
+    # Order placed event.
+    class OrderPlaced < Base
+      def order_id
+        data[:order_id]
+      end
+
+      def to_s
+        "OrderPlaced(#{order_id})"
+      end
+    end
+
+    # Order filled event.
+    class OrderFilled < Base
+      def order_id
+        data[:order_id]
+      end
+
+      def filled_quantity
+        data[:filled_quantity]
+      end
+
+      def filled_price
+        data[:filled_price]
+      end
+
+      def to_s
+        "OrderFilled(#{order_id}, #{filled_quantity}@#{filled_price})"
+      end
+    end
+
+    # Order cancelled event.
+    class OrderCancelled < Base
+      def order_id
+        data[:order_id]
+      end
+
+      def reason
+        data[:reason]
+      end
+
+      def to_s
+        "OrderCancelled(#{order_id}, reason=#{reason})"
+      end
+    end
+
+    # Order rejected event.
+    class OrderRejected < Base
+      def order_id
+        data[:order_id]
+      end
+
+      def error_code
+        data[:error_code]
+      end
+
+      def error_message
+        data[:error_message]
+      end
+
+      def to_s
+        "OrderRejected(#{order_id}, #{error_code}: #{error_message})"
+      end
+    end
+
+    # Stop loss hit event.
+    class SLHit < Base
+      def order_id
+        data[:order_id]
+      end
+
+      def trigger_price
+        data[:trigger_price]
+      end
+
+      def to_s
+        "SLHit(#{order_id}, trigger=#{trigger_price})"
+      end
+    end
+
+    # Take profit hit event.
+    class TPHit < Base
+      def order_id
+        data[:order_id]
+      end
+
+      def target_price
+        data[:target_price]
+      end
+
+      def to_s
+        "TPHit(#{order_id}, target=#{target_price})"
+      end
+    end
+
+    # Market data tick event.
+    class TickUpdated < Base
+      def security_id
+        data[:security_id]
+      end
+
+      def ltp
+        data[:ltp]
+      end
+
+      def volume
+        data[:volume]
+      end
+
+      def to_s
+        "TickUpdated(#{security_id}, ltp=#{ltp})"
+      end
+    end
+
+    # Position opened event.
+    class PositionOpened < Base
+      def security_id
+        data[:security_id]
+      end
+
+      def quantity
+        data[:quantity]
+      end
+
+      def side
+        data[:side]
+      end
+
+      def to_s
+        "PositionOpened(#{security_id}, #{side} #{quantity})"
+      end
+    end
+
+    # Position closed event.
+    class PositionClosed < Base
+      def security_id
+        data[:security_id]
+      end
+
+      def profit_loss
+        data[:profit_loss]
+      end
+
+      def to_s
+        "PositionClosed(#{security_id}, pnl=#{profit_loss})"
+      end
+    end
+
+    # Strategy signal event.
+    class StrategySignal < Base
+      def strategy_name
+        data[:strategy_name]
+      end
+
+      def signal_type
+        data[:signal_type]
+      end
+
+      def strength
+        data[:strength]
+      end
+
+      def to_s
+        "StrategySignal(#{strategy_name}, #{signal_type}, strength=#{strength})"
+      end
+    end
+  end
+end