DhanHQ 4.1.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d79f2577f59f6c04874eb44e4d318e5584e711e205be25f6fa000053ec772846
-  data.tar.gz: dca8144795ab2b77700a3947512c04e73c8edcbaa287b74adb746e671158e583
+  metadata.gz: 2929a9a1a182987ee1a71b822d28db5879919348e6598a545d2133d86721d82d
+  data.tar.gz: afc1857745b80f145d5f2aa0e6f3445ec5c5c0adbc43de58bfddda58f1e8f33f
 SHA512:
-  metadata.gz: e5a38d2663377da284188dc32fd0e796394ee899a34b61d5f82b5a487b0a47477a9e6bc1c0fdfc0b7fa93959d8673e257a83b7eea1af1a48885526ecc506a89f
-  data.tar.gz: 3f2023c47fc5e5b1f6fcce29f704c2c4ac03ad887a91dbc0c33bba201a151e8f03793bdc736915a295e98a5e661810e6229e32b37ea11c09b977fbcbb1b1c5d3
+  metadata.gz: 2bc9cbb45c476e9372673549ff6f6a92605dae6408b986a08b4f4944a8dcba8e02587cfd9098011159ad3a00ce43ec1e6dbf50c7b0b7ae38bb3daac272667b05
+  data.tar.gz: b0acc9f195069adc8a6a38b1faf5ddd09d4c189d78a64fc0eb78e363477988eebfeabc7521b9cc5d7ddc1f52d221c6b427a5e9c2a652b6eefeba25ae84e00e83

data/CHANGELOG.md

