DhanHQ 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa2811b4faf1f45f3ddc18b5f0b1ae03f481aa30fe48f1b1be3b3a928f87c581
-  data.tar.gz: cd4829e129d27e6b939bedaac18828f44237674ef5c84135ce9a647c4af37bcc
+  metadata.gz: 474564a108e478d3e2cc7bb0ad2b313a885b265ca3ece5091bd04dc1bb31b014
+  data.tar.gz: ab2a03010eb2ca03f7e6c9a01011b1b4b84f805611f22c55f7c2c07af1a7e063
 SHA512:
-  metadata.gz: 2b8fedf28da427de98161f6d2288230dc6e34a112bbfb56bda85d6373f0d2489cdfa8c2427facf0dc98e729790b4ee2023f534888f1b84989885993e9272545a
-  data.tar.gz: 11500ff76de75b2f9b9205e7f5af1210940291fe05b5c53b5f40d4f91e1a8d1c56346e8adb65c1fb2e2a36509b0c80f198f9264d402be8ced0622057fb288d64
+  metadata.gz: 531c7d4fba8e753c2371569a47562ed32cd026c8a2828e28bb7b617f5f342bec870ace4fac6f95b4e122b360c164c42a65a34a90899e2e100b18e7cc594ffea0
+  data.tar.gz: 82332825d24456beeb67b61836472c05047ff323c3826f2f8324ac06ae036c10e9324788a43e1e7dbdcc74fb60cdbc385aaf373d99d851bb6732c51f6bf7638b

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,50 @@
+## [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
 

data/docs/RELEASE_GUIDE.md

@@ -148,8 +148,9 @@ When you push a tag (e.g., `v2.1.12`), the **Release** workflow (`.github/workfl
 2. ✅ **Generate OTP code** from secret `RUBYGEMS_OTP_SECRET`
 3. ✅ **Build gem** using `gem build DhanHQ.gemspec`
 4. ✅ **Push to RubyGems** with OTP using `GEM_HOST_API_KEY` (from secret `RUBYGEMS_API_KEY`)
+5. ✅ **Attach gem to GitHub Release** — uploads `DhanHQ-<version>.gem` as a downloadable asset on the GitHub Release for the tag, creating the release (with auto-generated notes) if it doesn't already exist, or uploading to it if it does
 
-Tests run on push/PR via the main CI workflow; the release job does not run tests. No GitHub Release is created (tag-only publish, same pattern as ollama-client).
+Tests run on push/PR via the main CI workflow; the release job does not run tests. A GitHub Release page is created/updated with the built `.gem` attached as a downloadable asset (verified working on the real v3.1.0 release: https://github.com/shubhamtaywade82/dhanhq-client/releases/tag/v3.1.0).
 
 **No manual intervention needed!** ⚡
 
@@ -286,6 +287,16 @@ on:
    gem push "DhanHQ-${gem_version}.gem" --otp "$otp_code"
    ```
 
+5. **Attach gem to GitHub Release**
+   ```bash
+   # Creates the release (with --generate-notes) if it doesn't exist yet, else uploads to it
+   if gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+     gh release upload "$tag" "$gem_file" --repo "$GITHUB_REPOSITORY" --clobber
+   else
+     gh release create "$tag" "$gem_file" --repo "$GITHUB_REPOSITORY" --title "$tag" --generate-notes
+   fi
+   ```
+
 ### Security Features
 
 - 🔒 **MFA Required** - `rubygems_mfa_required = "true"` in gemspec
@@ -476,7 +487,7 @@ The old workflow (`.github/workflows/main.yml`):
 ✅ **MFA secured:** OTP authentication on every release
 ✅ **Production ready:** Battle-tested release workflow
 ✅ **Tests integrated:** Ensures quality before release
-✅ **Tag-only release:** Same pattern as ollama-client; push tag `v*` to publish
+✅ **Tag-triggered release:** push tag `v*` to publish to RubyGems and attach the built gem to a GitHub Release
 
 Questions or issues? Check the [Troubleshooting](#troubleshooting) section above.
 

data/docs/STANDALONE_RUBY_WEBSOCKET_INTEGRATION.md

@@ -996,8 +996,8 @@ class MarketDataCLI
       volume: full[:vol],
       day_high: full[:day_high],
       day_low: full[:day_low],
-      open: full[:open],
-      close: full[:close],
+      open: full[:day_open],
+      close: full[:day_close],
       timestamp: timestamp.iso8601
     }