DhanHQ 3.0.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d9d117dd455fc2a006a98cf0532297688a247498f5a12e98fb609a355ffc195
-  data.tar.gz: 2334b0e16f35ecc00f414739f3d40da1cac7640ede1b64079248b35e02cc0851
+  metadata.gz: aa2811b4faf1f45f3ddc18b5f0b1ae03f481aa30fe48f1b1be3b3a928f87c581
+  data.tar.gz: cd4829e129d27e6b939bedaac18828f44237674ef5c84135ce9a647c4af37bcc
 SHA512:
-  metadata.gz: 577d961c10faa0381d7e4f17a835688c181457bc7ed2222755123dd4cb7735431c1652af5d7026420c977b330863d9576354cc65c44aa1d7bc9342c1e759cce3
-  data.tar.gz: fc6ba43d2e0e37d8e87c19aa7b803330377aa7c38bff4f90c451192d410a94a9864ea887f90b8a5419c608e0ca57fcb8711bd462976568772318aee29abbcb45
+  metadata.gz: 2b8fedf28da427de98161f6d2288230dc6e34a112bbfb56bda85d6373f0d2489cdfa8c2427facf0dc98e729790b4ee2023f534888f1b84989885993e9272545a
+  data.tar.gz: 11500ff76de75b2f9b9205e7f5af1210940291fe05b5c53b5f40d4f91e1a8d1c56346e8adb65c1fb2e2a36509b0c80f198f9264d402be8ced0622057fb288d64

data/.rubocop.yml

@@ -11,6 +11,8 @@ require:
 AllCops:
   TargetRubyVersion: 3.2
   NewCops: enable
