DhanHQ 2.1.3 → 2.1.6

data/README.md

@@ -4,8 +4,28 @@ A clean Ruby client for **Dhan API v2** with ORM-like models (Orders, Positions,
 
 * ActiveRecord-style models: `find`, `all`, `where`, `save`, `update`, `cancel`
 * Validations & errors exposed via ActiveModel-like interfaces
-* REST coverage: Orders, Super Orders, Forever Orders, Trades, Positions, Holdings, Funds/Margin, HistoricalData, OptionChain, MarketFeed
-* **WebSocket**: subscribe/unsubscribe dynamically, auto-reconnect with backoff, 429 cool-off, idempotent subs, header+payload binary parsing, normalized ticks
+* REST coverage: Orders, Super Orders, Forever Orders, Trades, Positions, Holdings, Funds/Margin, HistoricalData, OptionChain, MarketFeed, ExpiredOptionsData
+* **WebSocket**: Orders, Market Feed, Market Depth - subscribe/unsubscribe dynamically, auto-reconnect with backoff, 429 cool-off, idempotent subs, header+payload binary parsing, normalized ticks
+
+## ⚠️ BREAKING CHANGE NOTICE
+
+**IMPORTANT**: Starting from version 2.1.5, the require statement has changed:
+
+```ruby
+# OLD (deprecated)
+require 'DhanHQ'
+
+# NEW (current)
+require 'dhan_hq'
+```
+
+**Migration**: Update all your `require 'DhanHQ'` statements to `require 'dhan_hq'` in your codebase. This change affects:
+- All Ruby files that require the gem
+- Documentation examples
+- Scripts and automation tools
+- Rails applications using this gem
+
+The gem name remains `DhanHQ` in your Gemfile, only the require statement changes.
 
 ---
 
@@ -36,7 +56,7 @@ gem install DhanHQ
 ### From ENV / .env
 
 ```ruby
-require 'DhanHQ'
+require 'dhan_hq'
 
 DhanHQ.configure_with_env
 DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
@@ -126,153 +146,194 @@ initializers, service objects, workers, and ActionCable wiring tailored for the
 
 ---
 
-## WebSocket Market Feed (NEW)
+## WebSocket Integration (Orders, Market Feed, Market Depth)
 
-### What you get
+The DhanHQ gem provides comprehensive WebSocket integration with three distinct WebSocket types, featuring improved architecture, security, and reliability:
 
-* **Modes**
+### Key Features
 
-  * `:ticker` → LTP + LTT
-  * `:quote`  → OHLCV + totals (recommended default)
-  * `:full`   → quote + **OI** + **best-5 depth**
-* **Normalized ticks** (Hash):
+- **🔒 Secure Logging** - Sensitive information (access tokens) are automatically sanitized from logs
+- **⚡ Rate Limit Protection** - Built-in protection against 429 errors with proper connection management
+- **🔄 Automatic Reconnection** - Exponential backoff with 60-second cool-off periods
+- **🧵 Thread-Safe Operation** - Safe for Rails applications and multi-threaded environments
+- **📊 Comprehensive Examples** - Ready-to-use examples for all WebSocket types
+- **🛡️ Error Handling** - Robust error handling and connection management
+- **🔍 Dynamic Symbol Resolution** - Easy instrument lookup using `.find()` method
 
-  ```ruby
-  {
-    kind: :quote,                 # :ticker | :quote | :full | :oi | :prev_close | :misc
-    segment: "NSE_FNO",           # string enum
-    security_id: "12345",
-    ltp: 101.5,
-    ts:  1723791300,              # LTT epoch (sec) if present
-    vol: 123456,                  # quote/full
-    atp: 100.9,                   # quote/full
-    day_open: 100.1, day_high: 102.4, day_low: 99.5, day_close: nil,
-    oi: 987654,                   # full or OI packet
-    bid: 101.45, ask: 101.55      # from depth (mode :full)
-  }
-  ```
+### 1. Orders WebSocket - Real-time Order Updates
 
-### Start, subscribe, stop
+Receive live updates whenever your orders transition between states (placed → traded → cancelled, etc.).
 
 ```ruby
-require 'DhanHQ'
-
-DhanHQ.configure_with_env
-DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
-
-ws = DhanHQ::WS::Client.new(mode: :quote).start
-
-ws.on(:tick) do |t|
-  puts "[#{t[:segment]}:#{t[:security_id]}] LTP=#{t[:ltp]} kind=#{t[:kind]}"
+# Simple connection
+DhanHQ::WS::Orders.connect do |order_update|
+  puts "Order Update: #{order_update.order_no} - #{order_update.status}"
+  puts "  Symbol: #{order_update.symbol}"
+  puts "  Quantity: #{order_update.quantity}"
+  puts "  Traded Qty: #{order_update.traded_qty}"
+  puts "  Price: #{order_update.price}"
+  puts "  Execution: #{order_update.execution_percentage}%"
 end
 
-# Subscribe instruments (≤100 per frame; send multiple frames if needed)
-ws.subscribe_one(segment: "IDX_I",   security_id: "13")     # NIFTY index value
-ws.subscribe_one(segment: "NSE_FNO", security_id: "12345")  # an option
-
-# Unsubscribe
-ws.unsubscribe_one(segment: "NSE_FNO", security_id: "12345")
+# Advanced usage with multiple event handlers
+client = DhanHQ::WS::Orders.client
+client.on(:update) { |order| puts "📝 Order updated: #{order.order_no}" }
+client.on(:status_change) { |change| puts "🔄 Status: #{change[:previous_status]} -> #{change[:new_status]}" }
+client.on(:execution) { |exec| puts "✅ Executed: #{exec[:new_traded_qty]} shares" }
+client.on(:order_rejected) { |order| puts "❌ Rejected: #{order.order_no}" }
+client.start
+```
 
-# Graceful disconnect (sends broker disconnect code 12, no reconnect)
-ws.disconnect!
+### 2. Market Feed WebSocket - Live Market Data
 
-# Or hard stop (no broker message, just closes and halts loop)
-ws.stop
+Subscribe to real-time market data for indices and stocks.
 
-# Safety: kill all local sockets (useful in IRB)
-DhanHQ::WS.disconnect_all_local!
-```
+```ruby
+# Ticker data (LTP updates) - Recommended for most use cases
+market_client = DhanHQ::WS.connect(mode: :ticker) do |tick|
+  timestamp = tick[:ts] ? Time.at(tick[:ts]) : Time.now
+  puts "Market Data: #{tick[:segment]}:#{tick[:security_id]} = #{tick[:ltp]} at #{timestamp}"
+end
 
-### Under the hood
+# Subscribe to major Indian indices
+market_client.subscribe_one(segment: "IDX_I", security_id: "13")  # NIFTY
+market_client.subscribe_one(segment: "IDX_I", security_id: "25")  # BANKNIFTY
+market_client.subscribe_one(segment: "IDX_I", security_id: "29")  # NIFTYIT
+market_client.subscribe_one(segment: "IDX_I", security_id: "51")  # SENSEX
 
-* **Request codes** (per Dhan docs)
+# Quote data (LTP + volume + OHLC)
+DhanHQ::WS.connect(mode: :quote) do |quote|
+  puts "#{quote[:symbol]}: LTP=#{quote[:ltp]}, Volume=#{quote[:vol]}"
+end
 
-  * Subscribe: **15** (ticker), **17** (quote), **21** (full)
-  * Unsubscribe: **16**, **18**, **22**
-  * Disconnect: **12**
-* **Limits**
+# Full market data
+DhanHQ::WS.connect(mode: :full) do |full|
+  puts "#{full[:symbol]}: #{full.inspect}"
+end
+```
 
-  * Up to **100 instruments per SUB/UNSUB** message (client auto-chunks)
-  * Up to 5 WS connections per user (per Dhan)
-* **Backoff & 429 cool-off**
+### 3. Market Depth WebSocket - Real-time Market Depth
 
-  * Exponential backoff with jitter
-  * Handshake **429** triggers a **60s cool-off** before retry
-* **Reconnect & resubscribe**
+Get real-time market depth data including bid/ask levels and order book information.
 
-  * On reconnect the client resends the **current subscription snapshot** (idempotent)
-* **Graceful shutdown**
+```ruby
+# Real-time market depth for stocks (using dynamic symbol resolution with underlying_symbol)
+reliance = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+tcs = DhanHQ::Models::Instrument.find("NSE_EQ", "TCS")
 
-  * `ws.disconnect!` or `ws.stop` prevents reconnects
-  * An `at_exit` hook stops all registered WS clients to avoid leaked sockets
+symbols = []
+if reliance
+  symbols << { symbol: "RELIANCE", exchange_segment: reliance.exchange_segment, security_id: reliance.security_id }
+end
+if tcs
+  symbols << { symbol: "TCS", exchange_segment: tcs.exchange_segment, security_id: tcs.security_id }
+end
 
----
+DhanHQ::WS::MarketDepth.connect(symbols: symbols) do |depth_data|
+  puts "Market Depth: #{depth_data[:symbol]}"
+  puts "  Best Bid: #{depth_data[:best_bid]}"
+  puts "  Best Ask: #{depth_data[:best_ask]}"
+  puts "  Spread: #{depth_data[:spread]}"
+  puts "  Bid Levels: #{depth_data[:bids].size}"
+  puts "  Ask Levels: #{depth_data[:asks].size}"
+end
+```
 
-## Order Update WebSocket (NEW)
+### Unified WebSocket Architecture
 
-Receive live updates whenever your orders transition between states (placed → traded → cancelled, etc.).
+All WebSocket connections provide:
+- **Automatic reconnection** with exponential backoff
+- **Thread-safe operation** for Rails applications
+- **Consistent event handling** patterns
+- **Built-in error handling** and logging
+- **429 rate limiting** protection with cool-off periods
+- **Secure logging** with automatic credential sanitization
 
-### Standalone Ruby script
+### Connection Management
 
 ```ruby
-require 'DhanHQ'
+# Sequential connections to avoid rate limiting (recommended)
+orders_client = DhanHQ::WS::Orders.connect { |order| puts "Order: #{order.order_no}" }
+orders_client.stop
+sleep(2)  # Wait between connections
 
-DhanHQ.configure_with_env
-DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
+market_client = DhanHQ::WS.connect(mode: :ticker) { |tick| puts "Market: #{tick[:symbol]}" }
+market_client.stop
+sleep(2)
 
-ou = DhanHQ::WS::Orders::Client.new.start
+depth_client = DhanHQ::WS::MarketDepth.connect(symbols: symbols) { |depth| puts "Depth: #{depth[:symbol]}" }
+depth_client.stop
 
-ou.on(:update) do |payload|
-  data = payload[:Data] || {}
-  puts "ORDER #{data[:OrderNo]} #{data[:Status]} traded=#{data[:TradedQty]} avg=#{data[:AvgTradedPrice]}"
-end
+# Check connection status
+puts "Orders connected: #{orders_client.connected?}"
+puts "Market connected: #{market_client.connected?}"
+puts "Depth connected: #{depth_client.connected?}"
 
-# Keep the script alive (CTRL+C to exit)
-sleep
-
-# Later, stop the socket
-ou.stop
+# Graceful shutdown
+DhanHQ::WS.disconnect_all_local!
 ```
 
-Or, if you just need a quick callback:
+### Examples
 
-```ruby
-DhanHQ::WS::Orders.connect do |payload|
-  # handle :update callbacks only
-end
-```
+The gem includes comprehensive examples in the `examples/` directory:
 
-### Rails bot integration
+- `market_feed_example.rb` - Market Feed WebSocket with major indices
+- `order_update_example.rb` - Order Update WebSocket with event handling
+- `market_depth_example.rb` - Market Depth WebSocket with RELIANCE and TCS
+- `comprehensive_websocket_examples.rb` - All three WebSocket types
 
-Mirror the market-feed supervisor by adding an Order Update hub singleton that hydrates your local DB and hands off to execution services.
+Run examples:
 
-1. **Service** – `app/services/live/order_update_hub.rb`
+```bash
+# Individual examples
+bundle exec ruby examples/market_feed_example.rb
+bundle exec ruby examples/order_update_example.rb
+bundle exec ruby examples/market_depth_example.rb
 
-   ```ruby
-   Live::OrderUpdateHub.instance.start!
-   ```
+# Comprehensive example
+bundle exec ruby examples/comprehensive_websocket_examples.rb
+```
 
-   The hub wires `DhanHQ::WS::Orders::Client` to:
+### Instrument Model with Trading Fields
 
-   * Upsert local `BrokerOrder` rows so UIs always reflect current broker status.
-   * Auto-subscribe traded entry legs on your existing `Live::WsHub` (if defined).
-   * Refresh `Execution::PositionGuard` (if present) with fill prices/qty for trailing exits.
+The Instrument model now includes comprehensive trading fields for order validation, risk management, and compliance:
 
-2. **Initializer** – `config/initializers/order_update_hub.rb`
+```ruby
+# Find instrument with trading fields
+reliance = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+
+# Trading permissions and restrictions
+puts "Trading Allowed: #{reliance.buy_sell_indicator == 'A'}"
+puts "Bracket Orders: #{reliance.bracket_flag == 'Y' ? 'Supported' : 'Not Supported'}"
+puts "Cover Orders: #{reliance.cover_flag == 'Y' ? 'Supported' : 'Not Supported'}"
+puts "ASM/GSM Status: #{reliance.asm_gsm_flag == 'Y' ? reliance.asm_gsm_category : 'No Restrictions'}"
+
+# Margin and leverage information
+puts "ISIN: #{reliance.isin}"
+puts "MTF Leverage: #{reliance.mtf_leverage}x"
+puts "Buy Margin %: #{reliance.buy_co_min_margin_per}%"
+puts "Sell Margin %: #{reliance.sell_co_min_margin_per}%"
+```
 
-   ```ruby
-   if ENV["ENABLE_WS"] == "true"
-     Rails.application.config.to_prepare do
-       Live::OrderUpdateHub.instance.start!
-     end
+**Available Trading Fields:**
+- `isin` - International Securities Identification Number
+- `instrument_type` - Classification (ES, INDEX, FUT, OPT)
+- `expiry_flag` - Whether instrument has expiry
+- `bracket_flag` - Bracket order support
+- `cover_flag` - Cover order support
+- `asm_gsm_flag` - Additional Surveillance Measure status
+- `buy_sell_indicator` - Trading permission
+- `buy_co_min_margin_per` - Buy CO minimum margin percentage
+- `sell_co_min_margin_per` - Sell CO minimum margin percentage
+- `mtf_leverage` - Margin Trading Facility leverage
 
-     at_exit { Live::OrderUpdateHub.instance.stop! }
-   end
-   ```
+### Comprehensive Documentation
 
-   Flip `ENABLE_WS=true` in your Procfile or `.env` to boot the hub alongside the existing feed supervisor. On shutdown the client is stopped cleanly to avoid leaked sockets.
+The gem includes detailed documentation for different integration scenarios:
 
-The hub is resilient to missing dependencies—if you do not have a `BrokerOrder` model, it safely skips persistence while keeping downstream callbacks alive.
+- **[WebSocket Integration Guide](docs/websocket_integration.md)** - Complete guide covering all WebSocket types and trading fields
+- **[Rails Integration Guide](docs/rails_websocket_integration.md)** - Rails-specific patterns and best practices
+- **[Standalone Ruby Guide](docs/standalone_ruby_websocket_integration.md)** - Scripts, daemons, and CLI tools
 
 ---
 
@@ -377,40 +438,283 @@ end
 
 ---
 
-## Super Orders (example)
+## Super Orders
 
-```ruby
-intent = {
-  exchange_segment: "NSE_FNO",
-  security_id:      "12345",   # option
-  transaction_type: "BUY",
-  quantity:         50,
-  # derived risk params from ATR/ADX
-  take_profit:      0.35,      # 35% target
-  stop_loss:        0.18,      # 18% SL
-  trailing_sl:      0.12       # 12% trail
+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
 }
+```
 
-# If your SuperOrder model exposes create/modify:
-o = DhanHQ::Models::SuperOrder.create(intent)
-# or fallback:
-mkt = DhanHQ::Models::Order.new(
-  transaction_type: "BUY", exchange_segment: "NSE_FNO",
-  order_type: "MARKET", validity: "DAY",
-  security_id: "12345", quantity: 50
-).save
+#### 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"
+}
 ```
 
-If you placed a Super Order and want to trail SL upward using WS ticks:
+| Field          | Type        | Description                                         |
+| -------------- | ----------- | --------------------------------------------------- |
+| `order_id`     | string      | Order identifier generated by Dhan                  |
+| `order_status` | enum string | Latest status. `TRANSIT`, `PENDING`, or `REJECTED`. |
 
-```ruby
-DhanHQ::Models::SuperOrder.modify(
-  order_id: o.order_id,
-  stop_loss: new_abs_price,    # broker API permitting
-  trailing_sl: nil
-)
+### 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
+      }
+    ]
+  }
+]
+```
+
+#### 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.
+
 ---
 
 ## Packet parsing (for reference)