@@ -1,3 +1,50 @@
+## [4.1.1] - 2026-10-11
+
+### Fixed — pre-trade risk pipeline
+
+- **The risk checks only saw parameters whose key happened to be a single lowercase word.** Checks read snake_case String keys (`"order_type"`, `"product_type"`, `"security_id"`), but orders arrive as camelCase Strings (models) or Symbols (direct resource calls). `OrderType`, `ProductSupport` and `Concentration` therefore never ran on real orders, and Symbol-keyed callers failed `Quantity must be > 0` on a valid quantity — which blocked every `SuperOrder.create`. `OrderAudit` now normalises keys before running the pipeline.
+- **Risk-reducing orders are never blocked by a limit.** An order on the opposite side of an open position, same security / segment / product, for no more than the position size, skips the size caps, open-position count, daily loss, concentration and ASM/GSM checks; it still gets trading-permission, product, order-type, quantity > 0 and market-hours validation. Previously a stop-out could be refused precisely because the account was over its loss or position limit.
+- **`OrderType` accepts `STOP_LOSS` and `STOP_LOSS_MARKET`** (was `MARKET`/`LIMIT` only). With the key fix above, the old list would have rejected every stop-loss order.
+- **`Concentration` matches positions by security id** (and segment) when the order names no trading symbol, and counts the new order's notional; it compared a trading symbol against a security id and so never matched an order. A MARKET entry (which carries no price) is priced from its trigger price or the instrument's LTP; an entry that cannot be priced is refused rather than counted as zero exposure.
+- **`MaxLoss` counts realized plus unrealized P&L** for the day (was unrealized only).
+- **Positions are fetched once per order** and shared by every check (was up to three `GET /v2/positions` calls per order).
+- **`SuperOrder.create`, `IcebergOrder.create` and `TwapOrder.create` raised `ArgumentError` after a successful placement** (Ruby 3 keyword arguments: the attributes hash was splatted into keywords). The order existed at Dhan while the caller saw an exception — a retry would duplicate it. The super-order spec stubbed `.new` with the same broken signature, which hid it.
+
+### Fixed — endpoint wire format and error mapping
+
+- **Data-API error codes sent as integers never matched the error mapping.** Dhan's data APIs answer with numeric codes (`{"errorCode":807,"errorMessage":"Token expired"}` — see `spec/vcr_cassettes/client/error_806.yml`), but `ResponseHelper#handle_error` compared them against string-keyed `DHAN_ERROR_MAPPING`, so every integer code fell through to the HTTP-status fallback: token expiry (807) surfaced as `InvalidAuthenticationError`, invalid expiry date (811) as a generic `InputExceptionError`, and so on. The code is now normalized with `.to_s` before the lookup. New wire-format specs in `spec/dhan_hq/resources/historical_data_spec.rb` and `expired_options_data_spec.rb` cover the mapping.
+- **`Resources::Instruments#by_segment` swallowed HTTP errors.** On 4xx/5xx it returned the raw JSON error body as if it were CSV — no exception, unlike every other resource. Failures now raise the status-mapped `DhanHQ::Error` subclass (`NotFoundError`, `InvalidAuthenticationError`, …). New spec in `spec/dhan_hq/resources/instruments_spec.rb`.
+- **`Resources::MarginCalculator#calculate_multi` sent nested `scripList` entries in snake_case.** Only top-level keys were camelized, so the API received `security_id`/`exchange_segment` inside each scrip (the `Models::Margin` layer pre-camelized as a workaround; the raw resource did not). The resource now deep-camelizes like `multi_orders` does for its legs. New spec in `spec/dhan_hq/resources/margin_calculator_spec.rb`.
+- New WebMock wire-format specs for every non-order REST endpoint — funds, holdings, trades, positions, profile, statements, market feed (ltp/ohlc/quote), option chain, charts, expired options, margin calculator, instruments, EDIS, IP setup, kill switch — asserting method, path, headers, body shape, param camelization/titleization, and typed error mapping. (Orders endpoints excluded per scope.)
+
+### Fixed — authentication
+
+- **`DhanHQ::Auth.renew_token` called the wrong URL.** `conn.post("/RenewToken")` on the `https://api.dhan.co/v2` base made Faraday drop `/v2` (a leading slash is an absolute path), so renewals hit `https://api.dhan.co/RenewToken`. It now requests `/v2/RenewToken` with **GET**, matching Dhan's documented curl example (`dhanhq.co/docs/v2/authentication`) and the official Python SDK (`dhanhq` 2.3.0). `generate_access_token` also uses a relative path now.
+- **Successful auth responses returned `{}`.** The auth connection had no JSON parsing, so the body arrived as a string and `handle_response` discarded it — the new `accessToken` was lost on every successful renewal or generation. Bodies are now parsed regardless of `Content-Type`.
+- **Auth failures are typed by cause.** 429 raises `DhanHQ::RateLimitError`, 5xx `DhanHQ::InternalServerError`, timeouts and connection failures `DhanHQ::NetworkError`; only refused credentials raise `DhanHQ::InvalidAuthenticationError`. Previously every failure, including outages, looked like bad credentials. All remain `DhanHQ::Error` subclasses, and `response_body` now carries the parsed error payload.
+- **Auth requests have timeouts** (`DHAN_CONNECT_TIMEOUT` / `DHAN_READ_TIMEOUT` / `DHAN_WRITE_TIMEOUT`, defaults 10/30/30s, as `Client#build_connection`). They were unbounded.
+- New `spec/dhan_hq/auth_spec.rb` covers both endpoints, error mapping, timeouts and `Auth::TokenRenewal`; the auth module previously had no specs.
+
+### Added
+
+- **Configurable risk limits** — `config.risk_limits = { max_quantity:, max_notional:, max_open_positions:, daily_max_loss:, max_concentration_pct: }` or `DHAN_RISK_MAX_QUANTITY`, `DHAN_RISK_MAX_NOTIONAL`, `DHAN_RISK_MAX_OPEN_POSITIONS`, `DHAN_RISK_DAILY_MAX_LOSS`, `DHAN_RISK_MAX_CONCENTRATION_PCT`. Defaults are unchanged (10 units, ₹1,00,000 notional, 20 positions, ₹50,000 daily loss, 25%). Unknown names or non-positive values raise `ArgumentError` at configuration time.
+
+### Upgrade notes
+
+- **`max_quantity` defaults to 10 units, so one NIFTY lot (75) is rejected** on any order whose instrument resolves. This was already true for camelCase-keyed orders before this release; it now applies to every key style. F&O users must raise `max_quantity` (in units, not lots) and usually `max_notional`.
+- Checks that never ran before now run on every order: `OrderType`, `ProductSupport` (CO/BO support flags) and `Concentration` (one extra `GET /v2/fundlimit` per new-exposure order).
+- A risk-check failure still fails open: if the instrument lookup or a positions/funds fetch raises, the pipeline is skipped and logged as `DHAN_RISK_CHECK_SKIPPED` (unchanged behaviour).
+
+### Fixed (review against docs.dhanhq.co, dhanhq.co/docs/v2 and the live/sandbox OpenAPI documents)
+
+- **`:hybrid` mode sent the production token to the sandbox host.** Dhan runs sandbox and production with separate credentials and rejects each other's tokens (docs.dhanhq.co, *Sandbox*), so every sandbox-bound request in `:hybrid` was a guaranteed DH-901. New `sandbox_client_id` / `sandbox_access_token` (`DHAN_SANDBOX_CLIENT_ID` / `DHAN_SANDBOX_ACCESS_TOKEN`) are used for every request routed to the sandbox — `access-token` and `client-id` headers, and a body `dhanClientId` that equals the production ID. In `:sandbox` mode they fall back to `client_id` / `access_token`, so existing setups are unaffected; in `:hybrid` they are required and their absence raises `DhanHQ::AuthenticationError` before any I/O.
+- **Sandbox-unsupported endpoints now fail fast.** Requests routed to the sandbox for super orders, conditional/multi orders, P&L exit, multi-scrip margin, IP setup, ScanX, market quotes, option chain, rolling options and Global Stocks raise `DhanHQ::SandboxUnsupportedError` instead of returning an opaque 404. They are never redirected to production. The list (`Constants::SANDBOX_UNSUPPORTED_PATH_PREFIXES`) is the set of paths that are absent from the sandbox OpenAPI document and answer 404 on `sandbox.dhan.co`.
+- **Full Market Depth (20/200-level) WebSocket never emitted data.** The decoder parsed frames as JSON, while Dhan sends binary packets (12-byte header plus 16-byte `float64`/`uint32`/`uint32` rows, bid and ask as separate stacked packets). Rewritten as a binary decoder; the client merges each instrument's bid and ask packets into one `:depth_update` (`bids`, `asks`, `best_bid`, `best_ask`, `spread`, totals) and emits `:disconnect` for server disconnect packets (code 50).
+- **Market depth unsubscribe request code is now 25** (was 24). docs.dhanhq.co gives 25 in both its Annexure and the Full Market Depth page; the older dhanhq.co/docs/v2 Annexure says 24. Not verified against the live feed (it is geo-restricted from CI).
+- **200-level depth subscription uses the documented flat format** (`{RequestCode, ExchangeSegment, SecurityId}`), not the 20-level instrument list, and a second instrument on a 200-level connection is refused (one instrument per connection). 20-level connections cap at 50 instruments.
+- **`MarketDepth::Client#subscribe(hash)`** subscribed nothing — `Array(hash)` split the instrument hash into key/value pairs.
+- **`OrderStatus::INACTIVE`** added; it is in the documented `orderStatus` response enum.
+
 ## [4.1.0] - 2026-10-10
 
 ### Fixed (full-gem review pass — `ruby-agent-skills` audit)

