DhanHQ 2.1.0 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f37f6e3a5253ced5b53845fe8cdb43d7f13cbbfae8699d3ffa29737a0ac8386
-  data.tar.gz: 9035ad6b0d08a5d83b342341c6d799e06e860c1f66eabeea16cdd4dacdd5ed9c
+  metadata.gz: 0ee56ccabd71b9f769e99d6470cf32309c4f6fa17eec5de17417b1c153ee9293
+  data.tar.gz: 000fcabd622e0e690f6c65bf03665b8e4b3dfc23572534d29101fca0576757be
 SHA512:
-  metadata.gz: b72eef88a4c4e6e1a41a09ffc3da297b6cf701d9d7c79b63b7eec7c76a19355134c3daa3d5d64b5eb0cfb537a61529bd7906230a8b6c4f97176404f0afc0e586
-  data.tar.gz: 32dc61f28fed01d6cb1caced8e343c29b10e482ed3b8673e32131a59c47c794a7ad98bcd889057bd1a5b4a6ef4ca403c7ed5e2763853e91a09a3d50ae553cae5
+  metadata.gz: 6aeecd46b742a5cbdf74ffb4e38086be502385fda9e18bee4b6413a488b005b2a713dd089cd2d83c6628096d084d063bb6da468292b785d08f968fc9336838ac
+  data.tar.gz: b4fe91bca2051073b297693d1ea2789911b8b50b3a948ccf96cc7b0647a1fe824020f39ca0cbfebf53946b453253d8348df7d673eb199068d24d444453191b8d

data/README.md

@@ -44,9 +44,9 @@ DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Lo
 
 **Minimum environment variables**
 
-| Variable | Purpose |
-| --- | --- |
-| `CLIENT_ID` | Trading account client id issued by Dhan. |
+| Variable       | Purpose                                           |
+| -------------- | ------------------------------------------------- |
+| `CLIENT_ID`    | Trading account client id issued by Dhan.         |
 | `ACCESS_TOKEN` | API access token generated from the Dhan console. |
 
 `configure_with_env` raises if either value is missing. Load them via `dotenv`,
@@ -58,14 +58,14 @@ initialisation.
 Set these variables _before_ calling `configure_with_env` when you need to
 override defaults supplied by the gem:
 
-| Variable | When to use |
-| --- | --- |
-| `DHAN_LOG_LEVEL` | Adjust logger verbosity (`INFO` by default). |
-| `DHAN_BASE_URL` | Point REST calls to a different API hostname. |
-| `DHAN_WS_VERSION` | Pin to a specific WebSocket API version. |
-| `DHAN_WS_ORDER_URL` | Override the order update WebSocket endpoint. |
-| `DHAN_WS_USER_TYPE` | Switch between `SELF` and `PARTNER` streaming modes. |
-| `DHAN_PARTNER_ID` / `DHAN_PARTNER_SECRET` | Required when `DHAN_WS_USER_TYPE=PARTNER`. |
+| Variable                                  | When to use                                          |
+| ----------------------------------------- | ---------------------------------------------------- |
+| `DHAN_LOG_LEVEL`                          | Adjust logger verbosity (`INFO` by default).         |
+| `DHAN_BASE_URL`                           | Point REST calls to a different API hostname.        |
+| `DHAN_WS_VERSION`                         | Pin to a specific WebSocket API version.             |
+| `DHAN_WS_ORDER_URL`                       | Override the order update WebSocket endpoint.        |
+| `DHAN_WS_USER_TYPE`                       | Switch between `SELF` and `PARTNER` streaming modes. |
+| `DHAN_PARTNER_ID` / `DHAN_PARTNER_SECRET` | Required when `DHAN_WS_USER_TYPE=PARTNER`.           |
 
 ### Logging
 
