DhanHQ 3.0.1 → 3.2.0

data/README.md

@@ -117,7 +117,11 @@ For the full dependency flow and extension pattern, see [ARCHITECTURE.md](ARCHIT
 - **Instrument convenience methods** — `.ltp`, `.ohlc`, `.option_chain` directly on instruments
 - **Order audit logging** — every order attempt logs machine, IP, environment, and correlation ID as structured JSON
 - **Live trading guard** — prevents accidental order placement unless `ENV["LIVE_TRADING"]="true"`
-- **Full REST coverage** — Orders, Trades, Forever Orders, Super Orders, Positions, Holdings, Funds, HistoricalData, OptionChain, MarketFeed, EDIS, Kill Switch, P&L Exit, Alert Orders, Margin Calculator
+- **Dry-run mode** — `config.dry_run = true` validates and logs every write while reads stay live, so a full strategy can be rehearsed against real prices
+- **No duplicate orders on retry** — transient failures on order writes are surfaced, not blindly retried
+- **Global Stocks (US equities)** — separate order book, holdings, trades, USD funds, market status, charge estimator and margin calculator
+- **Basket orders** — up to 15 orders in a single request, with per-leg acceptance results
+- **Full REST coverage** — Orders, Trades, Forever Orders, Super Orders, Multi (basket) Orders, Positions, Holdings, Funds, HistoricalData, OptionChain, MarketFeed, EDIS, Kill Switch, P&L Exit, Alert Orders, Margin Calculator, IP Setup, Global Stocks
 - **P&L Based Exit** — automatic position exit on profit/loss thresholds
 - **Postback parser** — parse Dhan webhook payloads with `Postback.parse` and status predicates
 - **EDIS model** — ORM-style T-PIN, form, and status inquiry for delivery instruction slips
@@ -127,10 +131,12 @@ For the full dependency flow and extension pattern, see [ARCHITECTURE.md](ARCHIT
 ## Reliability & Safety
 
 - retry-on-401 with token refresh
-- WebSocket auto-reconnect and backoff
+- WebSocket auto-reconnect, backoff, and automatic re-subscription
 - 429 rate-limit protection
 - live trading guard via `LIVE_TRADING=true`
 - structured order audit logs
+- dry-run mode via `DHAN_DRY_RUN=true`
+- order writes are never silently retried, so a timeout cannot become two orders
 
 See [ARCHITECTURE.md](ARCHITECTURE.md), [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md), and [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for the deeper implementation details.
 
@@ -219,6 +225,95 @@ LIVE_TRADING=false   # or simply omit
 
 Attempting to place an order without `LIVE_TRADING=true` raises `DhanHQ::LiveTradingDisabledError`.
 
+### Dry-Run Mode
+
+`dry_run` suppresses every request that would change account state — order placement,
+modification, cancellation, position exits, kill switch, P&L exit — while letting reads
+through untouched. Market data, the option chain, positions and holdings stay live, so a
+strategy can be rehearsed end-to-end against real prices without any risk of an order
+reaching the exchange.
+
+```ruby
+DhanHQ.configure do |config|
+  config.dry_run = true      # or DHAN_DRY_RUN=true
+end
+
+order = DhanHQ::Models::Order.place(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::INTRADAY,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  validity: DhanHQ::Constants::Validity::DAY,
+  security_id: "11536", quantity: 5, price: 1500.0
+)
+```
+
+Suppressed writes are logged at WARN level with the full payload, and order placements come
+back with a simulated `orderId` so downstream code paths run to completion:
+
+```json
+{ "event": "DHAN_DRY_RUN", "method": "POST", "path": "/v2/orders", "payload": { "…": "…" } }
+```
+
+Note that a POST is not automatically a write on this API: the option chain, market feed,
+historical charts and the margin calculators are read-only POSTs, and dry-run leaves them
+alone.
+
+This works through the high-level models too, not just `Client#request`. Because
+`Order.place` re-fetches after placing, the SDK records each simulated order and replays reads
+for its `DRYRUN-…` id locally — so a rehearsal issues no request for a fake order, and the
+model you get back carries the fields you submitted:
+
+```ruby
+order.order_id    # => "DRYRUN-9F7BEB55D0F9"
+order.security_id # => "11536"
+```
+
+`dry_run` complements `Agent::OrderPreview` — preview validates a single order and returns a
+summary, while `dry_run` covers every write path in the SDK, including skills and the MCP
+tools.
+
+### Order Retries and Duplicate Protection
+
+The DhanHQ API has no idempotency key. A `POST /v2/orders` that times out may well have
+reached the exchange, so retrying it can place a second, real order. By default this SDK
+therefore **does not** retry non-idempotent writes — the transient error is raised to you:
+
+```ruby
+begin
+  DhanHQ::Models::Order.place(...)
+rescue DhanHQ::NetworkError
+  # The order may or may not have been accepted. Reconcile before resubmitting.
+end
+```
+
+Reads, and read-only POSTs like the option chain, are still retried with exponential backoff.
+
+To reconcile after a timeout, place orders with a correlation id and look the order up by it:
+
+```ruby
+DhanHQ.configure do |config|
+  config.auto_correlation_id = true   # or DHAN_AUTO_CORRELATION_ID=true
+end
+```
+
+With this on, any order placement missing a `correlationId` gets one (`dhq-<hex>`), which you
+can then resolve via `GET /v2/orders/external/{correlation-id}`:
+
+```ruby
+DhanHQ::Resources::Orders.new.by_correlation("dhq-2f9c1a…")
+```
+
+It is off by default because it changes the request body, which would break callers that match
+recorded fixtures on the exact payload. An explicit `correlation_id` is always preserved.
+
+If you would rather have the old auto-retry behaviour, opt back in — accepting the duplicate
+risk:
+
+```ruby
+DhanHQ.configure { |config| config.retry_non_idempotent_writes = true }
+```
+
 ### Order Audit Logging
 
 Every order attempt (place, modify, slice) automatically logs a structured JSON line at WARN level:
@@ -342,6 +437,45 @@ DhanHQ::WS::MarketDepth.connect(symbols: [
 end
 ```
 
+### Lifecycle Hooks and Health Checks
+
+Subscriptions are restored automatically on reconnect — the server keeps no subscription state
+across connections, so the client replays the desired set on every new session. Hook `:reconnect`
+when you need to re-seed derived state (candle builders, caches) after a gap:
+
+```ruby
+client = DhanHQ::WS.connect(mode: :ticker) { |tick| handle(tick) }
+
+client.on(:open)      { |info| logger.info "feed open, #{info[:resubscribed].size} restored" }
+client.on(:reconnect) { |info| logger.warn "reconnect ##{info[:attempt]}"; candles.reset! }
+client.on(:close)     { |info| logger.warn "closed #{info[:code]} #{info[:reason]}" }
+client.on(:error)     { |message| logger.error message }
+```
+
+A feed can be connected and still be dead — the socket stays open while the server stops
+publishing. For long-running daemons, watch frame arrival rather than the socket alone:
+
+```ruby
+client.connected?                  # socket state
+client.healthy?                    # connected AND delivering frames (default: within 45s)
+client.healthy?(stale_after: 20)   # tighter threshold
+client.last_message_at             # Time of the most recent frame
+client.seconds_since_last_message
+client.reconnect_count
+client.subscriptions               # ["NSE_EQ:11536", …] — survives reconnects
+
+client.health
+# => { mode: :ticker, started: true, connected: true, healthy: true,
+#      connected_at: …, last_message_at: …, seconds_since_last_message: 0.4,
+#      reconnect_count: 2, subscription_count: 37 }
+```
+
+`health` is shaped for a monitoring endpoint or a periodic log line.
+
+> **Connection limit:** Dhan allows **5 concurrent WebSocket connections per client id**, with
+> 5,000 instruments per connection and 100 instruments per subscribe frame. Running several
+> strategies in separate processes counts against the same limit — a 6th connection is refused.
+
 ### Cleanup
 
 ```ruby
@@ -373,6 +507,110 @@ DhanHQ::Models::SuperOrder.create(
 
 ---
 
+## Basket Orders (Multi Order)
+
+Place up to 15 unconditional orders in a single request. Each leg carries a `sequence` that
+identifies it in the response, so partial acceptance is visible:
+
+```ruby
+result = DhanHQ::Models::MultiOrder.place([
+  { sequence: "1", transaction_type: "BUY", exchange_segment: "NSE_EQ", product_type: "CNC",
+    order_type: "LIMIT", validity: "DAY", security_id: "11536", quantity: 1, price: 1500.0 },
+  { sequence: "2", transaction_type: "BUY", exchange_segment: "NSE_EQ", product_type: "CNC",
+    order_type: "MARKET", validity: "DAY", security_id: "1333", quantity: 2 }
+])
+
+result.all_accepted?              # => true
+result.order_ids                  # => ["112111182198", "112111182199"]
+result.rejected                   # legs the exchange refused
+result.partially_accepted?        # some in, some out
+result.for_sequence("1").order_id # look a leg up by its sequence
+```
+
+Every leg is validated before anything is sent, and each one gets its own audit log line.
+Requires `LIVE_TRADING=true` like any other order path.
+
+---
+
+## Global Stocks (US Equities)
+
+US stocks are a **separate book** from domestic NSE/BSE trading: their own order book,
+holdings, trades, and a USD fund limit. They are namespaced under `GlobalStocks` so a USD
+position can never be mistaken for an INR one.
+
+```ruby
+# Is the US market open?
+DhanHQ::Models::GlobalStocks::MarketStatus.fetch.open?
+
+# USD balance and portfolio
+DhanHQ::Models::GlobalStocks::Funds.fetch.available_cash
+DhanHQ::Models::GlobalStocks::Holding.all.each do |h|
+  puts "#{h.trading_symbol}: #{h.quantity} @ $#{h.avg_cost_price} (#{h.gain_percentage}%)"
+end
+DhanHQ::Models::GlobalStocks::Holding.total_current_value
+```
+
+### Placing US orders
+
+Global Stocks orders carry **no exchange segment, product type, or validity** — and quantity
+is a float, because fractional shares are supported:
+
+```ruby
+DhanHQ::Models::GlobalStocks::Order.place(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  order_type:       DhanHQ::Constants::GlobalStocks::OrderType::LIMIT,
+  security_id:      "AAPL",
+  quantity:         0.5,          # fractional shares
+  price:            180.0
+)
+```
+
+`AMOUNT` is a notional order type unique to this book — you name a dollar value instead of a
+share count:
+
+```ruby
+DhanHQ::Models::GlobalStocks::Order.place(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  order_type:       DhanHQ::Constants::GlobalStocks::OrderType::AMOUNT,
+  security_id:      "AAPL",
+  amount:           500.0         # buy $500 worth
+)
+```
+
+### Pre-trade checks
+
+```ruby
+params = { security_id: "AAPL", transaction_type: "BUY", price: 180.0, quantity: 10 }
+
+estimate = DhanHQ::Models::GlobalStocks::OrderEstimate.calculate(params)
+estimate.total_charges           # brokerage + exchange + GST + turnover + other
+
+margin = DhanHQ::Models::GlobalStocks::Margin.calculate(params)
+margin.sufficient?               # false when the account is short
+margin.total_margin
+```
+
+### Order and trade books
+
+```ruby
+DhanHQ::Models::GlobalStocks::Order.all              # today's US order book
+DhanHQ::Models::GlobalStocks::Order.find(order_id)
+DhanHQ::Models::GlobalStocks::Trade.all              # today's US fills
+DhanHQ::Models::GlobalStocks::Trade.find_by_security_id("AAPL")
+```
+
+Writes go through the same `LIVE_TRADING` gate, audit logging, and dry-run handling as
+domestic orders. The pre-trade `Risk::Pipeline` is deliberately **not** applied: its checks
+resolve instruments from the Indian scrip master and encode NSE/BSE rules (lot sizes, ASM/GSM
+surveillance, F&O product support, IST market hours), none of which apply to US equities. Use
+`Margin#sufficient?` and `OrderEstimate` as the pre-trade gate here instead.
+
+The Global Stocks live feed (`wss://global-stocks-api-feed.dhan.co`, segment `INX_EQ`, code
+`14`) is documented in `DhanHQ::Constants::GlobalStocks`; its binary packet decoder is not yet
+implemented.
+
+---
+
 ## Real-World Example: NIFTY Trend Monitor
 
 ```ruby
@@ -421,13 +659,18 @@ Need initializers, service objects, ActionCable wiring, and background workers?
 
 These scripts are designed around user goals rather than API surfaces:
 
-| Example | Use case |
-| ------- | -------- |
-| [examples/basic_trading_bot.rb](examples/basic_trading_bot.rb) | Pull historical data, evaluate a simple signal, and place a guarded order |
-| [examples/portfolio_monitor.rb](examples/portfolio_monitor.rb) | Snapshot funds, holdings, and positions for a monitoring script |
+| Example | What it covers |
+| ------- | --------------- |
+| [examples/basic_trading_bot.rb](examples/basic_trading_bot.rb) | Trading bot scaffold with live-trading guard |
+| [examples/comprehensive_websocket_examples.rb](examples/comprehensive_websocket_examples.rb) | WebSocket mode coverage and timeout handling |
 | [examples/options_watchlist.rb](examples/options_watchlist.rb) | Build a live options watchlist with index quotes and option-chain context |
 | [examples/market_feed_example.rb](examples/market_feed_example.rb) | Subscribe to major market indices over WebSocket |
+| [examples/market_depth_example.rb](examples/market_depth_example.rb) | Market depth streaming example |
 | [examples/live_order_updates.rb](examples/live_order_updates.rb) | Track order lifecycle events in real time |
+| [examples/order_update_example.rb](examples/order_update_example.rb) | Single-session order-update flow |
+| [examples/portfolio_monitor.rb](examples/portfolio_monitor.rb) | Snapshot funds, holdings, and positions for a monitoring script |
+| [examples/trading_fields_example.rb](examples/trading_fields_example.rb) | Dhan order-field mappings and constants example |
+| [examples/instrument_finder_test.rb](examples/instrument_finder_test.rb) | Instrument search/resolution troubleshooting |
 
 For search-driven discovery and onboarding content, see:
 
@@ -471,6 +714,149 @@ For search-driven discovery and onboarding content, see:
 
 ---
 
+## MCP Server (AI Agent Integration)
+
+DhanHQ includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI coding agents (Claude Code, Codex, OpenCode, Cursor) interact with your Dhan account directly from the editor or CLI.
+
+### Quick Start
+
+```bash
+# 1. Configure credentials
+export DHAN_CLIENT_ID="your_client_id"
+export DHAN_ACCESS_TOKEN="your_access_token"
+
+# 2. Start the server (stdio)
+bundle exec dhanhq-mcp
+```
+
+Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "dhanhq": {
+      "command": "bundle",
+      "args": ["exec", "dhanhq-mcp"],
+      "env": {
+        "DHAN_CLIENT_ID": "your_client_id",
+        "DHAN_ACCESS_TOKEN": "your_access_token"
+      }
+    }
+  }
+}
+```
+
+### MCP Features
+
+| Feature | Description |
+| ------- | ----------- |
+| **Tools** | 32 total: 12 domestic primitives (profile, funds, holdings, positions, order history, order preview/place/cancel, instruments, market feed) + 9 Global Stocks and basket tools (`dhan_global_*`, `dhan_multi_order`) + 11 skill-derived tools (`dhan_skill_*` — one per builtin strategy in [Skills System](#skills-system) below) |
+| **Resources** | 6 URI-addressable data endpoints: `dhanhq://account/profile`, `dhanhq://account/funds`, `dhanhq://account/holdings`, `dhanhq://account/positions`, `dhanhq://account/orders`, `dhanhq://market/capabilities` |
+| **Prompts** | 5 pre-built AI prompts: `portfolio_summary`, `market_analysis`, `risk_report`, `order_preview`, `suggest_strategy` |
+
+### Security & Policy
+
+```ruby
+# Read-only mode (no order placement)
+DhanHQ::Agent::Policy.read_only
+
+# Scope-based policy from env (DHANHQ_AGENT_SCOPES)
+DhanHQ::Agent::Policy.from_env
+```
+
+The policy engine respects `DHANHQ_MCP_ENABLE_WRITES` and `LIVE_TRADING` env vars. Write operations are blocked by default — explicit opt-in required.
+
+## Skills System
+
+Skills are reusable, composable trading strategies. DhanHQ ships with **11 builtin skills** and a registry for discovery and invocation.
+
+### Builtin Skills
+
+| Skill | Type | Description |
+| ----- | ---- | ----------- |
+| `buy_atm_call` | Single-leg | Buy ATM call option |
+| `square_off_all` | Action | Square off all open positions |
+| `square_off_position` | Action | Square off a specific position |
+| `iron_condor` | Multi-leg | Sell OTM put + buy further OTM put + sell OTM call + buy further OTM call |
+| `strangle` | Multi-leg | Buy OTM put + buy OTM call |
+| `covered_call` | Multi-leg | Buy equity + sell OTM call |
+| `bull_put_spread` | Multi-leg | Sell OTM put + buy further OTM put |
+| `bear_call_spread` | Multi-leg | Sell OTM call + buy further OTM call |
+| `protective_put` | Multi-leg | Buy equity + buy OTM put |
+| `straddle` | Multi-leg | Buy ATM call + buy ATM put |
+| `market_data_summarizer` | Read-only | Summarize technicals and/or option chain for a symbol |
+
+### Using Skills
+
+```ruby
+# Register all builtin skills
+DhanHQ::Skills::Registry.load_builtins
+
+# Find a skill by name
+skill = DhanHQ::Skills::Registry.find("covered_call")
+
+# Invoke — returns an intent hash (trade_type, legs, risk metadata)
+result = skill.call(symbol: "RELIANCE", expiry: "2026-06-25")
+# => { intent: { trade_type: "COVERED_CALL", legs: [...], total_premium: ..., break_even: ..., note: "..." } }
+```
+
+Skills return intent hashes (not executed trades), keeping a human-in-the-loop safety pattern.
+
+## AI Integration
+
+DhanHQ provides prompt helpers and risk reporting for LLM-powered trading agents.
+
+### Prompt Helpers
+
+```ruby
+require 'dhan_hq/ai'
+
+# Portfolio summary for AI consumption
+DhanHQ::AI::PromptHelpers.portfolio_summary
+# => "Portfolio Summary\n━━━━━━━━━━━━━\nFunds: ₹1,00,000.00\n..."
+
+# Risk report
+DhanHQ::AI::PromptHelpers.risk_report
+# => "🔴 RISK ALERT: 394.6% drawdown..."
+```
+
+### Risk Pipeline
+
+```ruby
+# Run pre-trade risk checks
+DhanHQ::Risk::Pipeline.run!(
+  instrument: instrument,
+  args: { quantity: 25, price: 24_500 },
+  type: :fno,
+  now: Time.now
+)
+```
+
+Available checks:
+- **TradingPermission** — blocks instruments where trading is disabled (`buy_sell_indicator != "A"`)
+- **AsmGsm** — blocks ASM/GSM restricted instruments
+- **ProductSupport** — validates bracket/cover order support for the instrument
+- **OrderType** — restricts to `MARKET`/`LIMIT` order types
+- **Quantity** — max 10 units / ₹1,00,000 notional (an agent-safety limit, not a general trading cap)
+- **MarketHours** — verifies market is open (9:15 AM–3:30 PM IST)
+- **PositionLimits** — max 20 concurrent open positions
+- **Concentration** — max 25% of available balance in a single symbol
+- **Options** (options only) — index-only, requires stop loss + target + risk-reward
+- **MaxLoss** (daily) — daily loss limit (default ₹50,000)
+
+Checks raise `DhanHQ::RiskViolation` with human-readable messages, safe for AI parsing. Wired into every order-placing path via `DhanHQ::Concerns::OrderAudit#run_risk_checks!` (Orders, SuperOrders, ForeverOrders, AlertOrders, TwapOrders, IcebergOrders, PnL Exit) and into the `dhan_place_order` MCP tool.
+
+### Known Limitations
+
+This gem's core REST/WS client (orders, positions, funds, market data) is mature and already depended on in production by other repos in this workspace. The MCP server, Skills system, and Risk pipeline are newer and have now been verified live end to end — including the full write path — against real Dhan accounts, a real independent MCP client, and a real order-matching engine — see [CHANGELOG.md](CHANGELOG.md#known-limitations) for details:
+
+- Read path (profile/funds/holdings/positions/orders/instrument lookup/option chains, all 11 skills' intent-building, WebSocket streaming) — live-verified.
+- Write path — `dhan_place_order`, `dhan_cancel_order`, `dhan_skill_square_off_all`, and `dhan_skill_square_off_position` all verified end-to-end through the MCP-gated path (instrument resolution, full risk pipeline, audit logging, real execution). Dhan's own sandbox never executes real fills (by design, per Dhan's docs), so fills were exercised against `simulators/paper_exchange`'s real matching engine via a throwaway Dhan-API-compatible adapter. Found and fixed a real bug in the process: both square-off skills used `p[:net_quantity]`-style hash indexing on `Position` (which has no `[]` method), silently finding zero positions to close every time — invisible until a real position finally existed to test against.
+- Risk checks that read portfolio state (`Concentration`, `PositionLimits`, `MaxLoss`) have only been observed against zero/low-balance accounts and a single simulated position — not a large multi-symbol portfolio.
+- The sandbox environment's security-ID catalog is disconnected from the production instrument master — resolve IDs from sandbox order history, not `Instrument.find`, when testing against sandbox.
+
+---
+
 ## Best Practices
 
 - Keep `on(:tick)` handlers **non-blocking** — push heavy work to a queue/thread

data/docs/AUTHENTICATION.md

@@ -54,7 +54,7 @@ If the token was **generated from Dhan Web** (not API key flow), you can refresh
 
 ```ruby
 # Returns a hash with API response (e.g. accessToken, expiryTime). Use the new token for subsequent requests.
-response = DhanHQ::Auth.renew_token(current_access_token, client_id)
+response = DhanHQ::Auth.renew_token(access_token: current_access_token, client_id: client_id)
 new_token = response["accessToken"] || response[:accessToken]
 # Optional: response may include "expiryTime"
 ```
@@ -68,7 +68,7 @@ Example: refresh in provider and cache the result until near expiry:
 config.access_token_provider = lambda do
   stored = YourTokenStore.current
   if stored.nil? || stored.expired_soon?
-    response = DhanHQ::Auth.renew_token(stored&.access_token || ENV["DHAN_ACCESS_TOKEN"], config.client_id)
+    response = DhanHQ::Auth.renew_token(access_token: stored&.access_token || ENV["DHAN_ACCESS_TOKEN"], client_id: config.client_id)
     YourTokenStore.update!(response["accessToken"], response["expiryTime"])
     stored = YourTokenStore.current
   end
@@ -219,6 +219,4 @@ 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.
+Production-grade automation: enable_auto_token_management! (generate + renew)

data/docs/CONFIGURATION.md

@@ -9,7 +9,7 @@ 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.
+`configure_with_env` reads `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` from `ENV`. It does **not** raise if either is missing — they're simply left `nil`, and a `DhanHQ::AuthenticationError` (or similar) surfaces later, only when a request actually needs the token.
 
 ## Required Environment Variables
 
@@ -25,7 +25,8 @@ 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_SANDBOX`                   | `false`    | Set `"true"` to route REST calls to `https://sandbox.dhan.co/v2` instead of production. Note: Dhan's sandbox validates request/response plumbing only — it does not execute real order fills/matching. Placed orders stay `PENDING` indefinitely. See [ENDPOINTS_AND_SANDBOX.md](ENDPOINTS_AND_SANDBOX.md). |
+| `DHAN_BASE_URL`                  | Dhan prod  | Point REST calls to a different API hostname. Takes precedence over `DHAN_SANDBOX` only when explicitly set to something other than the production default. |
 | `DHAN_WS_VERSION`                | latest     | Pin WebSocket connections to a specific API version     |
 | `DHAN_WS_ORDER_URL`              | Dhan prod  | Override the order update WebSocket endpoint            |
 | `DHAN_WS_USER_TYPE`              | `SELF`     | Switch between `SELF` and `PARTNER` streaming modes     |

data/docs/CONSTANTS_REFERENCE.md

@@ -17,8 +17,9 @@ Exchange segments for different markets and instruments.
 | `NSE_EQ` | `"NSE_EQ"` | NSE - Equity Cash | 1 |
 | `NSE_FNO` | `"NSE_FNO"` | NSE - Futures & Options | 2 |
 | `NSE_CURRENCY` | `"NSE_CURRENCY"` | NSE - Currency | 3 |
-| `BSE_EQ` | `"BSE_EQ"` | BSE - Equity Cash | 4 |
-| `MCX_COMM` | `"MCX_COMM"` | MCX - Commodity | 5 |
+| `NSE_COMM` | `"NSE_COMM"` | NSE - Commodity | 4 |
+| `BSE_EQ` | `"BSE_EQ"` | BSE - Equity Cash | 5 |
+| `MCX_COMM` | `"MCX_COMM"` | MCX - Commodity | 6 |
 | `BSE_CURRENCY` | `"BSE_CURRENCY"` | BSE - Currency | 7 |
 | `BSE_FNO` | `"BSE_FNO"` | BSE - Futures & Options | 8 |
 
@@ -431,7 +432,7 @@ end
 
 ### Validation Helpers
 
-Consider adding validation helpers:
+Already implemented in `lib/DhanHQ/constants.rb`:
 
 ```ruby
 module DhanHQ
@@ -439,7 +440,7 @@ module DhanHQ
     def self.valid?(module_name, value)
       const_get(module_name)::ALL.include?(value)
     end
-    
+
     def self.all_for(module_name)
       const_get(module_name)::ALL
     end
@@ -457,10 +458,11 @@ DhanHQ::Constants.all_for(:OrderType) # => ["LIMIT", "MARKET", ...]
 
 | API Type | Per Second | Per Minute | Per Hour | Per Day |
 |----------|------------|------------|----------|---------|
-| Order APIs | 10 | 250 | 1,000 | 7,000 |
-| Data APIs | 5 | - | - | 100,000 |
+| Order APIs | 10 | Unlimited | Unlimited | 100,000 |
+| Data APIs | 5 | - | - | 7,000 |
 | Quote APIs | 1 | Unlimited | Unlimited | Unlimited |
 | Non Trading APIs | 20 | Unlimited | Unlimited | Unlimited |
+| Option Chain | 1 per 3 sec | - | - | - |
 
 **Note:** Order modifications are capped at 25 modifications per order.
 

data/docs/ENDPOINTS_AND_SANDBOX.md

@@ -2,6 +2,7 @@
 
 ## Sandbox behavior
 
+- **Sandbox does NOT execute real order fills/matching.** Confirmed both via Dhan's own docs ("the sandbox behaves like the live API but does not execute real orders") and empirically: a `MARKET` order placed on sandbox validates and returns a real `orderId`, but stays at `PENDING` indefinitely — it never transitions to `TRADED`, even after 24+ seconds of polling. Use sandbox to validate request/response plumbing (auth, payload shape, error codes), not to test fill, cancel, or square-off behavior.
 - **REST:** When `DhanHQ.configuration.sandbox == true` (or `ENV["DHAN_SANDBOX"]=true`), the client uses `https://sandbox.dhan.co/v2` as the base URL for **all** requests that go through `DhanHQ::Client`. Every wrapped REST endpoint listed below is therefore **sent** to the sandbox host when sandbox is enabled.
 - **Sandbox does NOT support WebSocket.** Order updates, market feed, and market depth are **production-only**. The gem always uses production WebSocket URLs regardless of the `sandbox` setting. There are no sandbox WebSocket endpoints in the Dhan v2 API; do not rely on sandbox for real-time streams.
 - **Auth endpoints** (`DhanHQ::Auth`) do **not** use sandbox. They always call:

data/docs/LIVE_ORDER_UPDATES.md

@@ -320,24 +320,19 @@ This ensures safe usage in multi-threaded applications.
 
 ## Testing
 
-For comprehensive testing examples and interactive console helpers, see the [Testing Guide](TESTING_GUIDE.md). The guide includes:
+For comprehensive testing examples, see the [Testing Guide](TESTING_GUIDE.md). It covers:
 
 - **Order Update WebSocket Testing**: Complete examples for all order update features
 - **Event Handler Testing**: Examples for all event types
 - **Order State Management**: Testing order tracking and querying
-- **Interactive Console Helpers**: Load `bin/test_helpers.rb` for quick test functions
 
 **Quick start in console:**
 ```ruby
 # Start console
 bin/console
 
-# Load test helpers
-load 'bin/test_helpers.rb'
-
-# Test order WebSocket
-test_order_websocket(10)        # Test order updates for 10 seconds
-
-# Monitor specific order
-monitor_order("112111182045")   # Monitor order by ID
+# Test order WebSocket for 10 seconds
+client = DhanHQ::WS::Orders.connect { |update| puts update.inspect }
+sleep 10
+client.stop
 ```

data/docs/RAILS_INTEGRATION.md

@@ -122,7 +122,7 @@ end
 
 When the API returns 401 or token-expired (error code 807) and `access_token_provider` is set, the client retries the request **once** with a fresh token from the provider. `on_token_expired` is called before that retry so you can refresh your store if needed.
 
-**RenewToken (web-generated tokens only):** If the token was generated from Dhan Web (24h validity), you can refresh it with `DhanHQ::Auth.renew_token(access_token, client_id)` and store the result; use it in your provider or call it from `on_token_expired`. The gem does **not** implement API key/secret or Partner consent flows—implement those in your app and pass the token to the gem. See [docs/AUTHENTICATION.md](AUTHENTICATION.md).
+**RenewToken (web-generated tokens only):** If the token was generated from Dhan Web (24h validity), you can refresh it with `DhanHQ::Auth.renew_token(access_token: access_token, client_id: client_id)` (keyword arguments) and store the result; use it in your provider or call it from `on_token_expired`. The gem does **not** implement API key/secret or Partner consent flows—implement those in your app and pass the token to the gem. See [docs/AUTHENTICATION.md](AUTHENTICATION.md).
 
 ## 3. Build service objects for REST flows
 

data/docs/RELEASE_GUIDE.md

@@ -148,8 +148,9 @@ When you push a tag (e.g., `v2.1.12`), the **Release** workflow (`.github/workfl
 2. ✅ **Generate OTP code** from secret `RUBYGEMS_OTP_SECRET`
 3. ✅ **Build gem** using `gem build DhanHQ.gemspec`
 4. ✅ **Push to RubyGems** with OTP using `GEM_HOST_API_KEY` (from secret `RUBYGEMS_API_KEY`)
+5. ✅ **Attach gem to GitHub Release** — uploads `DhanHQ-<version>.gem` as a downloadable asset on the GitHub Release for the tag, creating the release (with auto-generated notes) if it doesn't already exist, or uploading to it if it does
 
-Tests run on push/PR via the main CI workflow; the release job does not run tests. No GitHub Release is created (tag-only publish, same pattern as ollama-client).
+Tests run on push/PR via the main CI workflow; the release job does not run tests. A GitHub Release page is created/updated with the built `.gem` attached as a downloadable asset (verified working on the real v3.1.0 release: https://github.com/shubhamtaywade82/dhanhq-client/releases/tag/v3.1.0).
 
 **No manual intervention needed!** ⚡
 
@@ -286,6 +287,16 @@ on:
    gem push "DhanHQ-${gem_version}.gem" --otp "$otp_code"
    ```
 
+5. **Attach gem to GitHub Release**
+   ```bash
+   # Creates the release (with --generate-notes) if it doesn't exist yet, else uploads to it
+   if gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+     gh release upload "$tag" "$gem_file" --repo "$GITHUB_REPOSITORY" --clobber
+   else
+     gh release create "$tag" "$gem_file" --repo "$GITHUB_REPOSITORY" --title "$tag" --generate-notes
+   fi
+   ```
+
 ### Security Features
 
 - 🔒 **MFA Required** - `rubygems_mfa_required = "true"` in gemspec
@@ -476,7 +487,7 @@ The old workflow (`.github/workflows/main.yml`):
 ✅ **MFA secured:** OTP authentication on every release
 ✅ **Production ready:** Battle-tested release workflow
 ✅ **Tests integrated:** Ensures quality before release
-✅ **Tag-only release:** Same pattern as ollama-client; push tag `v*` to publish
+✅ **Tag-triggered release:** push tag `v*` to publish to RubyGems and attach the built gem to a GitHub Release
 
 Questions or issues? Check the [Troubleshooting](#troubleshooting) section above.
 

data/docs/STANDALONE_RUBY_WEBSOCKET_INTEGRATION.md

@@ -996,8 +996,8 @@ class MarketDataCLI
       volume: full[:vol],
       day_high: full[:day_high],
       day_low: full[:day_low],
-      open: full[:open],
-      close: full[:close],
+      open: full[:day_open],
+      close: full[:day_close],
       timestamp: timestamp.iso8601
     }