data/GUIDE.md

@@ -103,6 +103,9 @@ 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
+  # Sandbox credentials are separate from production ones (cloud.dhanhq.co)
+  config.sandbox_client_id    = ENV["DHAN_SANDBOX_CLIENT_ID"]
+  config.sandbox_access_token = ENV["DHAN_SANDBOX_ACCESS_TOKEN"]
   # Optional: per-tier escape hatch on top of the mode
   # config.environment_overrides = { non_trading_api: :live }
 end

data/README.md

@@ -264,9 +264,11 @@ 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
+  config.client_id            = ENV["DHAN_CLIENT_ID"]             # production — market data
+  config.access_token         = ENV["DHAN_ACCESS_TOKEN"]
+  config.sandbox_client_id    = ENV["DHAN_SANDBOX_CLIENT_ID"]     # sandbox — execution
+  config.sandbox_access_token = ENV["DHAN_SANDBOX_ACCESS_TOKEN"]  # (generate on cloud.dhanhq.co)
+  config.mode                 = :hybrid   # or :live (default) / :sandbox
 end
 
 # Same code, split routing:
@@ -284,6 +286,18 @@ config.environment_overrides = { non_trading_api: :live }  # e.g. read the real
 ```
 
 - Env vars: `DHAN_MODE=live|sandbox|hybrid` (or the legacy `DHAN_SANDBOX=true`).
+- **Two credential sets.** Dhan's sandbox and production are separate environments and
+  each rejects the other's tokens, so `:hybrid` needs both: sandbox-bound requests
+  authenticate with `DHAN_SANDBOX_CLIENT_ID` / `DHAN_SANDBOX_ACCESS_TOKEN` (header *and*
+  body `dhanClientId`), production-bound ones with `DHAN_CLIENT_ID` / `DHAN_ACCESS_TOKEN`.
+  Missing sandbox credentials raise `DhanHQ::AuthenticationError` before any request.
+  In `:sandbox` mode the sandbox pair falls back to the primary pair, so existing setups
+  keep working.
+- **Endpoints the sandbox does not serve** (super orders, conditional/multi orders, P&L
+  exit, multi-scrip margin, IP setup, ScanX, market quotes, option chain, rolling options,
+  Global Stocks) raise `DhanHQ::SandboxUnsupportedError` when routed there — they are
+  never silently sent to production. Route a read-only tier to production with
+  `environment_overrides` if you need it.
 - 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

data/docs/AUTHENTICATION.md

@@ -77,7 +77,18 @@ config.access_token_provider = lambda do
 end
 ```
 
-**Note:** RenewToken is only for tokens generated from Dhan Web. For API key or Partner flows, obtain a new token using Dhan’s consent APIs in your app.
+**Note:** RenewToken is only for tokens generated from Dhan Web, and only while the token is still active: renewing an expired token returns an error, so renew before expiry and fall back to `generate_access_token` (PIN + TOTP) if renewal is refused. For API key or Partner flows, obtain a new token using Dhan’s consent APIs in your app.
+
+`renew_token` and `generate_access_token` raise by failure class, so callers can tell "retry later" from "re-authenticate":
+
+| Error | When |
+|---|---|
+| `DhanHQ::InvalidAuthenticationError` | Dhan refused the token or credentials (4xx other than 429) |
+| `DhanHQ::RateLimitError` | 429 — back off and retry |
+| `DhanHQ::InternalServerError` | 5xx — retry later |
+| `DhanHQ::NetworkError` | Timeout or connection failure — retry later |
+
+All inherit from `DhanHQ::Error`, and `error.response_body` holds Dhan's parsed error payload.
 
 ## Retry-on-401
 
@@ -193,7 +204,7 @@ Behavior:
 On first use: calls TOTP TokenGenerator → applies token.
 Before each request: ensure_valid_token!:
 If no token → generate.
