DhanHQ 2.1.0 → 2.1.3

data/lib/dhanhq/analysis/multi_timeframe_analyzer.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "json"
+require "dry/validation"
+
+module DhanHQ
+  module Analysis
+    class MultiTimeframeAnalyzer
+      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

data/lib/dhanhq/analysis/options_buying_advisor.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative "helpers/bias_aggregator"
+require_relative "helpers/moneyness_helper"
+require_relative "../contracts/options_buying_advisor_contract"
+
+module DhanHQ
+  module Analysis
+    class OptionsBuyingAdvisor
+      DEFAULT_CONFIG = {
+        timeframe_weights: { m1: 0.1, m5: 0.2, m15: 0.25, m25: 0.15, m60: 0.3 },
+        min_adx_for_trend: 22,
+        strong_adx: 35,
+        min_oi: 1_000,
+        max_spread_pct: 3.0,
+        preferred_deltas: {
+          ce: { otm: (0.35..0.45), atm: (0.48..0.52), itm: (0.55..0.70) },
+          pe: { otm: (-0.45..-0.35), atm: (-0.52..-0.48), itm: (-0.70..-0.55) }
+        },
+        risk: { sl_pct: 0.30, tp_pct: 0.60, trail_arm_pct: 0.20, trail_step_pct: 0.10 },
+        atr_to_rupees_factor: 1.0,
+        min_confidence: 0.58
+      }.freeze
+
+      def initialize(data:, config: {})
+        @data   = deep_symbolize(data || {})
+        @config = deep_merge(DEFAULT_CONFIG, config || {})
+      end
+
+      def call
+        validate!
+        return unsupported("unsupported instrument") unless index_instrument?(@data[:meta])
+
+        ensure_option_chain!
+
+        bias = BiasAggregator.new(@data[:indicators], @config).call
+        # Neutral override: if higher TF trend is strong and short-term momentum aligns, allow a modest-confidence entry
+        bias = neutral_override(bias) if bias[:bias] == :neutral
+        if bias[:bias] == :neutral || bias[:confidence].to_f < @config[:min_confidence].to_f
+          return no_trade("neutral/low confidence")
+        end
+
+        side = bias[:bias] == :bullish ? :ce : :pe
+        moneyness = MoneynessHelper.pick_moneyness(indicators: @data[:indicators],
+                                                   min_adx: @config[:min_adx_for_trend],
+                                                   strong_adx: @config[:strong_adx],
+                                                   bias: bias[:bias])
+        strike_pick = select_strike(side: side, moneyness: moneyness)
+        return no_trade("no liquid strikes passed filters") unless strike_pick
+
+        build_recommendation(side: side, moneyness: moneyness, bias: bias, strike_pick: strike_pick)
+      end
+
+      private
+
+      # If bias is neutral, try to infer a directional tilt using strong higher timeframe ADX and M5/M15 momentum
+      def neutral_override(bias)
+        ind = @data[:indicators] || {}
+        m60 = ind[:m60] || {}
+        m5  = ind[:m5]  || {}
+        m15 = ind[:m15] || {}
+
+        adx60 = m60[:adx].to_f
+        strong = adx60 >= @config[:strong_adx].to_f
+        return bias unless strong
+
+        # Simple momentum checks
+        rsi5  = m5[:rsi]
+        rsi15 = m15[:rsi]
+        macd5 = (m5[:macd] || {})[:hist]
+        macd15 = (m15[:macd] || {})[:hist]
+
+        bullish = (rsi5 && rsi5 >= 55) || (rsi15 && rsi15 >= 55) || (macd5 && macd5 >= 0) || (macd15 && macd15 >= 0)
+        bearish = (rsi5 && rsi5 <= 45) || (rsi15 && rsi15 <= 45) || (macd5 && macd5 <= 0) || (macd15 && macd15 <= 0)
+
+        if bullish && !bearish
+          return { bias: :bullish, confidence: [@config[:min_confidence].to_f, 0.62].max, refs: %i[m5 m15 m60],
+                   notes: ["Override: strong M60 ADX with bullish M5/M15 momentum"] }
+        end
+        if bearish && !bullish
+          return { bias: :bearish, confidence: [@config[:min_confidence].to_f, 0.62].max, refs: %i[m5 m15 m60],
+                   notes: ["Override: strong M60 ADX with bearish M5/M15 momentum"] }
+        end
+
+        bias
+      end
+
+      def ensure_option_chain!
+        return if Array(@data[:option_chain]).any?
+
+        # Use OptionChain model: pick nearest/next expiry and fetch chain
+        sid = @data.dig(:meta, :security_id)
+        seg = @data.dig(:meta, :exchange_segment) || "IDX_I"
+        return unless sid && seg
+
+        expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(underlying_scrip: sid.to_i, underlying_seg: seg)
+        return if expiries.empty?
+
+        # Choose the nearest expiry (first element); adjust selection if API returns sorted differently
+        expiry = expiries.first
+        raw = DhanHQ::Models::OptionChain.fetch(underlying_scrip: sid.to_i, underlying_seg: seg, expiry: expiry)
+        oc = raw[:oc] || {}
+        # Transform OC structure into advisor-friendly array [{ strike:, ce: {...}, pe: {...} }]
+        @data[:option_chain] = oc.map do |strike, strike_data|
+          {
+            strike: strike.to_f,
+            ce: normalize_leg(strike_data["ce"] || {}),
+            pe: normalize_leg(strike_data["pe"] || {})
+          }
+        end
+      rescue StandardError
+        @data[:option_chain] ||= []
+      end
+
+      def normalize_leg(cepe)
+        {
+          ltp: cepe["last_price"], bid: cepe["best_bid_price"], ask: cepe["best_ask_price"],
+          iv: cepe["iv"], oi: cepe["oi"], volume: cepe["volume"],
+          delta: cepe["delta"], gamma: cepe["gamma"], vega: cepe["vega"], theta: cepe["theta"],
+          lot_size: cepe["lot_size"], tradable: true
+        }
+      end
+
+      def validate!
+        res = DhanHQ::Contracts::OptionsBuyingAdvisorContract.new.call(@data)
+        raise ArgumentError, res.errors.to_h.inspect unless res.success?
+      end
+
+      def index_instrument?(meta)
+        meta[:instrument].to_s == "INDEX" || meta[:exchange_segment].to_s == "IDX_I"
+      end
+
+      def select_strike(side:, moneyness:)
+        chain = Array(@data[:option_chain])
+        return nil if chain.empty?
+
+        target_range = @config[:preferred_deltas][side][moneyness]
+        best = nil
+        chain.each do |row|
+          leg = row[side]
+          next unless leg && leg[:tradable]
+          next if leg[:oi].to_i < @config[:min_oi]
+
+          spread = spread_pct(leg[:bid], leg[:ask])
+          next if spread.nil? || spread > @config[:max_spread_pct]
+
+          delta = leg[:delta]
+          next unless delta && target_range.cover?(delta)
+
+          candidate = { strike: row[:strike], leg: leg, spread: spread, oi: leg[:oi].to_i, delta: delta }
+          best = rank_pick(best, candidate)
+        end
+        best
+      end
+
+      def spread_pct(bid, ask)
+        return nil if bid.to_f <= 0.0 || ask.to_f <= 0.0
+
+        mid = (bid.to_f + ask.to_f) / 2.0
+        return nil if mid <= 0.0
+
+        ((ask.to_f - bid.to_f) / mid) * 100.0
+      end
+
+      def rank_pick(best, cand)
+        return cand unless best
+
+        target_center = cand[:delta] >= 0 ? 0.5 : -0.5
+        best_score = [delta_distance(best[:delta], target_center), best[:spread], -best[:oi]]
+        cand_score = [delta_distance(cand[:delta], target_center), cand[:spread], -cand[:oi]]
+        cand_score < best_score ? cand : best
+      end
+
+      def delta_distance(delta, center)
+        (delta.to_f - center).abs
+      end
+
+      def build_recommendation(side:, moneyness:, bias:, strike_pick:)
+        risk = compute_risk(strike_pick[:leg])
+        {
+          meta: { symbol: @data.dig(:meta, :symbol), security_id: @data.dig(:meta, :security_id), ts: Time.now },
+          decision: :enter_long,
+          side: side,
+          moneyness: moneyness,
+          rationale: {
+            bias: bias[:bias],
+            confidence: bias[:confidence],
+            notes: bias[:notes]
+          },
+          instrument: {
+            spot: @data[:spot],
+            ref_timeframes: bias[:refs],
+            atr_rupees_hint: atr_to_rupees
+          },
+          strike: {
+            recommended: strike_pick[:strike],
+            alternatives: [],
+            selection_basis: "delta window, spread, OI"
+          },
+          risk: risk
+        }
+      end
+
+      def atr_to_rupees
+        m15 = @data.dig(:indicators, :m15, :atr)
+        return nil unless m15
+
+        (m15.to_f * @config[:atr_to_rupees_factor].to_f).round(2)
+      end
+
+      def compute_risk(leg)
+        entry = leg[:ltp].to_f
+        sl = (entry * (1.0 - @config.dig(:risk, :sl_pct).to_f)).round(2)
+        tp = (entry * (1.0 + @config.dig(:risk, :tp_pct).to_f)).round(2)
+        {
+          entry_ltp: entry,
+          sl_ltp: sl,
+          tp_ltp: tp,
+          trail: { start_at_gain_pct: (@config.dig(:risk, :trail_arm_pct) * 100).to_i,
+                   step_pct: (@config.dig(:risk, :trail_step_pct) * 100).to_i }
+        }
+      end
+
+      def unsupported(reason)
+        { decision: :no_trade, reason: reason }
+      end
+
+      def no_trade(reason)
+        { decision: :no_trade, reason: reason }
+      end
+
+      def deep_merge(a, b)
+        return a unless b
+
+        a.merge(b) { |_, av, bv| av.is_a?(Hash) && bv.is_a?(Hash) ? deep_merge(av, bv) : bv }
+      end
+
+      def deep_symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+        when Array
+          obj.map { |v| deep_symbolize(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/dhanhq/contracts/options_buying_advisor_contract.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module DhanHQ
+  module Contracts
+    class OptionsBuyingAdvisorContract < Dry::Validation::Contract
+      params do
+        required(:meta).hash do
+          required(:exchange_segment).filled(:string)
+          required(:instrument).filled(:string)
+          required(:security_id).filled(:string)
+          optional(:symbol).maybe(:string)
+          optional(:timestamp)
+        end
+        required(:spot).filled(:float)
+        required(:indicators).hash
+        optional(:option_chain).array(:hash)
+        optional(:config).hash
+      end
+    end
+  end
+end

data/lib/ta/candles.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "time"
+
+module TA
+  module Candles
+    module_function
+
+    def parse_time_like(val)
+      return Time.at(val) if val.is_a?(Numeric)
+
+      s = val.to_s
+      return Time.at(s.to_i) if /\A\d+\z/.match?(s) && s.length >= 10 && s.length <= 13
+
+      Time.parse(s)
+    end
+
+    def from_series(series)
+      ts = series["timestamp"] || series[:timestamp]
+      open = series["open"] || series[:open]
+      high = series["high"] || series[:high]
+      low  = series["low"]  || series[:low]
+      close = series["close"] || series[:close]
+      vol = series["volume"] || series[:volume]
+      return [] unless ts && open && high && low && close && vol
+      return [] if close.empty?
+
+      (0...close.size).map do |i|
+        { t: parse_time_like(ts[i]), o: open[i].to_f, h: high[i].to_f, l: low[i].to_f, c: close[i].to_f,
+          v: vol[i].to_f }
+      end
+    rescue StandardError
+      []
+    end
+
+    def resample(candles, minutes)
+      return candles if minutes.to_i == 1
+
+      grouped = {}
+      candles.each do |c|
+        key = Time.at((c[:t].to_i / 60) / minutes * minutes * 60)
+        b = (grouped[key] ||= { t: key, o: c[:o], h: c[:h], l: c[:l], c: c[:c], v: 0.0 })
+        b[:h] = [b[:h], c[:h]].max
+        b[:l] = [b[:l], c[:l]].min
+        b[:c] = c[:c]
+        b[:v] += c[:v]
+      end
+      grouped.keys.sort.map { |k| grouped[k] }
+    end
+  end
+end

data/lib/ta/fetcher.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "date"
+
+module TA
+  class Fetcher
+    def initialize(throttle_seconds: 3.0, max_retries: 3)
+      @throttle_seconds = throttle_seconds.to_f
+      @max_retries = max_retries.to_i
+    end
+
+    def intraday(params, interval)
+      with_retries(":intraday/#{interval}") do
+        DhanHQ::Models::HistoricalData.intraday(
+          security_id: params[:security_id],
+          exchange_segment: params[:exchange_segment],
+          instrument: params[:instrument],
+          interval: interval.to_s,
+          from_date: params[:from_date],
+          to_date: params[:to_date]
+        )
+      end
+    end
+
+    def intraday_windowed(params, interval)
+      from_d = Date.parse(params[:from_date])
+      to_d   = Date.parse(params[:to_date])
+      max_span = 90
+      return intraday(params, interval) if (to_d - from_d).to_i <= max_span
+
+      merged = { "open" => [], "high" => [], "low" => [], "close" => [], "volume" => [], "timestamp" => [] }
+      cursor = from_d
+      while cursor <= to_d
+        chunk_to = [cursor + max_span, to_d].min
+        chunk_params = params.merge(from_date: cursor.strftime("%Y-%m-%d"), to_date: chunk_to.strftime("%Y-%m-%d"))
+        part = intraday(chunk_params, interval)
+        %w[open high low close volume timestamp].each do |k|
+          ary = (part[k] || part[k.to_sym]) || []
+          merged[k].concat(Array(ary))
+        end
+        cursor = chunk_to + 1
+        sleep_with_jitter
+      end
+      merged
+    end
+
+    private
+
+    def sleep_with_jitter(multiplier = 1.0)
+      base = @throttle_seconds * multiplier
+      jitter = rand * 0.3
+      sleep(base + jitter)
+    end
+
+    def with_retries(_label)
+      retries = 0
+      begin
+        yield
+      rescue DhanHQ::RateLimitError => e
+        retries += 1
+        raise e if retries > @max_retries
+
+        backoff = [5 * retries, 30].min
+        sleep_with_jitter(backoff / 3.0)
+        retry
+      end
+    end
+  end
+end