DhanHQ 2.4.0 → 2.5.0

data/docs/AUTHENTICATION.md

@@ -113,50 +113,112 @@ Rescue `AuthenticationError` for local config/token resolution failures; rescue
 # SUPPORTED AUTHENTICATION AND TOKEN GENERATION APPROACHES:
 
 We now support five distinct authentication approaches in this gem.
+
 1️⃣ Static token (manual, simplest)
 What: You paste a token you got from Dhan (web, OAuth, partner, whatever) into config.
 How:
-DhanHQ.configure do |config|  config.client_id    = ENV["DHAN_CLIENT_ID"]  config.access_token = ENV["DHAN_ACCESS_TOKEN"]end
+```ruby
+DhanHQ.configure do |config|
+  config.client_id    = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
+end
+```
 When: You’re OK rotating tokens manually (e.g. cron job, ops runbook).
+
 2️⃣ Dynamic token via access_token_provider
 What: Gem asks you for a token on every request (proc/lambda).
 How:
-DhanHQ.configure do |config|  config.client_id = ENV["DHAN_CLIENT_ID"]  config.access_token_provider = -> { MyTokenStore.fetch_current_token }  config.on_token_expired = ->(error) { MyTokenStore.refresh!(error) }end
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = ENV["DHAN_CLIENT_ID"]
+  config.access_token_provider = -> { MyTokenStore.fetch_current_token }
+  config.on_token_expired = ->(error) { MyTokenStore.refresh!(error) }
+end
+```
 Behavior:
 On 401 (auth failure), client calls on_token_expired, then retries once using a fresh token from access_token_provider.
+
 3️⃣ Fetch-from-token-endpoint (configure_from_token_endpoint)
 What: Gem calls your HTTP endpoint once to get access_token + client_id.
 How:
-DhanHQ.configure_from_token_endpoint(  base_url:    "https://myapp.com",  bearer_token: ENV["DHAN_TOKEN_ENDPOINT_BEARER"])# expects JSON: { access_token: "...", client_id: "...", base_url: "..." (optional) }
+```ruby
+DhanHQ.configure_from_token_endpoint(
+  base_url:    "https://myapp.com",
+  bearer_token: ENV["DHAN_TOKEN_ENDPOINT_BEARER"]
+)
+# expects JSON: { access_token: "...", client_id: "...", base_url: "..." (optional) }
+```
 When: Multi-tenant or central credential service, you don’t want tokens in ENV directly.
+
 4️⃣ TOTP-based token generation (new DhanHQ::Auth flow)
 Module API (low-level)
 What: Direct call to Dhan’s generateAccessToken endpoint using TOTP.
-totp = DhanHQ::Auth.generate_totp(ENV["DHAN_TOTP_SECRET"])response = DhanHQ::Auth.generate_access_token(  dhan_client_id: ENV["DHAN_CLIENT_ID"],  pin:           ENV["DHAN_PIN"],  totp:          totp)token  = response["accessToken"]expiry = response["expiryTime"]
+```ruby
+totp = DhanHQ::Auth.generate_totp(ENV["DHAN_TOTP_SECRET"])
+response = DhanHQ::Auth.generate_access_token(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp:          totp
+)
+token  = response["accessToken"]
+expiry = response["expiryTime"]
+```
+
 Client API (high-level, returns TokenResponse)
-client = DhanHQ::Client.new(api_type: :order_api)token = client.generate_access_token(  dhan_client_id: ENV["DHAN_CLIENT_ID"],  pin:           ENV["DHAN_PIN"],  totp_secret:   ENV["DHAN_TOTP_SECRET"] # or `totp:` if you computed it)# auto-applies token + client_id to `DhanHQ.configuration`
+```
+client = DhanHQ::Client.new(api_type: :order_api)
+token = client.generate_access_token(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp_secret:   ENV["DHAN_TOTP_SECRET"] # or `totp:` if you computed it
+)
+# auto-applies token + client_id to `DhanHQ.configuration`
+```
+
 When: Fully automated individual setup (no manual web token generation).
+
 5️⃣ Auto token lifecycle management (TokenManager)
 What: Gem handles generate + renew + retry around every API call.
 How:
-client = DhanHQ::Client.new(api_type: :order_api)client.enable_auto_token_management!(  dhan_client_id: ENV["DHAN_CLIENT_ID"],  pin:           ENV["DHAN_PIN"],  totp_secret:   ENV["DHAN_TOTP_SECRET"])# From now on, `client.request` auto-ensures a valid token.
+```ruby
+client = DhanHQ::Client.new(api_type: :order_api)
+client.enable_auto_token_management!(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp_secret:   ENV["DHAN_TOTP_SECRET"]
+)
+# From now on, `client.request` auto-ensures a valid token.
+```
 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 renewal fails with auth error → falls back to full generate.
+
 6️⃣ Web-token renewal only (RenewToken)
 Module API:
-response = DhanHQ::Auth.renew_token(  access_token: current_token,  client_id:    ENV["DHAN_CLIENT_ID"])
+```ruby
+response = DhanHQ::Auth.renew_token(
+  access_token: current_token,
+  client_id:    ENV["DHAN_CLIENT_ID"]
+)
+```
 Client / manager (high-level):
-client.renew_access_token (returns TokenResponse, updates config).
-TokenManager#refresh! internally uses Auth::TokenRenewal.
+
+`client.renew_access_token` (returns TokenResponse, updates config).
+`TokenManager#refresh!` internally uses Auth::TokenRenewal.
 When: You’re using web-generated 24h tokens and want to extend them without switching to TOTP.
