DhanHQ 3.1.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa2811b4faf1f45f3ddc18b5f0b1ae03f481aa30fe48f1b1be3b3a928f87c581
-  data.tar.gz: cd4829e129d27e6b939bedaac18828f44237674ef5c84135ce9a647c4af37bcc
+  metadata.gz: 287ad8c77adb3623574c0ee14102cfc3e88695168f75e1550a25dbbff9eb8508
+  data.tar.gz: a61b3f8e664f45f203b1afc3f840c9ed62a4e3c40e2f2d17fedc080ac682e029
 SHA512:
-  metadata.gz: 2b8fedf28da427de98161f6d2288230dc6e34a112bbfb56bda85d6373f0d2489cdfa8c2427facf0dc98e729790b4ee2023f534888f1b84989885993e9272545a
-  data.tar.gz: 11500ff76de75b2f9b9205e7f5af1210940291fe05b5c53b5f40d4f91e1a8d1c56346e8adb65c1fb2e2a36509b0c80f198f9264d402be8ced0622057fb288d64
+  metadata.gz: 2c9ad1a3df906b585b0308809fb75235cf475a23c4eaddfea3f699de2e577819a1b78315b60012b6c51bb6c398dcaa35daab31d9ae9452d81d84e3e76741f0a9
+  data.tar.gz: 888e390276144b239a1bdd43afb9e77b58d21703587b898497b2426b8b78b47c7e03fd607bb3306fea49f9c2ae0e04a11ccb1b6968fc109fe61a8d2627b750a4

data/ARCHITECTURE.md

@@ -32,6 +32,11 @@ This document describes the architecture of the DhanHQ v2 API client gem: layers
 │  → Dry::Validation, shared macros in BaseContract               │
 ├─────────────────────────────────────────────────────────────────┤
 │  WebSocket (WS::*) — separate subsystem                         │
+├─────────────────────────────────────────────────────────────────┤
+│  AI / Agent layer (Agent, Skills, Risk, MCP) — separate subsystem│
+│  MCP server (JSON-RPC over stdio) → Agent::ToolRegistry          │
+│  → primitive tools (Models) + skill tools (Skills::Registry)     │
+│  → gated by Agent::Policy + Risk::Pipeline before any order      │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -45,12 +50,20 @@ This document describes the architecture of the DhanHQ v2 API client gem: layers
 | `core/` | Base abstractions | BaseAPI (HTTP verbs, path building, param formatting), BaseModel (attributes, resource, validation, CRUD helpers), BaseResource (CRUD on BaseAPI), AuthAPI, ErrorHandler |
 | `helpers/` | Cross-cutting | APIHelper, AttributeHelper (keys, normalization), ValidationHelper (validate_params!, validate!), RequestHelper (headers, payload, build_from_response), ResponseHelper (parse_json, handle_response, error mapping) |
 | `models/` | Domain / facade | Typed wrappers (Order, Position, Holding, etc.). Define `resource`, optional `validation_contract`, and domain methods. Validate then delegate to resource. |
+| `models/global_stocks/`, `resources/global_stocks/` | US equities book | DhanHQ's Global Stocks API (`/v2/globalstocks/*`) — its own Order, Trade, Holding, Funds (USD), Margin, OrderEstimate and MarketStatus. Namespaced so a USD position is never mistaken for an INR one. Orders here have no exchange segment / product type / validity, quantity is a float (fractional shares), and `AMOUNT` adds notional orders. The India-specific `Risk::Pipeline` does not apply. |
 | `resources/` | REST wrappers | One class per API surface (Orders, Positions, MarketFeed, OptionChain, …). Set `HTTP_PATH`, `API_TYPE`; implement get/post/put/delete via BaseAPI. |
 | `contracts/` | Request/response validation | Dry::Validation contracts (PlaceOrderContract, ModifyOrderContract, OptionChainContract, etc.). BaseContract provides shared macros (e.g. lot_size, tick_size). |
 | `auth/` | Token lifecycle | Token generator/renewal/manager for dynamic tokens. |
 | `concerns/` | Shared behavior | Modules included across layers (e.g. `OrderAudit` for live trading guard + audit logging, included in all order resources). |
 | `utils/` | Utilities | Cross-cutting utilities not tied to a single layer (e.g. `NetworkInspector` for IP/hostname/env lookup used by order audit logging). |
+| `dry_run/`, `write_paths.rb` | Write-path collaborators | `WritePaths` classifies a request as mutating / order-placing; `DryRun::Simulator` answers mutating requests locally and `DryRun::Ledger` remembers simulated orders so the models' refetch resolves without a live call. Extracted from `Client`, which was accumulating HTTP, auth retry, transient retry, rate limiting, path taxonomy and simulation. |
 | `ws/` | WebSocket | Connection, packets, decoder, market depth, orders client — isolated from REST. |
