DhanHQ 2.1.3 → 2.1.6

data/examples/order_update_example.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Order Update WebSocket Example
+# This script demonstrates how to use the DhanHQ Order Update WebSocket
+# Receives real-time order status updates and execution notifications
+# NOTE: Uses a SINGLE connection to avoid rate limiting
+
+require "dhan_hq"
+
+# Configure DhanHQ
+DhanHQ.configure do |config|
+  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
+  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  config.ws_user_type = ENV["DHAN_WS_USER_TYPE"] || "SELF"
+end
+
+puts "DhanHQ Order Update WebSocket Example"
+puts "====================================="
+puts "Receives real-time order updates including:"
+puts "- Order status changes"
+puts "- Execution notifications"
+puts "- Order rejections"
+puts "- Trade confirmations"
+puts ""
+puts "NOTE: Using SINGLE connection to avoid rate limiting (429 errors)"
+puts "Dhan allows up to 5 WebSocket connections per user"
+puts ""
+
+# Order Update WebSocket Connection
+puts "Order Update WebSocket Connection"
+puts "================================="
+
+# Create a single order update WebSocket connection
+puts "Creating Order Update WebSocket connection..."
+orders_client = DhanHQ::WS::Orders.connect do |order_update|
+  puts "Order Update: #{order_update.order_no} - #{order_update.status}"
+  puts "  Symbol: #{order_update.symbol}"
+  puts "  Quantity: #{order_update.quantity}"
+  puts "  Traded Qty: #{order_update.traded_qty}"
+  puts "  Price: #{order_update.price}"
+  puts "  Execution: #{order_update.execution_percentage}%"
+  puts "  ---"
+end
+
+# Add event handlers for different order events
+puts "\nSetting up event handlers..."
+
+orders_client.on(:update) do |order_update|
+  puts "📝 Order Updated: #{order_update.order_no} - #{order_update.status}"
+end
+
+orders_client.on(:status_change) do |change_data|
+  puts "🔄 Status Changed: #{change_data[:previous_status]} -> #{change_data[:new_status]}"
+end
+
+orders_client.on(:execution) do |execution_data|
+  puts "✅ Execution: #{execution_data[:new_traded_qty]} shares executed"
+end
+
+orders_client.on(:order_traded) do |order_update|
+  puts "💰 Order Traded: #{order_update.order_no} - #{order_update.symbol}"
+end
+
+orders_client.on(:order_rejected) do |order_update|
+  puts "❌ Order Rejected: #{order_update.order_no} - #{order_update.reason_description}"
+end
+
+orders_client.on(:error) do |error|
+  puts "⚠️  WebSocket Error: #{error}"
+end
+
+orders_client.on(:close) do |close_info|
+  if close_info.is_a?(Hash)
+    puts "🔌 WebSocket Closed: #{close_info[:code]} - #{close_info[:reason]}"
+  else
+    puts "🔌 WebSocket Closed: #{close_info}"
+  end
+end
+
+puts "\nOrder Update WebSocket connected successfully!"
+puts "Waiting 30 seconds to receive order updates..."
+puts "Press Ctrl+C to stop early"
+puts ""
+
+# Wait for order updates
+begin
+  sleep(30)
+rescue Interrupt
+  puts "\nStopping early due to user interrupt..."
+end
+
+# Graceful shutdown
+puts "\nShutting down Order Update WebSocket connection..."
+orders_client.stop
+
+puts "Order Update WebSocket connection closed."
+puts "Example completed!"
+puts ""
+puts "Summary:"
+puts "- Successfully demonstrated Order Update WebSocket"
+puts "- Real-time order status tracking"
+puts "- Multiple event handlers for different order events"
+puts "- Used single connection to avoid rate limiting (429 errors)"
+puts "- Proper connection cleanup prevents resource leaks"

data/examples/trading_fields_example.rb

