DhanHQ 2.6.2 → 2.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4469f87602b1825aa53ac5d53ef3493fb3a6fd40b00fd58199f23ba3c4a3e129
-  data.tar.gz: 7b5c65ab06cf2f945f488af2ab63499eb9a5fe2cea6ec04579db12a227ac121e
+  metadata.gz: ef2616285615327c5e0ad08a85440d91617ea66818add0a55e4cd6c5e65512aa
+  data.tar.gz: 4232cfcd4c9626683e3bf993f75aa0a8add2f8c83702435c66edb2c58a3e252e
 SHA512:
-  metadata.gz: 13683dc64df357c014a4427bbf3ee9981f3c52ad12795cd7f08d02e3d2cab3597efdb3668f63521f3bd2d43d616ac5ba577b11e104b304738c1b1c0769438bd2
-  data.tar.gz: cc2992611f9d3d4c785be89edc8bb3c33bffb6170a2575a20c532c8ff4ee9838bc1bf0021cdec6327349ff008fa7ae278b8e56d7cc2286310df3d0f4cd604292
+  metadata.gz: c0ba9cd2119899ed6c9eaefe27601b142e75abbc541538f241058712b82bccdc5fab6af888489c5ac01423c1bfb387e42cdfcee22487bbafce6d32c7ce6f54b2
+  data.tar.gz: 4107fc9f9a5ced70692469c21a88f2ed6979739af7e3ef5444d1506e5ba574ba4124f2f7f264747a147157164610606ff22408dcd3612649cb19b9f1e558ca8a

data/.rubocop.yml

@@ -28,9 +28,21 @@ RSpec/ExampleLength:
 RSpec/MultipleMemoizedHelpers:
   Max: 10
 
+Lint/ScriptPermission:
+  Exclude:
+    - "bin/**/*"
+
+Metrics/AbcSize:
+  Exclude:
+    - "bin/call_all_endpoints.rb"
+
+Layout/LineLength:
+  Exclude:
+    - "bin/call_all_endpoints.rb"
+
 DhanHQ/UseConstants:
   Enabled: true
   Exclude:
-    - 'lib/DhanHQ/constants.rb'
-    - 'lib/DhanHQ/ws/segments.rb'
-    - 'spec/**/*'
+    - "lib/DhanHQ/constants.rb"
+    - "lib/DhanHQ/ws/segments.rb"
+    - "spec/**/*"

data/ARCHITECTURE.md

