DhanHQ 3.2.1 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 287ad8c77adb3623574c0ee14102cfc3e88695168f75e1550a25dbbff9eb8508
-  data.tar.gz: a61b3f8e664f45f203b1afc3f840c9ed62a4e3c40e2f2d17fedc080ac682e029
+  metadata.gz: 6d97f7473f5bb7c4968750c3e21e5721a9c9ba1261e6e00d450818613edb74ec
+  data.tar.gz: 49464e4909ac0f52947fc86735b6b43bef6877f8ba0a1f796eb3b1c58c60bfde
 SHA512:
-  metadata.gz: 2c9ad1a3df906b585b0308809fb75235cf475a23c4eaddfea3f699de2e577819a1b78315b60012b6c51bb6c398dcaa35daab31d9ae9452d81d84e3e76741f0a9
-  data.tar.gz: 888e390276144b239a1bdd43afb9e77b58d21703587b898497b2426b8b78b47c7e03fd607bb3306fea49f9c2ae0e04a11ccb1b6968fc109fe61a8d2627b750a4
+  metadata.gz: 5a70be1d7aa2af222df63e8188af1b60e110431d73ae36317244693d974e46a3fcb84a9a49d9276fbadeea105c1124753129aa1c057d089924f0b71c7075f481
+  data.tar.gz: cb8a910ad46ae08b570eb9b19ac3a553de9a050e1b2a409d1414f3eb18d7eb762cb2fc62d6f2a5a72ad9014f726a1195541fa29ea80d749ba4c1dc21d6b0903f

data/CHANGELOG.md