@@ -0,0 +1,215 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# DhanHQ Trading Fields Example
+# This script demonstrates how to use the new trading fields in the Instrument model
+# for practical trading operations and risk management
+
+require "dhan_hq"
+
+# Configure DhanHQ
+DhanHQ.configure do |config|
+  config.client_id = ENV["CLIENT_ID"] || "your_client_id"
+  config.access_token = ENV["ACCESS_TOKEN"] || "your_access_token"
+  config.ws_user_type = ENV["DHAN_WS_USER_TYPE"] || "SELF"
+end
+
+puts "DhanHQ Trading Fields Example"
+puts "============================="
+puts "Demonstrating essential trading fields for risk management and order validation"
+puts ""
+
+# Helper method to display trading information
+def display_trading_info(instrument, name)
+  return unless instrument
+
+  puts "✅ #{name} Trading Information:"
+  puts "   Symbol: #{instrument.symbol_name}"
+  puts "   Underlying Symbol: #{instrument.underlying_symbol}" if instrument.underlying_symbol
+  puts "   Security ID: #{instrument.security_id}"
+  puts "   ISIN: #{instrument.isin}"
+  puts "   Instrument Type: #{instrument.instrument_type}"
+  puts "   Exchange Segment: #{instrument.exchange_segment}"
+  puts "   Lot Size: #{instrument.lot_size}"
+  puts "   Tick Size: #{instrument.tick_size}"
+  puts "   Expiry Flag: #{instrument.expiry_flag}"
+  puts "   Bracket Flag: #{instrument.bracket_flag}"
+  puts "   Cover Flag: #{instrument.cover_flag}"
+  puts "   ASM/GSM Flag: #{instrument.asm_gsm_flag}"
+  puts "   ASM/GSM Category: #{instrument.asm_gsm_category}" if instrument.asm_gsm_category != "NA"
+  puts "   Buy/Sell Indicator: #{instrument.buy_sell_indicator}"
+  puts "   Buy CO Min Margin %: #{instrument.buy_co_min_margin_per}"
+  puts "   Sell CO Min Margin %: #{instrument.sell_co_min_margin_per}"
+  puts "   MTF Leverage: #{instrument.mtf_leverage}"
+  puts ""
+end
+
+# Helper method to check trading eligibility
+def check_trading_eligibility(instrument, name)
+  return unless instrument
+
+  puts "🔍 #{name} Trading Eligibility Check:"
+
+  # Check if instrument allows trading
+  if instrument.buy_sell_indicator == "A"
+    puts "   ✅ Trading Allowed"
+  else
+    puts "   ❌ Trading Not Allowed"
+    return
+  end
+
+  # Check bracket orders
+  if instrument.bracket_flag == "Y"
+    puts "   ✅ Bracket Orders Allowed"
+  else
+    puts "   ❌ Bracket Orders Not Allowed"
+  end
+
+  # Check cover orders
+  if instrument.cover_flag == "Y"
+    puts "   ✅ Cover Orders Allowed"
+  else
+    puts "   ❌ Cover Orders Not Allowed"
+  end
+
+  # Check ASM/GSM status
+  if instrument.asm_gsm_flag == "Y"
+    puts "   ⚠️  ASM/GSM Applied: #{instrument.asm_gsm_category}"
+  else
+    puts "   ✅ No ASM/GSM Restrictions"
+  end
+
+  # Check expiry
+  if instrument.expiry_flag == "Y"
+    puts "   ⚠️  Instrument Has Expiry: #{instrument.expiry_date}"
+  else
+    puts "   ✅ No Expiry (Perpetual)"
+  end
+
+  puts ""
+end
+
+# Helper method to calculate margin requirements
+def calculate_margin_requirements(instrument, name, quantity, price)
+  return unless instrument
+
+  puts "💰 #{name} Margin Calculation:"
+  puts "   Quantity: #{quantity}"
+  puts "   Price: ₹#{price}"
+  puts "   Lot Size: #{instrument.lot_size}"
+
+  total_value = quantity * price * instrument.lot_size
+  puts "   Total Value: ₹#{total_value}"
+
+  # Calculate margin requirements
+  buy_margin = total_value * (instrument.buy_co_min_margin_per / 100.0)
+  sell_margin = total_value * (instrument.sell_co_min_margin_per / 100.0)
+
+  puts "   Buy CO Margin Required: ₹#{buy_margin}"
+  puts "   Sell CO Margin Required: ₹#{sell_margin}"
+
+  # Calculate MTF leverage
+  if instrument.mtf_leverage > 0
+    mtf_value = total_value * instrument.mtf_leverage
+    puts "   MTF Leverage: #{instrument.mtf_leverage}x"
+    puts "   MTF Value: ₹#{mtf_value}"
+  end
+
+  puts ""
+end
+
+puts "1. Finding Instruments with Trading Fields"
+puts "=" * 50
+
+# Find popular trading instruments
+reliance = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+tcs = DhanHQ::Models::Instrument.find("NSE_EQ", "TCS")
+hdfc = DhanHQ::Models::Instrument.find("NSE_EQ", "HDFC")
+nifty = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
+banknifty = DhanHQ::Models::Instrument.find("IDX_I", "BANKNIFTY")
+
+# Display trading information
+display_trading_info(reliance, "RELIANCE")
+display_trading_info(tcs, "TCS")
+display_trading_info(hdfc, "HDFC")
+display_trading_info(nifty, "NIFTY")
+display_trading_info(banknifty, "BANKNIFTY")
+
+puts "2. Trading Eligibility Checks"
+puts "=" * 40
+
+# Check trading eligibility
+check_trading_eligibility(reliance, "RELIANCE")
+check_trading_eligibility(tcs, "TCS")
+check_trading_eligibility(nifty, "NIFTY")
+
+puts "3. Margin Calculations"
+puts "=" * 25
+
+# Calculate margin requirements for different scenarios
+calculate_margin_requirements(reliance, "RELIANCE", 10, 2500)
+calculate_margin_requirements(tcs, "TCS", 5, 3500)
+calculate_margin_requirements(nifty, "NIFTY", 1, 20_000)
+
+puts "4. Practical Trading Scenarios"
+puts "=" * 35
+
+# Scenario 1: Check if instrument supports bracket orders
+puts "Scenario 1: Bracket Order Support"
+puts "-" * 30
+instruments = [reliance, tcs, hdfc, nifty, banknifty]
+instruments.each do |instrument|
+  next unless instrument
+
+  puts "#{instrument.underlying_symbol || instrument.symbol_name}: #{instrument.bracket_flag == "Y" ? "✅ Supports" : "❌ No Support"}"
+end
+puts ""
+
+# Scenario 2: Find instruments with ASM/GSM restrictions
+puts "Scenario 2: ASM/GSM Restricted Instruments"
+puts "-" * 40
+asm_instruments = instruments.select { |i| i&.asm_gsm_flag == "Y" }
+if asm_instruments.any?
+  asm_instruments.each do |instrument|
+    puts "#{instrument.underlying_symbol || instrument.symbol_name}: #{instrument.asm_gsm_category}"
+  end
+else
+  puts "No ASM/GSM restricted instruments found in sample"
+end
+puts ""
+
+# Scenario 3: Find instruments with high MTF leverage
+puts "Scenario 3: High MTF Leverage Instruments"
+puts "-" * 40
+high_leverage = instruments.select { |i| i&.mtf_leverage && i.mtf_leverage > 3.0 }
+if high_leverage.any?
+  high_leverage.each do |instrument|
+    puts "#{instrument.underlying_symbol || instrument.symbol_name}: #{instrument.mtf_leverage}x leverage"
+  end
+else
+  puts "No high leverage instruments found in sample"
+end
+puts ""
+
+puts "5. Trading Field Summary"
+puts "=" * 25
+puts "Essential trading fields now available:"
+puts "✅ ISIN - International Securities Identification Number"
+puts "✅ Instrument Type - Classification (ES, INDEX, etc.)"
+puts "✅ Expiry Flag - Whether instrument has expiry"
+puts "✅ Bracket Flag - Bracket order support"
+puts "✅ Cover Flag - Cover order support"
+puts "✅ ASM/GSM Flag - Additional Surveillance Measure status"
+puts "✅ Buy/Sell Indicator - Trading permission"
+puts "✅ Margin Requirements - CO minimum margin percentages"
+puts "✅ MTF Leverage - Margin Trading Facility leverage"
+puts ""
+
+puts "Example completed!"
+puts "=================="
+puts "These trading fields enable:"
+puts "- Order validation and eligibility checks"
+puts "- Margin requirement calculations"
+puts "- Risk management and compliance"
+puts "- Trading strategy implementation"
+puts "- Regulatory compliance monitoring"

