DhanHQ 3.3.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 065ac08985790dc4172816430025c482f539b506445c84181f69bdb56d30f510
-  data.tar.gz: 8f545f2ac8416dfadfe4fc0a5216b4203d06eaf05e1b1094d14ee571e84de342
+  metadata.gz: 8c2f0784210b7f48ccb056b8cc486ce5c3ef655f69a4bd2834a150b1d04a8bc7
+  data.tar.gz: a6628fc83e8ec61bd4ca4b0eb6147a67232156f98ab49196c0a81850f9b4ac59
 SHA512:
-  metadata.gz: 27d821b96f67997c64f1a523c2a366736dabcea5175e621014e22c9b691f35835f008f3bacaefe6b26229d2de92a78d44719f1b5ebff3e288960f156f7192331
-  data.tar.gz: 76558d36116bbc9c2b024aacc0c6cb1c30640b777cf2cd0832cb6d8da9b142fd6aca350318489a3d13f848136c1089bcd1ef014a2a975c8f66bde1e7c8131d10
+  metadata.gz: d0a4147017f7722d9a74cec3105fb57e9b8710142abda6c04d5948caa7500b21ce8c31958cc501e99643a31afffe5e64846b5a73ff239f1a8fb87074e57a6856
+  data.tar.gz: 508f55621273349e9060e941cc9bf8b7cef7fb28befb8026b57b977ba0954760f783eb5dbb26c19593ac113232c12fa74884fcd57a81b61dd21dbc3d66c7b9e9

data/CHANGELOG.md