+  Exclude:
+    - "skills/**/*"
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -1,3 +1,54 @@
+## [3.1.0] - 2026-07-20
+
+### Added
+
+- **MCP resources support** — 6 URI-addressable resources (`dhanhq://account/profile`, `funds`, `holdings`, `positions`, `orders`, `dhanhq://market/capabilities`) with `resources/list` and `resources/read`.
+- **MCP prompts support** — 5 pre-built AI prompts (`portfolio_summary`, `market_analysis`, `risk_report`, `order_preview`, `suggest_strategy`) with `prompts/list` and `prompts/get`.
+- **5 new builtin skills** — `covered_call`, `bull_put_spread`, `bear_call_spread`, `protective_put`, `straddle` (10 total).
+- **3 new risk checks** — `PositionLimits` (max 20 concurrent positions), `Concentration` (max 25% per symbol), `MaxLoss` (daily loss limit, default ₹50,000).
+- **Extended risk pipeline** — `DhanHQ::Risk::Pipeline` now includes `DAILY_CHECKS` constant and runs all new checks.
+- **Risk pipeline wired into all order paths** — `Risk::Pipeline.run!` now fires before every order placement via the `OrderAudit` concern, covering Orders, SuperOrders, ForeverOrders, AlertOrders, TwapOrders, IcebergOrders, and PnL Exit. Instrument resolution failures are handled silently so transient lookup issues never block a valid order.
+- **SDK + AI integration docs** — README sections for MCP Server, Skills System, and AI Integration.
+
+### Changed
+
+- `DhanHQ::MCP::Server` now requires `dhan_hq/ai` for prompt generation.
+- CI RuboCop step no longer uses `continue-on-error: true`.
+- Spec path for risk check specs moved to `spec/dhan_hq/risk/checks/`.
+- **`OrderAudit` concern extended** — new `run_risk_checks!(params)` method runs the risk pipeline before order placement, with `trade_type_for` mapping exchange segments to pipeline types. All 7 order resources call it in their `create`/`configure` methods.
+
+### Fixed
+
+- Syntax error in MCP server spec (orphaned `if response["error"]` debug lines removed).
+- `[]` method stub pattern in risk check specs (use `receive(:[])` instead of hash double syntax).
+- `MaxLoss` spec test data corrected to trigger the daily loss limit correctly.
+- All RSpec VerifiedDoubles and MultipleExpectations offenses resolved (0 RuboCop offenses).
+- **Position model accessors in risk checks** — replaced `p[:net_quantity]`, `p[:unrealized_profit_loss]`, and `p[:trading_symbol]` hash indexing with real model accessors (`p.net_qty`, `p.unrealized_profit`, `p.trading_symbol`).
+- **`ltp` access in all 9 skills** — `instrument.ltp` returns a Float, not a Hash; removed the `ltp[:ltp]` unwrapping pattern.
+- **`market_analysis` prompt** — resolves symbol to integer security ID via `Instrument.find` before passing to `MarketFeed.quote`.
+- **`OrderAudit#run_risk_checks!` resolved the wrong instrument** — called `Instrument.find(exchange_segment, security_id)`, but `find`'s second argument is a symbol name (e.g. `"RELIANCE"`), not a security ID. Every real order silently failed instrument resolution (`Instrument.find` returned `nil` for a numeric ID), which combined with the surrounding `rescue StandardError; nil` meant **risk checks never ran for any real order placed through any of the 7 order resources**, despite the "wired into all order paths" claim above. Fixed by switching to the new `Instrument.find_by_security_id`. Confirmed live against a real account: `find("NSE_EQ", "2885")` → `nil`; `find_by_security_id("NSE_EQ", "2885")` → resolves RELIANCE correctly.
+- **MCP JSON-RPC compliance** — notifications (requests with no `id`) no longer receive a response; dispatch errors preserve the caller's request `id`; error codes now use the correct `-32700`/`-32601`/`-32602`/`-32603` instead of a single generic `-32000`; `protocolVersion` is negotiated against the client's request instead of hardcoded.
+- **`dhan_place_order` MCP tool bypassed all risk checks** — now resolves the instrument via `find_by_security_id` and runs `Risk::Pipeline.run!` before calling `Order.place`, same as the resource-level fix above, gated by the same live-write policy checks.
+- **Option chain shape mismatch in 8 of 11 skills** — `Instrument#option_chain` returns `{ last_price:, strikes: [{ strike:, call:, put: }] }` (nested Hash), but `iron_condor`, `straddle`, `strangle`, `buy_atm_call`, `covered_call`, `protective_put`, `bull_put_spread`, and `bear_call_spread` were written assuming a flat array of `{ strike:, option_type:, security_id: }` leg-hashes. Every one of these skills raised `NoMethodError`/`TypeError` against the real API; all specs passed anyway because their fixtures invented the same wrong shape. Confirmed broken live, fixed against real NIFTY/RELIANCE option chains (real security IDs verified), all fixtures rewritten to match reality (`spec/support/option_chain_helpers.rb`).
+- **MCP tool call could hang indefinitely** — a rate-limited `tools/call` blocked the single-threaded stdio loop with no error surfaced. Added a 15s timeout (`DhanHQ::MCP::Server#tool_call_timeout`) that returns a structured error instead.
+- **`dhan_skill_*` tool descriptions** showed the raw Ruby class name (e.g. `"DhanHQ::Skills::Builtin::IronCondor"`) instead of anything useful to an LLM client. Added a `description` class macro to `Skills::Base`; all 11 builtin skills now declare a human-readable one-liner. Verified live via `tools/list`.
+- **`Instrument.find`/`.find_by_security_id` could hang for minutes and use gigabytes of RAM** — both built a full `Instrument` model object (each with ~52 `define_singleton_method` calls from `BaseModel#assign_attributes`) for *every row* in the segment before filtering. Confirmed live: a single `find_by_security_id("NSE_EQ", ...)` call ran 98.9% CPU, 4.2GB RSS, and was killed after 3.5 minutes without finishing — `NSE_EQ` has ~219,000 rows. Fixed both methods to scan raw CSV rows and instantiate only the matching one (~9–11s now, down from unbounded). Added dedicated `.find` spec coverage (previously none existed) including a regression guard asserting only one `Instrument` is ever constructed.
+- **`correlation_id` accepted up to 30 characters in 4 order contracts** (`PlaceOrderContract`, `ForeverOrderContract`, `IcebergOrderContract`, `TwapOrderContract`), but Dhan's real API caps it at 25 and rejects the **entire order** with a generic, field-agnostic `DH-905` error if exceeded — giving no indication `correlation_id` was the problem. Confirmed live by bisecting the exact boundary (25 chars: success: 26 chars: `DH-905`) against a real sandbox order. All 4 contracts corrected to `max_size?: 25`.
+- **`square_off_all`/`square_off_position` never actually found any positions to close** — `SquareOffAll#fetch_positions` called `p[:net_quantity]` on a `Position` model (no `[]` method defined), silently rescued to `0`, and filtered out every real position, always reporting zero exits. `SquareOffPosition#find_position` had the same pattern for `exchange_segment`/`trading_symbol`/`security_id`/`net_quantity`, unguarded by any rescue, so it would raise `NoMethodError` the moment a real position existed. Both bugs were invisible until this session, because no test — unit or live — had ever exercised these skills against a real non-empty `Position.all` result; the unit-test doubles stubbed the same wrong `net_quantity` attribute name the buggy code called. Fixed both to use the real model accessors (`p.net_qty`, `p.exchange_segment`, `p.trading_symbol`, `p.security_id`); fixed both specs' doubles to match. Confirmed live: built a Dhan-API-compatible translation adapter in front of `simulators/paper_exchange` (a real Rails order-matching/fills/positions simulator already in this workspace) so a real order could actually fill (Dhan's own sandbox never executes real fills — confirmed via its docs), producing a genuine non-zero position, then ran `dhan_skill_square_off_all` and `dhan_skill_square_off_position` through the full MCP-gated path against it: both correctly found the position and closed it (`net_qty` 4→0 and 2→0 respectively) with a real `SUCCESS` response.
+
+### Known Limitations
+
+Verified live against a real Dhan account (live-scoped and sandbox), a real independent MCP client, and — for the two paths sandbox cannot simulate (real fills, real position closure) — a purpose-built Dhan-API-compatible adapter in front of `simulators/paper_exchange`'s real order-matching engine.
+
+- **Live-tested, all of it, including the full write path**: core REST client, MCP protocol layer, all 11 skills' intent-building, WebSocket streaming, and — end to end — `dhan_place_order`, `dhan_cancel_order`, `dhan_skill_square_off_all`, and `dhan_skill_square_off_position`, each through the actual MCP-gated path (instrument resolution → full risk pipeline → audit log → real order execution). Dhan's sandbox itself only validates request/response plumbing and never executes a real fill (confirmed via Dhan's own docs: "the sandbox behaves like the live API but does not execute real orders") — fills were exercised against `simulators/paper_exchange`'s real matching engine via a throwaway adapter (not shipped, not committed) instead.
+- **`Concentration`/`PositionLimits`/`MaxLoss` risk checks** have only been observed against zero-position, zero-or-low-balance accounts, and against `paper_exchange`'s simulated position (a single small equity position). Their math is unit-tested; behavior against a large, multi-symbol real portfolio has not been observed.
+- **The sandbox environment's instrument/security-ID catalog appears disconnected from the production instrument master** — a real production TCS security ID (`532540`, resolved via `Instrument.find`) was rejected by the sandbox's matching engine (`DH-906: Transaction has Failed`), while an ID from a prior sandbox test (`11536`) validated successfully. Anyone testing against sandbox should resolve security IDs from sandbox-originated data (e.g. prior order history), not the live instrument master.
+- **`release.yml`'s GitHub Release gem-asset upload** has not fired end-to-end — no tag has been pushed since the fix landed.
+- **v3.1.0 is not tagged** — CHANGELOG reflects work in progress on `main`, not a cut release.
+- **Nothing from this session is committed.**
+
+---
+
 ## [3.0.0] - 2026-05-19
 
 ### Breaking Changes

data/README.md

@@ -421,13 +421,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 +476,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** | 12 primitive tools (profile, funds, holdings, positions, order history, order preview/place/cancel, instruments, market feed) + 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/CONSTANTS_REFERENCE.md

@@ -457,10 +457,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/exe/dhanhq-mcp

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "dhan_hq"
+require "dhan_hq/mcp"
+
+DhanHQ::MCP::Server.new.run

data/lib/DhanHQ/agent/tool_registry.rb

@@ -65,6 +65,10 @@ module DhanHQ
       end
 
       def build_tools
+        (primitive_tools + skill_tools).to_h { |tool_item| [tool_item.name, tool_item] }
+      end
+
+      def primitive_tools
         [
           tool("dhan_profile", "Fetch Dhan profile", "portfolio:read", "read_only",
                object_schema, profile_handler,
@@ -124,7 +128,31 @@ module DhanHQ
                cancel_schema, cancel_order_handler,
                version: "1.0.0",
                output_schema: { type: "object", properties: { order_id: { type: "string" }, status: { type: "string" } } })
-        ].to_h { |tool_item| [tool_item.name, tool_item] }
+        ]
+      end
+
+      # Exposes each registered DhanHQ::Skills::Registry strategy as an MCP tool,
+      # gated by the risk/scope the skill class declares (see DhanHQ::Skills::Base).
+      def skill_tools
+        DhanHQ::Skills::Registry.list.map do |skill|
+          klass = DhanHQ::Skills::Registry.find(skill[:name])
+          tool("dhan_skill_#{skill[:name]}", skill[:description], klass.scope, klass.risk,
+               skill_input_schema(skill[:params]),
+               ->(arguments) { DhanHQ::Skills::Registry.call(skill[:name], arguments) },
+               version: "1.0.0")
+        end
+      end
+
+      def skill_input_schema(params)
+        properties = params.transform_values do |config|
+          { type: skill_param_type(config[:type]) }.tap { |h| h[:description] = config[:description] if config[:description] }
+        end
+        required = params.select { |_, config| config[:required] }.keys.map(&:to_s)
+        { type: "object", properties: properties, required: required, additionalProperties: false }
+      end
+
+      def skill_param_type(type)
+        { string: "string", integer: "integer", number: "number", boolean: "boolean" }.fetch(type.to_sym, "string")
       end
 
       # rubocop:disable Metrics/ParameterLists
