DhanHQ 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 065ac08985790dc4172816430025c482f539b506445c84181f69bdb56d30f510
-  data.tar.gz: 8f545f2ac8416dfadfe4fc0a5216b4203d06eaf05e1b1094d14ee571e84de342
+  metadata.gz: 6d97f7473f5bb7c4968750c3e21e5721a9c9ba1261e6e00d450818613edb74ec
+  data.tar.gz: 49464e4909ac0f52947fc86735b6b43bef6877f8ba0a1f796eb3b1c58c60bfde
 SHA512:
-  metadata.gz: 27d821b96f67997c64f1a523c2a366736dabcea5175e621014e22c9b691f35835f008f3bacaefe6b26229d2de92a78d44719f1b5ebff3e288960f156f7192331
-  data.tar.gz: 76558d36116bbc9c2b024aacc0c6cb1c30640b777cf2cd0832cb6d8da9b142fd6aca350318489a3d13f848136c1089bcd1ef014a2a975c8f66bde1e7c8131d10
+  metadata.gz: 5a70be1d7aa2af222df63e8188af1b60e110431d73ae36317244693d974e46a3fcb84a9a49d9276fbadeea105c1124753129aa1c057d089924f0b71c7075f481
+  data.tar.gz: cb8a910ad46ae08b570eb9b19ac3a553de9a050e1b2a409d1414f3eb18d7eb762cb2fc62d6f2a5a72ad9014f726a1195541fa29ea80d749ba4c1dc21d6b0903f

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [3.4.0] - 2026-08-15
+
+### Added
+
+- **`DhanHQ::Backtest::Runner`** (with `Trade` and `Result`) — replays a `DhanHQ::Strategy::Base` against historical `OHLCSeries` candles and returns a trade log, a per-bar equity curve, and summary stats (`total_return_pct`, `win_rate`, `max_drawdown_pct`, `num_trades`, `avg_trade_pnl`).
+
+  Both entries and exits fill at the *next* candle's open, never the signal candle's own price — deciding to act on a candle and then filling somewhere inside that same candle is look-ahead bias, since the fill price would have to come from before the candle closed. The equity curve stays flat on the signal bar itself for the same reason: a position isn't marked-to-market until it's actually been filled on the following bar. Risk-rule violations reuse `Strategy::Base#check_risks` rather than a second DSL, and an unclosed position at the end of the dataset is force-closed at the final candle's close. Optional `max_bars_held:` guards against a strategy bug holding a position across the entire dataset.
+
+- **`QUICKSTART.md`** — the 5 most common tasks (install/config, reads, safe order placement, WS streaming, strategy building) in under 50 lines, linked from the README.
+
+- **`DHAN_WS_DEBUG=true`** (`config.ws_debug`) — hex-dumps every raw inbound WebSocket frame at `debug` level before it's parsed, for troubleshooting binary parse errors and dead-but-connected feeds. Off by default, checked before any hex-encoding work so there's no cost when disabled, and capped at 256 bytes per frame (with a `...truncated` marker and the full byte count always logged) so a market-depth feed at tick frequency can't flood the log.
+
+  There isn't a single choke point all raw frames pass through: the market-feed `DhanHQ::WS::Connection` predates `BaseConnection` and has its own `on(:message)` handler, `DhanHQ::WS::Orders::Connection` overrides `BaseConnection#handle_message` entirely without calling `super`, and only `DhanHQ::WS::MarketDepth::Client` goes through `BaseConnection` unmodified. `DhanHQ::WS.debug_frame` is wired into all three so there's one hex-dump implementation, not three that could drift.
+
+- **`rails generate dhanhq:install`** — scaffolds `config/initializers/dhanhq.rb`, an order-placing service object, a Sidekiq market-feed worker, and an ActionCable channel in one command.
+
+- **`DhanHQ::Jobs::PlaceOrderJob`** — an ActiveJob wrapper around `Order.place!`. Uses `discard_on` for `DhanHQ::OrderError`/`DhanHQ::RiskViolation` rather than a manual `rescue`: `discard_on` is handled inside ActiveJob's own `execute`, before an exception would ever reach a queue adapter's own backend-level retry (Sidekiq retries unhandled exceptions by default, independent of ActiveJob's opt-in `retry_on`) — the only adapter-agnostic way to guarantee this non-idempotent write is never silently retried.
+
+### Fixed
+
+- **`docs/RAILS_INTEGRATION.md`'s Sidekiq examples (§5, §6) called `client.wait!`, `client.subscribe(array)`, and `DhanHQ::WS::Client.new(kind: :order_updates)`** — none of which exist. `DhanHQ::WS::Client`/`DhanHQ::WS::Orders::Client` have no blocking wait method at all; `Client#start` spawns a background thread and returns immediately. Replaced with the real API (`DhanHQ::WS.connect`/`DhanHQ::WS::Orders.connect` plus a `connected?`-based liveness loop), guarded by a new spec that locks down the method names these examples call by name.
+- **`dry-validation` had no version floor in the gemspec.** A fresh `bundle install` could resolve it to `0.4.1` — a 2016-era, pre-`Dry::Validation::Contract` API generation every contract in `lib/DhanHQ/contracts/` is incompatible with. Pinned to `~> 1.11`. Found while investigating whether the Ruby floor could drop to 3.1 (it can't — see below); confirmed by forcing an actual fresh resolve under Ruby 3.1.6, which hit exactly this.
+- **`spec/dhan_hq/contracts/expired_options_data_contract_spec.rb` and `expired_options_data_spec.rb` hardcoded `from_date: "2021-08-02"`**, which is itself now more than 5 years in the past and so failed the contract's own "cannot be more than 5 years ago" rule — the shared fixture failed the exact rule it existed to exercise, cascading into every test merged onto it. Replaced every literal 2021 date with one computed relative to `Date.today`, preserving each test's original intent (span length, ordering, the exact-31-day boundary).
+
+### Investigated, not changed
+
+- **Lowering `required_ruby_version` below `3.2.0`.** This gem's own code needed only two trivial fixes (anonymous `**` keyword forwarding, genuinely 3.2-only syntax — endless methods and anonymous `&` block forwarding, the original suspects, are 3.0+ and 3.1+ respectively and were never the issue). But forcing a fresh dependency resolve under Ruby 3.1.6 — after fixing the `dry-validation` pin above — still forced `activesupport` down to 7.2.3.2 (ActiveSupport 8.x itself requires Ruby ≥ 3.2), and AS 7-vs-8 behavioral differences broke `Agent::ToolRegistry`, `MCP::Server`, and `Risk::Pipeline`: 63 failures across areas with no connection to Ruby version syntax at all. That's a materially larger compatibility surface than a floor bump, so `required_ruby_version` stays `>= 3.2.0`.
+
 ## [3.3.0] - 2026-07-26
 
 ### Added

data/README.md

@@ -1,31 +1,44 @@
-# DhanHQ — The Ruby SDK for Dhan API v2
+# DhanHQ — Ruby SDK & Client for Dhan API v2
 
 [![Gem Version](https://badge.fury.io/rb/DhanHQ.svg)](https://rubygems.org/gems/DhanHQ)
 [![CI](https://github.com/shubhamtaywade82/dhanhq-client/actions/workflows/main.yml/badge.svg)](https://github.com/shubhamtaywade82/dhanhq-client/actions/workflows/main.yml)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](https://www.ruby-lang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.txt)
 
-Build trading systems in Ruby without fighting raw HTTP, fragile auth flows, or unreliable market streams.
+**DhanHQ** is a production-grade **Ruby SDK for the Dhan API v2** — build algorithmic trading systems, market data pipelines, and portfolio management tools for Indian markets (NSE, BSE, MCX) with clean Ruby abstractions, resilient WebSocket streaming, typed models, dry-validation contracts, and safety-focused order workflows for Ruby on Rails and standalone Ruby applications.
 
-DhanHQ is a production-grade Ruby SDK for the [Dhan trading API](https://dhanhq.co/docs/v2/), designed for:
+If you're looking for a Ruby gem for the Dhan trading API, this is built to be the default choice.
 
-- trading bots
-- real-time market data streaming
-- portfolio and order management
-- Rails or standalone trading systems
+## Quick Start
 
-If you're looking for a Ruby SDK for Dhan API, this is built to be the default choice.
+```ruby
+# Gemfile
+gem 'DhanHQ'
+```
 
-Unlike thin wrappers, DhanHQ gives you:
+```ruby
+require 'dhan_hq'
+
+DhanHQ.configure do |c|
+  c.client_id    = ENV["DHAN_CLIENT_ID"]
+  c.access_token = ENV["DHAN_ACCESS_TOKEN"]
+end
 
-- typed models for orders, positions, holdings, and more
-- WebSocket clients with auto-reconnect and backoff
-- token lifecycle management with retry-on-401
-- safety rails for live trading
+# You're live — no manual HTTP, no JSON parsing
+positions = DhanHQ::Models::Position.all
+```
 
-This is closer to trading infrastructure than a simple API client.
+## Features
 
-## Install and Run in 60 Seconds
+- **Typed models** for orders, positions, holdings, funds, and trades
+- **WebSocket market feed** with auto-reconnect and exponential backoff
+- **WebSocket order updates** — real-time execution events
+- **Token lifecycle management** with automatic retry-on-401
+- **dry-validation contracts** for every trading request
+- **Rails integration** with ActionCable, config generators, and rake tasks
+- **Safety rails** — validation before transport, no blind retries
+- **Comprehensive docs** — 25+ guides covering auth, WebSocket, orders, super orders, TA, and testing
+- **REST API** — orders, super orders, positions, holdings, funds, instruments, option chain, historical data, and more
 
 ```ruby
 # Gemfile
@@ -62,7 +75,7 @@ positions = DhanHQ::Models::Position.all
 
 ## Start Here (Pick Your Use Case)
 
-Pick the path that matches what you want to build:
+Pick the path that matches what you want to build, or just read the [Quickstart](QUICKSTART.md) top to bottom:
 
 - **Get live prices fast** → [Market Feed WebSocket](#market-feed-ticker--quote--full)
 - **Place orders safely** → [Order Safety](#order-safety)
@@ -529,6 +542,10 @@ client.health
 > 5,000 instruments per connection and 100 instruments per subscribe frame. Running several
 > strategies in separate processes counts against the same limit — a 6th connection is refused.
 
+If frames stop arriving or parsing fails and `healthy?`/logs alone aren't enough, set
+`DHAN_WS_DEBUG=true` to hex-dump every raw inbound frame at debug level — see
+[Troubleshooting](docs/TROUBLESHOOTING.md#websocket-frame-debugging).
+
 ### Cleanup
 
 ```ruby
@@ -704,7 +721,11 @@ sleep   # keep the script alive
 
 ## Rails Integration
 
-Need initializers, service objects, ActionCable wiring, and background workers? See the [Rails Integration Guide](docs/RAILS_INTEGRATION.md).
+```bash
+rails generate dhanhq:install
+```
+
+Scaffolds `config/initializers/dhanhq.rb`, an order-placing service object, a Sidekiq market-feed worker, and an ActionCable channel in one command. For the full picture — service objects, ActionCable wiring, background workers, dynamic token providers — see the [Rails Integration Guide](docs/RAILS_INTEGRATION.md).
 
 ---
 
@@ -743,6 +764,7 @@ For search-driven discovery and onboarding content, see:
 
 | Guide | What it covers |
 | ----- | -------------- |
+| [Quickstart](QUICKSTART.md) | The 5 most common tasks in under 50 lines |
 | [Architecture](ARCHITECTURE.md) | Layering, dependency flow, design patterns, extension points |
 | [Authentication](docs/AUTHENTICATION.md) | Token flows, TOTP, OAuth, auto-management |
 | [Configuration Reference](docs/CONFIGURATION.md) | Full ENV matrix, logging, timeouts, available resources |

data/docs/CONFIGURATION.md

@@ -51,6 +51,7 @@ These change what a write request *does*, not just where it goes. All default to
 | `DHAN_RETRY_WRITES=true`               | `config.retry_non_idempotent_writes` | `false` | Auto-retries a non-idempotent write (order placement, modify, cancel) after a transient failure (429, 5xx, timeout). Off by default because the API has no idempotency key — a timed-out POST may have already reached the exchange, and retrying it can place a duplicate order. |
 | `DHAN_AUTO_CORRELATION_ID=true`        | `config.auto_correlation_id`         | `false` | Fills in a `correlationId` (`dhq-<hex>`) on order placements that lack one, so a timed-out placement can be reconciled via `GET /v2/orders/external/{correlation-id}`. Off by default because it changes the request body; an explicit correlation id is always preserved. |
 | `DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false` | `config.warn_on_ambiguous_write_failure` | `true` (on) | Logs a once-per-call-site deprecation notice when a non-bang write method (`Order.place`, `#modify`, …) reports failure as `nil`, `false`, or a `DhanHQ::ErrorObject` — these disagree today and unify on `ErrorObject` in 4.0.0. Use the `!` variant (`place!`, `#modify!`) to get a raised `DhanHQ::OrderError` instead of the ambiguous return value. |
+| `DHAN_WS_DEBUG=true`                   | `config.ws_debug`                    | `false` | Logs every raw inbound WebSocket frame (market feed, order updates, market depth) as a hex dump at `debug` level before it's parsed. Off by default — high volume, and there's no encoding cost when disabled since the flag is checked first. Requires `DHAN_LOG_LEVEL=debug` (see [Logging](#logging)) to actually see the output. See [Troubleshooting](TROUBLESHOOTING.md#websocket-frame-debugging). |
 
 ## `.env` File Setup
 

data/docs/RAILS_INTEGRATION.md

@@ -21,6 +21,11 @@ bundle install
 If you package the gem privately you can also point to a released version from
 RubyGems.
 
+**Fast path:** `rails generate dhanhq:install` scaffolds the initializer below plus
+a sample order service, a Sidekiq market-feed worker, and an ActionCable channel
+in one command. The rest of this guide covers what it generates and the options
+beyond it (dynamic tokens, order-update streaming, scheduled jobs).
+
 ## 2. Configure credentials & initializer
 
 Store the Dhan client id and access token using Rails credentials or ENV
@@ -173,6 +178,32 @@ The gem exposes models for positions, holdings, trades, funds, option chains,
 historical bars, etc. Instantiate them the same way (`Model.all`, `.find`,
 `.where`, `#save`).
 
+### Placing orders in the background
+
+For order placement from a controller action or another job, `DhanHQ::Jobs::PlaceOrderJob`
+ships with the gem — no service object required:
+
+```ruby
+DhanHQ::Jobs::PlaceOrderJob.perform_later(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type:     DhanHQ::Constants::ProductType::INTRADAY,
+  order_type:       DhanHQ::Constants::OrderType::LIMIT,
+  validity:         DhanHQ::Constants::Validity::DAY,
+  security_id:      "11536",
+  quantity:         5,
+  price:            1500.0
+)
+```
+
+It calls `Order.place!` and uses ActiveJob's `discard_on` for `DhanHQ::OrderError` and
+`DhanHQ::RiskViolation` — a rejection is logged, not silently retried. This matters because
+DhanHQ order writes are **not idempotent**: most queue adapters (Sidekiq chief among them)
+retry unhandled exceptions at the backend level by default, independent of ActiveJob's own
+opt-in `retry_on`, and a timed-out `POST /v2/orders` retry can place a duplicate order. Don't
+add your own `retry_on DhanHQ::OrderError` on top of this job — that would fight the
+`discard_on` and reintroduce the exact risk it exists to prevent.
+
 ## 4. Centralise error handling
 
 Wrap the gem's exceptions in a concern so Rails controllers and jobs return
@@ -209,21 +240,26 @@ ticks through ActionCable, Redis, or a database.
 # app/workers/dhan/market_feed_worker.rb
 class Dhan::MarketFeedWorker
   include Sidekiq::Worker
+  sidekiq_options retry: false # DhanHQ::WS::Client already reconnects and re-subscribes on its own
 
-  def perform(mode = :quote, securities = [])
-    client = DhanHQ::WS::Client.new(mode: mode.to_sym)
-
-    client.on(:open) { Rails.logger.info('Dhan WS connected') }
-    client.on(:close) { Rails.logger.warn('Dhan WS closed; worker will retry') }
-    client.on(:error) { |err| Rails.logger.error("Dhan WS error: #{err}") }
-
-    client.on(:tick) do |tick|
+  def perform(mode = "quote", securities = [])
+    client = DhanHQ::WS.connect(mode: mode.to_sym) do |tick|
       ActionCable.server.broadcast('market_feed', tick)
     end
 
-    client.start
-    client.subscribe(securities) if securities.any?
-    client.wait! # blocks the worker thread while EventMachine runs
+    client.on(:reconnect) { |info| Rails.logger.warn("Dhan WS reconnect ##{info[:attempt]}") }
+    client.on(:error) { |message| Rails.logger.error("Dhan WS error: #{message}") }
+
+    securities.each { |segment, security_id| client.subscribe_one(segment: segment, security_id: security_id) }
+
+    # Client#start already spawned a background thread and returned -- there is
+    # no blocking wait! method. Hold the worker open for the life of the
+    # connection so Sidekiq doesn't consider the job "done" the instant the
+    # feed opens.
+    loop do
+      sleep 30
+      break unless client.connected?
+    end
   end
 end
 ```
@@ -255,22 +291,29 @@ Use the order-update WebSocket endpoint (configure `ws_order_url` and
 # app/workers/dhan/order_updates_worker.rb
 class Dhan::OrderUpdatesWorker
   include Sidekiq::Worker
+  sidekiq_options retry: false
 
   def perform
-    client = DhanHQ::WS::Client.new(kind: :order_updates)
-
-    client.on(:order_update) do |payload|
-      OrderStatusUpdater.call(payload)
+    client = DhanHQ::WS::Orders.connect do |order_update|
+      OrderStatusUpdater.call(order_update)
     end
 
     client.on(:error) { |err| Rails.logger.error("Dhan order WS error: #{err}") }
 
-    client.start
-    client.wait!
+    loop do
+      sleep 30
+      break unless client.connected?
+    end
   end
 end
 ```
 
+`DhanHQ::WS::Orders::Client` also tracks state for you without any extra
+wiring — `client.order_state(order_no)`, `client.orders_by_status(status)`,
+`client.pending_orders`, and friends stay in sync as updates arrive, so
+`OrderStatusUpdater` doesn't need to re-derive status transitions from raw
+payloads.
+
 Inside `OrderStatusUpdater` you can reconcile the payload with your local order
 records, notify users via ActionCable or email, etc.
 

data/docs/TROUBLESHOOTING.md

@@ -50,16 +50,30 @@ client = DhanHQ::WS.connect(mode: :ticker) { |tick| puts tick[:ltp] }
 
 **Solution:**
 - The client safely drops malformed frames and keeps the event loop alive.
-- Run with `DHAN_LOG_LEVEL=DEBUG` to inspect raw frames:
+- Turn on [WebSocket Frame Debugging](#websocket-frame-debugging) below to see the actual bytes that failed to parse.
+
+---
+
+## WebSocket Frame Debugging
+
+**Symptom:** Ticks stopped arriving, or you're seeing "unknown feed kind" / parse errors and need to see what the server actually sent — a bug report of "got garbage data" is unactionable without the raw bytes.
+
+**Solution:** Set `DHAN_WS_DEBUG=true` (or `config.ws_debug = true`) alongside debug-level logging. Every raw inbound frame — market feed, order updates, market depth — is logged as a hex dump before it's parsed:
 
 ```bash
+export DHAN_WS_DEBUG=true
 export DHAN_LOG_LEVEL=DEBUG
 ```
 
 ```ruby
+DhanHQ.configure do |c|
+  c.ws_debug = true
+end
 DhanHQ.logger.level = Logger::DEBUG
 ```
 
+This is off by default and high-volume when on — the flag is checked before any hex encoding work, so leaving it off costs nothing, but a live feed with `DHAN_WS_DEBUG=true` will log every single tick. Turn it off once you have what you need. See [Configuration Reference](CONFIGURATION.md#behavior-flags) for the full flag reference.
+
 ---
 
 ## Authentication Errors

data/lib/DhanHQ/backtest/result.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Backtest
+    # Aggregated outcome of a Runner run: the trade log, a per-bar equity
+    # curve, and derived summary statistics. Pure math over data Runner
+    # already computed — no I/O.
+    class Result
+      attr_reader :trades, :equity_curve, :initial_capital
+
+      # @param trades [Array<DhanHQ::Backtest::Trade>]
+      # @param equity_curve [Array<Float>] mark-to-market equity, one point per candle
+      # @param initial_capital [Float]
+      def initialize(trades:, equity_curve:, initial_capital:)
+        @trades = trades
+        @equity_curve = equity_curve
+        @initial_capital = initial_capital.to_f
+      end
+
+      # @return [Float] equity after the last candle (or initial_capital if no candles ran)
+      def final_equity
+        equity_curve.last || initial_capital
+      end
+
+      # @return [Float] total return over the run, as a percentage of initial capital
+      def total_return_pct
+        return 0.0 if initial_capital.zero?
+
+        ((final_equity - initial_capital) / initial_capital) * 100
+      end
+
+      # @return [Integer] number of completed round-trip trades
+      def num_trades
+        trades.size
+      end
+
+      # @return [Array<DhanHQ::Backtest::Trade>] trades that closed profitably
+      def winning_trades
+        trades.select(&:win?)
+      end
+
+      # @return [Float] percentage of trades that closed profitably
+      def win_rate
+        return 0.0 if trades.empty?
+
+        (winning_trades.size.to_f / trades.size) * 100
+      end
+
+      # @return [Float] mean pnl across all trades
+      def avg_trade_pnl
+        return 0.0 if trades.empty?
+
+        trades.sum(&:pnl) / trades.size
+      end
+
+      # @return [Float] largest peak-to-trough decline in the equity curve, as a percentage
+      def max_drawdown_pct
+        return 0.0 if equity_curve.empty?
+
+        peak = equity_curve.first
+        max_dd = 0.0
+
+        equity_curve.each do |equity|
+          peak = equity if equity > peak
+          next if peak.zero?
+
+          drawdown = ((peak - equity) / peak) * 100
+          max_dd = drawdown if drawdown > max_dd
+        end
+
+        max_dd
+      end
+
+      # @return [Hash] rounded snapshot of the metrics above, for reporting
+      def summary
+        {
+          total_return_pct: total_return_pct.round(2),
+          num_trades: num_trades,
+          win_rate: win_rate.round(2),
+          avg_trade_pnl: avg_trade_pnl.round(2),
+          max_drawdown_pct: max_drawdown_pct.round(2),
+          final_equity: final_equity.round(2)
+        }
+      end
+    end
+  end
+end

data/lib/DhanHQ/backtest/runner.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Backtest
+    # Replays a DhanHQ::Strategy::Base against historical OHLC candles and
+    # returns a Result.
+    #
+    # Both entries and exits fill at the *next* candle's open, never the
+    # signal candle's own price — evaluating a signal on a candle and then
+    # filling somewhere inside that same candle is look-ahead bias, since the
+    # fill price would have to come from before the candle closed (and so
+    # before the signal could have fired live). The one exception is the end
+    # of the dataset: an open position with no next candle to fill against is
+    # force-closed at the last candle's close.
+    #
+    # Only one position is held at a time, matching DhanHQ::Strategy::Base's
+    # single `@position` / entry-then-exit model — no pyramiding, no shorting.
+    class Runner
+      DEFAULT_QUANTITY = ->(equity, price) { price.positive? ? (equity / price).floor : 0 }
+      NO_FEES = ->(_trade_value) { 0.0 }
+
+      # @param strategy [DhanHQ::Strategy::Base]
+      # @param data [DhanHQ::MarketData::OHLCSeries]
+      # @param initial_capital [Float]
+      # @param quantity [#call, Integer] `->(equity, price) { ... }`, or a fixed integer
+      # @param fees [#call] `->(trade_value) { ... }`, charged once per leg (entry, exit)
+      # @param max_bars_held [Integer, nil] force-exit a position held this many bars or longer
+      def initialize(strategy:, data:, initial_capital:, quantity: DEFAULT_QUANTITY, fees: NO_FEES, max_bars_held: nil)
+        @strategy = strategy
+        @candles = data.respond_to?(:candles) ? data.candles : Array(data)
+        @initial_capital = initial_capital.to_f
+        @quantity = quantity.respond_to?(:call) ? quantity : ->(_equity, _price) { quantity }
+        @fees = fees
+        @max_bars_held = max_bars_held
+      end
+
+      # @return [DhanHQ::Backtest::Result]
+      def run
+        return Result.new(trades: [], equity_curve: [], initial_capital: @initial_capital) if @candles.empty?
+
+        equity = @initial_capital
+        equity_curve = []
+        trades = []
+        window_candles = []
+        open_trade = nil
+        entry_index = nil
+
+        @candles.each_with_index do |candle, index|
+          window_candles << candle
+          window = DhanHQ::MarketData::OHLCSeries.new(window_candles)
+          has_next = index < @candles.size - 1
+
+          if open_trade && has_next
+            trade = maybe_exit(open_trade, window, index, entry_index, equity, equity_curve, @candles[index + 1])
+
+            if trade
+              trades << trade
+              equity += trade.pnl
+              open_trade = nil
+              entry_index = nil
+            end
+          elsif open_trade.nil? && has_next
+            open_trade, entry_index = maybe_enter(window, @candles[index + 1], equity, index)
+          end
+
+          # A position opened this very iteration (via maybe_enter) isn't filled until the
+          # *next* candle — mark-to-market must stay flat until index reaches entry_index,
+          # or the equity curve would price the position off a fill that hasn't happened yet.
+          filled = open_trade && index >= entry_index
+          equity_curve << mark_to_market(equity, filled ? open_trade : nil, candle.close)
+        end
+
+        if open_trade
+          last = @candles.last
+          trade = close_trade(open_trade, last.timestamp, last.close, :end_of_data)
+          trades << trade
+          equity += trade.pnl
+          equity_curve[-1] = equity
+        end
+
+        Result.new(trades: trades, equity_curve: equity_curve, initial_capital: @initial_capital)
+      end
+
+      private
+
+      def maybe_enter(window, next_candle, equity, index)
+        signal = @strategy.evaluate_entry(window)
+        return [nil, nil] unless signal.buy?
+
+        qty = @quantity.call(equity, next_candle.open)
+        return [nil, nil] unless qty.positive?
+
+        [{ entry_time: next_candle.timestamp, entry_price: next_candle.open, quantity: qty }, index + 1]
+      end
+
+      def maybe_exit(open_trade, window, index, entry_index, equity, equity_curve, next_candle)
+        bars_held = index - entry_index
+        forced = @max_bars_held && bars_held >= @max_bars_held
+        drawdown = drawdown_pct(equity_curve, equity)
+        violations = @strategy.check_risks(equity: equity, position: open_trade, drawdown: drawdown)
+        signal = @strategy.evaluate_exit(window)
+
+        return unless forced || violations.any? || signal.sell?
+
+        reason = if forced
+                   :max_bars_held
+                 elsif violations.any?
+                   :risk_violation
+                 else
+                   :signal
+                 end
+        close_trade(open_trade, next_candle.timestamp, next_candle.open, reason)
+      end
+
+      def close_trade(open_trade, exit_time, exit_price, reason)
+        entry_value = open_trade[:entry_price] * open_trade[:quantity]
+        exit_value = exit_price * open_trade[:quantity]
+
+        Trade.new(
+          entry_time: open_trade[:entry_time],
+          entry_price: open_trade[:entry_price],
+          exit_time: exit_time,
+          exit_price: exit_price,
+          quantity: open_trade[:quantity],
+          exit_reason: reason,
+          fees: @fees.call(entry_value) + @fees.call(exit_value)
+        )
+      end
+
+      def mark_to_market(equity, open_trade, close_price)
+        return equity unless open_trade
+
+        equity + ((close_price - open_trade[:entry_price]) * open_trade[:quantity])
+      end
+
+      def drawdown_pct(equity_curve, current_equity)
+        peak = (equity_curve + [current_equity]).max
+        return 0.0 if peak.nil? || peak.zero?
+
+        [((peak - current_equity) / peak) * 100, 0.0].max
+      end
+    end
+  end
+end

data/lib/DhanHQ/backtest/trade.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Backtest
+    # A single completed long round-trip trade produced by Runner.
+    #
+    # `fees` is the total cost charged across both legs (entry + exit), already
+    # netted into `pnl` — it is not deducted again by callers.
+    Trade = Struct.new(
+      :entry_time, :entry_price, :exit_time, :exit_price, :quantity, :exit_reason, :fees
+    ) do
+      # Net profit/loss for this trade, after fees.
+      #
+      # @return [Float]
+      def pnl
+        ((exit_price - entry_price) * quantity) - fees.to_f
+      end
+
+      # Net profit/loss as a percentage of the entry value.
+      #
+      # @return [Float]
+      def pnl_pct
+        entry_value = entry_price.to_f * quantity.to_f
+        return 0.0 if entry_value.zero?
+
+        (pnl / entry_value) * 100
+      end
+
+      # @return [Boolean] whether this trade closed profitably after fees
+      def win?
+        pnl.positive?
+      end
+    end
+  end
+end

data/lib/DhanHQ/backtest.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Backtesting engine that replays a DhanHQ::Strategy::Base against historical
+  # OHLC data and reports trades, an equity curve, and summary performance stats.
+  #
+  # @example Backtest a strategy against daily candles
+  #   data = DhanHQ::Models::HistoricalData.daily(
+  #     security_id: "1333", exchange_segment: "NSE_EQ",
+  #     instrument: "EQUITY", from_date: "2024-01-01", to_date: "2024-12-31"
+  #   )
+  #   series = DhanHQ::MarketData::OHLCSeries.from_response(data)
+  #
+  #   result = DhanHQ::Backtest::Runner.new(
+  #     strategy: MyStrategy.new,
+  #     data: series,
+  #     initial_capital: 100_000.0
+  #   ).run
+  #
+  #   result.summary #=> { total_return_pct: 12.4, num_trades: 8, win_rate: 62.5, ... }
+  #
+  module Backtest
+  end
+end

data/lib/DhanHQ/configuration.rb

@@ -132,6 +132,15 @@ module DhanHQ
     # @return [Integer]
     attr_accessor :market_depth_level
 
+    # When true, every raw inbound WebSocket frame (market feed, order updates,
+    # market depth) is logged as a hex dump at debug level before it's parsed.
+    # Off by default -- high volume, and the check happens before any hex
+    # encoding work so there's no cost when disabled.
+    #
+    # Set via +DHAN_WS_DEBUG=true+ or in {DhanHQ.configure}.
+    # @return [Boolean]
+    attr_accessor :ws_debug
+
     # Setters for websocket URLs
     attr_writer :ws_order_url, :ws_market_feed_url, :ws_market_depth_url
 
@@ -198,6 +207,11 @@ module DhanHQ
       @auto_correlation_id == true
     end
 
+    # @return [Boolean] True when raw WebSocket frames should be hex-logged.
+    def ws_debug?
+      @ws_debug == true
+    end
+
     # Initializes a new configuration instance with default values.
     #
     # @example
@@ -218,6 +232,7 @@ module DhanHQ
       @ws_market_feed_url = ENV.fetch("DHAN_WS_MARKET_FEED_URL", nil)
       @ws_market_depth_url = ENV.fetch("DHAN_WS_MARKET_DEPTH_URL", nil)
       @market_depth_level = ENV.fetch("DHAN_MARKET_DEPTH_LEVEL", "20").to_i
+      @ws_debug       = env_flag("DHAN_WS_DEBUG", default: false)
       @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/jobs/place_order_job.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Jobs
+    # Places a Dhan order via ActiveJob, without ever letting a queue adapter
+    # (Sidekiq, Resque, ...) retry it.
+    #
+    # DhanHQ order writes are not idempotent -- a timed-out POST /v2/orders may
+    # already have reached the exchange, so retrying it can place a duplicate
+    # order (see the README's "Order Retries and Duplicate Protection"). Most
+    # adapters retry unhandled exceptions at the backend level by default
+    # (Sidekiq's own retry, independent of ActiveJob's opt-in `retry_on`), so
+    # the only adapter-agnostic way to guarantee this write is never silently
+    # retried is to make sure the exception never reaches the adapter at all.
+    # `discard_on` does exactly that: it's handled inside ActiveJob's own
+    # `execute`, so from the adapter's point of view the job completed, not
+    # failed -- there is nothing left for the adapter's own retry logic to
+    # act on.
+    #
+    # @example
+    #   DhanHQ::Jobs::PlaceOrderJob.perform_later(
+    #     transaction_type: DhanHQ::Constants::TransactionType::BUY,
+    #     exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+    #     product_type:     DhanHQ::Constants::ProductType::INTRADAY,
+    #     order_type:       DhanHQ::Constants::OrderType::LIMIT,
+    #     validity:         DhanHQ::Constants::Validity::DAY,
+    #     security_id:      "11536",
+    #     quantity:         5,
+    #     price:            1500.0
+    #   )
+    class PlaceOrderJob < ActiveJob::Base
+      discard_on DhanHQ::OrderError do |_job, error|
+        DhanHQ.logger&.error("[DhanHQ::Jobs::PlaceOrderJob] order rejected: #{error.message}")
+      end
+
+      discard_on DhanHQ::RiskViolation do |_job, error|
+        DhanHQ.logger&.warn("[DhanHQ::Jobs::PlaceOrderJob] risk check blocked the order: #{error.message}")
+      end
+
+      # @param params [Hash] Same params accepted by DhanHQ::Models::Order.place.
+      # @return [DhanHQ::Models::Order]
+      def perform(params)
+        DhanHQ::Models::Order.place!(params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/version.rb

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

data/lib/DhanHQ/ws/base_connection.rb

@@ -212,6 +212,7 @@ module DhanHQ
       # Handle WebSocket message event
       # @param ev [Event] WebSocket message event
       def handle_message(ev)
+        WS.debug_frame(self.class.name, ev.data)
         emit(:raw, ev.data)
         process_message(ev.data) if respond_to?(:process_message, true)
       end

data/lib/DhanHQ/ws/connection.rb

@@ -141,6 +141,7 @@ module DhanHQ
               @ws.on(:open) { |_| handle_open(sessions) }
 
               @ws.on :message do |ev|
+                WS.debug_frame(self.class.name, ev.data)
                 notify(:message, nil)
                 @on_binary&.call(ev.data) # raw frames to decoder
               end

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

@@ -63,6 +63,7 @@ module DhanHQ
         # Process incoming WebSocket message
         # @param ev [Event] WebSocket message event
         def handle_message(ev)
+          WS.debug_frame(self.class.name, ev.data)
           msg = JSON.parse(ev.data, symbolize_names: true)
           emit(:raw, msg)
           emit(:message, msg)

data/lib/DhanHQ/ws.rb

@@ -34,5 +34,30 @@ module DhanHQ
     def self.disconnect_all_local!
       Registry.stop_all
     end
+
+    # Cap on how many bytes of a frame get hex-dumped by {debug_frame}. A full
+    # depth packet can run several KB; at tick frequency that floods the log
+    # long before it adds diagnostic value beyond the first couple hundred
+    # bytes (header + the first few fields is normally enough to spot a
+    # parsing bug). The full frame size is always logged regardless of the cap.
+    DEBUG_FRAME_MAX_BYTES = 256
+
+    # Logs a raw inbound WebSocket frame as a hex dump when
+    # +config.ws_debug+ (+DHAN_WS_DEBUG=true+) is enabled. A no-op otherwise --
+    # the flag is checked before any hex encoding work, so there's no cost
+    # when debug logging is off. Frames longer than {DEBUG_FRAME_MAX_BYTES}
+    # are truncated in the dump, but the logged byte count is always the full
+    # frame size.
+    #
+    # @param source [String] short tag identifying which connection the frame came from
+    # @param data [String] raw frame bytes
+    # @return [void]
+    def self.debug_frame(source, data)
+      return unless DhanHQ.configuration&.ws_debug?
+
+      hex = data.byteslice(0, DEBUG_FRAME_MAX_BYTES).unpack1("H*")
+      hex += "...truncated" if data.bytesize > DEBUG_FRAME_MAX_BYTES
+      DhanHQ.logger&.debug("[DhanHQ::WS::#{source}] frame (#{data.bytesize} bytes): #{hex}")
+    end
   end
 end

data/lib/generators/dhanhq/install/install_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Dhanhq
+  # Scaffolds a DhanHQ initializer, a sample order-placing service object, and
+  # a Sidekiq worker + ActionCable channel for streaming market data.
+  #
+  #   rails generate dhanhq:install
+  #
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def create_initializer
+      template "initializer.rb", "config/initializers/dhanhq.rb"
+    end
+
+    def create_order_service
+      template "place_order_service.rb", "app/services/dhan/orders/place_order.rb"
+    end
+
+    def create_market_feed_worker
+      template "market_feed_worker.rb", "app/workers/dhan_market_feed_worker.rb"
+    end
+
+    def create_market_feed_channel
+      template "market_feed_channel.rb", "app/channels/dhan_market_feed_channel.rb"
+    end
+
+    def show_post_install_message
+      say ""
+      say "DhanHQ installed! Next steps:", :green
+      say "  1. Add your credentials:"
+      say "       rails credentials:edit"
+      say "       dhanhq:"
+      say "         client_id: \"your_client_id\""
+      say "         access_token: \"your_access_token\""
+      say "  2. Set LIVE_TRADING=true before placing real orders (see docs/CONFIGURATION.md)"
+      say "  3. Start the market feed: DhanMarketFeedWorker.perform_async"
+      say ""
+      say "Full reference: https://github.com/shubhamtaywade82/dhanhq-client/blob/main/docs/RAILS_INTEGRATION.md"
+      say ""
+    end
+  end
+end

data/lib/generators/dhanhq/install/templates/initializer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "dhan_hq"
+
+if (creds = Rails.application.credentials.dig(:dhanhq))
+  ENV["DHAN_CLIENT_ID"]    ||= creds[:client_id]
+  ENV["DHAN_ACCESS_TOKEN"] ||= creds[:access_token]
+end
+
+DhanHQ.configure_with_env
+
+log_level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase
+DhanHQ.logger.level = Logger.const_get(log_level)
+
+# Full optional configuration (base_url, ws_order_url, partner auth, timeouts,
+# DHAN_WS_DEBUG, ...) is documented in:
+#   https://github.com/shubhamtaywade82/dhanhq-client/blob/main/docs/CONFIGURATION.md
+#   https://github.com/shubhamtaywade82/dhanhq-client/blob/main/docs/RAILS_INTEGRATION.md

data/lib/generators/dhanhq/install/templates/market_feed_channel.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class DhanMarketFeedChannel < ApplicationCable::Channel
+  def subscribed
+    stream_from "dhan_market_feed"
+  end
+end

data/lib/generators/dhanhq/install/templates/market_feed_worker.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Keeps a DhanHQ market feed connection open and broadcasts ticks over
+# ActionCable. Start it with DhanMarketFeedWorker.perform_async -- the job
+# blocks for the life of the connection rather than completing immediately,
+# so Sidekiq's dashboard reflects whether the feed is actually running.
+#
+# retry: false because there is nothing to retry: the underlying
+# DhanHQ::WS::Client already reconnects and re-subscribes on its own.
+class DhanMarketFeedWorker
+  include Sidekiq::Worker
+  sidekiq_options retry: false
+
+  def perform(mode = "quote")
+    client = DhanHQ::WS.connect(mode: mode.to_sym) do |tick|
+      ActionCable.server.broadcast("dhan_market_feed", tick)
+    end
+
+    client.on(:reconnect) { |info| Rails.logger.warn("[DhanMarketFeedWorker] reconnect ##{info[:attempt]}") }
+    client.on(:error) { |message| Rails.logger.error("[DhanMarketFeedWorker] #{message}") }
+
+    loop do
+      sleep 30
+      break unless client.connected?
+    end
+  end
+end

data/lib/generators/dhanhq/install/templates/place_order_service.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Dhan
+  module Orders
+    # Places a Dhan order via the bang variant, so a rejection raises a
+    # specific, catchable error instead of Order.place's ambiguous
+    # nil/false/ErrorObject return.
+    class PlaceOrder
+      def initialize(params)
+        @params = params
+      end
+
+      def call
+        DhanHQ::Models::Order.place!(@params)
+      rescue DhanHQ::OrderError => e
+        Rails.logger.error("Dhan order rejected: #{e.message}")
+        raise
+      rescue DhanHQ::RiskViolation => e
+        Rails.logger.warn("Dhan risk check blocked the order: #{e.message}")
+        raise
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: DhanHQ
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Shubham Taywade
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-26 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -84,16 +84,16 @@ dependencies:
   name: dry-validation
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.11'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.11'
 - !ruby/object:Gem::Dependency
   name: eventmachine
   requirement: !ruby/object:Gem::Requirement
@@ -164,10 +164,11 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A production-grade Ruby SDK for Dhan API v2 built for algo trading, portfolio
-  monitoring, and live trading systems. Provides typed models, token lifecycle management,
-  dry-validation contracts, resilient WebSocket streaming, and safety-focused order
-  workflows for Ruby applications.
+description: A production-grade Ruby SDK and Ruby client for Dhan API v2 built for
+  algorithmic trading, portfolio monitoring, and live trading systems on NSE, BSE
+  and MCX. Provides typed models, token lifecycle management, dry-validation contracts,
+  resilient WebSocket streaming with auto-reconnect, and safety-focused order workflows
+  for Ruby on Rails and standalone Ruby applications.
 email:
 - shubhamtaywade82@gmail.com
 executables:
@@ -228,6 +229,10 @@ files:
 - lib/DhanHQ/auth/token_generator.rb
 - lib/DhanHQ/auth/token_manager.rb
 - lib/DhanHQ/auth/token_renewal.rb
+- lib/DhanHQ/backtest.rb
+- lib/DhanHQ/backtest/result.rb
+- lib/DhanHQ/backtest/runner.rb
+- lib/DhanHQ/backtest/trade.rb
 - lib/DhanHQ/client.rb
 - lib/DhanHQ/concerns/bang_writes.rb
 - lib/DhanHQ/concerns/order_audit.rb
@@ -283,6 +288,7 @@ files:
 - lib/DhanHQ/helpers/response_helper.rb
 - lib/DhanHQ/helpers/validation_helper.rb
 - lib/DhanHQ/indicators.rb
+- lib/DhanHQ/jobs/place_order_job.rb
 - lib/DhanHQ/json_loader.rb
 - lib/DhanHQ/market_data.rb
 - lib/DhanHQ/market_data/market_snapshot.rb
@@ -433,6 +439,11 @@ files:
 - lib/dhanhq/analysis/multi_timeframe_analyzer.rb
 - lib/dhanhq/analysis/options_buying_advisor.rb
 - lib/dhanhq/contracts/options_buying_advisor_contract.rb
+- lib/generators/dhanhq/install/install_generator.rb
+- lib/generators/dhanhq/install/templates/initializer.rb
+- lib/generators/dhanhq/install/templates/market_feed_channel.rb
+- lib/generators/dhanhq/install/templates/market_feed_worker.rb
+- lib/generators/dhanhq/install/templates/place_order_service.rb
 - lib/rubocop/cop/dhanhq/use_constants.rb
 - lib/ta.rb
 - lib/ta/candles.rb
@@ -469,14 +480,15 @@ files:
 - skills/dhanhq-ruby/scripts/resolve_security.rb
 - skills/dhanhq-ruby/scripts/trade_logger.rb
 - skills/dhanhq-ruby/scripts/validate_order.rb
-homepage: https://github.com/shubhamtaywade82/dhanhq-client
+homepage: https://shubhamtaywade82.github.io/dhanhq-client/
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/shubhamtaywade82/dhanhq-client
+  homepage_uri: https://shubhamtaywade82.github.io/dhanhq-client/
   source_code_uri: https://github.com/shubhamtaywade82/dhanhq-client
   changelog_uri: https://github.com/shubhamtaywade82/dhanhq-client/blob/main/CHANGELOG.md
+  documentation_uri: https://shubhamtaywade82.github.io/dhanhq-client/
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -496,5 +508,6 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: The Ruby SDK for Dhan API v2 with REST, WebSocket, and trading workflows.
+summary: Production-grade Ruby SDK for Dhan API v2 with REST APIs, WebSocket market
+  data, token lifecycle management, dry-validation contracts and trading workflows.
 test_files: []