+
 TL;DR
 Manual: Static token (access_token)
+
 Dynamic: access_token_provider (+ optional on_token_expired)
+
 Central service: configure_from_token_endpoint
+
 Fully automated: TOTP generate (Auth / Client#generate_access_token)
+
 Production-grade automation: enable_auto_token_management! (generate + renew)
+
 If you tell me your exact deployment style (single user box, multi-user SaaS, on-prem, etc.), I can tell you which one you should actually use and what to delete as overkill.

data/docs/CONFIGURATION.md

@@ -0,0 +1,109 @@
+# Configuration Reference
+
+This document covers all configuration options for the DhanHQ Ruby client.
+
+## Quick Setup
+
+```ruby
+require 'dhan_hq'
+DhanHQ.configure_with_env
+```
+
+`configure_with_env` reads `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` from `ENV` and raises if either is missing.
+
+## Required Environment Variables
+
+| Variable             | Purpose                                           |
+| -------------------- | ------------------------------------------------- |
+| `DHAN_CLIENT_ID`     | Trading account client ID issued by Dhan          |
+| `DHAN_ACCESS_TOKEN`  | API access token generated from the Dhan console  |
+
+## Optional Environment Variables
+
+Set these _before_ calling `configure_with_env` to override defaults:
+
+| Variable                         | Default    | Description                                             |
+| -------------------------------- | ---------- | ------------------------------------------------------- |
+| `DHAN_LOG_LEVEL`                 | `INFO`     | Logger verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`)     |
+| `DHAN_BASE_URL`                  | Dhan prod  | Point REST calls to a different API hostname            |
+| `DHAN_WS_VERSION`                | latest     | Pin WebSocket connections to a specific API version     |
+| `DHAN_WS_ORDER_URL`              | Dhan prod  | Override the order update WebSocket endpoint            |
+| `DHAN_WS_USER_TYPE`              | `SELF`     | Switch between `SELF` and `PARTNER` streaming modes     |
+| `DHAN_PARTNER_ID`                | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
+| `DHAN_PARTNER_SECRET`            | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
+| `DHAN_CONNECT_TIMEOUT`           | `10`       | Connection timeout in seconds                           |
+| `DHAN_READ_TIMEOUT`              | `30`       | Read timeout in seconds                                 |
+| `DHAN_WRITE_TIMEOUT`             | `30`       | Write timeout in seconds                                |
+| `DHAN_WS_MAX_TRACKED_ORDERS`     | `10000`    | Maximum orders to track in WebSocket                    |
+| `DHAN_WS_MAX_ORDER_AGE`          | `604800`   | Maximum order age in seconds before cleanup (7 days)    |
+
+## `.env` File Setup
+
+Create a `.env` file in your project root:
+
+```dotenv
+DHAN_CLIENT_ID=your_client_id
+DHAN_ACCESS_TOKEN=your_access_token
+
+# Optional overrides
+DHAN_LOG_LEVEL=DEBUG
+DHAN_CONNECT_TIMEOUT=15
+DHAN_READ_TIMEOUT=60
+```
+
+The gem requires `dotenv/load`, so these variables are loaded automatically when you require `dhan_hq`.
+
+## Block-Style Configuration
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id    = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
+end
+```
+
+## Logging
+
+```ruby
+DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
+```
+
+Set `DHAN_LOG_LEVEL=DEBUG` for full HTTP request/response and WebSocket frame logging during development.
+
+## Dynamic Access Token
+
+For production or OAuth-style flows, resolve the token at **request time**:
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = ENV["DHAN_CLIENT_ID"]
+  config.access_token_provider = lambda do
+    token = YourTokenStore.active_token  # e.g. from DB or OAuth
+    raise "Token expired or missing" unless token
+    token
+  end
+  # Optional: called when the API returns 401/token-expired
+  config.on_token_expired = ->(error) { YourTokenStore.refresh! }
+end
+```
+
+- **`access_token_provider`**: Callable (Proc/lambda) returning the token string. Called on every request (no memoization). When set, the gem uses it instead of `access_token`.
+- **`on_token_expired`**: Optional callable invoked when a 401/token-expired triggers a **single retry** (only when `access_token_provider` is set).
+
+For detailed authentication flows, see [AUTHENTICATION.md](AUTHENTICATION.md).
+
+## Available Resources
+
+| Resource                 | Model                                  | Actions                                             |
+| ------------------------ | -------------------------------------- | --------------------------------------------------- |
+| Orders                   | `DhanHQ::Models::Order`                | `find`, `all`, `where`, `place`, `update`, `cancel` |
+| Trades                   | `DhanHQ::Models::Trade`                | `all`, `find_by_order_id`                           |
+| Forever Orders           | `DhanHQ::Models::ForeverOrder`         | `create`, `find`, `modify`, `cancel`, `all`         |
+| Holdings                 | `DhanHQ::Models::Holding`              | `all`                                               |
+| Positions                | `DhanHQ::Models::Position`             | `all`, `find`, `exit!`                              |
+| Funds & Margin           | `DhanHQ::Models::Fund`                 | `fund_limit`, `margin_calculator`                   |
+| Ledger                   | `DhanHQ::Models::Ledger`               | `all`                                               |
+| Market Feeds             | `DhanHQ::Models::MarketFeed`           | `ltp`, `ohlc`, `quote`                              |
+| Historical Data (Charts) | `DhanHQ::Models::HistoricalData`       | `daily`, `intraday`                                 |
+| Option Chain             | `DhanHQ::Models::OptionChain`          | `fetch`, `fetch_expiry_list`                        |
+| Super Orders             | `DhanHQ::Models::SuperOrder`           | `create`, `modify`, `cancel`, `all`                 |

data/docs/SUPER_ORDERS.md

@@ -0,0 +1,284 @@
+# Super Orders — Full API Reference
+
+Super orders are built for smart execution. They club the entry, target, and stop-loss legs (with optional trailing jump) into a single request so you can manage risk immediately after entry.
+
+This gem exposes the full REST surface to create, modify, cancel, and list super orders across all supported exchanges and segments.
+
+## Endpoints
+
+| Method   | Path                                   | Description                           |
+| -------- | -------------------------------------- | ------------------------------------- |
+| `POST`   | `/super/orders`                        | Create a new super order              |
+| `PUT`    | `/super/orders/{order_id}`             | Modify a pending super order          |
+| `DELETE` | `/super/orders/{order_id}/{order_leg}` | Cancel a pending super order leg      |
+| `GET`    | `/super/orders`                        | Retrieve the list of all super orders |
+
+---
+
+## Place Super Order
+
+The place endpoint lets you submit a new super order that can include entry, target, stop-loss, and optional trailing jump definitions. It is available across exchanges and segments, and supports intraday, carry-forward, or MTF orders.
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking this API.
+
+```bash
+curl --request POST \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
+```
+
+### Request body
+
+```json
+{
+  "dhan_client_id": "1000000003",
+  "correlation_id": "123abc678",
+  "transaction_type": "BUY",
+  "exchange_segment": "NSE_EQ",
+  "product_type": "CNC",
+  "order_type": "LIMIT",
+  "security_id": "11536",
+  "quantity": 5,
+  "price": 1500,
+  "target_price": 1600,
+  "stop_loss_price": 1400,
+  "trailing_jump": 10
+}
+```
+
+### Parameters
+
+| Field              | Type                     | Description                                                                                                                                                                     |
+| ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dhan_client_id`   | string *(required)*      | User specific identification generated by Dhan. When you call through `DhanHQ::Models::SuperOrder`, the gem injects your configured client id so you can omit this key locally. |
+| `correlation_id`   | string                   | Caller generated correlation identifier                                                                                                                                         |
+| `transaction_type` | enum string *(required)* | Trading side. `BUY` or `SELL`.                                                                                                                                                  |
+| `exchange_segment` | enum string *(required)* | Exchange segment (see appendix).                                                                                                                                                |
+| `product_type`     | enum string *(required)* | Product type. `CNC`, `INTRADAY`, `MARGIN`, or `MTF`.                                                                                                                            |
+| `order_type`       | enum string *(required)* | Order type. `LIMIT` or `MARKET`.                                                                                                                                                |
+| `security_id`      | string *(required)*      | Exchange standard security identifier.                                                                                                                                          |
+| `quantity`         | integer *(required)*     | Number of shares for the order.                                                                                                                                                 |
+| `price`            | float *(required)*       | Price at which the entry leg is placed.                                                                                                                                         |
+| `target_price`     | float *(required)*       | Target price for the super order.                                                                                                                                               |
+| `stop_loss_price`  | float *(required)*       | Stop-loss price for the super order.                                                                                                                                            |
+| `trailing_jump`    | float *(required)*       | Price jump size used to trail the stop-loss.                                                                                                                                    |
+
+> 🐍 When you call `DhanHQ::Models::SuperOrder.create`, pass snake_case keys as shown above. The client automatically camelizes
+> them before posting to Dhan's REST API and injects your configured `dhan_client_id`, so you can omit that key in Ruby code.
+
+### Response
+
+```json
+{
+  "order_id": "112111182198",
+  "order_status": "PENDING"
+}
+```
+
+| Field          | Type        | Description                                         |
+| -------------- | ----------- | --------------------------------------------------- |
+| `order_id`     | string      | Order identifier generated by Dhan                  |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, or `REJECTED`. |
+
+---
+
+## Modify Super Order
+
+Use the modify endpoint to update any leg while the super order remains in `PENDING` or `PART_TRADED` status.
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking this API.
+
+```bash
+curl --request PUT \
+  --url https://api.dhan.co/v2/super/orders/{order_id} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
+```
+
+### Request body
+
+```json
+{
+  "dhan_client_id": "1000000009",
+  "order_id": "112111182045",
+  "order_type": "LIMIT",
+  "leg_name": "ENTRY_LEG",
+  "quantity": 40,
+  "price": 1300,
+  "target_price": 1450,
+  "stop_loss_price": 1350,
+  "trailing_jump": 20
+}
+```
+
+### Parameters
+
+| Field             | Type                                   | Description                                                                                                               |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `dhan_client_id`  | string *(required)*                    | User specific identification generated by Dhan. Automatically added when you call through the Ruby models.                |
+| `order_id`        | string *(required)*                    | Super order identifier generated by Dhan.                                                                                 |
+| `order_type`      | enum string *(conditionally required)* | `LIMIT` or `MARKET`. Required when modifying `ENTRY_LEG`.                                                                 |
+| `leg_name`        | enum string *(required)*               | `ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`. Entry leg updates entire order while status is `PENDING` or `PART_TRADED`. |
+| `quantity`        | integer *(conditionally required)*     | Quantity update for `ENTRY_LEG`.                                                                                          |
+| `price`           | float *(conditionally required)*       | Entry price update for `ENTRY_LEG`.                                                                                       |
+| `target_price`    | float *(conditionally required)*       | Target price update for `ENTRY_LEG` or `TARGET_LEG`.                                                                      |
+| `stop_loss_price` | float *(conditionally required)*       | Stop-loss price update for `ENTRY_LEG` or `STOP_LOSS_LEG`.                                                                |
+| `trailing_jump`   | float *(conditionally required)*       | Trailing jump update for `ENTRY_LEG` or `STOP_LOSS_LEG`. Omit or set to `0` to cancel trailing.                           |
+
+> ℹ️ Once the entry leg status becomes `TRADED`, only the `TARGET_LEG` and `STOP_LOSS_LEG` can be modified (price and trailing jump).
+
+### Response
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "TRANSIT"
+}
+```
+
+| Field          | Type        | Description                                                   |
+| -------------- | ----------- | ------------------------------------------------------------- |
+| `order_id`     | string      | Order identifier generated by Dhan                            |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, `REJECTED`, or `TRADED`. |
+
+---
+
+## Cancel Super Order
+
+Cancel a pending or active super order leg using the order ID. Cancelling the entry leg removes every leg. Cancelling a specific target or stop-loss leg removes only that leg and it cannot be re-added.
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking this API.
+
+```bash
+curl --request DELETE \
+  --url https://api.dhan.co/v2/super/orders/{order_id}/{order_leg} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+### Path parameters
+
+| Field       | Description                                                   | Example       |
+| ----------- | ------------------------------------------------------------- | ------------- |
+| `order_id`  | Super order identifier.                                       | `11211182198` |
+| `order_leg` | Leg to cancel. `ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`. | `ENTRY_LEG`   |
+
+### Response
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "CANCELLED"
+}
+```
+
+| Field          | Type        | Description                                                      |
+| -------------- | ----------- | ---------------------------------------------------------------- |
+| `order_id`     | string      | Order identifier generated by Dhan                               |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, `REJECTED`, or `CANCELLED`. |
+
+---
+
+## Super Order List
+
+List every super order placed during the trading day. The API nests leg details under the entry leg, and individual legs also appear in the main order book.
+
+```bash
+curl --request GET \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+### Response
+
+```json
+[
+  {
+    "dhan_client_id": "1100003626",
+    "order_id": "5925022734212",
+    "correlation_id": "string",
+    "order_status": "PENDING",
+    "transaction_type": "BUY",
+    "exchange_segment": "NSE_EQ",
+    "product_type": "CNC",
+    "order_type": "LIMIT",
+    "validity": "DAY",
+    "trading_symbol": "HDFCBANK",
+    "security_id": "1333",
+    "quantity": 10,
+    "remaining_quantity": 10,
+    "ltp": 1660.95,
+    "price": 1500,
+    "after_market_order": false,
+    "leg_name": "ENTRY_LEG",
+    "exchange_order_id": "11925022734212",
+    "create_time": "2025-02-27 19:09:42",
+    "update_time": "2025-02-27 19:09:42",
+    "exchange_time": "2025-02-27 19:09:42",
+    "oms_error_description": "",
+    "average_traded_price": 0,
+    "filled_qty": 0,
+    "leg_details": [
+      {
+        "order_id": "5925022734212",
+        "leg_name": "STOP_LOSS_LEG",
+        "transaction_type": "SELL",
+        "total_quantity": 0,
+        "remaining_quantity": 0,
+        "triggered_quantity": 0,
+        "price": 1400,
+        "order_status": "PENDING",
+        "trailing_jump": 10
+      },
+      {
+        "order_id": "5925022734212",
+        "leg_name": "TARGET_LEG",
+        "transaction_type": "SELL",
+        "remaining_quantity": 0,
+        "triggered_quantity": 0,
+        "price": 1550,
+        "order_status": "PENDING",
+        "trailing_jump": 0
+      }
+    ]
+  }
+]
+```
+
+### Response Parameters
+
+| Field                   | Type        | Description                                                                                         |
+| ----------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
+| `dhan_client_id`        | string      | User specific identification generated by Dhan.                                                     |
+| `order_id`              | string      | Order identifier generated by Dhan.                                                                 |
+| `correlation_id`        | string      | Correlation identifier supplied by the caller.                                                      |
+| `order_status`          | enum string | Latest status. `TRANSIT`, `PENDING`, `CLOSED`, `REJECTED`, `CANCELLED`, `PART_TRADED`, or `TRADED`. |
+| `transaction_type`      | enum string | Trading side. `BUY` or `SELL`.                                                                      |
+| `exchange_segment`      | enum string | Exchange segment.                                                                                   |
+| `product_type`          | enum string | Product type. `CNC`, `INTRADAY`, `MARGIN`, or `MTF`.                                                |
+| `order_type`            | enum string | Order type. `LIMIT` or `MARKET`.                                                                    |
+| `validity`              | enum string | Order validity. `DAY`.                                                                              |
+| `trading_symbol`        | string      | Trading symbol reference.                                                                           |
+| `security_id`           | string      | Exchange security identifier.                                                                       |
+| `quantity`              | integer     | Ordered quantity.                                                                                   |
+| `remaining_quantity`    | integer     | Quantity pending execution.                                                                         |
+| `ltp`                   | float       | Last traded price.                                                                                  |
+| `price`                 | float       | Order price.                                                                                        |
+| `after_market_order`    | boolean     | Indicates if the order was placed after market hours.                                               |
+| `leg_name`              | enum string | Leg identifier: `ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`.                                      |
+| `trailing_jump`         | float       | Trailing jump for stop-loss.                                                                        |
+| `exchange_order_id`     | string      | Exchange-generated order identifier.                                                                |
+| `create_time`           | string      | Order creation timestamp.                                                                           |
+| `update_time`           | string      | Latest update timestamp.                                                                            |
+| `exchange_time`         | string      | Exchange timestamp.                                                                                 |
+| `oms_error_description` | string      | OMS error description when applicable.                                                              |
+| `average_traded_price`  | float       | Average traded price.                                                                               |
+| `filled_qty`            | integer     | Quantity traded on the exchange.                                                                    |
+| `triggered_quantity`    | integer     | Quantity triggered for stop-loss or target legs.                                                    |
+| `leg_details`           | array       | Nested leg details for the super order.                                                             |
+
+> ✅ `CLOSED` indicates the entry leg plus either target or stop-loss leg completed for the entire quantity. `TRIGGERED` appears on target and stop-loss legs to show which leg fired; inspect `triggered_quantity` for the executed quantity.