@@ -461,3 +461,9 @@ PRs welcome! Please include tests for new packet decoders and WS behaviors (chun
 ## License
 
 MIT.
+
+## Technical Analysis (Indicators + Multi-Timeframe)
+
+See the guide for computing indicators and aggregating cross-timeframe bias:
+
+- docs/technical_analysis.md

data/docs/technical_analysis.md

@@ -0,0 +1,143 @@
+# Technical Analysis Guide
+
+This guide explains how to use the technical analysis modules bundled with this gem: fetching historical OHLC, computing indicators, and producing multi-timeframe summaries.
+
+## Modules Overview
+
+- `TA::TechnicalAnalysis`: Fetches intraday OHLC (1/5/15/25/60) from Dhan APIs with throttling/backoff, computes RSI/MACD/ADX/ATR, and returns a structured indicators hash.
+- `TA::Indicators`: Adapters for `ruby-technical-analysis` and `technical-analysis` gems, including safe fallbacks.
+- `TA::Candles`: Utilities for converting API series to candles and resampling (used for offline data only).
+- `TA::Fetcher`: Handles API calls, 90-day windowing, throttling, and retries.
+- `DhanHQ::Analysis::MultiTimeframeAnalyzer`: Consumes the indicator hash and outputs a consolidated bias summary across timeframes.
+
+## Prerequisites
+
+- Environment variables set: `CLIENT_ID`, `ACCESS_TOKEN`
+- Optional indicator gems:
+  - `gem install ruby-technical-analysis technical-analysis`
+
+## Quick Start: Compute Indicators
+
+```ruby
+require "ta"
+
+DhanHQ.configure_with_env
+
+ta = TA::TechnicalAnalysis.new(throttle_seconds: 2.5, max_retries: 3)
+indicators = ta.compute(
+  exchange_segment: "NSE_EQ",
+  instrument: "EQUITY",
+  security_id: "1333",
+  intervals: [1, 5, 15, 25, 60] # each fetched directly from API
+)
+```
+
+Output structure:
+
+```ruby
+{
+  meta: { exchange_segment: "...", instrument: "...", security_id: "...", from_date: "YYYY-MM-DD", to_date: "YYYY-MM-DD" },
+  indicators: {
+    m1:  { rsi: Float|nil, adx: Float|nil, atr: Float|nil, macd: { macd: Float|nil, signal: Float|nil, hist: Float|nil } },
+    m5:  { ... },
+    m15: { ... },
+    m25: { ... },
+    m60: { ... }
+  }
+}
+```
+
+Notes:
+- `to_date` defaults to today-or-last-trading-day via `TA::MarketCalendar`.
+- If `days_back` is not provided, the class auto-selects a sufficient lookback (trading days) per the selected intervals and indicator periods (max of [2×ADX, MACD slow, RSI+1, ATR+1]).
+- Requests are throttled with jitter; rate-limit errors trigger exponential backoff.
+
+## Offline Input (JSON OHLC)
+
+```ruby
+raw = JSON.parse(File.read("ohlc.json"))
+indicators = TA::TechnicalAnalysis.new.compute_from_file(
+  path: "ohlc.json", base_interval: 1, intervals: [1,5,15,25,60]
+)
+```
+
+## Analyze Multi-Timeframe Bias
+
+```ruby
+require "DhanHQ"
+
+analyzer = DhanHQ::Analysis::MultiTimeframeAnalyzer.new(data: indicators)
+summary = analyzer.call
+```
+
+Example summary:
+
+```ruby
+{
+  meta: { security_id: "1333", instrument: "EQUITY", exchange_segment: "NSE_EQ" },
+  summary: {
+    bias: :bullish,             # :bullish | :bearish | :neutral
+    setup: :buy_on_dip,         # :buy_on_dip | :sell_on_rise | :range_trade
+    confidence: 0.78,           # 0.0..1.0 weighted across timeframes
+    rationale: {
+      rsi: "Upward momentum across M5–M60",
+      macd: "MACD bullish signals dominant",
+      adx: "Strong higher timeframe trend",
+      atr: "Volatility expansion"
+    },
+    trend_strength: {
+      short_term: :weak_bullish,
+      medium_term: :neutral_to_bullish,
+      long_term: :strong_bullish
+    }
+  }
+}
+```
+
+## CLI Script
+
+A convenience script exists at `bin/ta_strategy.rb` to compute indicators and print JSON. Example:
+
+```bash
+./bin/ta_strategy.rb --segment NSE_EQ --instrument EQUITY --security-id 1333 \
+  --from 2025-10-06 --to 2025-10-07 --debug
+```
+
+Options:
+- `--print-creds` to verify env
+- `--data-file` to compute from JSON instead of API
+- `--interval` (with `--data-file`) to specify base file interval
+- `--rsi`, `--atr`, `--adx`, `--macd` to tune periods
+
+## Options Buying Advisor CLI
+
+Use `bin/options_advisor.rb` to compute indicators, summarize multi-TF bias, and produce a single index options-buying recommendation (CE/PE). If you do not provide `--spot`, the script fetches spot via MarketFeed LTP automatically.
+
+Examples:
+
+```bash
+# Auto-fetch spot via MarketFeed.ltp and chain via OptionChain model
+./bin/options_advisor.rb --segment IDX_I --instrument INDEX --security-id 13 --symbol NIFTY
+
+# Provide pre-fetched option chain from file (JSON array of strikes)
+./bin/options_advisor.rb --segment IDX_I --instrument INDEX --security-id 13 --symbol NIFTY \
+  --chain-file ./chain.json
+
+# Override spot explicitly
+./bin/options_advisor.rb --segment IDX_I --instrument INDEX --security-id 13 --symbol NIFTY --spot 24890
+
+# Verbose debug logging (prints steps to STDERR; JSON output unchanged)
+./bin/options_advisor.rb --segment IDX_I --instrument INDEX --security-id 13 --symbol NIFTY --debug
+```
+
+Behavior:
+- Spot: when `--spot` is omitted, the script calls `DhanHQ::Models::MarketFeed.ltp({ SEG => [security_id] })` and reads `data[SEG][security_id]["last_price"]`.
+- Option chain: when `--chain-file` is omitted, the advisor fetches via `DhanHQ::Models::OptionChain` (nearest expiry), transforming OC into an internal array of strikes with CE/PE legs.
+- Debugging: with `--debug`, the script logs options, spot resolution, indicators meta, missing fields per timeframe, analyzer summary, and advisor output to STDERR.
+
+## Best Practices & Tips
+
+- Keep intervals minimal per run to reduce rate limits; increase `throttle_seconds` if needed.
+- For higher intervals (e.g., 60m), ensure adequate `days_back` (auto-calculation is enabled by default).
+- The analyzer is heuristic; adjust weights or thresholds as your strategy matures.
+- See the advisor helpers under `lib/dhanhq/analysis/helpers/` to customize bias and moneyness rules.

data/lib/DhanHQ/constants.rb

@@ -131,13 +131,11 @@ module DhanHQ
     # Download URL for the detailed instrument master CSV.
     DETAILED_CSV_URL = "https://images.dhan.co/api-data/api-scrip-master-detailed.csv"
 
-    # API routes that require a `client-id` header in addition to the access token.
-    DATA_API_PATHS = %w[
-      /v2/marketfeed/ltp
-      /v2/marketfeed/ohlc
-      /v2/marketfeed/quote
+    # API route prefixes that require a `client-id` header in addition to the access token.
+    DATA_API_PREFIXES = %w[
+      /v2/marketfeed/
       /v2/optionchain
-      /v2/optionchain/expirylist
+      /v2/instrument/
     ].freeze
 
     # Mapping of DhanHQ error codes to SDK error classes for consistent exception handling.

data/lib/DhanHQ/contracts/instrument_list_contract.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Contracts
+    # Validates the exchange segment param for instrument list endpoint
+    class InstrumentListContract < BaseContract
+      params do
+        required(:exchange_segment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
+      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/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.3"
 end

data/lib/DhanHQ.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
+    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 = case rsi
+                        when nil then 0.5
+                        else
+                          return 0.65 if rsi >= 55
+                          return 0.35 if rsi <= 45
+
+                          0.5
+                        end
+
+        macd_component = case hist
+                         when nil then 0.5
+                         else
+                           hist >= 0 ? 0.6 : 0.4
+                         end
+
+        adx_component = case adx
+                        when nil then 0.5
+                        else
+                          if adx >= @strong_adx
+                            0.65
+                          elsif adx >= @min_adx
+                            0.55
+                          else
+                            0.45
+                          end
+                        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,23 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Analysis
+    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