@@ -1,3 +1,79 @@
+## [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
+
+- **Bang variants for every write method with a falsy failure contract** — `Order.place!`, `Order#modify!`/`#cancel!`/`#refresh!`, `SuperOrder.create!`/`#modify!`/`#cancel!`, `ForeverOrder.create!`, `IcebergOrder.create!`, `TwapOrder.create!`, `AlertOrder.create!`/`.modify!`, `PnlExit.configure!`/`.stop!`, `MultiOrder.place!`, `GlobalStocks::Order.place!`/`#modify!`/`#cancel!`.
+
+  Each raises `DhanHQ::OrderError` — which descends from `DhanHQ::Error`, so an existing `rescue DhanHQ::Error` handler still catches it — carrying whatever diagnostics the failure held. The non-bang methods are **untouched**: they return exactly what they returned before, so no existing caller changes behaviour.
+
+  This is step one of unifying the write return contracts. Today those contracts disagree: depending on the class and the failure, a rejected write comes back as `nil`, as `false`, or as a `DhanHQ::ErrorObject`, and `AlertOrder.modify` can return either of the first two from the same method. A caller cannot write one error branch. Unifying them outright would be a silent breaking change for dependent applications, because `nil` and `false` are falsy while `ErrorObject` is truthy — every `if result` failure branch in a dependent would quietly invert. So the migration is staged:
+
+  1. **This release** — additive bang variants. Opt in per call site.
+  2. **This release** — log a deprecation whenever a non-bang write returns a falsy failure, to find the remaining call sites from dependents' logs.
+  3. **4.0.0** — non-bang methods return `ErrorObject` uniformly, gated on step 2 going quiet.
+
+- **Deprecation notices for ambiguous write failures** (step two). When a non-bang write returns `nil`, `false` or a `DhanHQ::ErrorObject`, the SDK now logs once per call site:
+
+  ```
+  [DhanHQ] DEPRECATION: DhanHQ::Models::Order.place reported failure as nil. Write
+  methods return nil, false or a DhanHQ::ErrorObject inconsistently today and will all
+  return DhanHQ::ErrorObject in 4.0.0, which is truthy — an `if result` failure branch
+  will invert. Use DhanHQ::Models::Order.place! to get a DhanHQ::OrderError instead...
+  ```
+
+  The point is to surface the remaining call sites from dependent applications' logs before 4.0.0 changes any return value. Once per call site per process, not once per failure — a session that rejects hundreds of orders would otherwise produce noise that gets filtered out, defeating the purpose.
+
+  This layer only observes: it never alters a return value and never raises. It is silent on success, silent when reached through a bang variant (those callers have already migrated), and silent when you set `config.warn_on_ambiguous_write_failure = false` / `DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false`. Defaults to on, because a notice nobody sees finds nothing.
+
+- **`DhanHQ::Concerns::TrackedWrites`** — installs the observation. Uses `prepend` rather than `include`, since the write methods are defined directly on the model classes and an included module would sit behind them in the ancestor chain and never be reached.
+- **`DhanHQ::Deprecation`** — once-per-key notice registry, thread-safe, with `warned_keys` and `reset!` for tests.
+- **`DhanHQ::WriteResult`** — puts the knowledge of what a write failure looks like in one place (`failure?`, `success?`, `unwrap!`). `BaseModel#save!` now uses it instead of duplicating the same three-way check inline.
+- **`DhanHQ::Concerns::BangWrites`** — generates the bang variants by delegating to their non-bang counterparts, so the two cannot drift: no duplicated request building, validation or logging. Generated as a module, so a hand-written `place!` can still override and call `super`.
+
+### Fixed
+
+- **`DhanHQ::MCP` was unreachable on a bare `require "dhan_hq"`.** Same failure as the `DhanHQ::AI` fix earlier in this release: `mcp.rb` defines `DhanHQ::MCP` while Zeitwerk's inflector expected `DhanHQ::Mcp` from the filename, so `DhanHQ::MCP::Server` raised `NameError` unless something had already loaded the file by hand — which only `exe/dhanhq-mcp` and `lib/dhan_hq/mcp.rb` did. Found the same way the `AI` bug was: cross-referencing every `DhanHQ::` constant named in the docs against what actually resolves. Guarded by a new `spec/dhan_hq/zeitwerk_autoload_spec.rb`, which shells out to a subprocess so the check can't be satisfied by another spec having already loaded the file by hand.
+- **`lib/DhanHQ/configuration.rb`'s doc comment referenced `DhanHQ::Models::Order.find_by_correlation_id`, which does not exist** — the real method is `.find_by_correlation` (no `_id` suffix). Caught during the same audit.
+- A documentation pass across the gem ahead of this release, cross-checking every code example and referenced class/method against the actual codebase:
+  - `docs/CONFIGURATION.md`'s resource table named `DhanHQ::Models::Fund` (real class: `Funds`) and `DhanHQ::Models::Ledger` (real class: `LedgerEntry`), and listed `fund_limit`/`margin_calculator` as `Funds` methods — neither exists; the real methods are `Funds.fetch`/`.balance` and `Margin.calculate`/`.calculate_multi`. The table now also covers the resources 3.2.0/3.3.0 added (Iceberg/TWAP/Alert orders, Multi Order, P&L Exit, eDIS, Global Stocks) and lists the `!` write variants.
+  - `docs/CONFIGURATION.md` was missing `LIVE_TRADING`, `DHAN_DRY_RUN`, `DHAN_RETRY_WRITES`, `DHAN_AUTO_CORRELATION_ID`, `DHAN_WARN_AMBIGUOUS_WRITE_FAILURE` and `DHAN_MARKET_DEPTH_LEVEL` entirely, and documented `DHAN_LOG_LEVEL` as if the library read it automatically — it doesn't; only the existing `## Logging` snippet wires it up.
+  - `skills/dhanhq-ruby/references/portfolio.md`'s eDIS section had the class name miscased (`EDIS` vs. `Edis`), called a nonexistent `.open_browser_for_tpin`, called `.inquiry` instead of `.inquire`, and accessed the (Hash) result via method calls instead of keys.
+  - `README.md` called `DhanHQ::Models::Fund.balance` — same class-name typo as above.
+  - `docs/RELEASE_GUIDE.md` claimed `Required Ruby: >= 3.1.0`; the gemspec has required `>= 3.2.0` since 3.0.0.
+  - `GUIDE.md` had no mention of the bang write variants added in this release; added a short section pointing to the README's fuller treatment.
+
+### Changed
+
+- `BaseModel#save!`'s exception message is now `"<Class>#save failed: <details>"` rather than `"Failed to save the record: <details>"`. The exception class is unchanged (`DhanHQ::Error`), and nothing in the gem, specs or docs asserted the old text.
+
 ## [3.2.1] - 2026-07-26
 
 ### Fixed