-If needs_refresh? → TokenRenewal (POST /v2/RenewToken) with current token + dhanClientId.
+If needs_refresh? → TokenRenewal (GET /v2/RenewToken) with current token + dhanClientId.
 If renewal fails with auth error → falls back to full generate.
 
 6️⃣ Web-token renewal only (RenewToken)

data/docs/CONFIGURATION.md

@@ -25,6 +25,13 @@ Set these _before_ calling `configure_with_env` to override defaults:
 | Variable                         | Default    | Description                                             |
 | -------------------------------- | ---------- | ------------------------------------------------------- |
 | `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_RISK_MAX_QUANTITY`         | `10`       | Pre-trade cap on order quantity, in units (one NIFTY lot = 75). Applies to new exposure only; exits are never capped. Also `config.risk_limits[:max_quantity]`. |
+| `DHAN_RISK_MAX_NOTIONAL`         | `100000`   | Cap on quantity × price for new exposure. |
+| `DHAN_RISK_MAX_OPEN_POSITIONS`   | `20`       | New entries are refused at this many open positions. |
+| `DHAN_RISK_DAILY_MAX_LOSS`       | `50000`    | New entries are refused once realized + unrealized day P&L is below minus this value. |
+| `DHAN_RISK_MAX_CONCENTRATION_PCT`| `25`       | Max exposure in one instrument (open position + this order) as % of available funds. |
+| `DHAN_SANDBOX_CLIENT_ID`         | unset      | Client ID for `https://sandbox.dhan.co/v2` (Dhan Cloud). Used for every request routed to the sandbox. Required in `hybrid`; falls back to `DHAN_CLIENT_ID` in `sandbox` mode. |
+| `DHAN_SANDBOX_ACCESS_TOKEN`      | unset      | Sandbox access token. Dhan rejects production tokens on the sandbox and vice versa. Required in `hybrid`; falls back to `DHAN_ACCESS_TOKEN` in `sandbox` mode. |
 | `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. |

data/docs/ENDPOINTS_AND_SANDBOX.md

@@ -31,6 +31,24 @@ 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.
 
+### Credentials per environment
+
+Dhan treats sandbox and production as separate environments with separate credentials
+("Do not reuse production tokens for sandbox requests or sandbox tokens for production
+requests" — docs.dhanhq.co, *Sandbox*). The gem therefore resolves credentials per tier
+alongside the host:
+
+| Request routed to | `access-token` header | `client-id` header / body `dhanClientId` |
+| ----------------- | --------------------- | ---------------------------------------- |
+| production        | `access_token` (`DHAN_ACCESS_TOKEN`) | `client_id` (`DHAN_CLIENT_ID`) |
+| sandbox           | `sandbox_access_token` (`DHAN_SANDBOX_ACCESS_TOKEN`) | `sandbox_client_id` (`DHAN_SANDBOX_CLIENT_ID`) |
+
+A body `dhanClientId` equal to the production `client_id` (models fill it in) is rewritten
+to the sandbox ID on sandbox-bound requests; an explicitly different ID is left alone. In
+`:sandbox` mode the sandbox pair falls back to the primary pair; in `:hybrid` (or with a
+tier overridden to the sandbox) missing sandbox credentials raise
+`DhanHQ::AuthenticationError` before any I/O.
+
 ## 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.
@@ -44,37 +62,22 @@ request) → `environment_overrides[tier]` → mode default for that tier.
 
 ---
 
-## Sandbox: verified vs not working / unverified
-
-| Status    | Endpoints |
-|-----------|-----------|
-| **Verified on sandbox** (gem specs) | `GET /v2/profile`, `GET /v2/fundlimit` |
-| **Sandbox connectivity spec** | `spec/dhan_hq/sandbox_connectivity_spec.rb` — uses VCR `record: :new_episodes`. In CI, use committed cassettes or skip without sandbox credentials; locally, run with `VCR_RECORD=new_episodes` and sandbox credentials to record. |
-| **Not supported in sandbox** | All WebSocket endpoints (order updates, market feed, market depth). Use production only. |
-| **Not verified on sandbox** | All other REST endpoints below. They may fail, return differently, or be unavailable in sandbox. Use Dhan documentation or manual testing before relying on them in sandbox. |
-
-**REST endpoints not verified / may not work on sandbox** (only profile and funds are verified):
-
-- `/v2/ledger`, `/v2/trades/{from}/{to}/{page}` (statements)
-- `/v2/orders` (all order CRUD, slicing, external)
-- `/v2/positions`, `/v2/positions/convert`
-- `/v2/holdings`
-- `/v2/trades`, `/v2/trades/{order_id}`
-- `/v2/forever/orders` (all)
-- `/v2/super/orders` (all)
-- `/v2/killswitch`
-- `/trader-control`
-- `/ip/getIP`, `/ip/setIP`, `/ip/modifyIP`
-- `/edis/tpin`, `/edis/form`, `/edis/bulkform`, `/edis/inquire/{isin}`
-- `/alerts/orders`
-- `/v2/pnlExit`
-- `/v2/margincalculator`, `/v2/margincalculator/multi`
-- `/v2/instrument/{segment}`
-- `/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`)
+## Sandbox endpoint support
+
+Source: the sandbox's own OpenAPI document (`https://sandbox.dhan.co/v2/v3/api-docs`), the
+*Sandbox* page on docs.dhanhq.co, and an unauthenticated probe of each path (an existing
+route answers 401/400, a missing one 404).
+
+| Status | Endpoints |
+|--------|-----------|
+| **Served by the sandbox** | `/orders` (place, modify, cancel, book, by id, by correlation id), `/orders/slicing`, `/trades`, `/trades/{order-id}`, `/holdings`, `/positions`, `/positions/convert`, `POST /killswitch`, `/edis/tpin`, `/edis/form`, `/edis/bulkform`, `/edis/inquire/{isin}`, `/fundlimit`, `POST /margincalculator`, `/ledger`, `/trades/{from}/{to}/{page}`, `/charts/historical`, `/charts/intraday`, `/forever/orders` (in the sandbox OpenAPI document, not on the docs page), `/profile` (route exists; not documented) |
+| **Not served — 404** (gem raises `DhanHQ::SandboxUnsupportedError`) | `/super/orders`, `/alerts/orders`, `/alerts/multi/orders`, `/pnlExit`, `/margincalculator/multi`, `/ip/*`, `/marketfeed/*`, `/optionchain`, `/optionchain/expirylist`, `/charts/rollingoption`, `/data/*` (ScanX), `/globalstocks/*` |
+| **Unclear** | `GET /killswitch` and `DELETE /positions` answer 400 rather than 404 but are absent from both sandbox sources. Iceberg/TWAP (`/v2/orders/iceberg`, `/v2/orders/twap`) are not in any Dhan documentation; the gateway answers any `/v2/orders/*` path, so a probe cannot tell. |
+| **Not supported** | All WebSocket endpoints (order updates, market feed, market depth). Production only. |
+
+The deny-list lives in `DhanHQ::Constants::SANDBOX_UNSUPPORTED_PATH_PREFIXES`. In
+`:hybrid` mode a blocked request is **never** redirected to production — that would turn a
+paper order into a real one.
 
 ---
 
