DhanHQ 3.4.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d97f7473f5bb7c4968750c3e21e5721a9c9ba1261e6e00d450818613edb74ec
-  data.tar.gz: 49464e4909ac0f52947fc86735b6b43bef6877f8ba0a1f796eb3b1c58c60bfde
+  metadata.gz: d79f2577f59f6c04874eb44e4d318e5584e711e205be25f6fa000053ec772846
+  data.tar.gz: dca8144795ab2b77700a3947512c04e73c8edcbaa287b74adb746e671158e583
 SHA512:
-  metadata.gz: 5a70be1d7aa2af222df63e8188af1b60e110431d73ae36317244693d974e46a3fcb84a9a49d9276fbadeea105c1124753129aa1c057d089924f0b71c7075f481
-  data.tar.gz: cb8a910ad46ae08b570eb9b19ac3a553de9a050e1b2a409d1414f3eb18d7eb762cb2fc62d6f2a5a72ad9014f726a1195541fa29ea80d749ba4c1dc21d6b0903f
+  metadata.gz: e5a38d2663377da284188dc32fd0e796394ee899a34b61d5f82b5a487b0a47477a9e6bc1c0fdfc0b7fa93959d8673e257a83b7eea1af1a48885526ecc506a89f
+  data.tar.gz: 3f2023c47fc5e5b1f6fcce29f704c2c4ac03ad887a91dbc0c33bba201a151e8f03793bdc736915a295e98a5e661810e6229e32b37ea11c09b977fbcbb1b1c5d3

data/CHANGELOG.md

