DhanHQ 3.0.0 → 3.0.1

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

data/lib/DhanHQ/events/bus.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Event-driven architecture for the trading system.
+  #
+  # Provides pub/sub event bus, typed events, and async helpers.
+  #
+  # @example Subscribe to events
+  #   DhanHQ::Events.on(:order_filled) do |event|
+  #     puts "Order filled: #{event.order_id}"
+  #   end
+  #
+  # @example Emit events
+  #   DhanHQ::Events.emit(:order_filled, order_id: "123", filled_quantity: 10)
+  #
+  module Events
+    # Simple pub/sub event bus.
+    #
+    # Supports subscribing to specific event types or all events.
+    class Bus
+      def initialize
+        @subscribers = Hash.new { |h, k| h[k] = [] }
+        @global_subscribers = []
+      end
+
+      # Subscribe to an event type.
+      #
+      # @param event_type [Symbol, Class] Event type to subscribe to
+      # @param block [Proc] Handler block
+      # @return [Integer] Subscription ID for unsubscribing
+      def on(event_type, &block)
+        @subscribers[event_type] << block
+        @subscribers[event_type].length - 1
+      end
+
+      # Subscribe to all events.
+      #
+      # @param block [Proc] Handler block
+      # @return [Integer] Subscription ID
+      def subscribe_all(&block)
+        @global_subscribers << block
+        @global_subscribers.length - 1
+      end
+
+      # Unsubscribe from an event type.
+      #
+      # @param event_type [Symbol, Class] Event type
+      # @param subscription_id [Integer] Subscription ID from on()
+      # @return [Boolean] True if unsubscribed
+      # rubocop:disable Naming/PredicateMethod
+      def off(event_type, subscription_id)
+        return false unless @subscribers[event_type]
+
+        @subscribers[event_type].delete_at(subscription_id)
+        true
+      end
+
+      # Unsubscribe from all events.
+      #
+      # @param subscription_id [Integer] Subscription ID
+      # @return [Boolean] True if unsubscribed
+      def unsubscribe_all(subscription_id)
+        @global_subscribers.delete_at(subscription_id)
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Emit an event to all subscribers.
+      #
+      # @param event_type [Symbol, Class] Event type
+      # @param data [Hash] Event data
+      # @return [void]
+      def emit(event_type, data = {})
+        event = build_event(event_type, data)
+
+        # Notify type-specific subscribers
+        @subscribers[event_type]&.each do |handler|
+          handler.call(event)
+        rescue StandardError => e
+          DhanHQ.logger&.error("[Events] Error in handler for #{event_type}: #{e.message}")
+        end
+
+        # Notify global subscribers
+        @global_subscribers.each do |handler|
+          handler.call(event_type, event)
+        rescue StandardError => e
+          DhanHQ.logger&.error("[Events] Error in global handler: #{e.message}")
+        end
+      end
+
+      # Get count of subscribers for an event type.
+      #
+      # @param event_type [Symbol] Event type
+      # @return [Integer]
+      def subscriber_count(event_type)
+        @subscribers[event_type]&.length || 0
+      end
+
+      # Clear all subscribers.
+      def clear
+        @subscribers.clear
+        @global_subscribers.clear
+      end
+
+      private
+
+      def build_event(event_type, data)
+        case event_type
+        when :order_placed then OrderPlaced.new(data)
+        when :order_filled then OrderFilled.new(data)
+        when :order_cancelled then OrderCancelled.new(data)
+        when :order_rejected then OrderRejected.new(data)
+        when :sl_hit then SLHit.new(data)
+        when :tp_hit then TPHit.new(data)
+        when :tick_updated then TickUpdated.new(data)
+        when :position_opened then PositionOpened.new(data)
+        when :position_closed then PositionClosed.new(data)
+        when :strategy_signal then StrategySignal.new(data)
+        else
+          Base.new(data.merge(event_type: event_type))
+        end
+      end
+    end
+
+    # Default bus instance
+    @bus = Bus.new
+
+    class << self
+      # Get the default event bus.
+      attr_reader :bus
+
+      # Subscribe to an event type (delegates to bus).
+      def on(event_type, &)
+        bus.on(event_type, &)
+      end
+
+      # Subscribe to all events (delegates to bus).
+      def subscribe_all(&)
+        bus.subscribe_all(&)
+      end
+
+      # Emit an event (delegates to bus).
+      def emit(event_type, data = {})
+        bus.emit(event_type, data)
+      end
+
+      # Unsubscribe from an event type (delegates to bus).
+      def off(event_type, subscription_id)
+        bus.off(event_type, subscription_id)
+      end
+
+      # Clear all subscribers (delegates to bus).
+      def clear
+        bus.clear
+      end
+    end
+  end
+end

data/lib/DhanHQ/events.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "events/base"
+require_relative "events/bus"
+
+module DhanHQ
+  # Event-driven architecture for the trading system.
+  #
+  # Provides typed events, pub/sub event bus, and async helpers
+  # for building reactive trading applications.
+  #
+  # @example Subscribe to order events
+  #   DhanHQ::Events.on(:order_filled) do |event|
+  #     puts "Order filled: #{event.order_id}"
+  #     puts "Filled quantity: #{event.filled_quantity}"
+  #   end
+  #
+  # @example Emit events
+  #   DhanHQ::Events.emit(:order_filled, order_id: "123", filled_quantity: 10)
+  #
+  # @example Subscribe to all events
+  #   DhanHQ::Events.subscribe_all do |event_type, event|
+  #     puts "Event: #{event_type} - #{event}"
+  #   end
+  #
+  # Available event types:
+  # - :order_placed - Order placed successfully
+  # - :order_filled - Order fully or partially filled
+  # - :order_cancelled - Order cancelled
+  # - :order_rejected - Order rejected by exchange
+  # - :sl_hit - Stop loss triggered
+  # - :tp_hit - Take profit triggered
+  # - :tick_updated - New market tick received
+  # - :position_opened - New position opened
+  # - :position_closed - Position closed
+  # - :strategy_signal - Strategy generated a signal
+  #
+  module Events
+  end
+end