@@ -118,7 +121,7 @@ Paths are as built by the gem (HTTP_PATH + endpoint). Base URL is resolved per t
 | Purpose           | URL / path                     | Method |
 |-------------------|--------------------------------|--------|
 | Generate token    | `https://auth.dhan.co/app/generateAccessToken` | POST   |
-| Renew token       | `https://api.dhan.co/v2/RenewToken`           | POST   |
+| Renew token       | `https://api.dhan.co/v2/RenewToken`           | GET    |
 
 These are **not** mode-aware; they always use the URLs above.
 

data/lib/DhanHQ/auth.rb

@@ -38,18 +38,15 @@ module DhanHQ
     # @param pin [String] Your 6-digit Dhan PIN
     # @param totp [String] 6-digit TOTP code (or use generate_totp helper)
     # @return [Hash] Response hash with accessToken, expiryTime, etc.
-    # @raise [DhanHQ::InvalidAuthenticationError] On authentication failure
+    # @raise [DhanHQ::InvalidAuthenticationError] When Dhan rejects the credentials
+    # @raise [DhanHQ::RateLimitError, DhanHQ::InternalServerError, DhanHQ::NetworkError] On retryable failures
     def self.generate_access_token(dhan_client_id:, pin:, totp:)
-      conn = build_connection(AUTH_BASE_URL)
-
-      response = conn.post("/app/generateAccessToken") do |req|
-        req.headers["Accept"] = "application/json"
-
-        req.params = {
-          dhanClientId: dhan_client_id,
-          pin: pin,
-          totp: totp
-        }
+      response = perform("GenerateAccessToken") do
+        # Relative path: a leading slash would make Faraday discard the base URL's path.
+        build_connection(AUTH_BASE_URL).post("app/generateAccessToken") do |req|
+          req.headers["Accept"] = "application/json"
+          req.params = { dhanClientId: dhan_client_id, pin: pin, totp: totp }
+        end
       end
 
       handle_response(response, context: "GenerateAccessToken")
@@ -57,22 +54,26 @@ module DhanHQ
 
     # Renews a web-generated access token (24h validity).
     #
-    # POST https://api.dhan.co/v2/RenewToken
+    # GET https://api.dhan.co/v2/RenewToken
     #
-    # ⚠️ Works ONLY for tokens generated from Dhan Web dashboard.
+    # ⚠️ Works ONLY for tokens generated from Dhan Web dashboard, and only while
+    # the token is still active; renewing an expired token returns an error.
     # For TOTP-generated tokens, regenerate instead of renewing.
     #
     # @param access_token [String] Current JWT access token
     # @param client_id [String] Dhan client ID (dhanClientId)
     # @return [Hash] Response hash with new accessToken and expiryTime
-    # @raise [DhanHQ::InvalidAuthenticationError] On renewal failure
+    # @raise [DhanHQ::InvalidAuthenticationError] When Dhan rejects the token
+    # @raise [DhanHQ::RateLimitError, DhanHQ::InternalServerError, DhanHQ::NetworkError] On retryable failures
     def self.renew_token(access_token:, client_id:)