@@ -1,3 +1,61 @@
+## [4.1.0] - 2026-10-10
+
+### Fixed (full-gem review pass — `ruby-agent-skills` audit)
+
+- **WebSocket feed request codes now match the official Annexure table** (`dhanhq.co/docs/v2/annexure#feed-request-code`). Market feed subscribe per mode: 15/17/21 (was 15 for all three); unsubscribe: 16/18/22 (was 12 for all — 12 is the whole-connection *Disconnect Feed* frame, so per-instrument unsubscribes most plausibly tore down the entire socket). Market depth unsubscribe: 24 (was 12; subscribe stays 23). New spec `spec/dhan_hq/ws/connection_spec.rb` asserts the mapping. **Caveat:** verified against the published table only — `wss://api-feed.dhan.co` is not reachable from the CI environment (geo-block outside India), so a one-constant revert is documented in the review notes if live testing disagrees.
+- **Error contract consistency.** `Models::Order#modify/#cancel/#refresh/#slice_order` and `WS::Client` initialization now raise typed errors (`DhanHQ::OrderError`, `DhanHQ::AuthenticationError`) instead of bare `RuntimeError`s, so callers rescuing `DhanHQ::Error` no longer miss guard-clause failures.
+- **`RateLimiter` cleanup threads** now spawn only for intervals with finite limits (was 3 immortal threads per tier — 18 in a typical process; now 0 for quote/non-trading, 1 for order/data/global, 3 for option chain). The misleading "matches the published rate-limit table" comment was corrected: values follow this repo's own documented operational limits; per-minute platform caps remain an open question (table unreachable — broken docs site).
+- **`WS::Registry`** is now mutex-synchronized (register/unregister/stop_all were unsynchronized) and logs swallowed `stop` failures at debug level instead of rescuing silently.
+- **`BaseModel` attribute accessors** are defined once per class instead of two singleton methods per attribute per instance (allocation-heavy on collections). Parameter key style dispatches through `BaseModel.param_key_style` (:title for OptionChain) instead of the fragile `class.name.include?("OptionChain")` check. `validate_attributes` no longer crashes when no contract is declared.
+- **Timeouts on the token-endpoint fetch** (`configure_from_token_endpoint` / `configure_from_dashboard`): bounded open/read timeouts matching `Client#build_connection`; previously the only unbounded HTTP path in the gem.
+- **Dead code removed:** `BaseAPI#request` (unused private), the commented-out `format_params`/`optionchain_api?` block in `AttributeHelper`, the commented `validate_params!` line in `BaseModel.create`, and the redundant `class Error` reopen in `lib/dhan_hq.rb` (already fully defined in `errors.rb`).
+- **Docs:** `docs/ENDPOINTS_AND_SANDBOX.md` no longer documents the non-existent `bin/call_all_endpoints.rb`; the smoke-testing section now references `bin/console`, the sandbox connectivity spec, and `bin/ws_feed_test.rb`. The `DHAN_DEBUG` `puts` in `RateLimiter` was replaced with `DhanHQ.logger&.debug`.
+
+### Added
+
+- **Environment modes — `config.mode = :live | :sandbox | :hybrid` (`DHAN_MODE`)** — one switch that decides which Dhan host every request hits. `:live` (default) keeps today's behaviour; `:sandbox` replaces the old all-or-nothing `sandbox = true` flag; and the new **`:hybrid`** mode is the strategy-rehearsal combination the docs site describes — **live market data + sandbox execution**: market feed, option chain, historical charts, instruments and ScanX keep hitting `https://api.dhan.co/v2` for real prices while orders, positions, funds, statements and the rest of the trading surface hit `https://sandbox.dhan.co/v2`, where orders are validated but never fill.
+
+  ```ruby
+  DhanHQ.configure do |config|
+    config.mode = :hybrid      # or DHAN_MODE=hybrid
+  end
+
+  client.market_feed.ltp("NSE_EQ" => [11536])  # -> api.dhan.co     (live prices)
+  client.orders.create(...)                    # -> sandbox.dhan.co (paper execution)
+  ```
+
+  - Resolution is per API tier (`order_api`, `data_api`, `quote_api`, `option_chain`, `non_trading_api`, `global_stocks_api`) via `Configuration#base_url_for(api_type)` / `#environment_for(api_type)`; the client rebuilds its Faraday connection when the resolved URL changes, so a mid-flight mode switch takes effect.
+  - `config.environment_overrides = { non_trading_api: :live }` (or `DHAN_ENV_OVERRIDES="non_trading_api=live"`) overrides any tier on top of the mode — e.g. keep real fund limits while everything else runs on the sandbox.
+  - `sandbox = true` / `DHAN_SANDBOX=true` remain supported aliases for `mode = :sandbox`; `mode` takes precedence when both are given. Unknown modes raise `ArgumentError` at configuration time, not on the first request.
+  - Per-client override: `DhanHQ::Client.new(config: shared, mode: :hybrid)` **forks** the configuration rather than mutating the shared/global one, so two clients can run different modes side by side.
+  - **Global Stocks (US equities) stays on production in `:hybrid`** on its own `global_stocks_api` rate-limit tier (same limits as order APIs) — `sandbox.dhan.co` does not mirror the `/v2/globalstocks/*` surface.
+- **Sandbox-aware LIVE_TRADING gate** — the `ENV["LIVE_TRADING"]` guard now applies only to writes whose effective target is production. Any write routed to the sandbox host (full `:sandbox`, or the trading tiers under `:hybrid`) skips the gate automatically, because no real money can move there. Every order-audit log line now also records `"target":"live"|"sandbox"`, so the audit trail shows which host each attempt fired at.
+- **ScanX data API — `client.scanx`** — wraps the four `/v2/data/*` endpoints from the official API surface, each validated by a dry-validation contract, riding the `data_api` tier (live in `:hybrid`):
+  - `#company_info` — `POST /v2/data/companyinfo`: company overview, valuation/profitability ratios and shareholding pattern (`metrics: %w[CO RATIOS SHP]`).
+  - `#market_movers` — `POST /v2/data/marketmovers`: top options/futures/stocks by OI, volume or price movement; the contract enforces the API's own rule that `expiry` is required for derivative instruments and `universe` for EQUITY.
+  - `#news_headlines` — `POST /v2/data/newsheadline`: live news by category/stock (limit 1–50); `dhanClientId` is injected automatically.
+  - `#technical_data` — `POST /v2/data/technical`: 24 server-side indicators (SMA/EMA families, RSI_14, MACD_HIST, STOCH, ATR_14, ADX_14, pivots…) computed on the latest closed candle.
+  - `/v2/data` joins the `client-id`-header prefixes so ScanX requests authenticate like the other data APIs.
+
+## [4.0.0] - 2026-08-31
+
+### Added
+
+- **Multi-Instance Client Isolation (`DhanHQ::Client.new`)** — run multiple isolated client instances in the same process with separate configurations, credentials, sandbox environments, and rate limiters. Ideal for multi-tenant applications, managing multiple trading accounts concurrently, or comparing sandbox vs. production environments side-by-side.
+  ```ruby
+  client_a = DhanHQ::Client.new(client_id: "ACC_A", access_token: "TOKEN_A")
+  client_b = DhanHQ::Client.new(client_id: "ACC_B", access_token: "TOKEN_B", sandbox: true)
+
+  orders_a = client_a.orders.all
+  orders_b = client_b.orders.all
+  ```
+- **Instance-bound Resource Accessors** — direct accessors on `DhanHQ::Client` instances (`client.orders`, `client.positions`, `client.holdings`, `client.funds`, `client.trades`, `client.market_feed`, `client.option_chain`, `client.historical_data`, `client.forever_orders`, `client.alert_orders`, `client.iceberg_orders`, `client.super_orders`, `client.twap_orders`, `client.statements`, `client.kill_switch`, `client.pnl_exit`, `client.trader_control`, `client.ip_setup`, `client.edis`) bound to that client's configuration and routed to matching rate-limiting tiers (`client_for(API_TYPE)`).
+- **Instance-bound WebSocket Helpers** — `client.ws_market_feed`, `client.ws_order_update`, and `client.ws_market_depth` configured automatically with the client instance's credentials and URLs.
+- **Keyword Argument Initialization** — `DhanHQ::Client.new` accepts keyword configuration parameters (`dry_run: true`, `sandbox: true`, `client_id: "..."`, `access_token: "..."`) or a `Configuration` instance.
+- **Per-Instance Dry-Run Mode** — `DhanHQ::Client.new(dry_run: true)` simulates state-changing writes locally for that instance regardless of the global configuration.
+- **Dynamic Model Resource Invalidation** — `DhanHQ.reset_model_resources!` automatically refreshes class-level model caches (`Models::Order.resource`, etc.) whenever `DhanHQ.configure`, `configure_with_env`, `configuration=`, or `reset_configuration!` is invoked.
+- **Per-Client Auto Token Management** — `client.enable_auto_token_management!(dhan_client_id: ..., pin: ..., totp_secret: ...)` for automated TOTP-based token lifecycle management per client instance.
+
 ## [3.4.0] - 2026-08-15
 
 ### Added