@@ -228,7 +256,20 @@ module DhanHQ
 
       def preview_handler = ->(arguments) { OrderPreview.new(arguments).to_h }
 
-      def place_order_handler = ->(arguments) { DhanHQ::Models::Order.place(arguments) }
+      def place_order_handler
+        lambda do |arguments|
+          instrument = DhanHQ::Models::Instrument.find_by_security_id(arguments[:exchange_segment], arguments[:security_id])
+          unless instrument
+            raise DhanHQ::RiskViolation,
+                  "Cannot verify risk for unknown instrument: #{arguments[:exchange_segment]}:#{arguments[:security_id]}"
+          end
+
+          risk_type = instrument.instrument_type.to_s.start_with?("OPT") ? :options : :equity
+          DhanHQ::Risk::Pipeline.run!(instrument: instrument, args: stringify(arguments), type: risk_type)
+
+          DhanHQ::Models::Order.place(arguments)
+        end
+      end
 
       def cancel_order_handler
         lambda do |arguments|
@@ -244,6 +285,14 @@ module DhanHQ
         else value
         end
       end
+
+      def stringify(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, val), hash| hash[key.to_s] = stringify(val) }
+        when Array then value.map { |val| stringify(val) }
+        else value
+        end
+      end
     end
     # rubocop:enable Metrics/ModuleLength
   end

