DhanHQ 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c2f0784210b7f48ccb056b8cc486ce5c3ef655f69a4bd2834a150b1d04a8bc7
-  data.tar.gz: a6628fc83e8ec61bd4ca4b0eb6147a67232156f98ab49196c0a81850f9b4ac59
+  metadata.gz: d79f2577f59f6c04874eb44e4d318e5584e711e205be25f6fa000053ec772846
+  data.tar.gz: dca8144795ab2b77700a3947512c04e73c8edcbaa287b74adb746e671158e583
 SHA512:
-  metadata.gz: d0a4147017f7722d9a74cec3105fb57e9b8710142abda6c04d5948caa7500b21ce8c31958cc501e99643a31afffe5e64846b5a73ff239f1a8fb87074e57a6856
-  data.tar.gz: 508f55621273349e9060e941cc9bf8b7cef7fb28befb8026b57b977ba0954760f783eb5dbb26c19593ac113232c12fa74884fcd57a81b61dd21dbc3d66c7b9e9
+  metadata.gz: e5a38d2663377da284188dc32fd0e796394ee899a34b61d5f82b5a487b0a47477a9e6bc1c0fdfc0b7fa93959d8673e257a83b7eea1af1a48885526ecc506a89f
+  data.tar.gz: 3f2023c47fc5e5b1f6fcce29f704c2c4ac03ad887a91dbc0c33bba201a151e8f03793bdc736915a295e98a5e661810e6229e32b37ea11c09b977fbcbb1b1c5d3

data/CHANGELOG.md

@@ -1,3 +1,42 @@
+## [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

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.             |
@@ -93,6 +95,28 @@ 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