@@ -19,7 +77,9 @@
 ### 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.
+- **Every runtime dependency except `faraday` had no version floor at all** (`add_dependency "x"`, equivalent to `>= 0` — satisfied by any version ever published). Found while investigating whether the Ruby floor could drop to 3.1 (it can't — see below): forcing a fresh `bundle install` under Ruby 3.1.6 resolved `dry-validation` to `0.4.1`, a 2016-era, pre-`Dry::Validation::Contract` API generation every contract in `lib/DhanHQ/contracts/` is incompatible with — every contract spec failed at `require`-time. Pinning that alone wasn't enough: with `dry-validation` fixed, the same fresh resolve then pulled `activesupport` down to `7.2.3.2` (ActiveSupport 8.x itself requires Ruby ≥ 3.2), and AS 7-vs-8 behavioral differences broke `Agent::ToolRegistry`, `MCP::Server`, and `Risk::Pipeline` — 63 failures with no connection to Ruby version syntax at all.
+
+  All ten now have an explicit floor matching their currently locked major (`activesupport >= 8.0`, `dry-validation ~> 1.0`, and so on) — closing the class of bug, not just the two instances that happened to surface. The `dry-validation` constraint went through two attempts: the first pass in this same release pinned it to `~> 1.11`, which — because `~>` locks to the *last* segment given — actually meant `>= 1.11, < 1.12` and would have silently blocked every future 1.12+ release. Corrected to `~> 1.0`, which excludes the ancient `0.x` line (the actual problem) without capping legitimate 1.x updates.
 - **`spec/dhan_hq/contracts/expired_options_data_contract_spec.rb` and `expired_options_data_spec.rb` hardcoded `from_date: "2021-08-02"`**, which is itself now more than 5 years in the past and so failed the contract's own "cannot be more than 5 years ago" rule — the shared fixture failed the exact rule it existed to exercise, cascading into every test merged onto it. Replaced every literal 2021 date with one computed relative to `Date.today`, preserving each test's original intent (span length, ordering, the exact-31-day boundary).
 
 ### Investigated, not changed

data/GUIDE.md

@@ -57,6 +57,8 @@ Set any of the following environment variables _before_ calling
 
 | Variable                                  | Purpose                                              |
 | ----------------------------------------- | ---------------------------------------------------- |
+| `DHAN_MODE`                               | `live` (default), `sandbox`, or `hybrid` — see [Environments](#environments-live-sandbox-hybrid) below. |
+| `DHAN_ENV_OVERRIDES`                      | String-form per-tier overrides, e.g. `non_trading_api=live`. |
 | `DHAN_LOG_LEVEL`                          | Change logger verbosity (`INFO` default).            |
 | `DHAN_BASE_URL`                           | Override the REST API host.                          |
 | `DHAN_WS_VERSION`                         | Target a specific WebSocket API version.             |
@@ -77,6 +79,44 @@ For token rotation without restarting the app, set `access_token_provider` (Proc
 
 See [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) and README “Dynamic access token”.
 
+**Multi-instance clients (multi-account support)**
+
+When you need to trade across multiple accounts, run multi-tenant setups, or isolate sandbox/testing environments in a single process, use `DhanHQ::Client.new`:
+
+```ruby
+# Account 1
+client1 = DhanHQ::Client.new(client_id: "ACC_1", access_token: "TOKEN_1")
+
+# Account 2 (Sandbox)
+client2 = DhanHQ::Client.new(client_id: "ACC_2", access_token: "TOKEN_2", sandbox: true)
+
+# Resource accessors directly bound to client instance:
+orders1 = client1.orders.all
+orders2 = client2.orders.all
+```
+
+**Environments: live / sandbox / hybrid**
+
+`config.mode` picks which host each tier hits. `:hybrid` is the strategy-rehearsal mode —
+live market data from `api.dhan.co`, paper execution on `sandbox.dhan.co`:
+
+```ruby
+DhanHQ.configure do |config|
+  config.mode = :hybrid   # or DHAN_MODE=hybrid
+  # Optional: per-tier escape hatch on top of the mode
+  # config.environment_overrides = { non_trading_api: :live }
+end
+
+client.market_feed.ltp("NSE_EQ" => [11536])   # live prices from api.dhan.co
+client.orders.create(...)                     # paper execution on sandbox.dhan.co
+```
+
+The `LIVE_TRADING` gate is relaxed automatically for sandbox-targeted writes; production
+writes still require `ENV["LIVE_TRADING"]="true"`. Global Stocks always stays on production
+in `:hybrid`, and WebSocket streams are production-only (the Dhan sandbox has no WS).
+See [docs/ENDPOINTS_AND_SANDBOX.md](docs/ENDPOINTS_AND_SANDBOX.md) for the full routing
+and verification table.
+
 ---
 
 ## Working With Models

data/README.md

@@ -218,8 +218,106 @@ end
 
 When the API returns 401, the client retries **once** with a fresh token from your provider.
 
+### Multi-Instance Clients (Multi-Account / Multi-Tenant)
+
+For multi-tenant applications, managing multiple trading accounts concurrently, or isolating sandbox from production within the same process, construct explicit `DhanHQ::Client` instances:
+
+```ruby
+# Account 1 (Live Trading)
+client1 = DhanHQ::Client.new(
+  client_id: "ACC_1_ID",
+  access_token: "ACC_1_TOKEN"
+)
+
+# Account 2 (Sandbox / Testing)
+client2 = DhanHQ::Client.new(
+  client_id: "ACC_2_ID",
+  access_token: "ACC_2_TOKEN",
+  sandbox: true,
+  dry_run: true
+)
+
+# Resource accessors are bound to the client instance:
+positions = client1.positions.all
+orders    = client2.orders.all
+
+# Instance-bound WebSocket streams:
+ws_stream = client1.ws_market_feed(mode: :ticker) { |tick| puts tick[:ltp] }
+ws_orders = client1.ws_order_update
+```
+
 > **Full details**: TOTP flows, partner mode, token endpoint bootstrap, auto-management — see [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md).
 
+### Environments: Live / Sandbox / Hybrid
+
+`config.mode` decides which Dhan host each request hits:
+
+| Mode       | Market data (quotes, option chain, charts, instruments, ScanX) | Trading & account (orders, positions, funds, statements) |
+| ---------- | -------------------------------------------------------------- | -------------------------------------------------------- |
+| `:live`    | `api.dhan.co` (default)                                         | `api.dhan.co`                                            |
+| `:sandbox` | `sandbox.dhan.co`                                               | `sandbox.dhan.co`                                        |
+| `:hybrid`  | `api.dhan.co` — **live prices**                                 | `sandbox.dhan.co` — **paper execution**                   |
+
+`hybrid` is the strategy-rehearsal mode: your code reads real market data and places
+orders that are accepted and validated by the Dhan sandbox (which mirrors the live REST
+surface) without risking money.
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id    = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
+  config.mode         = :hybrid   # or :live (default) / :sandbox
+end
+
+# Same code, split routing:
+client.market_feed.ltp("NSE_EQ" => [11536])   # -> https://api.dhan.co/v2/marketfeed/ltp
+client.option_chain.fetch(...)                # -> https://api.dhan.co/v2/optionchain
+client.orders.create(...)                     # -> https://sandbox.dhan.co/v2/orders  (no LIVE_TRADING needed)
+client.positions.all                          # -> https://sandbox.dhan.co/v2/positions
+```
+
+Per-tier escape hatch when the defaults don't fit:
+
+```ruby
+config.mode = :hybrid
+config.environment_overrides = { non_trading_api: :live }  # e.g. read the real fund limits
+```
+
+- Env vars: `DHAN_MODE=live|sandbox|hybrid` (or the legacy `DHAN_SANDBOX=true`).
+- The `LIVE_TRADING` guard is **relaxed automatically** for requests routed to the
+  sandbox host — no real money can move there. Orders still hit the guard on `:live`.
+- Per-client override: `DhanHQ::Client.new(config: shared_config, mode: :hybrid)` forks
+  the config instead of mutating the shared one.
+- Global Stocks (US equities) always stay on production in `:hybrid` — the sandbox host
+  does not mirror them.
+- WebSocket streams are production-only (Dhan sandbox has no WS); in `:hybrid` the order
+  update stream reports your **real** account, not sandbox orders.
+- `sandbox = true` remains a supported alias for `mode = :sandbox`.
+
+> **Full details**: what each tier routes where, verified-vs-unverified sandbox endpoints —
+> see [docs/ENDPOINTS_AND_SANDBOX.md](docs/ENDPOINTS_AND_SANDBOX.md).
+
+---
+
+## ScanX Data API (company info, market movers, news, technicals)
+
+The `/v2/data/*` endpoints are wrapped by `client.scanx` — fundamentals, ranked movers,
+live news headlines and server-side indicators, all validated by dry-validation contracts:
+
+```ruby
+client.scanx.company_info(security_id: "1333", exchange_segment: "NSE_EQ",
+                          instrument: "EQUITY", metrics: %w[CO RATIOS SHP])
+
+client.scanx.technical_data(security_id: "1333", exchange_segment: "NSE_EQ",
+                            instrument: "EQUITY", timeframe: "D",
+                            indicators: %w[SMA_20 RSI_14 MACD_HIST PIVOT_CLASSIC])
+
+client.scanx.market_movers(exchange_segment: "NSE_FNO", instrument: %w[OPTIDX OPTSTK],
+                           category: "HIGHEST_OI", expiry: "2026-10-29", limit: 10)
+
+client.scanx.news_headlines(categories: %w[ALL], limit: 25)
+```
+
 ---
 
 ## Order Safety
@@ -238,6 +336,11 @@ LIVE_TRADING=false   # or simply omit
 
 Attempting to place an order without `LIVE_TRADING=true` raises `DhanHQ::LiveTradingDisabledError`.
 
+**Sandbox exception:** orders routed to the sandbox host (`mode = :sandbox`, or the trading
+tiers under `mode = :hybrid`) skip this guard automatically — the sandbox cannot move real
+money, so the gate only protects production writes. Every audit log line records the
+`target` host (`live`/`sandbox`) it fired at.
+
 ### Dry-Run Mode
 
 `dry_run` suppresses every request that would change account state — order placement,

data/docs/CONFIGURATION.md

@@ -24,7 +24,9 @@ Set these _before_ calling `configure_with_env` to override defaults:
 
 | Variable                         | Default    | Description                                             |
 | -------------------------------- | ---------- | ------------------------------------------------------- |
-| `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_MODE`                      | `live`     | `live`, `sandbox`, or `hybrid`. `hybrid` routes market data (quotes, option chain, charts, instruments, ScanX) to production and trading/account calls (orders, positions, funds, statements) to `https://sandbox.dhan.co/v2` — live prices, paper execution. Takes precedence over `DHAN_SANDBOX`. |
+| `DHAN_SANDBOX`                   | `false`    | Legacy alias: set `"true"` to route all REST calls to `https://sandbox.dhan.co/v2`. 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_ENV_OVERRIDES`             | unset      | String-form per-tier overrides on top of the mode, e.g. `"non_trading_api=live,data_api=sandbox"`. Equivalent to `config.environment_overrides`. |
 | `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            |
@@ -46,7 +48,7 @@ These change what a write request *does*, not just where it goes. All default to
 
 | 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. |
+| `LIVE_TRADING=true`                   | —                                    | unset   | **Required to place, modify, or cancel any real order, position exit, kill switch, EDIS, or P&L exit that targets production.** Without it, every production-bound write-path resource raises `DhanHQ::LiveTradingDisabledError` before making the request. Writes whose effective target is the sandbox host (`DHAN_MODE=sandbox`, or the trading tiers under `hybrid`) are exempt — no real money can move there. 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. |
@@ -106,6 +108,31 @@ end
 - **`access_token_provider`**: Callable (Proc/lambda) returning the token string. Called on every request (no memoization). When set, the gem uses it instead of `access_token`.
 - **`on_token_expired`**: Optional callable invoked when a 401/token-expired triggers a **single retry** (only when `access_token_provider` is set).
 
+## Multi-Instance Client Configuration
+
+For multi-account or multi-tenant architectures, construct explicit `DhanHQ::Client` instances without depending on global singleton state:
+
+```ruby
+# Direct configuration via keyword arguments
+client = DhanHQ::Client.new(
+  client_id: "YOUR_CLIENT_ID",
+  access_token: "YOUR_ACCESS_TOKEN",
+  sandbox: false,
+  dry_run: false
+)
+
+# Or via an explicit Configuration object
+custom_config = DhanHQ::Configuration.new do |c|
+  c.client_id = "TENANT_CLIENT_ID"
+  c.access_token = "TENANT_ACCESS_TOKEN"
+  c.dry_run = true
+end
+
+client = DhanHQ::Client.new(config: custom_config)
+```
+
+Each client instance manages its own Faraday connection, isolated configuration, dry-run state, and instance-bound resource accessors (`client.orders`, `client.positions`, `client.market_feed`, etc.).
+
 For detailed authentication flows, see [AUTHENTICATION.md](AUTHENTICATION.md).
 
 ## Available Resources

data/docs/ENDPOINTS_AND_SANDBOX.md

@@ -1,14 +1,46 @@
-# DhanHQ gem — Endpoints and sandbox support
+# DhanHQ gem — Endpoints, environments and sandbox support
+
+## Environments: `:live`, `:sandbox`, `:hybrid`
+
+`DhanHQ.configuration.mode` (or `DHAN_MODE`) selects which host each REST request hits.
+The legacy `sandbox = true` / `DHAN_SANDBOX=true` remains an alias for `mode = :sandbox`.
+
+| Mode       | Data tiers (`data_api`, `quote_api`, `option_chain`) | Trading/account tiers (`order_api`, `non_trading_api`) | Global Stocks (`global_stocks_api`) |
+| ---------- | ---------------------------------------------------- | ------------------------------------------------------ | ----------------------------------- |
+| `:live` (default) | `api.dhan.co/v2`                              | `api.dhan.co/v2`                                        | `api.dhan.co/v2`                    |
+| `:sandbox` | `sandbox.dhan.co/v2`                                  | `sandbox.dhan.co/v2`                                    | `sandbox.dhan.co/v2`                |
+| `:hybrid`  | `api.dhan.co/v2` — live prices                        | `sandbox.dhan.co/v2` — paper execution                  | `api.dhan.co/v2` (sandbox does not mirror it) |
+
+`hybrid` exists for strategy rehearsal: read live market data, place orders against the
+sandbox host. Per-tier overrides (`environment_overrides`) win over the mode defaults —
+for example keeping the real fund limits while everything else runs on the sandbox:
+
+```ruby
+DhanHQ.configure do |c|
+  c.mode = :hybrid
+  c.environment_overrides = { non_trading_api: :live }  # or String form: "non_trading_api=live"
+end
+```
+
+Per-client override (forks the config, never mutates the shared one):
+
+```ruby
+client = DhanHQ::Client.new(config: shared_config, mode: :hybrid)
+```
+
+Resolution order for any request: explicit `config.base_url` (if set, it wins for every
+request) → `environment_overrides[tier]` → mode default for that tier.
 
 ## 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:
+- **REST:** every wrapped REST endpoint listed below is sent to the host its tier resolves to (see the mode table above) — `:sandbox` sends everything to `https://sandbox.dhan.co/v2`, `:hybrid` splits data vs trading.
+- **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 mode. There are no sandbox WebSocket endpoints in the Dhan v2 API; do not rely on sandbox for real-time streams. Under `:hybrid` the order-update stream therefore reports your **real** account, not sandbox orders.
+- **LIVE_TRADING gate** is relaxed automatically for any write whose effective target is the sandbox host (no real money at risk). Production-targeted writes still require `ENV["LIVE_TRADING"]="true"`. Order audit log lines carry `"target":"live"|"sandbox"`.
+- **Auth endpoints** (`DhanHQ::Auth`) do **not** follow the mode. They always call:
   - `https://auth.dhan.co` — token generation
-  - `https://api.dhan.co/v2` — token renewal  
-  So token generation/renewal always hit production; only data/order REST calls follow the sandbox flag.
+  - `https://api.dhan.co/v2` — token renewal
+  So token generation/renewal always hit production; only data/order REST calls follow the mode.
 
 ---
 
@@ -41,36 +73,43 @@
 - `/v2/marketfeed/ltp`, `/v2/marketfeed/ohlc`, `/v2/marketfeed/quote`
 - `/v2/optionchain`, `/v2/optionchain/expirylist`
 - `/v2/charts/historical`, `/v2/charts/intraday`, `/v2/charts/rollingoption`
+- `/v2/data/companyinfo`, `/v2/data/marketmovers`, `/v2/data/newsheadline`, `/v2/data/technical` (ScanX)
+- `/v2/globalstocks/*` (Global Stocks — assumed unavailable on sandbox; always production in `:hybrid`)
 
 ---
 
 ## REST endpoints integrated in the gem
 
-Paths are as built by the gem (HTTP_PATH + endpoint). Base URL is either `https://api.dhan.co/v2` (production) or `https://sandbox.dhan.co/v2` (sandbox).
+Paths are as built by the gem (HTTP_PATH + endpoint). Base URL is resolved per tier — see the mode table above.
 
 | Resource / model           | Path(s)                                      | Methods   | API type        |
-|---------------------------|----------------------------------------------|-----------|-----------------|
-| **Profile**               | `/v2/profile`                               | GET       | non_trading_api |
-| **Funds**                 | `/v2/fundlimit`                              | GET       | non_trading_api |
-| **Statements**            | `/v2/ledger`, `/v2/trades/{from}/{to}/{page}`| GET       | non_trading_api |
-| **Orders**                | `/v2/orders`, `/v2/orders/{id}`, `/v2/orders/external/{correlation_id}`, `/v2/orders/slicing` | GET, POST, PUT, DELETE | order_api |
-| **Positions**             | `/v2/positions`, `/v2/positions/convert`     | GET, POST, DELETE | order_api |
-| **Holdings**              | `/v2/holdings`                               | GET       | order_api       |
-| **Trades**                | `/v2/trades`, `/v2/trades/{order_id}`        | GET       | order_api       |
-| **Forever orders**        | `/v2/forever/orders`, `/v2/forever/orders/{id}` | GET, POST, PUT, DELETE | order_api |
-| **Super orders**          | `/v2/super/orders`, `/v2/super/orders/{id}`, leg delete | GET, POST, PUT, DELETE | order_api |
-| **Kill switch**           | `/v2/killswitch`                             | GET, POST | order_api       |
-| **Trader control**        | `/trader-control`                            | GET, POST | order_api       |
-| **IP setup**              | `/ip/getIP`, `/ip/setIP`, `/ip/modifyIP`     | GET, POST, PUT | order_api |
-| **EDIS**                  | `/edis/tpin`, `/edis/form`, `/edis/bulkform`, `/edis/inquire/{isin}` | GET, POST | order_api |
-| **Alert orders**          | `/alerts/orders`                             | GET, POST, PUT, DELETE | order_api |
-| **PnL exit**              | `/v2/pnlExit`                                | GET, POST, DELETE | order_api |
-| **Margin calculator**     | `/v2/margincalculator`, `/v2/margincalculator/multi` | POST      | order_api       |
-| **Instruments**           | `/v2/instrument/{segment}` (redirect to CSV) | GET       | data_api        |
-| **Market feed**           | `/v2/marketfeed/ltp`, `/v2/marketfeed/ohlc`, `/v2/marketfeed/quote` | POST      | data_api / quote_api |
-| **Option chain**          | `/v2/optionchain`, `/v2/optionchain/expirylist` | POST      | data_api        |
-| **Historical data**       | `/v2/charts/historical`, `/v2/charts/intraday` | POST      | data_api        |
-| **Expired options data**  | `/v2/charts/rollingoption`                   | POST      | data_api        |
+|----------------------------|----------------------------------------------|-----------|-----------------|
+| **Profile**                | `/v2/profile`                                | GET       | non_trading_api |
+| **Funds**                  | `/v2/fundlimit`                              | GET       | order_api       |
+| **Statements**             | `/v2/ledger`, `/v2/trades/{from}/{to}/{page}`| GET       | non_trading_api |
+| **Orders**                 | `/v2/orders`, `/v2/orders/{id}`, `/v2/orders/external/{correlation_id}`, `/v2/orders/slicing` | GET, POST, PUT, DELETE | order_api |
+| **Positions**              | `/v2/positions`, `/v2/positions/convert`     | GET, POST, DELETE | order_api |
+| **Holdings**               | `/v2/holdings`                               | GET       | order_api       |
+| **Trades**                 | `/v2/trades`, `/v2/trades/{order_id}`        | GET       | order_api       |
+| **Forever orders**         | `/v2/forever/orders`, `/v2/forever/orders/{id}` | GET, POST, PUT, DELETE | order_api |
+| **Super orders**           | `/v2/super/orders`, `/v2/super/orders/{id}`, leg delete | GET, POST, PUT, DELETE | order_api |
+| **Kill switch**            | `/v2/killswitch`                             | GET, POST | order_api       |
+| **Trader control**         | `/trader-control`                            | GET, POST | order_api       |
+| **IP setup**               | `/ip/getIP`, `/ip/setIP`, `/ip/modifyIP`     | GET, POST, PUT | order_api |
+| **EDIS**                   | `/edis/tpin`, `/edis/form`, `/edis/bulkform`, `/edis/inquire/{isin}` | GET, POST | order_api |
+| **Alert orders**           | `/alerts/orders`                             | GET, POST, PUT, DELETE | order_api |
+| **PnL exit**               | `/v2/pnlExit`                                | GET, POST, DELETE | order_api |
+| **Margin calculator**      | `/v2/margincalculator`, `/v2/margincalculator/multi` | POST      | order_api       |
+| **Instruments**            | `/v2/instrument/{segment}` (redirect to CSV) | GET       | data_api        |
+| **Market feed**            | `/v2/marketfeed/ltp`, `/v2/marketfeed/ohlc`, `/v2/marketfeed/quote` | POST      | data_api / quote_api |
+| **Option chain**           | `/v2/optionchain`, `/v2/optionchain/expirylist` | POST      | data_api        |
+| **Historical data**        | `/v2/charts/historical`, `/v2/charts/intraday` | POST      | data_api        |
+| **Expired options data**   | `/v2/charts/rollingoption`                   | POST      | data_api        |
+| **ScanX — company info**   | `/v2/data/companyinfo`                       | POST      | data_api        |
+| **ScanX — market movers**  | `/v2/data/marketmovers`                      | POST      | data_api        |
+| **ScanX — news**           | `/v2/data/newsheadline`                      | POST      | data_api        |
+| **ScanX — technicals**     | `/v2/data/technical`                         | POST      | data_api        |
+| **Global Stocks**          | `/v2/globalstocks/orders`, `/v2/globalstocks/holdings`, `/v2/globalstocks/fundlimit`, `/v2/globalstocks/trades`, `/v2/globalstocks/marketstatus`, `/v2/globalstocks/margincalculator`, `/v2/globalstocks/transEstimate` | GET/POST/PUT/DELETE | global_stocks_api |
 
 ---
 
@@ -81,7 +120,7 @@ Paths are as built by the gem (HTTP_PATH + endpoint). Base URL is either `https:
 | Generate token    | `https://auth.dhan.co/app/generateAccessToken` | POST   |
 | Renew token       | `https://api.dhan.co/v2/RenewToken`           | POST   |
 
-These are **not** sandbox-aware; they always use the URLs above.
+These are **not** mode-aware; they always use the URLs above.
 
 ---
 
@@ -93,24 +132,30 @@ These are **not** sandbox-aware; they always use the URLs above.
 | Market feed    | `wss://api-feed.dhan.co` |
 | Market depth   | `wss://depth-api-feed.dhan.co/twentydepth` |
 
-**Sandbox:** Dhan sandbox does **not** provide WebSocket services. These endpoints are production-only. The gem never switches WS URLs based on `sandbox`; you can still override via `DhanHQ.configuration.ws_order_url`, `ws_market_feed_url`, `ws_market_depth_url`, or env vars `DHAN_WS_ORDER_URL`, `DHAN_WS_MARKET_FEED_URL`, `DHAN_WS_MARKET_DEPTH_URL` if you have a different production URL.
+**Sandbox:** Dhan sandbox does **not** provide WebSocket services. These endpoints are production-only. The gem never switches WS URLs based on the mode; you can still override via `DhanHQ.configuration.ws_order_url`, `ws_market_feed_url`, `ws_market_depth_url`, or env vars `DHAN_WS_ORDER_URL`, `DHAN_WS_MARKET_FEED_URL`, `DHAN_WS_MARKET_DEPTH_URL` if you have a different production URL.
 
 ---
 
 ## Summary
 
-- **REST:** When `sandbox` is true, all REST calls go to `https://sandbox.dhan.co/v2`. Only `GET /v2/profile` and `GET /v2/fundlimit` are verified working on sandbox; other REST endpoints are not verified — see "Sandbox: verified vs not working / unverified" above.
+- **Modes:** `:live` (default — everything on production), `:sandbox` (everything on `sandbox.dhan.co`), `:hybrid` (data tiers live, trading tiers sandbox, Global Stocks live). Set via `config.mode`, `DHAN_MODE`, or the legacy `config.sandbox` / `DHAN_SANDBOX`.
+- **Verified on sandbox:** only `GET /v2/profile` and `GET /v2/fundlimit` — see "Sandbox: verified vs not working / unverified" above.
+- **LIVE_TRADING:** required only for writes that target production; sandbox-targeted writes are exempt.
 - **Auth:** Token generation and renewal always use production hosts.
 - **WebSockets:** Sandbox does **not** support WebSocket. Order updates, market feed, and market depth always use production URLs; the gem does not publish or use any sandbox WebSocket URLs.
 
-## Call-all-endpoints script
+## Smoke testing
 
-`bin/call_all_endpoints.rb` invokes every REST endpoint exposed by the gem (read-only by default; use `--all` to include write/destructive calls). Useful for connectivity checks or sandbox verification.
+There is no shipped call-all-endpoints script (an earlier revision of this page
+referenced `bin/call_all_endpoints.rb`, which does not exist in the repo). Use
+what is actually here:
 
 ```bash
-bin/call_all_endpoints.rb              # read-only
-bin/call_all_endpoints.rb --list       # print endpoint list
-bin/call_all_endpoints.rb --all        # include POST/PUT/DELETE
+bin/console                  # IRB with the gem preloaded — try client.profile.get,
+                              # client.market_feed.ltp(...), client.fundlimit.get ...
+bundle exec rspec spec/dhan_hq/sandbox_connectivity_spec.rb   # guarded sandbox probes
+bin/ws_feed_test.rb          # live market-feed smoke test (production WS only)
 ```
 
-Requires `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN`. Optional: `DHAN_SANDBOX=true`, `DHAN_TEST_SECURITY_ID`, `DHAN_TEST_ORDER_ID`, `DHAN_TEST_ISIN`, `DHAN_TEST_EXPIRY`. When not using `--skip-unavailable`, the script creates a temporary alert for GET/PUT/DELETE alert endpoints and deletes it at exit.
+Requires `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN`. Optional: `DHAN_MODE=hybrid`
+(or `DHAN_SANDBOX=true`).