DhanHQ 2.1.0 → 2.1.5

data/lib/dhanhq/analysis/options_buying_advisor.rb

@@ -0,0 +1,251 @@
+# 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
+    # Options buying advisor for INDEX options (NIFTY/BANKNIFTY/SENSEX)
+    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(first_hash, second_hash)
+        return first_hash unless second_hash
+
+        first_hash.merge(second_hash) { |_, 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,24 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module DhanHQ
+  module Contracts
+    # Validation contract for options buying advisor input
+    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,52 @@
+# frozen_string_literal: true
+
+require "time"
+
+module TA
+  # Candle data processing and resampling utilities
+  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,70 @@
+# frozen_string_literal: true
+
+require "date"
+
+module TA
+  # Historical data fetching with windowing and throttling
+  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

data/lib/ta/indicators.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module TA
+  # Technical indicator calculations with fallback implementations
+  module Indicators
+    module_function
+
+    def ema(series, period)
+      return nil if series.nil? || series.empty?
+
+      k = 2.0 / (period + 1)
+      series.each_with_index.reduce(nil) do |ema_prev, (v, i)|
+        i.zero? ? v.to_f : (v.to_f * k) + ((ema_prev || v.to_f) * (1 - k))
+      end
+    end
+
+    def rsi(series, period)
+      if defined?(RubyTechnicalAnalysis) && RubyTechnicalAnalysis.const_defined?(:RSI)
+        return RubyTechnicalAnalysis::RSI.new(series: series, period: period).call
+      end
+      if defined?(TechnicalAnalysis) && TechnicalAnalysis.respond_to?(:rsi)
+        return TechnicalAnalysis.rsi(series, period: period)
+      end
+
+      simple_rsi(series, period)
+    end
+
+    def macd(series, fast, slow, signal)
+      if defined?(RubyTechnicalAnalysis) && RubyTechnicalAnalysis.const_defined?(:MACD)
+        out = RubyTechnicalAnalysis::MACD.new(series: series, fast_period: fast, slow_period: slow,
+                                              signal_period: signal).call
+        if out.is_a?(Hash)
+          m = out[:macd]
+          s = out[:signal]
+          h = out[:histogram] || out[:hist]
+          m = m.last if m.is_a?(Array)
+          s = s.last if s.is_a?(Array)
+          h = h.last if h.is_a?(Array)
+          return { macd: m, signal: s, hist: h }
+        end
+      end
+      if defined?(TechnicalAnalysis) && TechnicalAnalysis.respond_to?(:macd)
+        out = TechnicalAnalysis.macd(series, fast: fast, slow: slow, signal: signal)
+        if out.is_a?(Hash)
+          m = out[:macd]
+          s = out[:signal]
+          h = out[:hist]
+          m = m.last if m.is_a?(Array)
+          s = s.last if s.is_a?(Array)
+          h = h.last if h.is_a?(Array)
+          return { macd: m, signal: s, hist: h }
+        end
+      end
+      simple_macd(series, fast, slow, signal)
+    end
+
+    def adx(high, low, close, period)
+      if defined?(RubyTechnicalAnalysis) && RubyTechnicalAnalysis.const_defined?(:ADX)
+        return RubyTechnicalAnalysis::ADX.new(high: high, low: low, close: close, period: period).call
+      end
+      if defined?(TechnicalAnalysis) && TechnicalAnalysis.respond_to?(:adx)
+        return TechnicalAnalysis.adx(high: high, low: low, close: close, period: period)
+      end
+
+      simple_adx(high, low, close, period)
+    end
+
+    def atr(high, low, close, period)
+      if defined?(RubyTechnicalAnalysis) && RubyTechnicalAnalysis.const_defined?(:ATR)
+        return RubyTechnicalAnalysis::ATR.new(high: high, low: low, close: close, period: period).call
+      end
+      if defined?(TechnicalAnalysis) && TechnicalAnalysis.respond_to?(:atr)
+        return TechnicalAnalysis.atr(high: high, low: low, close: close, period: period)
+      end
+
+      simple_atr(high, low, close, period)
+    end
+
+    def simple_rsi(series, period)
+      gains = []
+      losses = []
+      series.each_cons(2) do |a, b|
+        ch = b - a
+        gains << [ch, 0].max
+        losses << [(-ch), 0].max
+      end
+      avg_gain = gains.first(period).sum / period.to_f
+      avg_loss = losses.first(period).sum / period.to_f
+      rsi_vals = Array.new(series.size, nil)
+      gains.drop(period).each_with_index do |g, idx|
+        l = losses[period + idx]
+        avg_gain = ((avg_gain * (period - 1)) + g) / period
+        avg_loss = ((avg_loss * (period - 1)) + l) / period
+        rs = avg_loss.zero? ? 100.0 : (avg_gain / avg_loss)
+        rsi_vals[period + 1 + idx] = 100.0 - (100.0 / (1 + rs))
+      end
+      rsi_vals
+    end
+
+    def simple_macd(series, fast, slow, signal)
+      e_fast = ema(series, fast)
+      e_slow = ema(series, slow)
+      e_sig  = ema(series, signal)
+      return { macd: nil, signal: nil, hist: nil } if [e_fast, e_slow, e_sig].any?(&:nil?)
+
+      macd_line = e_fast - e_slow
+      signal_line = e_sig
+      { macd: macd_line, signal: signal_line, hist: macd_line - signal_line }
+    end
+
+    def true_ranges(high, low, close)
+      trs = []
+      close.each_with_index do |_c, i|
+        if i.zero?
+          trs << (high[i] - low[i]).abs
+        else
+          tr = [(high[i] - low[i]).abs, (high[i] - close[i - 1]).abs, (low[i] - close[i - 1]).abs].max
+          trs << tr
+        end
+      end
+      trs
+    end
+
+    def simple_atr(high, low, close, period)
+      trs = true_ranges(high, low, close)
+      out = []
+      atr_prev = trs.first(period).sum / period.to_f
+      trs.each_with_index do |tr, i|
+        if i < period
+          out << nil
+        elsif i == period
+          out << atr_prev
+        else
+          atr_prev = ((atr_prev * (period - 1)) + tr) / period.to_f
+          out << atr_prev
+        end
+      end
+      out
+    end
+
+    def simple_adx(high, low, close, period)
+      plus_dm = [0]
+      minus_dm = [0]
+      (1...high.size).each do |i|
+        up_move = high[i] - high[i - 1]
+        down_move = low[i - 1] - low[i]
+        plus_dm << (up_move > down_move && up_move.positive? ? up_move : 0)
+        minus_dm << (down_move > up_move && down_move.positive? ? down_move : 0)
+      end
+      trs = true_ranges(high, low, close)
+      smooth_tr = trs.first(period).sum
+      smooth_plus_dm = plus_dm.first(period).sum
+      smooth_minus_dm = minus_dm.first(period).sum
+      adx_vals = Array.new(high.size, nil)
+      di_vals = []
+      (period...high.size).each do |i|
+        smooth_tr = smooth_tr - (smooth_tr / period) + trs[i]
+        smooth_plus_dm = smooth_plus_dm - (smooth_plus_dm / period) + plus_dm[i]
+        smooth_minus_dm = smooth_minus_dm - (smooth_minus_dm / period) + minus_dm[i]
+        plus_di = 100.0 * (smooth_plus_dm / smooth_tr)
+        minus_di = 100.0 * (smooth_minus_dm / smooth_tr)
+        dx = 100.0 * ((plus_di - minus_di).abs / (plus_di + minus_di))
+        di_vals << dx
+        adx_vals[i] = di_vals.last(period).sum / period.to_f if di_vals.size >= period
+      end
+      adx_vals
+    end
+  end
+end

data/lib/ta/market_calendar.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "date"
+
+module TA
+  # Market calendar utilities for trading day calculations
+  module MarketCalendar
+    MARKET_HOLIDAYS = [
+      Date.new(2025, 8, 15),
+      Date.new(2025, 10, 2),
+      Date.new(2025, 8, 27)
+    ].freeze
+
+    def self.weekday?(date)
+      w = date.wday
+      w.between?(1, 5)
+    end
+
+    def self.trading_day?(date)
+      weekday?(date) && !MARKET_HOLIDAYS.include?(date)
+    end
+
+    def self.last_trading_day(from: Date.today)
+      d = from
+      d -= 1 until trading_day?(d)
+      d
+    end
+
+    def self.prev_trading_day(from: Date.today)
+      d = from - 1
+      d -= 1 until trading_day?(d)
+      d
+    end
+
+    def self.today_or_last_trading_day
+      trading_day?(Date.today) ? Date.today : last_trading_day(from: Date.today)
+    end
+
+    def self.trading_days_ago(date, days)
+      raise ArgumentError, "days must be >= 0" if days.to_i.negative?
+
+      d = trading_day?(date) ? date : today_or_last_trading_day
+      count = 0
+      while count < days
+        d = prev_trading_day(from: d)
+        count += 1
+      end
+      d
+    end
+  end
+end