data/lib/DhanHQ/config.rb

@@ -2,6 +2,7 @@
 
 require "logger"
 
+# DhanHQ Ruby SDK for trading and market data
 module DhanHQ
   class << self
     # keep whatever you already have; add these if missing:

data/lib/DhanHQ/configuration.rb

@@ -40,6 +40,18 @@ module DhanHQ
     # @return [String]
     attr_accessor :ws_order_url
 
+    # Websocket market feed endpoint.
+    # @return [String]
+    attr_accessor :ws_market_feed_url
+
+    # Websocket market depth endpoint.
+    # @return [String]
+    attr_accessor :ws_market_depth_url
+
+    # Market depth level (20 or 200).
+    # @return [Integer]
+    attr_accessor :market_depth_level
+
     # Websocket user type for order updates.
     # @return [String] "SELF" or "PARTNER".
     attr_accessor :ws_user_type
@@ -63,7 +75,10 @@ module DhanHQ
       @access_token = ENV.fetch("ACCESS_TOKEN", nil)
       @base_url       = ENV.fetch("DHAN_BASE_URL", "https://api.dhan.co/v2")
       @ws_version     = ENV.fetch("DHAN_WS_VERSION", 2).to_i
-      @ws_order_url   = ENV.fetch("DHAN_WS_ORDER_URL", "wss://api-order-update.dhan.co")
+      @ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", "wss://api-order-update.dhan.co")
+      @ws_market_feed_url = ENV.fetch("DHAN_WS_MARKET_FEED_URL", "wss://api-feed.dhan.co")
+      @ws_market_depth_url = ENV.fetch("DHAN_WS_MARKET_DEPTH_URL", "wss://depth-api-feed.dhan.co/twentydepth")
+      @market_depth_level = ENV.fetch("DHAN_MARKET_DEPTH_LEVEL", "20").to_i
       @ws_user_type   = ENV.fetch("DHAN_WS_USER_TYPE", "SELF")
       @partner_id     = ENV.fetch("DHAN_PARTNER_ID", nil)
       @partner_secret = ENV.fetch("DHAN_PARTNER_SECRET", nil)