+| `mcp/` | MCP server | `DhanHQ::MCP::Server` — hand-rolled JSON-RPC 2.0 stdio server. Exposes `tools/list`, `tools/call`, `resources/*`, `prompts/*` to any MCP client (Claude Desktop, Claude Code, etc.). Launched via `exe/dhanhq-mcp`. |
+| `agent/` | AI tool registry | `Agent::ToolRegistry` — 12 domestic primitives (`dhan_profile`, `dhan_place_order`, …), 9 Global Stocks / basket tools (`dhan_global_*`, `dhan_multi_order`), plus one `dhan_skill_*` tool per registered `Skills::Registry` entry (32 total). `Agent::Policy` gates every call by scope + `LIVE_TRADING`/`DHANHQ_MCP_ENABLE_WRITES`. `Agent::OrderPreview` validates without submitting. |
+| `skills/` | Composable strategies | `Skills::Base` DSL (`param`, `step`, `risk`, `scope`, `description`) + `Skills::Registry`. 11 builtin skills (`iron_condor`, `straddle`, `strangle`, `buy_atm_call`, `covered_call`, `protective_put`, `bull_put_spread`, `bear_call_spread`, `square_off_all`, `square_off_position`, `market_data_summarizer`) under `skills/builtin/`. |
+| `risk/` | Pre-trade risk gate | `Risk::Pipeline.run!` — runs `TradingPermission`, `AsmGsm`, `ProductSupport`, `OrderType`, `Quantity`, `MarketHours`, `PositionLimits`, `Concentration`, `Options` (options-only), `MaxLoss` (daily) under `risk/checks/`. Wired into every order-placing resource via `Concerns::OrderAudit#run_risk_checks!` and into the `dhan_place_order` MCP tool. |
+| `ai/` | LLM prompt helpers | `AI::PromptHelpers` — human-readable portfolio summaries and risk reports, consumed by the MCP server's `prompts/get`. |
+| `strategy/`, `market_data/`, `option_analytics/`, `events/` | Analysis modules | Strategy base class, market-data snapshot/OHLC types, option analytics (Black-Scholes, max pain), and typed event objects (`Events::Base`, `Events::Bus`). Zeitwerk-autoloaded like the rest of `DhanHQ::*` — distinct from the separate opt-in `lib/dhanhq/analysis` and `lib/dhanhq/ta` modules (lowercase namespace, require explicitly; see [3.0.0] in CHANGELOG.md). |
 
 ---
 