data/lib/DhanHQ/concerns/order_audit.rb

@@ -4,7 +4,8 @@ require_relative "../utils/network_inspector"
 
 module DhanHQ
   module Concerns
-    # Shared behavior for order audit logging and live trading safety.
+    # Shared behavior for order audit logging, live trading safety, and
+    # pre-trade risk checks.
     #
     # Include this module in any Resource that submits, modifies, or cancels
     # orders on the Dhan API. It provides:
@@ -17,12 +18,18 @@ module DhanHQ
     #   unless +ENV["LIVE_TRADING"]+ is +"true"+, preventing accidental order
     #   placement from development machines.
     #
+    # - {#run_risk_checks!}: runs {DhanHQ::Risk::Pipeline} against the order
+    #   params before execution.  Catches unresolvable instruments and other
+    #   edge cases silently so the risk layer never blocks a valid order due
+    #   to a transient lookup failure.
+    #
     # @example Including in a resource
     #   class MyOrders < BaseAPI
     #     include DhanHQ::Concerns::OrderAudit
     #
     #     def create(params)
     #       ensure_live_trading!
+    #       run_risk_checks!(params)
     #       log_order_context("MY_ORDER_ATTEMPT", params)
     #       post("", params: params)
     #     end
@@ -39,6 +46,41 @@ module DhanHQ
               "Live trading is disabled. Set ENV[\"LIVE_TRADING\"]=\"true\" to enable order placement."
       end
 
