DhanHQ 2.1.0 → 2.1.5

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/helpers/request_helper.rb

@@ -26,6 +26,9 @@ module DhanHQ
     # @param path [String] The API endpoint path.
     # @return [Hash] The request headers.
     def build_headers(path)
+      # Public CSV endpoint for segment-wise instruments requires no auth
+      return { "Accept" => "text/csv" } if path.start_with?("/v2/instrument/")
+
       headers = {
         "Content-Type" => "application/json",
         "Accept" => "application/json",
@@ -43,7 +46,8 @@ module DhanHQ
     # @param path [String] The API endpoint path.
     # @return [Boolean] True if the path belongs to a DATA API.
     def data_api?(path)
-      DhanHQ::Constants::DATA_API_PATHS.include?(path)
+      prefixes = DhanHQ::Constants::DATA_API_PREFIXES
+      prefixes.any? { |p| path.start_with?(p) }
     end
 
     # Prepares the request payload based on the HTTP method.

data/lib/DhanHQ/models/instrument.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../contracts/instrument_list_contract"
+
+module DhanHQ
+  module Models
+    # Model wrapper for fetching instruments by exchange segment.
+    class Instrument < BaseModel
+      attributes :security_id, :symbol_name, :display_name, :exchange_segment, :instrument, :series,
+                 :lot_size, :tick_size, :expiry_date, :strike_price, :option_type
+
+      class << self
+        # @return [DhanHQ::Resources::Instruments]
+        def resource
+          @resource ||= DhanHQ::Resources::Instruments.new
+        end
+
+        # Retrieve instruments for a given segment, returning an array of models.
+        # @param exchange_segment [String]
+        # @return [Array<Instrument>]
+        def by_segment(exchange_segment)
+          validate_params!({ exchange_segment: exchange_segment }, DhanHQ::Contracts::InstrumentListContract)
+
+          csv_text = resource.by_segment(exchange_segment)
+          return [] unless csv_text.is_a?(String) && !csv_text.empty?
+
+          require "csv"
+          rows = CSV.parse(csv_text, headers: true)
+          rows.map { |r| new(normalize_csv_row(r), skip_validation: true) }
+        end
+
+        def normalize_csv_row(row)
+          {
+            security_id: row["SECURITY_ID"].to_s,
+            symbol_name: row["SYMBOL_NAME"],
+            display_name: row["DISPLAY_NAME"],
+            exchange_segment: row["EXCH_ID"],
+            instrument: row["INSTRUMENT"],
+            series: row["SERIES"],
+            lot_size: row["LOT_SIZE"]&.to_f,
+            tick_size: row["TICK_SIZE"]&.to_f,
+            expiry_date: row["SM_EXPIRY_DATE"],
+            strike_price: row["STRIKE_PRICE"]&.to_f,
+            option_type: row["OPTION_TYPE"]
+          }
+        end
+      end
+
+      private
+
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/option_chain.rb

@@ -34,6 +34,8 @@ module DhanHQ
         # @param params [Hash] The request parameters (snake_case format)
         # @return [Array<String>] The list of expiry dates
         def fetch_expiry_list(params)
+          validate_params!(params, DhanHQ::Contracts::OptionChainExpiryListContract)
+
           response = resource.expirylist(params)
           response[:status] == "success" ? response[:data] : []
         end

data/lib/DhanHQ/rate_limiter.rb

@@ -33,9 +33,11 @@ module DhanHQ
       if @api_type == :option_chain
         last_request_time = @buckets[:last_request_time]
 
-        sleep_time = 4 - (Time.now - last_request_time)
+        sleep_time = 3 - (Time.now - last_request_time)
         if sleep_time.positive?
-          puts "Sleeping for #{sleep_time.round(2)} seconds due to option_chain rate limit"
+          if ENV["DHAN_DEBUG"] == "true"
+            puts "Sleeping for #{sleep_time.round(2)} seconds due to option_chain rate limit"
+          end
           sleep(sleep_time)
         end
 

data/lib/DhanHQ/resources/instruments.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client for fetching segment-wise instrument lists.
+    class Instruments < BaseAPI
+      # Instruments are served via the non-trading/data tier
+      API_TYPE = :data_api
+      # Base path for instruments endpoint
+      HTTP_PATH = "/v2/instrument"
+
+      # Fetch instruments for a given exchange segment.
+      # Returns CSV text; the client parses to Array<Hash> upstream if needed.
+      #
+      # @param exchange_segment [String] e.g. "NSE_EQ", "NSE_FNO", "IDX_I"
+      # @return [String] CSV content
+      def by_segment(exchange_segment)
+        path = "#{HTTP_PATH}/#{exchange_segment}"
+        resp = client.connection.get(path)
+        if resp.status.between?(300, 399) && resp.headers["location"]
+          redirect_url = resp.headers["location"]
+          return Faraday.get(redirect_url).body
+        end
+        resp.body
+      end
+    end
+  end
+end

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "2.1.0"
+  VERSION = "2.1.5"
 end

data/lib/DhanHQ/ws/client.rb

@@ -161,7 +161,7 @@ module DhanHQ
 
       private
 
-      def prune(h) = { ExchangeSegment: h[:ExchangeSegment], SecurityId: h[:SecurityId] }
+      def prune(hash) = { ExchangeSegment: hash[:ExchangeSegment], SecurityId: hash[:SecurityId] }
 
       def emit(event, payload)
         begin

data/lib/DhanHQ/ws/connection.rb

@@ -94,7 +94,7 @@ module DhanHQ
         backoff = 2.0
         until @stop
           failed = false
-          got_429 = false # rubocop:disable Naming/VariableNumber
+          got_429 = false
 
           # respect any active cool-off window
           sleep (@cooloff_until - Time.now).ceil if @cooloff_until && Time.now < @cooloff_until

data/lib/DhanHQ/ws/orders/client.rb

@@ -6,6 +6,7 @@ require_relative "connection"
 module DhanHQ
   module WS
     module Orders
+      # WebSocket client for real-time order updates
       class Client
         def initialize(url: nil)
           @callbacks = Concurrent::Map.new { |h, k| h[k] = [] }
@@ -16,6 +17,7 @@ module DhanHQ
 
         def start
           return self if @started.true?
+
           @started.make_true
           @conn = Connection.new(url: @url) do |msg|
             emit(:update, msg) if msg&.dig(:Type) == "order_alert"
@@ -28,6 +30,7 @@ module DhanHQ
 
         def stop
           return unless @started.true?
+
           @started.make_false
           @conn&.stop
           emit(:close, true)

data/lib/DhanHQ/ws/orders/connection.rb

@@ -8,6 +8,7 @@ require "thread" # rubocop:disable Lint/RedundantRequireStatement
 module DhanHQ
   module WS
     module Orders
+      # WebSocket connection for real-time order updates
       class Connection
         COOL_OFF_429 = 60
         MAX_BACKOFF  = 90
@@ -84,12 +85,10 @@ module DhanHQ
             end
 
             @ws.on :message do |ev|
-              begin
-                msg = JSON.parse(ev.data, symbolize_names: true)
-                @on_json&.call(msg)
-              rescue StandardError => e
-                DhanHQ.logger&.error("[DhanHQ::WS::Orders] bad JSON #{e.class}: #{e.message}")
-              end
+              msg = JSON.parse(ev.data, symbolize_names: true)
+              @on_json&.call(msg)
+            rescue StandardError => e
+              DhanHQ.logger&.error("[DhanHQ::WS::Orders] bad JSON #{e.class}: #{e.message}")
             end
 
             @ws.on :close do |ev|

data/lib/DhanHQ/ws/orders.rb

@@ -4,9 +4,10 @@ require_relative "orders/client"
 
 module DhanHQ
   module WS
+    # WebSocket orders module for real-time order updates
     module Orders
-      def self.connect(&on_update)
-        Client.new.start.on(:update, &on_update)
+      def self.connect(&)
+        Client.new.start.on(:update, &)
       end
     end
   end

data/lib/DhanHQ/ws/registry.rb

@@ -3,6 +3,7 @@
 require "concurrent"
 
 module DhanHQ
+  # WebSocket registry for managing connections and subscriptions
   module WS
     # Tracks the set of active WebSocket clients so they can be collectively
     # disconnected when required.

data/lib/DhanHQ/ws/segments.rb

@@ -47,11 +47,11 @@ module DhanHQ
       #   - ExchangeSegment is a STRING enum (e.g., "NSE_FNO")
       #   - SecurityId is a STRING
       #
-      # @param h [Hash]
+      # @param hash [Hash]
       # @return [Hash] Normalized instrument hash.
-      def self.normalize_instrument(h)
-        seg = to_request_string(h[:ExchangeSegment] || h["ExchangeSegment"])
-        sid = (h[:SecurityId] || h["SecurityId"]).to_s
+      def self.normalize_instrument(hash)
+        seg = to_request_string(hash[:ExchangeSegment] || hash["ExchangeSegment"])
+        sid = (hash[:SecurityId] || hash["SecurityId"]).to_s
         { ExchangeSegment: seg, SecurityId: sid }
       end
 

data/lib/DhanHQ/ws/sub_state.rb

@@ -53,7 +53,7 @@ module DhanHQ
 
       private
 
-      def key_for(i) = "#{i[:ExchangeSegment]}:#{i[:SecurityId]}"
+      def key_for(instrument) = "#{instrument[:ExchangeSegment]}:#{instrument[:SecurityId]}"
     end
   end
 end

data/lib/{DhanHQ.rb → dhan_hq.rb}

@@ -44,6 +44,7 @@ require_relative "DhanHQ/resources/trades"
 require_relative "DhanHQ/resources/historical_data"
 require_relative "DhanHQ/resources/margin_calculator"
 require_relative "DhanHQ/resources/market_feed"
+require_relative "DhanHQ/resources/instruments"
 require_relative "DhanHQ/resources/edis"
 require_relative "DhanHQ/resources/kill_switch"
 require_relative "DhanHQ/resources/profile"
@@ -56,6 +57,7 @@ require_relative "DhanHQ/models/forever_order"
 require_relative "DhanHQ/models/super_order"
 require_relative "DhanHQ/models/historical_data"
 require_relative "DhanHQ/models/market_feed"
+require_relative "DhanHQ/models/instrument"
 require_relative "DhanHQ/models/position"
 require_relative "DhanHQ/models/holding"
 require_relative "DhanHQ/models/ledger_entry"
@@ -68,6 +70,12 @@ require_relative "DhanHQ/models/profile"
 require_relative "DhanHQ/constants"
 require_relative "DhanHQ/ws"
 require_relative "DhanHQ/ws/singleton_lock"
+require_relative "ta"
+require_relative "dhanhq/analysis/multi_timeframe_analyzer"
+require_relative "dhanhq/analysis/helpers/bias_aggregator"
+require_relative "dhanhq/analysis/helpers/moneyness_helper"
+require_relative "dhanhq/contracts/options_buying_advisor_contract"
+require_relative "dhanhq/analysis/options_buying_advisor"
 
 # The top-level module for the DhanHQ client library.
 #

data/lib/dhanhq/analysis/helpers/bias_aggregator.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Analysis
+    # Aggregates indicator scores across timeframes into a single bias and confidence score
+    class BiasAggregator
+      DEFAULT_WEIGHTS = { m1: 0.1, m5: 0.2, m15: 0.25, m25: 0.15, m60: 0.3 }.freeze
+
+      def initialize(indicators, config = {})
+        @indicators = indicators || {}
+        @weights = config[:timeframe_weights] || DEFAULT_WEIGHTS
+        @min_adx = (config[:min_adx_for_trend] || 22).to_f
+        @strong_adx = (config[:strong_adx] || 35).to_f
+      end
+
+      def call
+        score = 0.0
+        wsum = 0.0
+        refs = []
+        notes = []
+
+        @weights.each do |tf, w|
+          next unless @indicators[tf]
+
+          s = score_tf(@indicators[tf])
+          next if s.nil?
+
+          score += s * w
+          wsum += w
+          refs << tf
+        end
+
+        avg = wsum.zero? ? 0.5 : (score / wsum)
+        bias = if avg > 0.55
+                 :bullish
+               elsif avg < 0.45
+                 :bearish
+               else
+                 :neutral
+               end
+
+        { bias: bias, confidence: avg.round(2), refs: refs, notes: notes }
+      end
+
+      private
+
+      def score_tf(val)
+        rsi  = val[:rsi]
+        macd = val[:macd] || {}
+        hist = macd[:hist]
+        adx  = val[:adx]
+
+        rsi_component = if rsi.nil?
+                          0.5
+                        elsif rsi >= 55
+                          0.65
+                        elsif rsi <= 45
+                          0.35
+                        else
+                          0.5
+                        end
+
+        macd_component = if hist.nil?
+                           0.5
+                         else
+                           hist >= 0 ? 0.6 : 0.4
+                         end
+
+        adx_component = if adx.nil?
+                          0.5
+                        elsif adx >= @strong_adx
+                          0.65
+                        elsif adx >= @min_adx
+                          0.55
+                        else
+                          0.45
+                        end
+
+        (rsi_component * 0.4) + (macd_component * 0.3) + (adx_component * 0.3)
+      end
+    end
+  end
+end

data/lib/dhanhq/analysis/helpers/moneyness_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Analysis
+    # Helper module to determine the recommended moneyness (ITM/ATM/OTM) based on market conditions
+    module MoneynessHelper
+      module_function
+
+      def pick_moneyness(indicators:, min_adx:, strong_adx:, bias: nil)
+        # Mark bias as intentionally observed for future rules
+        bias&.to_sym
+
+        m60 = indicators[:m60] || {}
+        adx = m60[:adx].to_f
+        rsi = m60[:rsi].to_f
+
+        return :atm if adx < min_adx
+        return :otm if adx >= strong_adx && rsi >= 60
+
+        :atm
+      end
+    end
+  end
+end

data/lib/dhanhq/analysis/multi_timeframe_analyzer.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "json"
+require "dry/validation"
+
+module DhanHQ
+  module Analysis
+    # Analyzes multi-timeframe indicator data to produce a consolidated bias summary
+    class MultiTimeframeAnalyzer
+      # Input validation contract for multi-timeframe analyzer
+      class InputContract < Dry::Validation::Contract
+        params do
+          required(:meta).filled(:hash)
+          required(:indicators).filled(:hash)
+        end
+      end
+
+      TF_ORDER = %i[m1 m5 m15 m25 m60].freeze
+
+      def initialize(data:)
+        @data = symbolize(data)
+      end
+
+      def call
+        validate_data!
+        per_tf = compute_indicators(@data[:indicators])
+        aggregate_results(per_tf)
+      end
+
+      private
+
+      def symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize(v) }
+        when Array
+          obj.map { |v| symbolize(v) }
+        else
+          obj
+        end
+      end
+
+      def validate_data!
+        res = InputContract.new.call(@data)
+        raise ArgumentError, res.errors.to_h.inspect unless res.success?
+      end
+
+      def compute_indicators(indicators)
+        TF_ORDER.each_with_object({}) do |tf, out|
+          next unless indicators.key?(tf)
+
+          val = indicators[tf]
+          rsi   = val[:rsi]
+          adx   = val[:adx]
+          atr   = val[:atr]
+          macd  = val[:macd] || {}
+          macd_line   = macd[:macd]
+          macd_signal = macd[:signal]
+          macd_hist   = macd[:hist]
+
+          momentum = classify_rsi(rsi)
+          trend    = classify_adx(adx)
+          macd_sig = classify_macd(macd_line, macd_signal, macd_hist)
+          vol      = classify_atr(atr)
+
+          out[tf] = {
+            rsi: rsi, adx: adx, atr: atr, macd: macd,
+            momentum: momentum, trend: trend, macd_signal: macd_sig, volatility: vol,
+            bias: derive_bias(momentum, macd_sig)
+          }
+        end
+      end
+
+      def classify_rsi(rsi)
+        return :unknown if rsi.nil?
+        return :overbought if rsi >= 70
+        return :oversold if rsi <= 30
+        return :bullish if rsi >= 55
+        return :bearish if rsi <= 45
+
+        :neutral
+      end
+
+      def classify_adx(adx)
+        return :unknown if adx.nil?
+        return :strong if adx >= 25
+        return :weak if adx <= 15
+
+        :moderate
+      end
+
+      def classify_macd(macd, signal, hist)
+        return :unknown if macd.nil? || signal.nil?
+
+        # Treat histogram sign and distance as proxy for momentum direction
+        if macd > signal && (hist.nil? || hist >= 0)
+          :bullish
+        elsif macd < signal && (hist.nil? || hist <= 0)
+          :bearish
+        else
+          :neutral
+        end
+      end
+
+      def classify_atr(atr)
+        return :unknown if atr.nil?
+
+        # ATR is relative; without baseline we can only tag as present
+        atr.positive? ? :expanding : :flat
+      end
+
+      def derive_bias(momentum, macd_sig)
+        return :bullish if momentum == :bullish && macd_sig == :bullish
+        return :bearish if momentum == :bearish && macd_sig == :bearish
+
+        :neutral
+      end
+
+      def aggregate_results(per_tf)
+        weights = { m1: 1, m5: 2, m15: 3, m25: 3, m60: 4 }
+        scores = { bullish: 1.0, neutral: 0.5, bearish: 0.0 }
+
+        total_w = 0.0
+        acc = 0.0
+        per_tf.each do |tf, s|
+          w = weights[tf] || 1
+          total_w += w
+          acc += (scores[s[:bias]] || 0.5) * w
+        end
+        avg = total_w.zero? ? 0.5 : (acc / total_w)
+
+        bias = if avg >= 0.66
+                 :bullish
+               elsif avg <= 0.33
+                 :bearish
+               else
+                 :neutral
+               end
+
+        setup = if bias == :bullish
+                  :buy_on_dip
+                elsif bias == :bearish
+                  :sell_on_rise
+                else
+                  :range_trade
+                end
+
+        rationale = build_rationale(per_tf)
+        trend_strength = build_trend_strength(per_tf)
+
+        {
+          meta: (@data[:meta] || {}).slice(:security_id, :instrument, :exchange_segment),
+          summary: {
+            bias: bias,
+            setup: setup,
+            confidence: avg.round(2),
+            rationale: rationale,
+            trend_strength: trend_strength
+          }
+        }
+      end
+
+      def build_rationale(per_tf)
+        {
+          rsi: rsi_rationale(per_tf),
+          macd: macd_rationale(per_tf),
+          adx: adx_rationale(per_tf),
+          atr: atr_rationale(per_tf)
+        }
+      end
+
+      def rsi_rationale(per_tf)
+        ups = per_tf.count { |_tf, s| %i[bullish overbought].include?(s[:momentum]) }
+        downs = per_tf.count { |_tf, s| %i[bearish oversold].include?(s[:momentum]) }
+        if ups > downs
+          "Upward momentum across #{ups} TFs"
+        elsif downs > ups
+          "Downward momentum across #{downs} TFs"
+        else
+          "Mixed RSI momentum"
+        end
+      end
+
+      def macd_rationale(per_tf)
+        ups = per_tf.count { |_tf, s| s[:macd_signal] == :bullish }
+        downs = per_tf.count { |_tf, s| s[:macd_signal] == :bearish }
+        if ups > downs
+          "MACD bullish signals dominant"
+        elsif downs > ups
+          "MACD bearish signals dominant"
+        else
+          "MACD mixed/neutral"
+        end
+      end
+
+      def adx_rationale(per_tf)
+        strong = per_tf.count { |_tf, s| s[:trend] == :strong }
+        return "Strong higher timeframe trend" if strong >= 2
+
+        moderate = per_tf.count { |_tf, s| s[:trend] == :moderate }
+        return "Moderate trend context" if moderate >= 2
+
+        "Weak/unknown trend context"
+      end
+
+      def atr_rationale(per_tf)
+        exp = per_tf.count { |_tf, s| s[:volatility] == :expanding }
+        exp.positive? ? "Volatility expansion" : "Low/flat volatility"
+      end
+
+      def build_trend_strength(per_tf)
+        {
+          short_term: summarize_bias(%i[m1 m5], per_tf),
+          medium_term: summarize_bias(%i[m15 m25], per_tf),
+          long_term: summarize_bias(%i[m60], per_tf)
+        }
+      end
+
+      def summarize_bias(tfs, per_tf)
+        slice = per_tf.slice(*tfs)
+        ups = slice.count { |_tf, s| s[:bias] == :bullish }
+        downs = slice.count { |_tf, s| s[:bias] == :bearish }
+        return :strong_bullish if ups >= 2
+        return :strong_bearish if downs >= 2
+        return :weak_bullish if ups == 1 && downs.zero?
+        return :weak_bearish if downs == 1 && ups.zero?
+
+        :neutral
+      end
+    end
+  end
+end