-      conn = build_connection(API_BASE_URL)
-
-      response = conn.post("/RenewToken") do |req|
-        req.headers["access-token"] = access_token
-        req.headers["dhanClientId"] = client_id
-        req.headers["Accept"] = "application/json"
+      response = perform("RenewToken") do
+        # Relative path keeps the /v2 base. GET, per Dhan's documented curl
+        # example and the official Python SDK.
+        build_connection(API_BASE_URL).get("RenewToken") do |req|
+          req.headers["access-token"] = access_token
+          req.headers["dhanClientId"] = client_id
+          req.headers["Accept"] = "application/json"
+        end
       end
 
       handle_response(response, context: "RenewToken")
@@ -86,27 +87,55 @@ module DhanHQ
       ROTP::TOTP.new(secret).now
     end
 
-    private
-
+    # Bounded timeouts, same defaults as Client#build_connection: a stalled auth
+    # endpoint must not hang the caller.
     def self.build_connection(base_url)
       Faraday.new(url: base_url) do |c|
         c.request :url_encoded
+        c.options.timeout = ENV.fetch("DHAN_READ_TIMEOUT", 30).to_i
+        c.options.open_timeout = ENV.fetch("DHAN_CONNECT_TIMEOUT", 10).to_i
+        c.options.write_timeout = ENV.fetch("DHAN_WRITE_TIMEOUT", 30).to_i
         c.adapter Faraday.default_adapter
       end
     end
     private_class_method :build_connection
 
+    def self.perform(context)
+      yield
+    rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+      raise DhanHQ::NetworkError, "#{context} request failed: #{e.class}: #{e.message}"
+    end
+    private_class_method :perform
+
+    # Rate limits and server errors are retryable; everything else means the
+    # credentials themselves were refused.
     def self.handle_response(response, context:)
-      unless response.success?
-        body = response.body.is_a?(Hash) ? response.body : {}
-        error_message = body["errorMessage"] || body["message"] || response.body.to_s
+      body = parse_body(response.body)
+      return body if response.success?
 
-        raise DhanHQ::InvalidAuthenticationError,
-              "#{context} failed: #{response.status} #{error_message}"
+      message = body["errorMessage"] || body["message"] || response.body.to_s
+      raise error_class_for(response.status).new("#{context} failed: #{response.status} #{message}".strip, response_body: body)
+    end
+    private_class_method :handle_response
+
+    def self.error_class_for(status)
+      case status
+      when 429 then DhanHQ::RateLimitError
+      when 500..599 then DhanHQ::InternalServerError
+      else DhanHQ::InvalidAuthenticationError
       end
+    end
+    private_class_method :error_class_for
+
+    # Dhan does not always label responses as JSON, so parse whatever arrives.
+    def self.parse_body(body)
+      return body if body.is_a?(Hash)
+      return {} if body.to_s.strip.empty?
 
-      response.body.is_a?(Hash) ? response.body : {}
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      {}
     end
-    private_class_method :handle_response
+    private_class_method :parse_body
   end
 end

data/lib/DhanHQ/client.rb

@@ -130,6 +130,8 @@ module DhanHQ
       payload = with_correlation_id(method, path, payload)
       return dry_run.response_for(method, path, payload) if dry_run.simulates?(method, path)
 
+      ensure_sandbox_supports!(method, path)
+
       @token_manager&.ensure_valid_token!
       @rate_limiter.throttle!
 
@@ -270,6 +272,29 @@ module DhanHQ
 
     private
 
+    # Credentials for this client's API tier: the sandbox pair when the tier
+    # routes to the sandbox host, the production pair otherwise.
+    def request_access_token
+      @config.access_token_for(@api_type)
+    end
+
+    def request_client_id
+      @config.client_id_for(@api_type)
+    end
+
+    # Fails fast when this request would hit the sandbox host on a path it does
+    # not serve (see {Constants::SANDBOX_UNSUPPORTED_PATH_PREFIXES}), instead of
+    # surfacing an opaque 404. Never falls back to production.
+    def ensure_sandbox_supports!(method, path)
+      return unless environment == :sandbox
+      return unless Constants::SANDBOX_UNSUPPORTED_PATH_PREFIXES.any? { |prefix| path.start_with?(prefix) }
+
+      raise DhanHQ::SandboxUnsupportedError,
+            "#{method.to_s.upcase} #{path} is not available on the Dhan sandbox (#{@config.mode} mode routes " \
+            "#{@api_type} to it). For a read-only endpoint, route its tier to production with " \
+            "environment_overrides (e.g. { #{@api_type}: :live }); order-placing endpoints have no sandbox equivalent."
+    end
+
     def resolve_config(config_or_attrs, keyword_config, attrs = {})
       if config_or_attrs.is_a?(DhanHQ::Configuration)
         fork_config_with_attrs(config_or_attrs, attrs)

data/lib/DhanHQ/concerns/order_audit.rb

@@ -84,7 +84,7 @@ module DhanHQ
 
         DhanHQ::Risk::Pipeline.run!(
           instrument: instrument,
-          args: params,
+          args: risk_args(params),
           type: trade_type_for(exchange_segment),
           now: Time.now
         )