@@ -96,13 +109,46 @@ So: **Models → Resources → Client**; **Contracts** are used by Models (and o
 
 - Credentials and URLs live in `DhanHQ::Configuration` (access_token, client_id, base_url, sandbox, optional access_token_provider).
 - `DhanHQ.configure { }`, `configure_with_env`, and `configure_from_token_endpoint` set configuration. Never hardcode credentials; use env vars or token endpoint.
+- Write-path behaviour is also configuration: `dry_run`, `retry_non_idempotent_writes`, `auto_correlation_id` (see below).
+
+---
+
+## Write-path safety
+
+The distinction that matters on this API is **mutating vs read-only**, not GET vs POST — the
+option chain, market feed, historical charts and margin calculators are all read-only POSTs.
+`Constants::MUTATING_PATH_PREFIXES` names the paths whose non-GET requests actually change
+account state, and `ORDER_PLACEMENT_PATH_PREFIXES` narrows that to order creation.
+`DhanHQ::WritePaths` wraps those lists as predicates so `Client` does not carry the taxonomy
+itself. Two behaviours key off it:
+
+- **Dry run** (`config.dry_run`): `DryRun::Simulator` logs mutating requests and answers them
+  locally; reads still hit the API, so a strategy can be rehearsed against live prices.
+  Because the models place-then-refetch, each simulated placement is recorded in
+  `DryRun::Ledger` and reads for a `DRYRUN-…` id are replayed from it — otherwise the refetch
+  would carry a fabricated id to the live API. Responses are shaped per endpoint family: a
+  placement needs an `orderId` for the models to treat it as successful, and the basket
+  endpoint needs a per-leg `orders` array.
+- **Retry gating**: the API has no idempotency key, so a `POST /v2/orders` that times out may
+  already have reached the exchange. Mutating writes are therefore **not** auto-retried by
+  default (`config.retry_non_idempotent_writes`), while reads keep their exponential backoff.
+  `config.auto_correlation_id` fills in a `correlationId` so a caller can reconcile a timed-out
+  placement through `GET /v2/orders/external/{correlation-id}`.
 
 ---
 
 ## WebSocket (WS)
 
 - Separate subsystem under `DhanHQ::WS`: own connection, packet types, decoder, market depth, orders client.
-- Shares configuration (e.g. access token) but not the REST Client or Resources. Documented in code and specs; not expanded here.
+- Shares configuration (e.g. access token) but not the REST Client or Resources.
+- `WS::Connection` owns the socket, the reconnect loop with backoff, and subscription replay:
+  the server keeps no subscription state across connections, so `SubState`'s snapshot is
+  re-sent on every new session. It reports lifecycle transitions to its owner through an
+  `on_event` callable rather than knowing about callbacks itself.
+- `WS::Client` bridges those transitions onto its public callback bus (`:open`, `:reconnect`,
+  `:close`, `:error`, plus decoded `:tick`s) and maintains health counters — `last_message_at`,
+  `reconnect_count`, `healthy?`, `health`. Frame arrival is tracked separately from socket
+  state because a feed can stay connected while the server stops publishing.
 
 ---
 

data/CHANGELOG.md

@@ -1,3 +1,76 @@
+## [3.2.1] - 2026-07-26
+
+### Fixed
+
+- **Restored the Claude Agent Skill pack to the published gem.** Switching `spec.files` from a reject-list to an allowlist in 3.2.0 stripped 51 MB of junk (a 36 MB core dump and a 17 MB `diagram.html`), but it also dropped `skills/dhanhq-ruby/` — 28 files, 164 KB: `SKILL.md` and its trigger frontmatter, 12 reference guides, 11 examples and 4 helper scripts. That pack is product content, added deliberately in #41. No Ruby code loads it at runtime, so nothing broke and no spec noticed; users installing 3.2.0 simply stopped receiving it. `CODE_OF_CONDUCT.md` and `AGENTS.md` are restored alongside it.
+
+  Unaffected and still shipped throughout: the MCP server (`lib/DhanHQ/mcp/`, `exe/dhanhq-mcp`), the agent tool layer (all 32 tools), the Ruby skills classes (`lib/DhanHQ/skills/`, 11 builtin skills), the risk pipeline and the WebSocket subsystem.
+
+  Gem size: 3.1.0 was 5.9 MB, 3.2.0 was 292 KB, and this is 324 KB. The 20× reduction is real and almost entirely the core dump; the skill pack was collateral.
+- **`DhanHQ::AI` was unreachable on a bare `require "dhan_hq"`.** The Zeitwerk inflector had no `ai → AI` acronym, so it looked for `DhanHQ::Ai` while `ai.rb` defines `DhanHQ::AI`; both spellings raised `NameError`. The documented `DhanHQ::AI::PromptHelpers` and `DhanHQ::AI::ContextBuilder` entry points therefore only worked if something had already loaded the file by hand, which only `mcp/server.rb` did. Found while writing the first specs for that module.
+
+### Added
+
+- **`spec/dhan_hq/gem_packaging_spec.rb`** — pins both ends of what ships, since packaging has now failed in both directions. Asserts the entry point, both executables, RBS signatures, Rails initializer, MCP server, agent tool layer, Ruby skills and the Claude Skill pack are all present; asserts the known junk, any crash dump, the spec suite and development config are all absent; and caps the uncompressed payload at 3 MB so a stray binary fails loudly rather than silently adding megabytes to a release.
+- First specs for `AI::PromptHelpers` (13 examples), covering portfolio summaries, the risk report's P&L arithmetic — summed across every position, counted only for open ones — and order confirmation rendering. Built on real model instances rather than doubles, because `BaseModel` defines attribute readers per instance and `instance_double` cannot verify them.
+- Specs for the lazily-built connection (not opened on construction, memoised, rebuilt on a base-URL change) and for retry exhaustion (transport errors translated, SDK errors re-raised unchanged, reads still retried).
+
+### Changed
+
+- **`Client#with_transient_retry` no longer duplicates its retry branch.** It had two rescue clauses running near-identical backoff-log-sleep-retry logic, differing only in what they raised once retries were spent. Collapsed into one clause, with an `exhausted_error` helper naming the difference: Faraday's transport errors are translated to `DhanHQ::NetworkError` (they are not part of this gem's hierarchy, so a caller rescuing `DhanHQ::Error` would otherwise miss them), while the gem's own errors are re-raised unchanged. Clears the `Lint/DuplicateBranch` pressure on this method.
+- **`Client#initialize` no longer opens a connection.** It now establishes state and checks its one invariant; the Faraday connection is built on first use of `#connection` and rebuilt when the configured base URL changes. Behaviour is unchanged for callers — `#connection` is still public and still reflects a sandbox toggle mid-process — but constructing a client does no network setup.
+- **`Naming/PredicateMethod` is now scoped by method name instead of by file.** Seven file-level exclusions replaced with `AllowedMethods: [cancel, modify, destroy]` plus `AllowBangMethods: true`.
+
+  These are commands that report whether they succeeded, not predicates — `cancel?` would read as "should I cancel?", which is worse than the name it replaces, so adding `?` aliases would have been the wrong fix. The unambiguous-failure path for them is the bang variant (`cancel!`, `modify!`). Scoping by name rather than by file also means a genuinely mis-named predicate elsewhere in those same files is still caught, and it surfaced a now-redundant inline `rubocop:disable` in `risk/pipeline.rb`.
+- `AI::PromptHelpers.portfolio_summary` computed the open-position set twice (`count(&:open?)` then `select(&:open?)`); it now derives it once. Both it and `.risk_report` wrap their collections in `Array()`, so a nil from a failed fetch renders an empty section instead of raising from inside a prompt helper — `funds` was already guarded, the collections were not.
+
+## [3.2.0] - 2026-07-25
+
+### Added
+
+- **Global Stocks (US equities) API** — full coverage of the 11 `/v2/globalstocks/*` endpoints, previously absent:
+  - Resources: `Resources::GlobalStocks::Orders` (place/modify/cancel/find/all), `Trades` (all + by security id), `Holdings`, `Funds`, `MarginCalculator` (margin + charge estimate), `MarketStatus`.
+  - Models: `Models::GlobalStocks::Order`, `Trade`, `Holding`, `Funds`, `Margin`, `OrderEstimate`, `MarketStatus`.
+  - Contracts: `GlobalStocksPlaceOrderContract`, `GlobalStocksModifyOrderContract`, `GlobalStocksEstimatorContract`.
+  - Namespaced under `GlobalStocks` so a USD position can never be mistaken for an INR one.
+  - Handles the ways this book differs from domestic trading: no exchange segment / product type / validity on orders, float quantities (fractional shares), and the `AMOUNT` notional order type. `MarginCalculator` renders `price`/`quantity` as the strings the API documents while validating them as numbers.
+  - Writes are gated by `LIVE_TRADING` and audit-logged like any other order path. `Risk::Pipeline` is deliberately not applied — its checks resolve instruments from the Indian scrip master and encode NSE/BSE rules.
+- **Multi Order (basket) endpoint** — `POST /v2/alerts/multi/orders` via `Resources::MultiOrders` and `Models::MultiOrder`, with `MultiOrderContract` enforcing the documented 15-leg cap, unique `sequence` values, and per-leg price/trigger rules. `MultiOrder` exposes `order_ids`, `accepted`, `rejected`, `all_accepted?`, `partially_accepted?` and `for_sequence` so partial acceptance is visible. Previously undocumented as missing — earlier feature tables claimed it was covered.
+- **SDK-level dry-run mode** — `config.dry_run` / `DHAN_DRY_RUN=true`. Suppresses every state-changing request (orders, position exits, kill switch, P&L exit, EDIS, IP setup), logs the full payload as `DHAN_DRY_RUN`, and answers order placements with a simulated `DRYRUN-…` order id so caller code paths run to completion. Reads — including read-only POSTs like the option chain, market feed, charts and margin calculators — still hit the API, so a full strategy can be rehearsed against live prices. Complements `Agent::OrderPreview`, which covers a single order.
+- **Correlation-id reconciliation** — `config.auto_correlation_id` / `DHAN_AUTO_CORRELATION_ID=true` fills in a `correlationId` (`dhq-<hex>`) on order placements that lack one, so a timed-out placement can be resolved through `GET /v2/orders/external/{correlation-id}`. Off by default because it changes the request body; an explicit correlation id is always preserved.
+- **WebSocket lifecycle hooks** — `WS::Client#on` now emits `:open`, `:reconnect`, `:close` and `:error` in addition to `:tick`. `:reconnect` carries `{ attempt:, resubscribed: }` so callers can re-seed derived state (candle builders, caches) after a gap and see which instruments were restored. `WS::Connection` reports transitions through a new `on_event:` callable.
+- **WebSocket health checks** — `WS::Client#last_message_at`, `#seconds_since_last_message`, `#healthy?(stale_after: 45)`, `#connected_at`, `#reconnect_count`, `#subscriptions` and `#health`, for monitoring long-running daemons. Frame arrival is tracked separately from socket state because a feed can stay connected while the server stops publishing.
+- **9 new agent/MCP tools** (32 total) — `dhan_global_holdings`, `dhan_global_funds`, `dhan_global_orders`, `dhan_global_trades`, `dhan_global_market_status`, `dhan_global_order_estimate` (combines charges and margin in one call), `dhan_global_place_order`, `dhan_global_cancel_order`, `dhan_multi_order`. Each gated by `Agent::Policy` on the same scopes and risk levels as the domestic equivalents.
+- **Global Stocks constants** — `Constants::ExchangeSegment::INX_EQ` (kept out of `ALL` so it can never satisfy a domestic order contract) plus `Constants::GlobalStocks` with the `AMOUNT` order type, feed limits (segment code 14, 100 instruments per frame, 5,000 per connection, 5 connections per client), market-status values and feed message codes. `Urls::WS_GLOBAL_STOCKS_FEED` added.
+- **Mutating-path constants** — `Constants::MUTATING_PATH_PREFIXES` and `ORDER_PLACEMENT_PATH_PREFIXES` distinguish real writes from the API's several read-only POSTs, driving both dry-run and retry gating.
+- **`DhanHQ::WritePaths`** — path taxonomy (`mutating?`, `order_placement?`, `multi_order?`) extracted out of `Client`, which no longer needs to know it.
+- **`DhanHQ::DryRun::Simulator` and `::Ledger`** — the dry-run concern extracted out of `Client` as collaborators. The ledger retains up to 500 simulated orders per process, evicting oldest first.
+- **`AttributeHelper#deep_camelize_keys`** — recursive key camelization for the endpoints whose bodies nest objects (basket order legs, alert conditions).
+
+### Changed
+
+- **The published gem shrank from 52.5 MB to 1.15 MB.** Four tracked files nobody intended to ship were being published: `core` (a 36.5 MB ELF core dump from an unrelated `light-locker` process), `diagram.html` (17.3 MB), `TAGS`, and `watchlist.csv` — 51.3 MB of the payload, so every `gem install DhanHQ` downloaded a stranger's crash dump. They entered via `f46fde1 "Squashed commit"` and `.gitignore` matched none of them. Removed from tracking, `.gitignore` patterns added, and `spec.files` switched from a reject-list to an explicit allowlist so an unanticipated artifact cannot leak into a release again. All 217 `lib/` files and both executables are unchanged. (The blobs remain in git history; shrinking clones would need a separate history rewrite.)
+- **Non-idempotent writes are no longer auto-retried** (behaviour change). `Client#with_transient_retry` previously retried order placement, modification and cancellation on 429s, 5xxs and network timeouts. The DhanHQ API has no idempotency key, so a `POST /v2/orders` that timed out may already have reached the exchange — retrying it could place a second, real order. Transient failures on mutating paths now raise to the caller, who can reconcile before resubmitting. Reads and read-only POSTs keep their exponential backoff unchanged. Set `config.retry_non_idempotent_writes = true` (or `DHAN_RETRY_WRITES=true`) to restore the old behaviour, accepting the duplicate risk.
+- `WS::Connection#initialize` accepts an optional `on_event:` keyword; the socket-open handling moved into a `handle_open` method.
+- `Configuration` reads boolean env vars through a shared helper, so an empty value is treated as unset rather than false.
+- README, ARCHITECTURE.md and CLAUDE.md document the Global Stocks book, basket orders, dry-run mode, write-path safety, and the WebSocket hooks and health API. The "Indian markets only" rule is restated as "DhanHQ v2 API only" — Delta Exchange and other brokers stay out, while DhanHQ's own Global Stocks surface is in scope.
+- **`ToolCatalogue.tool` takes keyword arguments.** It had nine positional-and-keyword parameters, so a transposed `scope` and `risk` would have produced a silently mis-gated tool, and it needed an inline `rubocop:disable Metrics/ParameterLists`. Now keyword-only with a `**attributes` splat: an unknown attribute raises rather than half-building a tool, the repeated `version: "1.0.0"` is gone from all 21 definitions in favour of a default, and the inline suppression is removed. Verified by diffing the full 32-tool metadata dump before and after — byte-for-byte identical.
+- `.rubocop_todo.yml` excludes `constants.rb` from `Metrics/ModuleLength` (a pure enumeration module whose line count tracks API coverage) and adds `models/global_stocks/order.rb` to the existing `Naming/PredicateMethod` exclusions, matching the domestic `Models::Order`.
+
+### Fixed
+
+- **Basket order legs were sent in snake_case.** `BaseAPI` camelizes only the top level of a payload, so the nested `orders` entries reached the API as `transaction_type`/`exchange_segment`/`security_id` instead of `transactionType`/`exchangeSegment`/`securityId` — every basket order placed through the wrapper would have been rejected. Added `AttributeHelper#deep_camelize_keys` and applied it to the legs. Caught in review by Codex; the original spec only asserted top-level keys, which is why it passed.
+- **The same bug pre-existed in alert orders.** `Models::AlertOrder.create` and `.modify` shallow-camelized a payload whose `condition` and `orders` are nested objects, so `AlertCondition` fields (`comparisonType`, `securityId`, `timeFrame`, …) went out snake_cased. Now uses `deep_camelize_keys`.
+- **Dry run did not work through the model APIs.** `Models::Order.place` and `GlobalStocks::Order.place` re-fetch after placing, so a simulated `DRYRUN-…` id was carried into a live `GET /v2/orders/{id}` — a real network call and a guaranteed miss. `MultiOrder.place` received no `orders` array and returned an `ErrorObject`. Dry run therefore only worked for direct `Client#request` calls, contradicting the "rehearse a full strategy" claim. Fixed by extracting `DryRun::Simulator` and `DryRun::Ledger`: placements are recorded, reads for a `DRYRUN-` id are replayed locally, and the basket endpoint gets a per-leg response. Caught in review by Codex.
+- **`dhanClientId` was never injected for alert orders.** `PAYLOAD_REQUIRES_DHAN_CLIENT_ID_PREFIXES` listed `/alerts/orders`, but `Resources::AlertOrders` uses `HTTP_PATH = "/v2/alerts/orders"`, so the `start_with?` check never matched and the field the API documents as **required** was omitted from every conditional-order payload unless the caller passed it explicitly. Fixed by adding the versioned `/v2/alerts` prefix, which also covers the new multi-order path.
+- `DhanHQ::NetworkError` no longer reports "Request failed after 0 retries" when retries are disabled.
+
+### Tests
+
+- 1,052 examples, 0 failures (up from 833); RuboCop clean.
+- New specs for the review fixes: nested leg camelization on the wire, dry run completing through `Order.place` / `GlobalStocks::Order.place` / `MultiOrder.place` with zero network calls, `DryRun::Simulator` response shaping and read replay, `DryRun::Ledger` eviction, and `WritePaths` classification (including that read-only POSTs are not treated as writes).
+- New specs: Global Stocks resources (orders, holdings, funds, trades, market status, margin calculator) and models (order, holding, funds, trade, market status, margin, order estimate); `MultiOrder`; `Client` dry-run, retry gating and correlation-id behaviour; `WS::Client` lifecycle hooks and health tracking; `WS::Connection` subscription replay and reconnect reporting; agent tool registration and policy enforcement for the new tools; constants and configuration coverage for the new flags and path lists.
+
 ## [3.1.0] - 2026-07-20
 
 ### Added