@@ -0,0 +1,113 @@
+# dhanhq-client Architecture
+
+This document describes the architecture of the DhanHQ v2 API client gem: layers, dependencies, and design patterns in use.
+
+## Guiding principles
+
+- **Dependency rule**: High-level policy (models, domain) does not depend on low-level details (HTTP, JSON). Infrastructure (Client, BaseAPI) depends on configuration and helpers; models depend on resources (abstractions) and contracts.
+- **Single responsibility**: Each layer has one reason to change. Models own domain behavior; resources own HTTP; contracts own validation rules.
+- **Open/closed**: New endpoints are added by adding new Model + Resource + Contract pairs without modifying BaseAPI or BaseModel core.
+- **Don’t force patterns**: Patterns (Strategy, Factory Method, Facade) emerged from refactoring; we avoid speculative abstraction.
+
+---
+
+## Layer overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Entry & configuration (lib/dhan_hq.rb, Configuration)          │
+├─────────────────────────────────────────────────────────────────┤
+│  Domain / facade layer (Models)                                 │
+│  Order, Position, MarketFeed, OptionChain, ExpiredOptionsData…  │
+│  → validate via Contracts, delegate HTTP to Resources           │
+├─────────────────────────────────────────────────────────────────┤
+│  REST / HTTP layer (Resources, BaseAPI, BaseResource)           │
+│  → build path, format params, call Client                       │
+├─────────────────────────────────────────────────────────────────┤
+│  Transport layer (Client, RateLimiter, RequestHelper,           │
+│  ResponseHelper)                                                │
+│  → Faraday, headers, retries, error mapping                     │
+├─────────────────────────────────────────────────────────────────┤
+│  Validation (Contracts)                                         │
+│  → Dry::Validation, shared macros in BaseContract               │
+├─────────────────────────────────────────────────────────────────┤
+│  WebSocket (WS::*) — separate subsystem                         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Directory structure and roles
+
+| Path | Role | Responsibility |
+|------|------|----------------|
+| `lib/dhan_hq.rb` | Entry point | Zeitwerk setup, eager load of core/helpers/errors, `DhanHQ.configure` |
+| `core/` | Base abstractions | BaseAPI (HTTP verbs, path building, param formatting), BaseModel (attributes, resource, validation, CRUD helpers), BaseResource (CRUD on BaseAPI), AuthAPI, ErrorHandler |
+| `helpers/` | Cross-cutting | APIHelper, AttributeHelper (keys, normalization), ValidationHelper (validate_params!, validate!), RequestHelper (headers, payload, build_from_response), ResponseHelper (parse_json, handle_response, error mapping) |
+| `models/` | Domain / facade | Typed wrappers (Order, Position, Holding, etc.). Define `resource`, optional `validation_contract`, and domain methods. Validate then delegate to resource. |
+| `resources/` | REST wrappers | One class per API surface (Orders, Positions, MarketFeed, OptionChain, …). Set `HTTP_PATH`, `API_TYPE`; implement get/post/put/delete via BaseAPI. |
+| `contracts/` | Request/response validation | Dry::Validation contracts (PlaceOrderContract, ModifyOrderContract, OptionChainContract, etc.). BaseContract provides shared macros (e.g. lot_size, tick_size). |
+| `auth/` | Token lifecycle | Token generator/renewal/manager for dynamic tokens. |
+| `ws/` | WebSocket | Connection, packets, decoder, market depth, orders client — isolated from REST. |
+
+---
+
+## Dependency flow
+
+- **Configuration** is global (`DhanHQ.configuration`). Client and helpers read it (access_token, client_id, base_url).
+- **Models** depend on:
+  - **Resources** (Factory Method: `resource` returns the right BaseAPI subclass)
+  - **Contracts** (for validate_params!)
+  - **Helpers** (via BaseModel: ValidationHelper, RequestHelper, ResponseHelper, AttributeHelper, APIHelper)
+- **Resources** depend on:
+  - **Client** (injected via BaseAPI: `DhanHQ::Client.new(api_type)`)
+  - **Helpers** (BaseAPI includes APIHelper, AttributeHelper; Client uses RequestHelper, ResponseHelper)
+- **Client** depends on Configuration, RateLimiter, and helpers. No dependency on Models or Resources.
+- **Contracts** depend on Constants (and optional instrument_meta). No dependency on Models or HTTP.
+
+So: **Models → Resources → Client**; **Contracts** are used by Models (and optionally Resources); **Helpers** are used by Client, BaseAPI, and BaseModel.
+
+---
+
+## Design patterns in use
+
+| Pattern | Where | Purpose |
+|--------|--------|--------|
+| **Facade** | Models (e.g. `Order.place`, `MarketFeed.ltp`) | Single entry point for “place order” or “get LTP”; hide validation, normalization, and resource call. |
+| **Factory Method** | BaseModel `resource` | Subclasses override `resource` to return the correct REST wrapper (e.g. Orders, OptionChain) without callers knowing the class. |
+| **Strategy** | BaseAPI `param_formatter_for(full_path)` | Choose how to format params by path: pass-through (marketfeed), titleize (optionchain), default camelize. Encapsulated in lambdas. |
+| **Template Method** | BaseModel `save` | `save` calls `new_record? ? create : update`; subclasses override `create`/`update` or collection methods. |
+| **Adapter** | RequestHelper / ResponseHelper | Adapt external API (headers, JSON, status codes) to internal hashes and error classes. |
+| **Singleton (per API type)** | RateLimiter.for(api_type) | One rate limiter per API type so all clients share limits. |
+
+---
+
+## Error handling
+
+- **Validation failures**: Raised as `DhanHQ::ValidationError` with a message that includes contract errors (e.g. `"Invalid parameters: #{result.errors.to_h}"`). Used by ValidationHelper, ExpiredOptionsData, Trade, and any code that validates via contracts.
+- **HTTP / API errors**: Mapped in ResponseHelper (e.g. 401 → InvalidAuthenticationError, 807 → TokenExpiredError) and raised as appropriate `DhanHQ::*` subclasses.
+- **Client** retries on auth failures (once, with token refresh) and on transient/network errors (with backoff).
+
+---
+
+## Configuration
+
+- Credentials and URLs live in `DhanHQ::Configuration` (access_token, client_id, base_url, sandbox, optional access_token_provider).
+- `DhanHQ.configure { }`, `configure_with_env`, and `configure_from_token_endpoint` set configuration. Never hardcode credentials; use env vars or token endpoint.
+
+---
+
+## WebSocket (WS)
+
+- Separate subsystem under `DhanHQ::WS`: own connection, packet types, decoder, market depth, orders client.
+- Shares configuration (e.g. access token) but not the REST Client or Resources. Documented in code and specs; not expanded here.
+
+---
+
+## Adding a new API surface
+
+1. **Contract** (optional): Add a Dry::Validation contract under `contracts/` if the endpoint has structured input.
+2. **Resource**: Add a class under `resources/` inheriting BaseAPI (or BaseResource). Set `HTTP_PATH`, `API_TYPE`; implement methods that call `get`/`post`/`put`/`delete`.
+3. **Model**: Add a class under `models/` inheriting BaseModel. Override `resource` to return the new resource; override `validation_contract` if needed; implement class/instance methods that call `validate_params!` then `resource.*`.
+
+This keeps the dependency rule and keeps each layer focused on one concern.

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+## [2.6.3] - 2026-03-14
+
+### Added
+
+- **Constants::Urls**: All canonical Dhan API/auth/WebSocket URLs in one place (`REST_API_BASE`, `SANDBOX_API_BASE`, `AUTH_BASE`, `WS_MARKET_FEED`, `WS_ORDER_UPDATE`, `WS_DEPTH_20`, `WS_DEPTH_200`, `INSTRUMENT_CSV_*`, `DOCS`, `ORIGIN`). Configuration, Auth, and WS defaults now use these constants.
+- **Order modification limit enforcement**: `Order#modify` enforces Dhan’s 25-modifications-per-order cap per instance; the 26th modify raises `DhanHQ::ModificationLimitError` and does not call the API. Count is in-process only (fresh `find` resets it).
+- **DhanHQ::ModificationLimitError**: New error class for the 25-per-order limit (rescuable).
+- **API error payload on exceptions**: Raised API errors now expose the full response body as `error.response_body` (e.g. `errorCode`, `errorMessage`, and any future keys like `errors` or `details`). Useful for logging and debugging.
+- **DH-905 message hint**: For `InputExceptionError` (DH-905), the exception message now includes a note that the Dhan API does not return which field failed, and to check required params and value types for the endpoint.
+- **Kill switch status validation**: `Resources::KillSwitch#update(status)` and `Models::KillSwitch.update(status)` now validate that `status` is `ACTIVATE` or `DEACTIVATE` (case-insensitive); invalid values raise `DhanHQ::ValidationError` before the request.
+- **Super order cancel leg validation**: `Resources::SuperOrders#cancel(order_id, leg_name)` validates `leg_name` against the API path enum (`ENTRY_LEG`, `STOP_LOSS_LEG`, `TARGET_LEG`); invalid values raise `DhanHQ::ValidationError`.
+
+### Changed
+
+- **SliceOrderContract**: Aligned with Dhan v2 orders doc — `amoTime` now allows `PRE_OPEN`; validity restricted to `DAY`/`IOC`; product type restricted to `CNC`/`INTRADAY`/`MARGIN`/`MTF`; `correlationId` max length 30 (was 25).
+- **Order#modify** YARD: Documented modification limit and `ModificationLimitError`.
+- **Error#initialize**: `DhanHQ::Error` now accepts an optional `response_body:` keyword argument so API-raised errors can carry the parsed response. Subclasses unchanged; `raise ErrorClass, "msg"` still works.
+- **ResponseHelper**: When the API returns extra keys (`errors`, `details`, `validationErrors`), they are appended to the exception message. DH-905 errors include the endpoint hint above.
+- **Margin contracts**: `MarginCalculatorContract` and `MultiScripMarginCalcRequestContract` accept optional `orderType` (per OpenAPI; some accounts require it). `Margin` model and `bin/test_all` margin payloads send `order_type: LIMIT` when `DHAN_TEST_MARGIN=true`.
+- **bin/test_all**: Fixed `ArgumentError: wrong number of arguments (given 1, expected 0)` by invoking endpoint lambdas with no arguments inside `Timeout.timeout` (the timeout block receives the duration). Refactored `endpoint_list` for RuboCop Metrics/AbcSize; optional read endpoints (forever order by id, PnL exit, margin) are skipped unless `DHAN_TEST_FOREVER_ORDER_ID`, `DHAN_TEST_PNL_EXIT=true`, or `DHAN_TEST_MARGIN=true` are set.
+
+### Fixed
+
+- **bin/test_all**: All 30 read endpoints now run successfully by default (26 called, 4 optional); margin/PnL/forever-by-id no longer fail when fixtures are missing.
+
+### Removed
+
+- **docs/DHAN_V2_GAPS.md**: Removed; path/behavior alignment remains in `docs/API_VERIFICATION.md`.
+
+---
+
 ## [2.6.2] - 2026-03-07
 
 ### Changed