@@ -1,3 +1,52 @@
+## [4.0.0] - 2026-08-31
+
+### Added
+
+- **Multi-Instance Client Isolation (`DhanHQ::Client.new`)** — run multiple isolated client instances in the same process with separate configurations, credentials, sandbox environments, and rate limiters. Ideal for multi-tenant applications, managing multiple trading accounts concurrently, or comparing sandbox vs. production environments side-by-side.
+  ```ruby
+  client_a = DhanHQ::Client.new(client_id: "ACC_A", access_token: "TOKEN_A")
+  client_b = DhanHQ::Client.new(client_id: "ACC_B", access_token: "TOKEN_B", sandbox: true)
+
+  orders_a = client_a.orders.all
+  orders_b = client_b.orders.all
+  ```
+- **Instance-bound Resource Accessors** — direct accessors on `DhanHQ::Client` instances (`client.orders`, `client.positions`, `client.holdings`, `client.funds`, `client.trades`, `client.market_feed`, `client.option_chain`, `client.historical_data`, `client.forever_orders`, `client.alert_orders`, `client.iceberg_orders`, `client.super_orders`, `client.twap_orders`, `client.statements`, `client.kill_switch`, `client.pnl_exit`, `client.trader_control`, `client.ip_setup`, `client.edis`) bound to that client's configuration and routed to matching rate-limiting tiers (`client_for(API_TYPE)`).
+- **Instance-bound WebSocket Helpers** — `client.ws_market_feed`, `client.ws_order_update`, and `client.ws_market_depth` configured automatically with the client instance's credentials and URLs.
+- **Keyword Argument Initialization** — `DhanHQ::Client.new` accepts keyword configuration parameters (`dry_run: true`, `sandbox: true`, `client_id: "..."`, `access_token: "..."`) or a `Configuration` instance.
+- **Per-Instance Dry-Run Mode** — `DhanHQ::Client.new(dry_run: true)` simulates state-changing writes locally for that instance regardless of the global configuration.
+- **Dynamic Model Resource Invalidation** — `DhanHQ.reset_model_resources!` automatically refreshes class-level model caches (`Models::Order.resource`, etc.) whenever `DhanHQ.configure`, `configure_with_env`, `configuration=`, or `reset_configuration!` is invoked.
+- **Per-Client Auto Token Management** — `client.enable_auto_token_management!(dhan_client_id: ..., pin: ..., totp_secret: ...)` for automated TOTP-based token lifecycle management per client instance.
+
+## [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.
+- **Every runtime dependency except `faraday` had no version floor at all** (`add_dependency "x"`, equivalent to `>= 0` — satisfied by any version ever published). Found while investigating whether the Ruby floor could drop to 3.1 (it can't — see below): forcing a fresh `bundle install` under Ruby 3.1.6 resolved `dry-validation` to `0.4.1`, a 2016-era, pre-`Dry::Validation::Contract` API generation every contract in `lib/DhanHQ/contracts/` is incompatible with — every contract spec failed at `require`-time. Pinning that alone wasn't enough: with `dry-validation` fixed, the same fresh resolve then pulled `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 with no connection to Ruby version syntax at all.
+
+  All ten now have an explicit floor matching their currently locked major (`activesupport >= 8.0`, `dry-validation ~> 1.0`, and so on) — closing the class of bug, not just the two instances that happened to surface. The `dry-validation` constraint went through two attempts: the first pass in this same release pinned it to `~> 1.11`, which — because `~>` locks to the *last* segment given — actually meant `>= 1.11, < 1.12` and would have silently blocked every future 1.12+ release. Corrected to `~> 1.0`, which excludes the ancient `0.x` line (the actual problem) without capping legitimate 1.x updates.
+- **`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/GUIDE.md

@@ -77,6 +77,22 @@ For token rotation without restarting the app, set `access_token_provider` (Proc
 
 See [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) and README “Dynamic access token”.
 
+**Multi-instance clients (multi-account support)**
+
+When you need to trade across multiple accounts, run multi-tenant setups, or isolate sandbox/testing environments in a single process, use `DhanHQ::Client.new`:
+
+```ruby
+# Account 1
+client1 = DhanHQ::Client.new(client_id: "ACC_1", access_token: "TOKEN_1")
+
+# Account 2 (Sandbox)
+client2 = DhanHQ::Client.new(client_id: "ACC_2", access_token: "TOKEN_2", sandbox: true)
+
+# Resource accessors directly bound to client instance:
+orders1 = client1.orders.all
+orders2 = client2.orders.all
+```
+
 ---
 
 ## Working With Models

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'
+```
+
+```ruby
+require 'dhan_hq'
 
-Unlike thin wrappers, DhanHQ gives you:
+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)
@@ -205,6 +218,34 @@ end
 
 When the API returns 401, the client retries **once** with a fresh token from your provider.
 
+### Multi-Instance Clients (Multi-Account / Multi-Tenant)
+
+For multi-tenant applications, managing multiple trading accounts concurrently, or isolating sandbox from production within the same process, construct explicit `DhanHQ::Client` instances:
+
+```ruby
+# Account 1 (Live Trading)
+client1 = DhanHQ::Client.new(
+  client_id: "ACC_1_ID",
+  access_token: "ACC_1_TOKEN"
+)
+
+# Account 2 (Sandbox / Testing)
+client2 = DhanHQ::Client.new(
+  client_id: "ACC_2_ID",
+  access_token: "ACC_2_TOKEN",
+  sandbox: true,
+  dry_run: true
+)
+
+# Resource accessors are bound to the client instance:
+positions = client1.positions.all
+orders    = client2.orders.all
+
+# Instance-bound WebSocket streams:
+ws_stream = client1.ws_market_feed(mode: :ticker) { |tick| puts tick[:ltp] }
+ws_orders = client1.ws_order_update
+```
+
 > **Full details**: TOTP flows, partner mode, token endpoint bootstrap, auto-management — see [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md).
 
 ---
@@ -529,6 +570,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 +749,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 +792,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
 
@@ -105,6 +106,31 @@ end
 - **`access_token_provider`**: Callable (Proc/lambda) returning the token string. Called on every request (no memoization). When set, the gem uses it instead of `access_token`.
 - **`on_token_expired`**: Optional callable invoked when a 401/token-expired triggers a **single retry** (only when `access_token_provider` is set).
 
+## Multi-Instance Client Configuration
+
+For multi-account or multi-tenant architectures, construct explicit `DhanHQ::Client` instances without depending on global singleton state:
+
+```ruby
+# Direct configuration via keyword arguments
+client = DhanHQ::Client.new(
+  client_id: "YOUR_CLIENT_ID",
+  access_token: "YOUR_ACCESS_TOKEN",
+  sandbox: false,
+  dry_run: false
+)
+
+# Or via an explicit Configuration object
+custom_config = DhanHQ::Configuration.new do |c|
+  c.client_id = "TENANT_CLIENT_ID"
+  c.access_token = "TENANT_ACCESS_TOKEN"
+  c.dry_run = true
+end
+
+client = DhanHQ::Client.new(config: custom_config)
+```
+
+Each client instance manages its own Faraday connection, isolated configuration, dry-run state, and instance-bound resource accessors (`client.orders`, `client.positions`, `client.market_feed`, etc.).
+
 For detailed authentication flows, see [AUTHENTICATION.md](AUTHENTICATION.md).
 
 ## Available Resources

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