data/docs/TROUBLESHOOTING.md

@@ -0,0 +1,117 @@
+# Troubleshooting
+
+Common issues and solutions when working with the DhanHQ Ruby client.
+
+---
+
+## 429: Unexpected Response Code
+
+**Symptom:** WebSocket connection fails with a 429 status.
+
+**Cause:** Too many connections opened in quick succession, or exceeding the per-user WebSocket connection limit (5 per user).
+
+**Solution:**
+- The client automatically cools off for **60 seconds** and retries with exponential backoff.
+- Prefer `ws.disconnect!` before reconnecting to cleanly release server-side resources.
+- Call `DhanHQ::WS.disconnect_all_local!` to kill any straggler connections.
+- Avoid rapid connect/disconnect loops — the client handles backoff internally.
+
+```ruby
+# Kill all local WebSocket connections
+DhanHQ::WS.disconnect_all_local!
+
+# Wait before reconnecting
+sleep(2)
+
+# Reconnect
+client = DhanHQ::WS.connect(mode: :ticker) { |tick| puts tick[:ltp] }
+```
+
+---
+
+## No Ticks After Reconnect
+
+**Symptom:** WebSocket reconnects successfully but no market data arrives.
+
+**Cause:** Subscriptions were not restored after the connection dropped.
+
+**Solution:**
+- The client **automatically resends** the current subscription snapshot on reconnect — this should work transparently.
+- If you're managing connections manually, ensure you re-subscribe after a clean start.
+- Check that your instruments are valid and the market is open.
+
+---
+
+## Binary Parse Errors
+
+**Symptom:** Errors in logs related to binary frame parsing.
+
+**Cause:** Malformed or unexpected binary frames from the server.
+
+**Solution:**
+- The client safely drops malformed frames and keeps the event loop alive.
+- Run with `DHAN_LOG_LEVEL=DEBUG` to inspect raw frames:
+
+```bash
+export DHAN_LOG_LEVEL=DEBUG
+```
+
+```ruby
+DhanHQ.logger.level = Logger::DEBUG
+```
+
+---
+
+## Authentication Errors
+
+| Error Class                          | Meaning                                                    |
+| ------------------------------------ | ---------------------------------------------------------- |
+| `DhanHQ::AuthenticationError`        | Token could not be resolved (missing config, nil provider) |
+| `DhanHQ::InvalidAuthenticationError` | API returned 401 or error code DH-901                      |
+| `DhanHQ::TokenExpiredError`          | API returned error code 807 (token expired)                |
+| `DhanHQ::InvalidTokenError`          | API returned error code 809 (invalid token)                |
+
+**Solutions:**
+- Verify `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` are set correctly.
+- If using `access_token_provider`, ensure it returns a non-nil string.
+- For 401 retries: the client retries **once** with a fresh token when `access_token_provider` is configured.
+- See [AUTHENTICATION.md](AUTHENTICATION.md) for detailed token lifecycle handling.
+
+---
+
+## Connection Timeouts
+
+**Symptom:** REST API calls hang or fail with timeout errors.
+
+**Solution:** Adjust timeout settings via environment variables:
+
+```dotenv
+DHAN_CONNECT_TIMEOUT=15   # default: 10 seconds
+DHAN_READ_TIMEOUT=60      # default: 30 seconds
+DHAN_WRITE_TIMEOUT=60     # default: 30 seconds
+```
+
+---
+
+## Debug Logging
+
+Enable full debug output to diagnose any issue:
+
+```ruby
+DhanHQ.logger.level = Logger::DEBUG
+```
+
+Or via environment:
+
+```bash
+export DHAN_LOG_LEVEL=DEBUG
+```
+
+This logs HTTP requests/responses, WebSocket frames, and internal state transitions.
+
+---
+
+## Getting Help
+
+- [DhanHQ GitHub Issues](https://github.com/shubhamtaywade82/dhanhq-client/issues)
+- [Dhan API Documentation](https://dhanhq.co/docs/v2/)