@@ -248,6 +248,76 @@ 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
@@ -266,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. |

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`).

data/lib/DhanHQ/client.rb

@@ -49,8 +49,12 @@ module DhanHQ
     # @param config_or_attrs [DhanHQ::Configuration, Hash, nil] Optional configuration or attribute hash
     # @param config [DhanHQ::Configuration, nil] Optional keyword configuration
     # @param api_type [Symbol] Type of API (`:order_api`, `:data_api`, `:non_trading_api`)
+    # @param mode [Symbol, nil] Optional environment override (`:live`, `:sandbox`, `:hybrid`)
+    #   for this client. When combined with +config:+ the configuration is forked,
+    #   so a shared/global configuration is never mutated.
     # @param attrs [Hash] Additional keyword configuration attributes
-    def initialize(config_or_attrs = nil, config: nil, api_type: :order_api, **attrs)
+    def initialize(config_or_attrs = nil, config: nil, api_type: :order_api, mode: nil, **attrs)
+      attrs = attrs.merge(mode: mode) if mode
       @config = resolve_config(config_or_attrs, config, attrs)
       @api_type = api_type
       @rate_limiter = RateLimiter.for(api_type)
@@ -59,11 +63,12 @@ module DhanHQ
     end
 
     # The Faraday connection used for HTTP requests.
-    # Built on first use and rebuilt whenever the configured base URL changes.
+    # Built on first use and rebuilt whenever the base URL for this client's API
+    # tier changes — including a mid-flight mode switch.
     #
     # @return [Faraday::Connection]
     def connection
-      current_url = @config.base_url
+      current_url = @config.base_url_for(@api_type)
       return @connection if @connection && @last_base_url == current_url
 
       @last_base_url = current_url
@@ -92,6 +97,15 @@ module DhanHQ
     def trader_control = @trader_control ||= Resources::TraderControl.new(client: client_for(Resources::TraderControl::API_TYPE))
     def ip_setup = @ip_setup ||= Resources::IPSetup.new(client: client_for(Resources::IPSetup::API_TYPE))
     def edis = @edis ||= Resources::Edis.new(client: client_for(Resources::Edis::API_TYPE))
+    def scanx = @scanx ||= Resources::ScanX.new(client: client_for(Resources::ScanX::API_TYPE))
+
+    # The effective environment (+:live+ or +:sandbox+) for requests issued by
+    # this client, resolved from its API tier and the configured mode.
+    #
+    # @return [Symbol]
+    def environment
+      @config.environment_for(@api_type)
+    end
 
     # WebSocket streams bound to this client instance configuration
     def ws_market_feed(mode: :ticker, url: nil, &block)
@@ -258,11 +272,11 @@ module DhanHQ
 
     def resolve_config(config_or_attrs, keyword_config, attrs = {})
       if config_or_attrs.is_a?(DhanHQ::Configuration)
-        config_or_attrs
+        fork_config_with_attrs(config_or_attrs, attrs)
       elsif config_or_attrs.is_a?(Hash)
         DhanHQ::Configuration.new(config_or_attrs.merge(attrs))
       elsif keyword_config
-        keyword_config
+        fork_config_with_attrs(keyword_config, attrs)
       elsif attrs.any?
         DhanHQ::Configuration.new(attrs)
       else
@@ -270,6 +284,17 @@ module DhanHQ
       end
     end
 
+    # Copies a Configuration when per-instance attributes (e.g. +mode:+) are
+    # given alongside it, so an injected or global configuration is never
+    # mutated. Without extra attributes the original object is shared unchanged.
+    def fork_config_with_attrs(config, attrs)
+      return config if attrs.empty?
+
+      config.dup.tap do |forked|
+        attrs.each { |key, value| forked.public_send("#{key}=", value) }
+      end
+    end
+
     # Simulator that answers state-changing requests locally when dry run is on.
     #
     # @return [DhanHQ::DryRun::Simulator]

data/lib/DhanHQ/concerns/order_audit.rb

@@ -37,13 +37,28 @@ module DhanHQ
     module OrderAudit
       private
 
-      # Raises an error if LIVE_TRADING is not explicitly enabled.
-      # Set ENV["LIVE_TRADING"]="true" in production to allow order submission.
+      # Raises an error unless live trading is explicitly enabled OR the request
+      # targets the sandbox host, where no real money is at risk.
+      #
+      # Set ENV["LIVE_TRADING"]="true" to allow order submission against the
+      # production host. Orders routed to the sandbox host (config.mode =
+      # :sandbox, or the trading tiers under :hybrid) skip the gate because they
+      # cannot place real orders.
       def ensure_live_trading!
         return if ENV["LIVE_TRADING"] == "true"
+        return if sandbox_target?
 
         raise DhanHQ::LiveTradingDisabledError,
-              "Live trading is disabled. Set ENV[\"LIVE_TRADING\"]=\"true\" to enable order placement."
+              "Live trading is disabled. Set ENV[\"LIVE_TRADING\"]=\"true\" to enable order placement, " \
+              "or switch to the sandbox with DhanHQ.configure { |c| c.mode = :sandbox } / :hybrid."
+      end
+
+      # True when this resource's requests resolve to the sandbox host.
+      # Tolerates hosts that never got a client wired in (bare test doubles).
+      def sandbox_target?
+        return false unless respond_to?(:client) && client.respond_to?(:environment)
+
+        client.environment == :sandbox
       end
 
       # Runs the risk pipeline for the given order params.
@@ -120,6 +135,7 @@ module DhanHQ
           event: event,
           hostname: inspector.hostname,
           env: inspector.environment,
+          target: request_target,
           ipv4: inspector.public_ipv4,
           ipv6: inspector.public_ipv6,
           security_id: extract_param(params, :securityId, :security_id),
@@ -131,6 +147,13 @@ module DhanHQ
         DhanHQ.logger&.warn(JSON.generate(entry))
       end
 
+      # The host the order will be sent to, for the audit trail.
+      def request_target
+        return "sandbox" if sandbox_target?
+
+        "live"
+      end
+
       # Extracts a value from params trying both camelCase and snake_case keys,
       # as well as both symbol and string key types.
       def extract_param(params, camel_key, snake_key)