data/GUIDE.md

@@ -186,6 +186,22 @@ DhanHQ::Contracts::ModifyOrderContract.new.call(params).success?
 DhanHQ::Models::Order.resource.update("123", params)
 ```
 
+### Explicit Failures: Bang Variants
+
+`place`, `#modify`, `#cancel` and their equivalents across every write model do not agree on
+how they report failure — depending on the class, a rejected write comes back as `nil`,
+`false`, or a `DhanHQ::ErrorObject`. Each has a `!` variant that raises `DhanHQ::OrderError`
+instead, so one `rescue` handles every failure the same way:
+
+```ruby
+order = DhanHQ::Models::Order.place!(params)   # raises DhanHQ::OrderError on failure
+order.cancel!                                  # raises if the exchange did not cancel
+```
+
+The non-bang methods are unchanged — adopting the bang variant is opt-in, per call site.
+See the [README](README.md#explicit-failures-bang-variants) for the full list of `!` methods
+and the deprecation notice that flags remaining non-bang call sites ahead of 4.0.0.
+
 ### Slicing Orders
 
 Use the same fields as placement, but the contract allows additional validity options (`GTC`, `GTD`). The model helper accepts snake_case parameters and handles camelCase conversion as part of validation:

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)
@@ -314,6 +327,59 @@ risk:
 DhanHQ.configure { |config| config.retry_non_idempotent_writes = true }
 ```
 
+### Explicit Failures: Bang Variants
+
+Every write method has a `!` variant that raises instead of returning a falsy value:
+
+```ruby
+order = DhanHQ::Models::Order.place!(params)   # raises DhanHQ::OrderError on failure
+order.cancel!                                  # raises if the exchange did not cancel
+```
+
+This exists because the non-bang methods do not agree on how to report failure — some
+return `nil`, some `false`, some a `DhanHQ::ErrorObject` — so a caller cannot write one
+error branch:
+
+```ruby
+# Before: which falsy thing came back depends on which method and which failure
+order = DhanHQ::Models::Order.place(params)
+return unless order            # nil on rejection
+
+result = DhanHQ::Models::MultiOrder.place(legs)
+return if result.is_a?(DhanHQ::ErrorObject)   # truthy! `unless result` would not catch this
+```
+
+`DhanHQ::OrderError` descends from `DhanHQ::Error`, so an existing `rescue DhanHQ::Error`
+keeps working. The non-bang methods are unchanged, so adopting this is per call site:
+
+```ruby
+begin
+  DhanHQ::Models::Order.place!(params)
+rescue DhanHQ::OrderError => e
+  logger.error(e.message)   # carries the API's diagnostics
+end
+```
+
+When a non-bang write reports failure, the SDK logs once per call site to help you find
+what needs migrating before 4.0.0 changes the return value:
+
+```
+[DhanHQ] DEPRECATION: DhanHQ::Models::Order.place reported failure as nil. ...
+Use DhanHQ::Models::Order.place! to get a DhanHQ::OrderError instead, or set
+config.warn_on_ambiguous_write_failure = false to silence this.
+```
+
+It fires once per call site per process, never alters a return value, never raises, and
+goes quiet once you switch that site to the bang variant. To silence it entirely:
+
+```ruby
+DhanHQ.configure { |c| c.warn_on_ambiguous_write_failure = false }   # or DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false
+```
+
+Available on `Order`, `SuperOrder`, `ForeverOrder`, `IcebergOrder`, `TwapOrder`,
+`AlertOrder`, `PnlExit`, `MultiOrder` and `GlobalStocks::Order`. The non-bang methods are
+planned to converge on `ErrorObject` in 4.0.0 — see the CHANGELOG for the staged plan.
+
 ### Order Audit Logging
 
 Every order attempt (place, modify, slice) automatically logs a structured JSON line at WARN level:
@@ -374,7 +440,7 @@ order.cancel
 ```ruby
 DhanHQ::Models::Position.all
 DhanHQ::Models::Holding.all