+      # Runs the risk pipeline for the given order params.
+      #
+      # Extracts +security_id+ and +exchange_segment+ from the params,
+      # resolves the instrument, and calls {DhanHQ::Risk::Pipeline.run!}.
+      # If the instrument cannot be resolved the check is skipped silently
+      # rather than blocking the order.
+      def run_risk_checks!(params)
+        security_id = extract_param(params, :securityId, :security_id)
+        exchange_segment = extract_param(params, :exchangeSegment, :exchange_segment)
+        return unless security_id && exchange_segment
+
+        instrument = DhanHQ::Models::Instrument.find_by_security_id(exchange_segment, security_id)
+        return unless instrument
+
+        DhanHQ::Risk::Pipeline.run!(
+          instrument: instrument,
+          args: params,
+          type: trade_type_for(exchange_segment),
+          now: Time.now
+        )
+      rescue DhanHQ::RiskViolation
+        raise
+      rescue StandardError
+        nil
+      end
+
+      # Maps an exchange segment string to a pipeline trade type.
+      def trade_type_for(exchange_segment)
+        case exchange_segment.to_s
+        when /^NSE_FNO/, /^BSE_FNO/, /^NSE_CURRENCY/, /^BSE_CURRENCY/ then :fno
+        when /^MCX/ then :commodity
+        else :equity
+        end
+      end
+
       # Emits a structured JSON log line with machine/network/correlation context.
       # Uses WARN level so it appears even when INFO is silenced.
       def log_order_context(event, params = {})

data/lib/DhanHQ/constants.rb

@@ -381,9 +381,10 @@ module DhanHQ
 
     # Public rate limits published in DhanHQ API documentation.
     module RateLimit
-      ORDER_API = { per_second: 10, per_minute: 250, per_hour: 1000, per_day: 7000 }.freeze
-      DATA_API = { per_second: 5, per_day: 100_000 }.freeze
+      ORDER_API = { per_second: 10, per_day: 100_000 }.freeze
+      DATA_API = { per_second: 5, per_day: 7_000 }.freeze
       QUOTE_API = { per_second: 1 }.freeze
+      OPTION_CHAIN = { per_second: 1.0 / 3 }.freeze
       NON_TRADING_API = { per_second: 20 }.freeze
       ORDER_MODIFICATIONS_PER_ORDER = 25
     end

data/lib/DhanHQ/contracts/forever_order_contract.rb

@@ -17,7 +17,7 @@ module DhanHQ
         required(:quantity).filled(:integer, gt?: 0)
         required(:price).filled(:float, gt?: 0)
         required(:trigger_price).filled(:float)
-        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:correlation_id).maybe(:string, max_size?: 25, format?: /\A[a-zA-Z0-9 _-]*\z/)
         optional(:disclosed_quantity).maybe(:integer, gteq?: 0)
         optional(:price1).maybe(:float, gt?: 0)
         optional(:trigger_price1).maybe(:float)

data/lib/DhanHQ/contracts/iceberg_order_contract.rb

@@ -21,7 +21,7 @@ module DhanHQ
         required(:price).filled(:float, gt?: 0)
         required(:iceberg_qty).filled(:integer, gt?: 0)
         required(:disclosed_quantity).filled(:integer, gteq?: 0)
-        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:correlation_id).maybe(:string, max_size?: 25, format?: /\A[a-zA-Z0-9 _-]*\z/)
         optional(:trigger_price).maybe(:float, gteq?: 0)
         optional(:after_market_order).maybe(:bool)
         optional(:amo_time).maybe(:string, included_in?: AMO_TIMINGS)

data/lib/DhanHQ/contracts/place_order_contract.rb

@@ -17,7 +17,7 @@ module DhanHQ
         required(:quantity).filled(:integer, gt?: 0)
 
         # Optional fields
-        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:correlation_id).maybe(:string, max_size?: 25, format?: /\A[a-zA-Z0-9 _-]*\z/)
         optional(:disclosed_quantity).maybe(:integer, gteq?: 0)
         optional(:price).maybe(:float, gt?: 0)
         optional(:trigger_price).maybe(:float, gt?: 0)

data/lib/DhanHQ/contracts/twap_order_contract.rb

@@ -22,7 +22,7 @@ module DhanHQ
         required(:slice_interval).filled(:integer, gt?: 0)
         required(:start_time).filled(:string, format?: /\A([01]?\d|2[0-3]):([0-5]?\d):([0-5]?\d)\z/)
         required(:end_time).filled(:string, format?: /\A([01]?\d|2[0-3]):([0-5]?\d):([0-5]?\d)\z/)
-        optional(:correlation_id).maybe(:string, max_size?: 30, format?: /\A[a-zA-Z0-9 _-]*\z/)
+        optional(:correlation_id).maybe(:string, max_size?: 25, format?: /\A[a-zA-Z0-9 _-]*\z/)
         optional(:trigger_price).maybe(:float, gteq?: 0)
         optional(:after_market_order).maybe(:bool)
         optional(:amo_time).maybe(:string, included_in?: AMO_TIMINGS)