@@ -118,6 +118,18 @@ module DhanHQ
         )
       end
 
+      # The risk checks read snake_case String keys ("quantity", "order_type", ...).
+      # Order params arrive as camelCase Strings from the models and as Symbols or
+      # Strings from direct resource callers; without this, every check that reads a
+      # multi-word key silently saw nil, and Symbol-keyed callers failed
+      # "Quantity must be > 0" on a valid quantity.
+      #
+      # @param params [Hash]
+      # @return [Hash{String => Object}]
+      def risk_args(params)
+        (params || {}).to_h.transform_keys { |key| key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase }
+      end
+
       # Maps an exchange segment string to a pipeline trade type.
       def trade_type_for(exchange_segment)
         case exchange_segment.to_s

data/lib/DhanHQ/configuration.rb

@@ -41,6 +41,25 @@ module DhanHQ
     # @return [String, nil] The access token or `nil` if not set.
     attr_accessor :access_token
 
+    # Client ID issued for the Dhan sandbox (generated on Dhan Cloud, cloud.dhanhq.co).
+    #
+    # Dhan runs sandbox and production as separate environments with separate
+    # credentials: a production token is rejected by sandbox.dhan.co and vice
+    # versa. Every request routed to the sandbox host (see {#environment_for})
+    # authenticates with these credentials. In +:sandbox+ mode they fall back to
+    # {#client_id}/{#access_token} when unset, so existing full-sandbox setups
+    # keep working; in +:hybrid+ mode they are required.
+    #
+    # Set via +DHAN_SANDBOX_CLIENT_ID+ or in {DhanHQ.configure}.
+    # @return [String, nil]
+    attr_accessor :sandbox_client_id
+
+    # Access token issued for the Dhan sandbox. See {#sandbox_client_id}.
+    #
+    # Set via +DHAN_SANDBOX_ACCESS_TOKEN+ or in {DhanHQ.configure}.
+    # @return [String, nil]
+    attr_accessor :sandbox_access_token
+
     # Optional callable (Proc/lambda) that returns the access token at request time.
     # When set, {#resolved_access_token} calls this instead of using {#access_token}.
     # @return [Proc, nil]
@@ -286,6 +305,48 @@ module DhanHQ
       mode == :sandbox
     end
 
+    # Client ID to authenticate requests on the given API tier with.
+    #
+    # Sandbox-bound tiers use {#sandbox_client_id}; production-bound tiers use
+    # {#client_id}.
+    #
+    # @param api_type [Symbol, nil]
+    # @return [String, nil]
+    # @raise [DhanHQ::AuthenticationError] When a sandbox-bound tier has no
+    #   sandbox credentials outside +:sandbox+ mode.
+    def client_id_for(api_type)
+      return client_id unless environment_for(api_type) == :sandbox
+
+      sandbox_credential(sandbox_client_id, "sandbox_client_id", "DHAN_SANDBOX_CLIENT_ID", api_type) { client_id }
+    end
+
+    # Access token to authenticate requests on the given API tier with.
+    # See {#client_id_for}.
+    #
+    # @param api_type [Symbol, nil]
+    # @return [String, nil]
+    # @raise [DhanHQ::AuthenticationError]
+    def access_token_for(api_type)
+      return resolved_access_token unless environment_for(api_type) == :sandbox
+
+      sandbox_credential(sandbox_access_token, "sandbox_access_token", "DHAN_SANDBOX_ACCESS_TOKEN", api_type) do
+        resolved_access_token
+      end
+    end
+
+    # Thresholds for the pre-trade risk checks, keyed by {Risk::Limits::NAMES}
+    # (+max_quantity+, +max_notional+, +max_open_positions+, +daily_max_loss+,
+    # +max_concentration_pct+). Unset limits keep each check's built-in default.
+    # Also settable through +DHAN_RISK_*+ variables (see {Risk::Limits::ENV_KEYS}).
+    # @return [Hash{Symbol => Numeric}]
+    attr_reader :risk_limits
+
+    # @param value [Hash, nil]
+    # @raise [ArgumentError] On an unknown limit or a non-positive value.
+    def risk_limits=(value)
+      @risk_limits = Risk::Limits.coerce(value)
+    end
+
     # True when {#mode} is +:hybrid+ — live market data, sandbox execution.
     # @return [Boolean]
     def hybrid?
@@ -320,6 +381,8 @@ module DhanHQ
     def initialize(attrs = {})
       @client_id = attrs[:client_id] || ENV.fetch("DHAN_CLIENT_ID", nil)
       @access_token = attrs[:access_token] || ENV.fetch("DHAN_ACCESS_TOKEN", nil)
+      @sandbox_client_id = attrs[:sandbox_client_id] || ENV.fetch("DHAN_SANDBOX_CLIENT_ID", nil)
+      @sandbox_access_token = attrs[:sandbox_access_token] || ENV.fetch("DHAN_SANDBOX_ACCESS_TOKEN", nil)
       @access_token_provider = attrs[:access_token_provider]
       @on_token_expired = attrs[:on_token_expired]
       @sandbox = attrs.key?(:sandbox) ? attrs[:sandbox] : env_flag("DHAN_SANDBOX", default: false)