-DhanHQ::Models::Fund.balance
+DhanHQ::Models::Funds.balance
 ```
 
 ### Historical Data
@@ -476,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
@@ -651,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).
 
 ---
 
@@ -690,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

@@ -24,7 +24,6 @@ Set these _before_ calling `configure_with_env` to override defaults:
 
 | Variable                         | Default    | Description                                             |
 | -------------------------------- | ---------- | ------------------------------------------------------- |
-| `DHAN_LOG_LEVEL`                 | `INFO`     | Logger verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`)     |
 | `DHAN_SANDBOX`                   | `false`    | Set `"true"` to route REST calls to `https://sandbox.dhan.co/v2` instead of production. Note: Dhan's sandbox validates request/response plumbing only — it does not execute real order fills/matching. Placed orders stay `PENDING` indefinitely. See [ENDPOINTS_AND_SANDBOX.md](ENDPOINTS_AND_SANDBOX.md). |
 | `DHAN_BASE_URL`                  | Dhan prod  | Point REST calls to a different API hostname. Takes precedence over `DHAN_SANDBOX` only when explicitly set to something other than the production default. |
 | `DHAN_WS_VERSION`                | latest     | Pin WebSocket connections to a specific API version     |
@@ -32,12 +31,28 @@ Set these _before_ calling `configure_with_env` to override defaults:
 | `DHAN_WS_USER_TYPE`              | `SELF`     | Switch between `SELF` and `PARTNER` streaming modes     |
 | `DHAN_PARTNER_ID`                | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
 | `DHAN_PARTNER_SECRET`            | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
+| `DHAN_MARKET_DEPTH_LEVEL`        | `20`       | WebSocket market depth levels to subscribe to           |
 | `DHAN_CONNECT_TIMEOUT`           | `10`       | Connection timeout in seconds                           |
 | `DHAN_READ_TIMEOUT`              | `30`       | Read timeout in seconds                                 |
 | `DHAN_WRITE_TIMEOUT`             | `30`       | Write timeout in seconds                                |
 | `DHAN_WS_MAX_TRACKED_ORDERS`     | `10000`    | Maximum orders to track in WebSocket                    |
 | `DHAN_WS_MAX_ORDER_AGE`          | `604800`   | Maximum order age in seconds before cleanup (7 days)    |
 