data/README.md

@@ -117,7 +117,11 @@ For the full dependency flow and extension pattern, see [ARCHITECTURE.md](ARCHIT
 - **Instrument convenience methods** — `.ltp`, `.ohlc`, `.option_chain` directly on instruments
 - **Order audit logging** — every order attempt logs machine, IP, environment, and correlation ID as structured JSON
 - **Live trading guard** — prevents accidental order placement unless `ENV["LIVE_TRADING"]="true"`
-- **Full REST coverage** — Orders, Trades, Forever Orders, Super Orders, Positions, Holdings, Funds, HistoricalData, OptionChain, MarketFeed, EDIS, Kill Switch, P&L Exit, Alert Orders, Margin Calculator
+- **Dry-run mode** — `config.dry_run = true` validates and logs every write while reads stay live, so a full strategy can be rehearsed against real prices
+- **No duplicate orders on retry** — transient failures on order writes are surfaced, not blindly retried
+- **Global Stocks (US equities)** — separate order book, holdings, trades, USD funds, market status, charge estimator and margin calculator
+- **Basket orders** — up to 15 orders in a single request, with per-leg acceptance results
+- **Full REST coverage** — Orders, Trades, Forever Orders, Super Orders, Multi (basket) Orders, Positions, Holdings, Funds, HistoricalData, OptionChain, MarketFeed, EDIS, Kill Switch, P&L Exit, Alert Orders, Margin Calculator, IP Setup, Global Stocks
 - **P&L Based Exit** — automatic position exit on profit/loss thresholds
 - **Postback parser** — parse Dhan webhook payloads with `Postback.parse` and status predicates
 - **EDIS model** — ORM-style T-PIN, form, and status inquiry for delivery instruction slips
@@ -127,10 +131,12 @@ For the full dependency flow and extension pattern, see [ARCHITECTURE.md](ARCHIT
 ## Reliability & Safety
 
 - retry-on-401 with token refresh
-- WebSocket auto-reconnect and backoff
+- WebSocket auto-reconnect, backoff, and automatic re-subscription
 - 429 rate-limit protection
 - live trading guard via `LIVE_TRADING=true`
 - structured order audit logs
+- dry-run mode via `DHAN_DRY_RUN=true`
+- order writes are never silently retried, so a timeout cannot become two orders
 
 See [ARCHITECTURE.md](ARCHITECTURE.md), [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md), and [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for the deeper implementation details.
 
@@ -219,6 +225,95 @@ LIVE_TRADING=false   # or simply omit
 
 Attempting to place an order without `LIVE_TRADING=true` raises `DhanHQ::LiveTradingDisabledError`.
 
+### Dry-Run Mode
+
+`dry_run` suppresses every request that would change account state — order placement,
+modification, cancellation, position exits, kill switch, P&L exit — while letting reads
+through untouched. Market data, the option chain, positions and holdings stay live, so a
+strategy can be rehearsed end-to-end against real prices without any risk of an order
+reaching the exchange.
+
+```ruby
+DhanHQ.configure do |config|
+  config.dry_run = true      # or DHAN_DRY_RUN=true
+end
+
+order = DhanHQ::Models::Order.place(
+  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
+)
+```
+
+Suppressed writes are logged at WARN level with the full payload, and order placements come
+back with a simulated `orderId` so downstream code paths run to completion:
+
+```json
+{ "event": "DHAN_DRY_RUN", "method": "POST", "path": "/v2/orders", "payload": { "…": "…" } }
+```
+
+Note that a POST is not automatically a write on this API: the option chain, market feed,
+historical charts and the margin calculators are read-only POSTs, and dry-run leaves them
+alone.
+
+This works through the high-level models too, not just `Client#request`. Because
+`Order.place` re-fetches after placing, the SDK records each simulated order and replays reads
+for its `DRYRUN-…` id locally — so a rehearsal issues no request for a fake order, and the
+model you get back carries the fields you submitted:
+
+```ruby
+order.order_id    # => "DRYRUN-9F7BEB55D0F9"
+order.security_id # => "11536"
+```
+
+`dry_run` complements `Agent::OrderPreview` — preview validates a single order and returns a
+summary, while `dry_run` covers every write path in the SDK, including skills and the MCP
+tools.
+
+### Order Retries and Duplicate Protection
+
+The DhanHQ API has no idempotency key. A `POST /v2/orders` that times out may well have
+reached the exchange, so retrying it can place a second, real order. By default this SDK
+therefore **does not** retry non-idempotent writes — the transient error is raised to you:
+
+```ruby
+begin
+  DhanHQ::Models::Order.place(...)
+rescue DhanHQ::NetworkError
+  # The order may or may not have been accepted. Reconcile before resubmitting.
+end
+```
+
+Reads, and read-only POSTs like the option chain, are still retried with exponential backoff.
+
+To reconcile after a timeout, place orders with a correlation id and look the order up by it:
+
+```ruby
+DhanHQ.configure do |config|
+  config.auto_correlation_id = true   # or DHAN_AUTO_CORRELATION_ID=true
+end
+```
+
+With this on, any order placement missing a `correlationId` gets one (`dhq-<hex>`), which you
+can then resolve via `GET /v2/orders/external/{correlation-id}`:
+
+```ruby
+DhanHQ::Resources::Orders.new.by_correlation("dhq-2f9c1a…")
+```
+
+It is off by default because it changes the request body, which would break callers that match
+recorded fixtures on the exact payload. An explicit `correlation_id` is always preserved.
+
+If you would rather have the old auto-retry behaviour, opt back in — accepting the duplicate
+risk:
+
+```ruby
+DhanHQ.configure { |config| config.retry_non_idempotent_writes = true }
+```
+
 ### Order Audit Logging
 
 Every order attempt (place, modify, slice) automatically logs a structured JSON line at WARN level:
@@ -342,6 +437,45 @@ DhanHQ::WS::MarketDepth.connect(symbols: [
 end
 ```
 
+### Lifecycle Hooks and Health Checks
+
+Subscriptions are restored automatically on reconnect — the server keeps no subscription state
+across connections, so the client replays the desired set on every new session. Hook `:reconnect`
+when you need to re-seed derived state (candle builders, caches) after a gap:
+
+```ruby
+client = DhanHQ::WS.connect(mode: :ticker) { |tick| handle(tick) }
+
+client.on(:open)      { |info| logger.info "feed open, #{info[:resubscribed].size} restored" }
+client.on(:reconnect) { |info| logger.warn "reconnect ##{info[:attempt]}"; candles.reset! }
+client.on(:close)     { |info| logger.warn "closed #{info[:code]} #{info[:reason]}" }
+client.on(:error)     { |message| logger.error message }
+```
+
+A feed can be connected and still be dead — the socket stays open while the server stops
+publishing. For long-running daemons, watch frame arrival rather than the socket alone:
+
+```ruby
+client.connected?                  # socket state
+client.healthy?                    # connected AND delivering frames (default: within 45s)
+client.healthy?(stale_after: 20)   # tighter threshold
+client.last_message_at             # Time of the most recent frame
+client.seconds_since_last_message
+client.reconnect_count
+client.subscriptions               # ["NSE_EQ:11536", …] — survives reconnects
+
+client.health
+# => { mode: :ticker, started: true, connected: true, healthy: true,
+#      connected_at: …, last_message_at: …, seconds_since_last_message: 0.4,
+#      reconnect_count: 2, subscription_count: 37 }
+```
+
+`health` is shaped for a monitoring endpoint or a periodic log line.
+
+> **Connection limit:** Dhan allows **5 concurrent WebSocket connections per client id**, with
+> 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.
+
 ### Cleanup
 
 ```ruby
@@ -373,6 +507,110 @@ DhanHQ::Models::SuperOrder.create(
 
 ---
 
+## Basket Orders (Multi Order)
+
+Place up to 15 unconditional orders in a single request. Each leg carries a `sequence` that
+identifies it in the response, so partial acceptance is visible:
+
+```ruby
+result = DhanHQ::Models::MultiOrder.place([
+  { sequence: "1", transaction_type: "BUY", exchange_segment: "NSE_EQ", product_type: "CNC",
+    order_type: "LIMIT", validity: "DAY", security_id: "11536", quantity: 1, price: 1500.0 },
+  { sequence: "2", transaction_type: "BUY", exchange_segment: "NSE_EQ", product_type: "CNC",
+    order_type: "MARKET", validity: "DAY", security_id: "1333", quantity: 2 }
+])
+
+result.all_accepted?              # => true
+result.order_ids                  # => ["112111182198", "112111182199"]
+result.rejected                   # legs the exchange refused
+result.partially_accepted?        # some in, some out
+result.for_sequence("1").order_id # look a leg up by its sequence
+```
+
+Every leg is validated before anything is sent, and each one gets its own audit log line.
+Requires `LIVE_TRADING=true` like any other order path.
+
+---
+
+## Global Stocks (US Equities)
+
+US stocks are a **separate book** from domestic NSE/BSE trading: their own order book,
+holdings, trades, and a USD fund limit. They are namespaced under `GlobalStocks` so a USD
+position can never be mistaken for an INR one.
+
+```ruby
+# Is the US market open?
+DhanHQ::Models::GlobalStocks::MarketStatus.fetch.open?
+
+# USD balance and portfolio
+DhanHQ::Models::GlobalStocks::Funds.fetch.available_cash
+DhanHQ::Models::GlobalStocks::Holding.all.each do |h|
+  puts "#{h.trading_symbol}: #{h.quantity} @ $#{h.avg_cost_price} (#{h.gain_percentage}%)"
+end
+DhanHQ::Models::GlobalStocks::Holding.total_current_value
+```
+
+### Placing US orders
+
+Global Stocks orders carry **no exchange segment, product type, or validity** — and quantity
+is a float, because fractional shares are supported:
+
+```ruby
+DhanHQ::Models::GlobalStocks::Order.place(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  order_type:       DhanHQ::Constants::GlobalStocks::OrderType::LIMIT,
+  security_id:      "AAPL",
+  quantity:         0.5,          # fractional shares
+  price:            180.0
+)
+```
+
+`AMOUNT` is a notional order type unique to this book — you name a dollar value instead of a
+share count:
+
+```ruby
+DhanHQ::Models::GlobalStocks::Order.place(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  order_type:       DhanHQ::Constants::GlobalStocks::OrderType::AMOUNT,
+  security_id:      "AAPL",
+  amount:           500.0         # buy $500 worth
+)
+```
+
+### Pre-trade checks
+
+```ruby
+params = { security_id: "AAPL", transaction_type: "BUY", price: 180.0, quantity: 10 }
+
+estimate = DhanHQ::Models::GlobalStocks::OrderEstimate.calculate(params)
+estimate.total_charges           # brokerage + exchange + GST + turnover + other
+
+margin = DhanHQ::Models::GlobalStocks::Margin.calculate(params)
+margin.sufficient?               # false when the account is short
+margin.total_margin
+```
+
+### Order and trade books
+
+```ruby
+DhanHQ::Models::GlobalStocks::Order.all              # today's US order book
+DhanHQ::Models::GlobalStocks::Order.find(order_id)
+DhanHQ::Models::GlobalStocks::Trade.all              # today's US fills
+DhanHQ::Models::GlobalStocks::Trade.find_by_security_id("AAPL")
+```
+
+Writes go through the same `LIVE_TRADING` gate, audit logging, and dry-run handling as
+domestic orders. The pre-trade `Risk::Pipeline` is deliberately **not** applied: its checks
+resolve instruments from the Indian scrip master and encode NSE/BSE rules (lot sizes, ASM/GSM
+surveillance, F&O product support, IST market hours), none of which apply to US equities. Use
+`Margin#sufficient?` and `OrderEstimate` as the pre-trade gate here instead.
+
+The Global Stocks live feed (`wss://global-stocks-api-feed.dhan.co`, segment `INX_EQ`, code
+`14`) is documented in `DhanHQ::Constants::GlobalStocks`; its binary packet decoder is not yet
+implemented.
+
+---
+
 ## Real-World Example: NIFTY Trend Monitor
 
 ```ruby
@@ -512,7 +750,7 @@ Claude Desktop config (`claude_desktop_config.json`):
 
 | Feature | Description |
 | ------- | ----------- |
-| **Tools** | 12 primitive tools (profile, funds, holdings, positions, order history, order preview/place/cancel, instruments, market feed) + 11 skill-derived tools (`dhan_skill_*` — one per builtin strategy in [Skills System](#skills-system) below) |
+| **Tools** | 32 total: 12 domestic primitives (profile, funds, holdings, positions, order history, order preview/place/cancel, instruments, market feed) + 9 Global Stocks and basket tools (`dhan_global_*`, `dhan_multi_order`) + 11 skill-derived tools (`dhan_skill_*` — one per builtin strategy in [Skills System](#skills-system) below) |
 | **Resources** | 6 URI-addressable data endpoints: `dhanhq://account/profile`, `dhanhq://account/funds`, `dhanhq://account/holdings`, `dhanhq://account/positions`, `dhanhq://account/orders`, `dhanhq://market/capabilities` |
 | **Prompts** | 5 pre-built AI prompts: `portfolio_summary`, `market_analysis`, `risk_report`, `order_preview`, `suggest_strategy` |
 

data/docs/AUTHENTICATION.md

@@ -54,7 +54,7 @@ If the token was **generated from Dhan Web** (not API key flow), you can refresh
 
 ```ruby
 # Returns a hash with API response (e.g. accessToken, expiryTime). Use the new token for subsequent requests.
-response = DhanHQ::Auth.renew_token(current_access_token, client_id)
+response = DhanHQ::Auth.renew_token(access_token: current_access_token, client_id: client_id)
 new_token = response["accessToken"] || response[:accessToken]
 # Optional: response may include "expiryTime"
 ```
@@ -68,7 +68,7 @@ Example: refresh in provider and cache the result until near expiry:
 config.access_token_provider = lambda do
   stored = YourTokenStore.current
   if stored.nil? || stored.expired_soon?
-    response = DhanHQ::Auth.renew_token(stored&.access_token || ENV["DHAN_ACCESS_TOKEN"], config.client_id)
+    response = DhanHQ::Auth.renew_token(access_token: stored&.access_token || ENV["DHAN_ACCESS_TOKEN"], client_id: config.client_id)
     YourTokenStore.update!(response["accessToken"], response["expiryTime"])
     stored = YourTokenStore.current
   end
@@ -219,6 +219,4 @@ Central service: configure_from_token_endpoint
 
 Fully automated: TOTP generate (Auth / Client#generate_access_token)
 
-Production-grade automation: enable_auto_token_management! (generate + renew)
-
-If you tell me your exact deployment style (single user box, multi-user SaaS, on-prem, etc.), I can tell you which one you should actually use and what to delete as overkill.
+Production-grade automation: enable_auto_token_management! (generate + renew)

data/docs/CONFIGURATION.md

@@ -9,7 +9,7 @@ require 'dhan_hq'
 DhanHQ.configure_with_env
 ```
 
-`configure_with_env` reads `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` from `ENV` and raises if either is missing.
+`configure_with_env` reads `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` from `ENV`. It does **not** raise if either is missing — they're simply left `nil`, and a `DhanHQ::AuthenticationError` (or similar) surfaces later, only when a request actually needs the token.
 
 ## Required Environment Variables
 
@@ -25,7 +25,8 @@ Set these _before_ calling `configure_with_env` to override defaults:
 | Variable                         | Default    | Description                                             |
 | -------------------------------- | ---------- | ------------------------------------------------------- |
 | `DHAN_LOG_LEVEL`                 | `INFO`     | Logger verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`)     |
-| `DHAN_BASE_URL`                  | Dhan prod  | Point REST calls to a different API hostname            |
+| `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     |
 | `DHAN_WS_ORDER_URL`              | Dhan prod  | Override the order update WebSocket endpoint            |
 | `DHAN_WS_USER_TYPE`              | `SELF`     | Switch between `SELF` and `PARTNER` streaming modes     |

data/docs/CONSTANTS_REFERENCE.md

@@ -17,8 +17,9 @@ Exchange segments for different markets and instruments.
 | `NSE_EQ` | `"NSE_EQ"` | NSE - Equity Cash | 1 |
 | `NSE_FNO` | `"NSE_FNO"` | NSE - Futures & Options | 2 |
 | `NSE_CURRENCY` | `"NSE_CURRENCY"` | NSE - Currency | 3 |
-| `BSE_EQ` | `"BSE_EQ"` | BSE - Equity Cash | 4 |
-| `MCX_COMM` | `"MCX_COMM"` | MCX - Commodity | 5 |
+| `NSE_COMM` | `"NSE_COMM"` | NSE - Commodity | 4 |
+| `BSE_EQ` | `"BSE_EQ"` | BSE - Equity Cash | 5 |
+| `MCX_COMM` | `"MCX_COMM"` | MCX - Commodity | 6 |
 | `BSE_CURRENCY` | `"BSE_CURRENCY"` | BSE - Currency | 7 |
 | `BSE_FNO` | `"BSE_FNO"` | BSE - Futures & Options | 8 |
 
@@ -431,7 +432,7 @@ end
 
 ### Validation Helpers
 
-Consider adding validation helpers:
+Already implemented in `lib/DhanHQ/constants.rb`:
 
 ```ruby
 module DhanHQ
@@ -439,7 +440,7 @@ module DhanHQ
     def self.valid?(module_name, value)
       const_get(module_name)::ALL.include?(value)
     end
-    
+
     def self.all_for(module_name)
       const_get(module_name)::ALL
     end

data/docs/ENDPOINTS_AND_SANDBOX.md

@@ -2,6 +2,7 @@
 
 ## Sandbox behavior
 
+- **Sandbox does NOT execute real order fills/matching.** Confirmed both via Dhan's own docs ("the sandbox behaves like the live API but does not execute real orders") and empirically: a `MARKET` order placed on sandbox validates and returns a real `orderId`, but stays at `PENDING` indefinitely — it never transitions to `TRADED`, even after 24+ seconds of polling. Use sandbox to validate request/response plumbing (auth, payload shape, error codes), not to test fill, cancel, or square-off behavior.
 - **REST:** When `DhanHQ.configuration.sandbox == true` (or `ENV["DHAN_SANDBOX"]=true`), the client uses `https://sandbox.dhan.co/v2` as the base URL for **all** requests that go through `DhanHQ::Client`. Every wrapped REST endpoint listed below is therefore **sent** to the sandbox host when sandbox is enabled.
 - **Sandbox does NOT support WebSocket.** Order updates, market feed, and market depth are **production-only**. The gem always uses production WebSocket URLs regardless of the `sandbox` setting. There are no sandbox WebSocket endpoints in the Dhan v2 API; do not rely on sandbox for real-time streams.
 - **Auth endpoints** (`DhanHQ::Auth`) do **not** use sandbox. They always call:

data/docs/LIVE_ORDER_UPDATES.md

@@ -320,24 +320,19 @@ This ensures safe usage in multi-threaded applications.
 
 ## Testing
 
-For comprehensive testing examples and interactive console helpers, see the [Testing Guide](TESTING_GUIDE.md). The guide includes:
+For comprehensive testing examples, see the [Testing Guide](TESTING_GUIDE.md). It covers:
 
 - **Order Update WebSocket Testing**: Complete examples for all order update features
 - **Event Handler Testing**: Examples for all event types
 - **Order State Management**: Testing order tracking and querying
-- **Interactive Console Helpers**: Load `bin/test_helpers.rb` for quick test functions
 
 **Quick start in console:**
 ```ruby
 # Start console
 bin/console
 
-# Load test helpers
-load 'bin/test_helpers.rb'
-
-# Test order WebSocket
-test_order_websocket(10)        # Test order updates for 10 seconds
-
-# Monitor specific order
-monitor_order("112111182045")   # Monitor order by ID
+# Test order WebSocket for 10 seconds
+client = DhanHQ::WS::Orders.connect { |update| puts update.inspect }
+sleep 10
+client.stop
 ```

data/docs/RAILS_INTEGRATION.md

@@ -122,7 +122,7 @@ end
 
 When the API returns 401 or token-expired (error code 807) and `access_token_provider` is set, the client retries the request **once** with a fresh token from the provider. `on_token_expired` is called before that retry so you can refresh your store if needed.
 
-**RenewToken (web-generated tokens only):** If the token was generated from Dhan Web (24h validity), you can refresh it with `DhanHQ::Auth.renew_token(access_token, client_id)` and store the result; use it in your provider or call it from `on_token_expired`. The gem does **not** implement API key/secret or Partner consent flows—implement those in your app and pass the token to the gem. See [docs/AUTHENTICATION.md](AUTHENTICATION.md).
+**RenewToken (web-generated tokens only):** If the token was generated from Dhan Web (24h validity), you can refresh it with `DhanHQ::Auth.renew_token(access_token: access_token, client_id: client_id)` (keyword arguments) and store the result; use it in your provider or call it from `on_token_expired`. The gem does **not** implement API key/secret or Partner consent flows—implement those in your app and pass the token to the gem. See [docs/AUTHENTICATION.md](AUTHENTICATION.md).
 
 ## 3. Build service objects for REST flows