@@ -337,6 +400,7 @@ module DhanHQ
         attrs[:environment_overrides] || ENV.fetch("DHAN_ENV_OVERRIDES", nil)
       )
       @mode = resolve_mode(attrs)
+      @risk_limits = attrs.key?(:risk_limits) ? Risk::Limits.coerce(attrs[:risk_limits]) : Risk::Limits.from_env
       @ws_version = (attrs[:ws_version] || ENV.fetch("DHAN_WS_VERSION", 2)).to_i
       @ws_order_url = attrs[:ws_order_url] || ENV.fetch("DHAN_WS_ORDER_URL", nil)
       @ws_market_feed_url = attrs[:ws_market_feed_url] || ENV.fetch("DHAN_WS_MARKET_FEED_URL", nil)
@@ -351,6 +415,21 @@ module DhanHQ
 
     private
 
+    # Returns a sandbox credential, falling back to the production one only in
+    # full +:sandbox+ mode (where the "production" fields have always held the
+    # sandbox credentials). Anywhere else — +:hybrid+, or a tier overridden to
+    # the sandbox — sending a production credential to the sandbox host is a
+    # guaranteed DH-901, so it fails fast with an actionable message instead.
+    def sandbox_credential(value, attr_name, env_name, api_type)
+      return value.to_s unless value.to_s.strip.empty?
+      return yield if mode == :sandbox
+
+      raise DhanHQ::AuthenticationError,
+            "#{attr_name} is required: #{api_type || "this"} requests route to the Dhan sandbox in " \
+            "#{mode} mode, and the sandbox rejects production credentials. " \
+            "Set #{env_name} (generate it on https://cloud.dhanhq.co)."
+    end
+
     # Resolves the initial mode from attributes and ENV.
     #
     # Precedence: an explicit +:mode+ attribute wins, then +DHAN_MODE+, then the

data/lib/DhanHQ/constants.rb

@@ -88,8 +88,12 @@ module DhanHQ
       TRADED = "TRADED"
       EXPIRED = "EXPIRED"
       MODIFIED = "MODIFIED"
+      # Listed in the orderStatus response enum of the order, super order and
+      # slicing endpoints (docs.dhanhq.co).
+      INACTIVE = "INACTIVE"
 
-      ALL = [TRANSIT, PENDING, CLOSED, TRIGGERED, REJECTED, CANCELLED, PART_TRADED, TRADED, EXPIRED, MODIFIED].freeze
+      ALL = [TRANSIT, PENDING, CLOSED, TRIGGERED, REJECTED, CANCELLED, PART_TRADED, TRADED, EXPIRED, MODIFIED,
+             INACTIVE].freeze
     end
 
     # AMO (after market order) timing options.
@@ -597,6 +601,28 @@ module DhanHQ
       "/v2/data"
     ].freeze
 
+    # Path prefixes the Dhan sandbox (https://sandbox.dhan.co/v2) does not serve.
+    #
+    # Derived from the sandbox's own OpenAPI document (sandbox.dhan.co/v2/v3/api-docs)
+    # and the "Sandbox" page of docs.dhanhq.co, and confirmed by each prefix
+    # answering HTTP 404 on the sandbox host. Requests routed to the sandbox for
+    # these paths fail fast with {DhanHQ::SandboxUnsupportedError}.
+    #
+    # Deliberately a deny-list of verified gaps rather than an allow-list: a
+    # sandbox route Dhan adds later keeps working without a gem release.
+    SANDBOX_UNSUPPORTED_PATH_PREFIXES = %w[
+      /v2/marketfeed/
+      /v2/optionchain
+      /v2/charts/rollingoption
+      /v2/data/
+      /v2/super/orders
+      /v2/alerts/
+      /v2/pnlExit
+      /v2/margincalculator/multi
+      /v2/ip/
+      /v2/globalstocks/
+    ].freeze
+
     # Path prefixes for which the request body (POST/PUT/PATCH) must include dhanClientId.
     # Injection is done in the client layer when building the payload.
     PAYLOAD_REQUIRES_DHAN_CLIENT_ID_PREFIXES = %w[

data/lib/DhanHQ/errors.rb

@@ -48,6 +48,12 @@ module DhanHQ
   # Raised when the 25-modifications-per-order API cap would be exceeded.
   # Count is tracked per Order instance in this process only (see Order#modify).
   class ModificationLimitError < Error; end
+  # Raised before any network I/O when a request would be routed to the Dhan
+  # sandbox host for an endpoint the sandbox does not serve (super orders,
+  # conditional orders, P&L exit, market quotes, option chain, ...). The request
+  # is never redirected to production instead: in +:hybrid+ mode that would turn
+  # a paper order into a real one.
+  class SandboxUnsupportedError < Error; end
   # Raised when an order placement is attempted but ENV["LIVE_TRADING"] != "true".
   class LiveTradingDisabledError < Error; end
   # Raised when the API signals an issue with the requested data payload.