data/lib/DhanHQ/contracts/expired_options_data_contract.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require "date"
+
+module DhanHQ
+  module Contracts
+    ##
+    # Validation contract for expired options data requests
+    class ExpiredOptionsDataContract < BaseContract
+      params do
+        required(:exchange_segment).filled(:string)
+        required(:interval).filled(:integer)
+        required(:security_id).filled(:string)
+        required(:instrument).filled(:string)
+        required(:expiry_flag).filled(:string)
+        required(:expiry_code).filled(:integer)
+        required(:strike).filled(:string)
+        required(:drv_option_type).filled(:string)
+        required(:required_data).filled(:array)
+        required(:from_date).filled(:string)
+        required(:to_date).filled(:string)
+      end
+
+      rule(:exchange_segment) do
+        valid_segments = %w[NSE_FNO BSE_FNO NSE_EQ BSE_EQ]
+        key.failure("must be one of: #{valid_segments.join(", ")}") unless valid_segments.include?(value)
+      end
+
+      rule(:interval) do
+        valid_intervals = [1, 5, 15, 25, 60]
+        key.failure("must be one of: #{valid_intervals.join(", ")}") unless valid_intervals.include?(value)
+      end
+
+      rule(:instrument) do
+        valid_instruments = %w[OPTIDX OPTSTK]
+        key.failure("must be one of: #{valid_instruments.join(", ")}") unless valid_instruments.include?(value)
+      end
+
+      rule(:expiry_flag) do
+        valid_flags = %w[WEEK MONTH]
+        key.failure("must be one of: #{valid_flags.join(", ")}") unless valid_flags.include?(value)
+      end
+
+      rule(:strike) do
+        unless value.match?(/\AATM(\+|-)?\d*\z/) || value == "ATM"
+          key.failure("must be in format ATM, ATM+1, ATM-1, etc. " \
+                      "(up to ATM+10/ATM-10 for Index Options, ATM+3/ATM-3 for others)")
+        end
+      end
+
+      rule(:drv_option_type) do
+        valid_types = %w[CALL PUT]
+        key.failure("must be one of: #{valid_types.join(", ")}") unless valid_types.include?(value)
+      end
+
+      rule(:required_data) do
+        valid_data_types = %w[open high low close iv volume strike oi spot]
+        invalid_types = value - valid_data_types
+        if invalid_types.any?
+          key.failure("contains invalid data types: #{invalid_types.join(", ")}. " \
+                      "Valid types: #{valid_data_types.join(", ")}")
+        end
+      end
+
+      rule(:from_date, :to_date) do
+        if valid_date_format?(values[:from_date]) && valid_date_format?(values[:to_date])
+          begin
+            from_date = Date.parse(values[:from_date])
+            to_date = Date.parse(values[:to_date])
+
+            key.failure("from_date must be before to_date") if from_date >= to_date
+
+            # Check if date range is not too large (max 30 days)
+            key.failure("date range cannot exceed 30 days") if (to_date - from_date).to_i > 30
+
+            # Check if from_date is not too far in the past (max 5 years)
+            five_years_ago = Date.today - (5 * 365)
+            key.failure("from_date cannot be more than 5 years ago") if from_date < five_years_ago
+          rescue Date::Error
+            key.failure("invalid date format")
+          end
+        else
+          key.failure("must be in YYYY-MM-DD format (e.g., 2021-08-01)")
+        end
+      end
+
+      private
+
+      def valid_date_format?(date_string)
+        return false unless date_string.is_a?(String)
+        return false unless date_string.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        begin
+          Date.parse(date_string)
+          true
+        rescue Date::Error
+          false
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/contracts/modify_order_contract.rb