+`DHAN_LOG_LEVEL` is **not** read automatically — see [Logging](#logging) below for the one-line snippet that wires it up.
+
+## Behavior Flags
+
+These change what a write request *does*, not just where it goes. All default to the safe/conservative behavior and are off unless set.
+
+| Variable                             | Config attribute                    | Default | Effect |
+| ------------------------------------- | ------------------------------------ | ------- | ------ |
+| `LIVE_TRADING=true`                   | —                                    | unset   | **Required to place, modify, or cancel any real order, position exit, kill switch, EDIS, or P&L exit.** Without it, every write-path resource raises `DhanHQ::LiveTradingDisabledError` before making the request. This is the primary safety gate — see [ARCHITECTURE.md](../ARCHITECTURE.md) and the risk pipeline. |
+| `DHAN_DRY_RUN=true`                    | `config.dry_run`                     | `false` | Suppresses every state-changing request, logs the payload as `DHAN_DRY_RUN`, and answers order placements with a simulated `DRYRUN-…` id so caller code paths still run to completion. Reads still hit the API. |
+| `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
 
 Create a `.env` file in your project root:
@@ -95,16 +110,26 @@ For detailed authentication flows, see [AUTHENTICATION.md](AUTHENTICATION.md).
 
 ## Available Resources
 
-| Resource                 | Model                                  | Actions                                             |
-| ------------------------ | -------------------------------------- | --------------------------------------------------- |
-| Orders                   | `DhanHQ::Models::Order`                | `find`, `all`, `where`, `place`, `update`, `cancel` |
-| Trades                   | `DhanHQ::Models::Trade`                | `all`, `find_by_order_id`                           |
-| Forever Orders           | `DhanHQ::Models::ForeverOrder`         | `create`, `find`, `modify`, `cancel`, `all`         |
-| Holdings                 | `DhanHQ::Models::Holding`              | `all`                                               |
-| Positions                | `DhanHQ::Models::Position`             | `all`, `find`, `exit!`                              |
-| Funds & Margin           | `DhanHQ::Models::Fund`                 | `fund_limit`, `margin_calculator`                   |
-| Ledger                   | `DhanHQ::Models::Ledger`               | `all`                                               |
-| Market Feeds             | `DhanHQ::Models::MarketFeed`           | `ltp`, `ohlc`, `quote`                              |
-| Historical Data (Charts) | `DhanHQ::Models::HistoricalData`       | `daily`, `intraday`                                 |
-| Option Chain             | `DhanHQ::Models::OptionChain`          | `fetch`, `fetch_expiry_list`                        |
-| Super Orders             | `DhanHQ::Models::SuperOrder`           | `create`, `modify`, `cancel`, `all`                 |
+| Resource                 | Model                                   | Actions                                                                       |
+| ------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------ |
+| Orders                   | `DhanHQ::Models::Order`                 | `place`, `find`, `all`, `where`, `#modify`, `#cancel`, `#destroy` (`!` variants raise) |
+| Trades                   | `DhanHQ::Models::Trade`                 | `all`, `find_by_order_id`                                                     |
+| Forever Orders           | `DhanHQ::Models::ForeverOrder`          | `create`, `find`, `all`, `#modify`, `#cancel`                                 |
+| Iceberg Orders           | `DhanHQ::Models::IcebergOrder`          | `create`, `find`, `all`, `#modify`, `#cancel`                                 |
+| TWAP Orders              | `DhanHQ::Models::TwapOrder`             | `create`, `find`, `all`, `#modify`, `#cancel`                                 |
+| Alert Orders             | `DhanHQ::Models::AlertOrder`            | `create`, `find`, `all`, `modify(alert_id, params)`, `#destroy`               |
+| Super Orders             | `DhanHQ::Models::SuperOrder`            | `create`, `all`, `#modify`, `#cancel(leg_name)`                               |
+| Multi Order (basket)     | `DhanHQ::Models::MultiOrder`            | `place(orders, dhan_client_id:)` — up to 15 legs                              |
+| P&L Exit                 | `DhanHQ::Models::PnlExit`               | `configure`, `stop`, `status`                                                 |
+| Holdings                 | `DhanHQ::Models::Holding`               | `all`                                                                         |
+| Positions                | `DhanHQ::Models::Position`              | `all`, `active`, `#convert(params)`, `.exit_all!`                             |
+| Funds                    | `DhanHQ::Models::Funds`                 | `fetch`, `balance`                                                            |
+| Margin Calculator        | `DhanHQ::Models::Margin`                | `calculate(params)`, `calculate_multi(params)`                                |
+| Ledger                   | `DhanHQ::Models::LedgerEntry`           | `all(from_date:, to_date:)`                                                   |
+| eDIS                     | `DhanHQ::Models::Edis`                  | `generate_tpin`, `generate_form`, `generate_bulk_form`, `inquire(isin:)`      |
+| Market Feeds             | `DhanHQ::Models::MarketFeed`            | `ltp`, `ohlc`, `quote`                                                        |
+| Historical Data (Charts) | `DhanHQ::Models::HistoricalData`        | `daily`, `intraday`                                                           |
+| Option Chain             | `DhanHQ::Models::OptionChain`           | `fetch`, `fetch_expiry_list`                                                  |
+| Global Stocks Orders     | `DhanHQ::Models::GlobalStocks::Order`   | `place`, `find`, `all`, `#cancel` — see [ARCHITECTURE.md](../ARCHITECTURE.md) |
+
+`#method` denotes an instance method (called on a fetched or created record); everything else is a class method. Every write method above also has a `!` variant (`place!`, `#modify!`, `#cancel!`, …) that raises `DhanHQ::OrderError` instead of returning a falsy value or an `ErrorObject` — see the [CHANGELOG](../CHANGELOG.md) for the write-return-contract migration this is part of.

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/RELEASE_GUIDE.md

@@ -434,7 +434,7 @@ git push origin main v2.1.12
 
 - **Gem Name:** DhanHQ
 - **Current Version:** Check `lib/DhanHQ/version.rb`
-- **Required Ruby:** >= 3.1.0
+- **Required Ruby:** >= 3.2.0
 - **License:** MIT
 - **Homepage:** https://github.com/shubhamtaywade82/dhanhq-client
 

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