data/README.md

@@ -75,6 +75,8 @@ gem install DhanHQ
 
 > **Bleeding edge?** Use `gem 'DhanHQ', git: 'https://github.com/shubhamtaywade82/dhanhq-client.git', branch: 'main'` only if you need unreleased features.
 
+**`bundle update` / `bundle install` warnings** — If you see "Local specification for rexml-3.2.8 has different dependencies" or "Unresolved or ambiguous specs during Gem::Specification.reset: psych", the bundle still completes successfully. To clear the rexml warning once, run: `gem cleanup rexml`. The psych message is a known Bundler quirk and can be ignored.
+
 ### ⚠️ Breaking Change (v2.1.5+)
 
 The require statement changed:

data/docs/API_VERIFICATION.md

@@ -1,13 +1,12 @@
 # API Verification (Dhan v2)
 
-This document records how the gem’s implementation aligns with the official Dhan API v2 docs.
+Path/behavior alignment with the official Dhan API v2 docs.
 
 **Sources:**
 
 - [dhanhq.co/docs/v2](https://dhanhq.co/docs/v2/) – main docs
 - [dhanhq.co/docs/v2/edis](https://dhanhq.co/docs/v2/edis/) – EDIS
 - [api.dhan.co/v2](https://api.dhan.co/v2/#/) – Developer Kit (when available)
-- In-repo: `CODE_REVIEW_ISSUES.md` (Alert Orders, IP Setup paths)
 
 ---
 
@@ -32,7 +31,7 @@ This document records how the gem’s implementation aligns with the official Dh
 
 | Doc path                  | Gem resource              | Path used        |
 |---------------------------|---------------------------|------------------|
-| `/alerts/orders`          | `Resources::AlertOrders`  | `HTTP_PATH = "/alerts/orders"` |
+| `/alerts/orders`          | `Resources::AlertOrders`  | `HTTP_PATH = "/v2/alerts/orders"` |
 | GET/POST `/alerts/orders` | `#all`, `#create`         | BaseResource     |
 | GET/PUT/DELETE `/alerts/orders/{trigger-id}` | `#find`, `#update`, `#delete` | `/{id}` |
 
@@ -46,16 +45,19 @@ Model: `Models::AlertOrder`. Condition must include `exchange_segment`, `exp_dat
 
 | Doc path        | Gem method     | Path / body |
 |-----------------|----------------|-------------|
-| GET /ip/getIP   | `#current`     | `get("/getIP")` |
-| POST /ip/setIP  | `#set(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` | `post("/setIP", params: { ip:, ip_flag:, dhan_client_id: })`; `dhan_client_id` defaults from config |
-| PUT /ip/modifyIP| `#update(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` | `put("/modifyIP", params: { ip:, ip_flag:, dhan_client_id: })` |
+| GET /v2/ip/getIP   | `#current`     | `get("/getIP")` (HTTP_PATH = "/v2/ip") |
+| POST /v2/ip/setIP  | `#set(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` | `post("/setIP", params: { ip:, ip_flag:, dhan_client_id: })`; `dhan_client_id` defaults from config |
+| PUT /v2/ip/modifyIP| `#update(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` | `put("/modifyIP", params: { ip:, ip_flag:, dhan_client_id: })` |
 
 ---
 
 ## Trader Control / Kill Switch
 
-- **Kill Switch:** `Resources::KillSwitch`, `Models::KillSwitch` – path `/v2/killswitch`. Manage (activate/deactivate) uses **query parameter** per [traders-control](https://dhanhq.co/docs/v2/traders-control/): `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or `DEACTIVATE`) with no body. `#status` is GET.
-- **Trader Control:** `Resources::TraderControl` – path `/trader-control`; `#status`, `#enable`, `#disable`. Not found on the public docs; kept for compatibility.
+**Doc:** [dhanhq.co/docs/v2](https://dhanhq.co/docs/v2/) → Trading APIs → Trader's Control.
+
+- **Kill Switch:** `Resources::KillSwitch`, `Models::KillSwitch` – path `/v2/killswitch`. Manage (activate/deactivate) uses **query parameter**: `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or `DEACTIVATE`) with no body. `#status` is GET.
+- **P&L Exit:** `Models::PnlExit` – path `/v2/pnlExit`. GET status, POST configure, DELETE stop.
+- **TraderControl:** `Resources::TraderControl` – path `/trader-control` is **not** in the Dhan v2 API. The class is kept for backward compatibility but raises `DhanHQ::Error` when any method is called; use KillSwitch and PnlExit instead.
 
 ---
 

data/docs/ENDPOINTS_AND_SANDBOX.md

@@ -101,3 +101,15 @@ These are **not** sandbox-aware; they always use the URLs above.
 - **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.
 - **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
+
+`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.
+
+```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
+```
+
+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.

data/lib/DhanHQ/auth.rb

@@ -27,8 +27,8 @@ module DhanHQ
   #     client_id: ENV["DHAN_CLIENT_ID"]
   #   )
   module Auth
-    AUTH_BASE_URL = "https://auth.dhan.co"
-    API_BASE_URL  = "https://api.dhan.co/v2"
+    AUTH_BASE_URL = Constants::Urls::AUTH_BASE
+    API_BASE_URL  = Constants::Urls::REST_API_BASE
 
     # Generates an access token using TOTP authentication.
     #

data/lib/DhanHQ/client.rb

@@ -61,48 +61,56 @@ module DhanHQ
     # @raise [DhanHQ::Error] If an HTTP error occurs.
     def request(method, path, payload, retries: 3)
       @token_manager&.ensure_valid_token!
-      @rate_limiter.throttle! # **Ensure we don't hit rate limit before calling API**
-
-      # Ensure connection matches current configuration (e.g. sandbox toggle)
+      @rate_limiter.throttle!
       refresh_connection!
 
-      attempt = 0
-      auth_retry_done = false
-      begin
-        response = connection.send(method, path) do |req|
-          req.headers.merge!(build_headers(path))
-          prepare_payload(req, payload, method, path)
+      with_auth_retry do
+        with_transient_retry(retries: retries) do
+          response = connection.send(method, path) do |req|
+            req.headers.merge!(build_headers(path))
+            prepare_payload(req, payload, method, path)
+          end
+          handle_response(response)
         end
+      end
+    end
 
-        handle_response(response)
-      rescue DhanHQ::InvalidAuthenticationError, DhanHQ::InvalidTokenError,
-             DhanHQ::TokenExpiredError, DhanHQ::AuthenticationFailedError => e
-        config = DhanHQ.configuration
-        if !auth_retry_done && config&.access_token_provider
-          auth_retry_done = true
-          config.on_token_expired&.call(e)
-          DhanHQ.logger&.warn("[DhanHQ::Client] Auth failure (#{e.class}), retrying once with fresh token")
-          retry
-        end
-        raise
+    def with_auth_retry
+      yield
+    rescue DhanHQ::InvalidAuthenticationError, DhanHQ::InvalidTokenError,
+           DhanHQ::TokenExpiredError, DhanHQ::AuthenticationFailedError => e
+      config = DhanHQ.configuration
+      raise unless config&.access_token_provider
+
+      config.on_token_expired&.call(e)
+      DhanHQ.logger&.warn("[DhanHQ::Client] Auth failure (#{e.class}), retrying once with fresh token")
+      yield
+    end
+
+    def with_transient_retry(retries:)
+      attempt = 0
+      begin
+        yield
       rescue DhanHQ::RateLimitError, DhanHQ::InternalServerError, DhanHQ::NetworkError => e
         attempt += 1
-        if attempt <= retries
-          backoff_time = calculate_backoff(attempt)
-          DhanHQ.logger&.warn("[DhanHQ::Client] Transient error (#{e.class}), retrying in #{backoff_time}s (attempt #{attempt}/#{retries})")
-          sleep(backoff_time)
-          retry
-        end
-        raise
+        raise if attempt > retries
+
+        backoff = calculate_backoff(attempt)
+        DhanHQ.logger&.warn(
+          "[DhanHQ::Client] Transient error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
+        )
+        sleep(backoff)
+        retry
       rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
         attempt += 1
-        if attempt <= retries
-          backoff_time = calculate_backoff(attempt)
-          DhanHQ.logger&.warn("[DhanHQ::Client] Network error (#{e.class}), retrying in #{backoff_time}s (attempt #{attempt}/#{retries})")
-          sleep(backoff_time)
-          retry
-        end
-        raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}"
+        raise DhanHQ::NetworkError, "Request failed after #{retries} retries: #{e.message}" if attempt > retries
+
+        backoff = calculate_backoff(attempt)
+        DhanHQ.logger&.warn(
+          "[DhanHQ::Client] Network error (#{e.class}), retrying in #{backoff}s (attempt #{attempt}/#{retries})"
+        )
+        sleep(backoff)
+        retry
       end
     end
 

data/lib/DhanHQ/configuration.rb

@@ -9,13 +9,12 @@ module DhanHQ
   # @see https://dhanhq.co/docs/v2/ DhanHQ API Documentation
   class Configuration
     # Default REST API host used when the base URL is not overridden.
-    #
     # @return [String]
-    BASE_URL = "https://api.dhan.co/v2"
+    BASE_URL = Constants::Urls::REST_API_BASE
 
     # Default Sandbox API host.
     # @return [String]
-    SANDBOX_URL = "https://sandbox.dhan.co/v2"
+    SANDBOX_URL = Constants::Urls::SANDBOX_API_BASE
     # The client ID for API authentication.
     # @return [String, nil] The client ID or `nil` if not set.
     attr_accessor :client_id
@@ -58,21 +57,21 @@ module DhanHQ
     # Sandbox does not support WebSocket; always returns production URL unless overridden.
     # @return [String]
     def ws_order_url
-      @ws_order_url || "wss://api-order-update.dhan.co"
+      @ws_order_url || Constants::Urls::WS_ORDER_UPDATE
     end
 
     # Websocket market feed endpoint.
     # Sandbox does not support WebSocket; always returns production URL unless overridden.
     # @return [String]
     def ws_market_feed_url
-      @ws_market_feed_url || "wss://api-feed.dhan.co"
+      @ws_market_feed_url || Constants::Urls::WS_MARKET_FEED
     end
 
     # Websocket market depth endpoint.
     # Sandbox does not support WebSocket; always returns production URL unless overridden.
     # @return [String]
     def ws_market_depth_url
-      @ws_market_depth_url || "wss://depth-api-feed.dhan.co/twentydepth"
+      @ws_market_depth_url || Constants::Urls::WS_DEPTH_20
     end
 
     # Market depth level (20 or 200).

data/lib/DhanHQ/constants.rb

@@ -18,6 +18,14 @@ module DhanHQ
       BSE_FNO = "BSE_FNO"
 
       ALL = [IDX_I, NSE_EQ, NSE_FNO, NSE_CURRENCY, NSE_COMM, BSE_EQ, MCX_COMM, BSE_CURRENCY, BSE_FNO].freeze
+      # Segments allowed by POST /v2/margincalculator (single and multi).
+      MARGIN_CALC_ALL = [NSE_EQ, NSE_FNO, BSE_EQ, BSE_FNO, MCX_COMM].freeze
+      # Segments allowed by POST /v2/forever/orders (create).
+      FOREVER_ORDER_ALL = [NSE_EQ, NSE_FNO, BSE_EQ, BSE_FNO, MCX_COMM].freeze
+      # Segments for conditional trigger (equities and indices only). POST/PUT /v2/alerts/orders.
+      ALERT_CONDITION_ALL = [NSE_EQ, BSE_EQ, IDX_I].freeze
+      # Segments allowed by POST /v2/charts/historical and POST /v2/charts/intraday (excludes NSE_COMM).
+      CHART_ALL = [IDX_I, NSE_EQ, NSE_FNO, NSE_CURRENCY, BSE_EQ, BSE_FNO, BSE_CURRENCY, MCX_COMM].freeze
     end
 
     # Product types for order placement.
@@ -30,6 +38,10 @@ module DhanHQ
       BO = "BO"
 
       ALL = [CNC, INTRADAY, MARGIN, MTF, CO, BO].freeze
+      # Product types allowed by POST /v2/margincalculator (single and multi).
+      MARGIN_CALC_ALL = [CNC, INTRADAY, MARGIN, MTF].freeze
+      # Product types allowed by POST /v2/forever/orders (create). Only CNC and MTF.
+      FOREVER_ORDER_ALL = [CNC, MTF].freeze
     end
 
     # Buy/Sell transaction types.
@@ -112,6 +124,17 @@ module DhanHQ
     # Backward-compatible alias kept for existing SDK usage.
     Instrument = InstrumentType
 
+    # Minute intervals allowed by POST /v2/charts/intraday (charts annexure).
+    module ChartInterval
+      ONE = "1"
+      FIVE = "5"
+      FIFTEEN = "15"
+      TWENTY_FIVE = "25"
+      SIXTY = "60"
+
+      ALL = [ONE, FIVE, FIFTEEN, TWENTY_FIVE, SIXTY].freeze
+    end
+
     # Option types for derivatives trading.
     module OptionType
       CALL = "CALL"
@@ -365,10 +388,33 @@ module DhanHQ
       ORDER_MODIFICATIONS_PER_ORDER = 25
     end
 
+    # Canonical Dhan API, auth, WebSocket and instrument URLs (see https://dhanhq.co/docs/v2/).
+    # Configuration and Auth use these as defaults; ENV overrides apply at runtime.
+    module Urls
+      REST_API_BASE = "https://api.dhan.co/v2"
+      SANDBOX_API_BASE = "https://sandbox.dhan.co/v2"
+      AUTH_BASE = "https://auth.dhan.co"
+      WS_MARKET_FEED = "wss://api-feed.dhan.co"
+      WS_ORDER_UPDATE = "wss://api-order-update.dhan.co"
+      WS_DEPTH_20 = "wss://depth-api-feed.dhan.co/twentydepth"
+      WS_DEPTH_200 = "wss://full-depth-api.dhan.co/twohundreddepth"
+      INSTRUMENT_CSV_COMPACT = "https://images.dhan.co/api-data/api-scrip-master.csv"
+      INSTRUMENT_CSV_DETAILED = "https://images.dhan.co/api-data/api-scrip-master-detailed.csv"
+      DOCS = "https://dhanhq.co/docs/v2"
+      # Origin header value for WebSocket connections (Dhan main site).
+      ORIGIN = "https://dhanhq.co"
+    end
+
     # Backward-compatible arrays used across existing validations.
     TRANSACTION_TYPES = TransactionType::ALL
     EXCHANGE_SEGMENTS = ExchangeSegment::ALL
+    CHART_EXCHANGE_SEGMENTS = ExchangeSegment::CHART_ALL
     INSTRUMENTS = InstrumentType::ALL
+    CHART_INTERVALS = ChartInterval::ALL
+    MARGIN_CALCULATOR_SEGMENTS = ExchangeSegment::MARGIN_CALC_ALL
+    MARGIN_PRODUCT_TYPES = ProductType::MARGIN_CALC_ALL
+    FOREVER_ORDER_SEGMENTS = ExchangeSegment::FOREVER_ORDER_ALL
+    FOREVER_ORDER_PRODUCT_TYPES = ProductType::FOREVER_ORDER_ALL
     PRODUCT_TYPES = ProductType::ALL
     ORDER_TYPES = OrderType::ALL
     VALIDITY_TYPES = Validity::ALL
@@ -376,6 +422,8 @@ module DhanHQ
     ORDER_STATUSES = OrderStatus::ALL
     COMPARISON_TYPES = ComparisonType::ALL
     OPERATORS = Operator::ALL
+    ALERT_CONDITION_SEGMENTS = ExchangeSegment::ALERT_CONDITION_ALL
+    ALERT_TIMEFRAMES = %w[DATE ONE_MIN FIVE_MIN FIFTEEN_MIN DAY].freeze
 
     # Exchange aliases used when building subscription payloads.
     NSE = ExchangeSegment::NSE_EQ
@@ -387,7 +435,8 @@ module DhanHQ
     BSE_FNO = ExchangeSegment::BSE_FNO
     INDEX = ExchangeSegment::IDX_I
 
-    OPTION_SEGMENTS = [NSE, BSE, CUR, MCX, FNO, NSE_FNO, BSE_FNO, INDEX].freeze
+    # Underlying segments accepted by POST /v2/optionchain and POST /v2/optionchain/expirylist.
+    OPTION_CHAIN_UNDERLYING_SEGMENTS = %w[IDX_I NSE_FNO BSE_FNO MCX_FO].freeze
 
     # Canonical labels kept for compatibility with previous SDK versions.
     BUY = TransactionType::BUY
@@ -409,19 +458,30 @@ module DhanHQ
     IOC = Validity::IOC
 
     # Download URL for the compact instrument master CSV.
-    COMPACT_CSV_URL = "https://images.dhan.co/api-data/api-scrip-master.csv"
+    COMPACT_CSV_URL = Urls::INSTRUMENT_CSV_COMPACT
     # Download URL for the detailed instrument master CSV.
-    DETAILED_CSV_URL = "https://images.dhan.co/api-data/api-scrip-master-detailed.csv"
+    DETAILED_CSV_URL = Urls::INSTRUMENT_CSV_DETAILED
 
     # API route prefixes that require a `client-id` header in addition to the access token.
     DATA_API_PREFIXES = [
       "/v2/marketfeed/",
       "/v2/optionchain",
       "/v2/instrument/",
-      "/v2/charts",
-      "/v2/margincalculator",
-      "/v2/profile",
-      "/v2/fundlimit"
+      "/v2/charts"
+    ].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[
+      /alerts/orders
+      /v2/orders
+      /v2/forever
+      /v2/super/orders
+      /v2/positions
+      /v2/pnlExit
+      /v2/margincalculator
+      /v2/killswitch
+      /v2/ip
     ].freeze
 
     # Mapping of exchange and segment combinations to canonical exchange segment names.

data/lib/DhanHQ/contracts/alert_order_contract.rb

@@ -2,45 +2,52 @@
 
 module DhanHQ
   module Contracts
-    # Validates alert order payloads for create/update per dhanhq.co/docs/v2/conditional-trigger/
-    # Condition requires exchange_segment, exp_date, frequency; time_frame required for TECHNICAL_* comparison types.
+    # Validates Conditional Trigger (alert order) payloads for POST /v2/alerts/orders and PUT /v2/alerts/orders/{alertId}.
+    # Condition: exchangeSegment (NSE_EQ|BSE_EQ|IDX_I), timeframe (required), comparisonType, operator, expDate, frequency;
+    #   indicatorName/time_frame required for TECHNICAL_* comparison types.
+    # Orders: transactionType, exchangeSegment, productType (CNC|INTRADAY|MARGIN|MTF), orderType, securityId,
+    #   quantity, validity, price (required); discQuantity, triggerPrice optional.
     class AlertOrderContract < BaseContract
       params do
         required(:condition).hash do
           required(:security_id).filled(:string, max_size?: 20)
-          required(:exchange_segment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
+          required(:exchange_segment).filled(:string, included_in?: ALERT_CONDITION_SEGMENTS)
           required(:comparison_type).filled(:string, included_in?: COMPARISON_TYPES)
-          optional(:indicator_name).maybe(:string)
-          optional(:time_frame).maybe(:string)
+          required(:time_frame).filled(:string, included_in?: ALERT_TIMEFRAMES)
           required(:operator).filled(:string, included_in?: OPERATORS)
+          required(:exp_date).filled(:string, format?: /\A\d{4}-\d{2}-\d{2}\z/)
+          required(:frequency).filled(:string)
+          optional(:indicator_name).maybe(:string)
           optional(:comparing_value).maybe(:float)
           optional(:comparing_indicator_name).maybe(:string)
-          required(:exp_date).filled(:string)
-          required(:frequency).filled(:string)
+          optional(:user_note).maybe(:string)
         end
         required(:orders).array(:hash) do
           required(:transaction_type).filled(:string, included_in?: TRANSACTION_TYPES)
           required(:exchange_segment).filled(:string, included_in?: EXCHANGE_SEGMENTS)
-          required(:product_type).filled(:string, included_in?: PRODUCT_TYPES)
+          required(:product_type).filled(:string, included_in?: MARGIN_PRODUCT_TYPES)
           required(:order_type).filled(:string, included_in?: ORDER_TYPES)
           required(:security_id).filled(:string, max_size?: 20)
           required(:quantity).filled(:integer, gt?: 0)
           required(:validity).filled(:string, included_in?: VALIDITY_TYPES)
-          optional(:price).maybe(:float)
-          optional(:trigger_price).maybe(:float)
+          required(:price).filled # string or number; API expects string, coerce in serialization
+          optional(:disc_quantity).maybe(:string)
+          optional(:trigger_price).maybe(:string)
         end
       end
 
       rule(condition: :indicator_name) do
-        if values[:condition] && values[:condition][:comparison_type].to_s.start_with?("TECHNICAL") && !value
-          key(condition: :indicator_name).failure("is required for technical comparisons")
-        end
+        next unless values.dig(:condition, :comparison_type).to_s.start_with?("TECHNICAL")
+        next if value && !value.to_s.strip.empty?
+
+        key(%i[condition indicator_name]).failure("is required for technical comparisons")
       end
 
       rule(condition: :time_frame) do
-        if values[:condition] && values[:condition][:comparison_type].to_s.start_with?("TECHNICAL") && !value
-          key(condition: :time_frame).failure("is required for technical comparisons")
-        end
+        next unless values.dig(:condition, :comparison_type).to_s.start_with?("TECHNICAL")
+        next if value && !value.to_s.strip.empty?
+
+        key(%i[condition time_frame]).failure("is required for technical comparisons")
       end
     end
   end

data/lib/DhanHQ/contracts/expired_options_data_contract.rb

@@ -23,7 +23,9 @@ module DhanHQ
       end
 
       rule(:exchange_segment) do
-        valid_segments = %w[NSE_FNO BSE_FNO NSE_EQ BSE_EQ]
+        # IDX_I for index options, NSE_EQ/BSE_EQ for equity options,
+        # plus NSE_FNO/BSE_FNO for derivatives.
+        valid_segments = %w[IDX_I NSE_EQ BSE_EQ NSE_FNO BSE_FNO]
         key.failure("must be one of: #{valid_segments.join(", ")}") unless valid_segments.include?(value)
       end
 
@@ -43,7 +45,7 @@ module DhanHQ
       end
 
       rule(:strike) do
-        unless value.match?(/\AATM(\+|-)?\d*\z/) || value == "ATM"
+        unless value.match?(/\AATM(\+|-)?\d+\z/) || value == "ATM"
           key.failure("must be in format ATM, ATM+1, ATM-1, etc. " \
                       "(up to ATM+10/ATM-10 for Index Options, ATM+3/ATM-3 for others)")
         end