@@ -2,6 +2,7 @@
 
 module DhanHQ
   module Contracts
+    # Validation contract for order modification requests
     class ModifyOrderContract < Dry::Validation::Contract
       params do
         required(:dhanClientId).filled(:string)

data/lib/DhanHQ/contracts/option_chain_contract.rb

@@ -6,7 +6,7 @@ module DhanHQ
   module Contracts
     # **Validation contract for fetching option chain data**
     #
-    # Validates request parameters for fetching option chains & expiry lists.
+    # Validates request parameters for fetching option chains.
     class OptionChainContract < BaseContract
       params do
         required(:underlying_scrip).filled(:integer) # Security ID
@@ -27,5 +27,15 @@ module DhanHQ
         end
       end
     end
+
+    # **Validation contract for fetching option chain expiry list**
+    #
+    # Validates request parameters for fetching expiry lists (expiry not required).
+    class OptionChainExpiryListContract < BaseContract
+      params do
+        required(:underlying_scrip).filled(:integer) # Security ID
+        required(:underlying_seg).filled(:string, included_in?: %w[IDX_I NSE_FNO BSE_FNO MCX_FO])
+      end
+    end
   end
 end

data/lib/DhanHQ/contracts/trade_contract.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Contracts
+    ##
+    # Validation contract for trade-related operations
+    class TradeContract < BaseContract
+      # No input validation needed for GET requests
+      # These contracts are mainly for documentation and future extensibility
+    end
+
+    ##
+    # Validation contract for trade history requests
+    class TradeHistoryContract < BaseContract
+      params do
+        required(:from_date).filled(:string)
+        required(:to_date).filled(:string)
+        optional(:page).filled(:integer, gteq?: 0)
+      end
+
+      rule(:from_date) do
+        key.failure("must be in YYYY-MM-DD format (e.g., 2024-01-15)") unless valid_date_format?(value)
+      end
+
+      rule(:to_date) do
+        key.failure("must be in YYYY-MM-DD format (e.g., 2024-01-15)") unless valid_date_format?(value)
+      end
+
+      rule(:from_date, :to_date) do
+        from_date_valid = valid_date_format?(values[:from_date])
+        to_date_valid = valid_date_format?(values[:to_date])
+
+        if values[:from_date] && values[:to_date] && from_date_valid && to_date_valid
+          begin
+            from_date = Date.parse(values[:from_date])
+            to_date = Date.parse(values[:to_date])
+
+            key.failure("from_date must be before or equal to to_date") if from_date > to_date
+          rescue Date::Error
+            # This shouldn't happen since we already validated format, but just in case
+            key.failure("invalid date format")
+          end
+        end
+      end
+
+      private
+
+      def valid_date_format?(date_string)
+        return false unless date_string.is_a?(String)
+        return false unless date_string.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        # Additional check to ensure it's a valid date
+        begin
+          Date.parse(date_string)
+          true
+        rescue Date::Error
+          false
+        end
+      end
+    end
+
+    ##
+    # Validation contract for trade by order ID requests
+    class TradeByOrderIdContract < BaseContract
+      params do
+        required(:order_id).filled(:string, min_size?: 1)
+      end
+    end
+  end
+end

data/lib/DhanHQ/errors.rb

@@ -25,6 +25,8 @@ module DhanHQ
   class InputExceptionError < Error; end
   # DH-811, DH-812, DH-813, DH-814
   class InvalidRequestError < Error; end
+  # Validation errors for input parameters
+  class ValidationError < Error; end
 
   # Order and market data errors
   class OrderError < Error; end