DhanHQ 3.0.1 → 3.1.0

data/lib/DhanHQ/mcp/server.rb

@@ -1,16 +1,47 @@
 # frozen_string_literal: true
 
 require "json"
+require "timeout"
 require_relative "../agent"
+require_relative "../ai"
 
 module DhanHQ
   module MCP
     # Minimal MCP-compatible stdio JSON-RPC server for DhanHQ agent tools.
     class Server
-      def initialize(input: $stdin, output: $stdout, policy: DhanHQ::Agent::Policy.from_env)
+      # Raised for an unrecognized top-level JSON-RPC method (maps to -32601).
+      class UnknownMethodError < StandardError; end
+      # Raised for a well-formed request with invalid/unknown params (maps to -32602).
+      class InvalidParamsError < StandardError; end
+
+      SUPPORTED_PROTOCOL_VERSIONS = ["2024-11-05"].freeze
+      DEFAULT_TOOL_CALL_TIMEOUT_SECONDS = 15
+
+      RESOURCES = [
+        { uri: "dhanhq://account/profile", name: "Dhan Profile", description: "Current account profile including client ID, PAN, name, and trading permissions",
+          mimeType: "application/json" },
+        { uri: "dhanhq://account/funds", name: "Fund Limits", description: "Available balance, used margin, and withdrawal capacity", mimeType: "application/json" },
+        { uri: "dhanhq://account/holdings", name: "Portfolio Holdings", description: "Current equity holdings with quantity, average price, and P&L", mimeType: "application/json" },
+        { uri: "dhanhq://account/positions", name: "Open Positions", description: "Current F&O and equity positions with net quantity and unrealized P&L",
+          mimeType: "application/json" },
+        { uri: "dhanhq://account/orders", name: "Recent Orders", description: "Recent order history with status, quantity, and fill details", mimeType: "application/json" },
+        { uri: "dhanhq://market/capabilities", name: "Agent Capabilities", description: "All available tools, scopes, risk levels, and version info", mimeType: "application/json" }
+      ].freeze
+
+      PROMPTS = [
+        { name: "portfolio_summary", description: "Generate a human-readable summary of your current portfolio, positions, and available funds" },
+        { name: "market_analysis", description: "Analyze current market conditions and generate a trading context summary" },
+        { name: "risk_report", description: "Review current risk exposure including open positions, P&L, and position limits" },
+        { name: "suggest_strategy", description: "Suggest a trading strategy based on current portfolio and market conditions" },
+        { name: "order_preview", description: "Preview an order before placing it with risk validation" }
+      ].freeze
+
+      def initialize(input: $stdin, output: $stdout, policy: DhanHQ::Agent::Policy.from_env,
+                     tool_call_timeout: DEFAULT_TOOL_CALL_TIMEOUT_SECONDS)
         @input = input
         @output = output
         @policy = policy
+        @tool_call_timeout = tool_call_timeout
       end
 
       def run
@@ -19,32 +50,164 @@ module DhanHQ
 
       def handle_line(line)
         request = JSON.parse(line)
-        respond(request["id"], dispatch(request["method"], request["params"] || {}))
-      rescue StandardError => e
-        respond(nil, nil, code: -32_000, message: e.message)
+      rescue JSON::ParserError => e
+        respond(nil, nil, code: -32_700, message: "Parse error: #{e.message}")
+      else
+        handle_request(request)
       end
 
       private
 
+      def handle_request(request)
+        return unless request.key?("id") # JSON-RPC notification — must not receive a response
+
+        id = request["id"]
+        respond(id, dispatch(request["method"], request["params"] || {}))
+      rescue StandardError => e
+        respond(id, nil, code: error_code_for(e), message: e.message)
+      end
+
+      def error_code_for(error)
+        case error
+        when UnknownMethodError then -32_601
+        when InvalidParamsError then -32_602
+        else -32_603
+        end
+      end
+
       def dispatch(method, params)
         case method
         when "initialize"
           {
-            protocolVersion: "2024-11-05",
+            protocolVersion: negotiate_protocol_version(params["protocolVersion"]),
             serverInfo: { name: "dhanhq-ruby", version: DhanHQ::VERSION },
-            capabilities: { tools: {} }
+            capabilities: { tools: {}, resources: {}, prompts: {} }
           }
         when "tools/list"
           { tools: DhanHQ::Agent::ToolRegistry.list.map { |t| mcp_tool(t) } }
         when "tools/call"
-          result = DhanHQ::Agent::ToolRegistry.execute(
+          { content: [{ type: "text", text: JSON.pretty_generate(serialize(call_tool(params))) }] }
+        when "resources/list"
+          { resources: resource_definitions }
+        when "resources/read"
+          resource = resources.find { |r| r[:uri] == params["uri"] }
+          raise InvalidParamsError, "Unknown resource: #{params["uri"]}" unless resource
+
+          { contents: [resource_read(resource)] }
+        when "prompts/list"
+          { prompts: prompt_definitions }
+        when "prompts/get"
+          prompt = prompts.find { |p| p[:name] == params["name"] }
+          raise InvalidParamsError, "Unknown prompt: #{params["name"]}" unless prompt
+
+          prompt_result(prompt, params.fetch("arguments", {}))
+        else
+          raise UnknownMethodError, "Unsupported MCP method: #{method}"
+        end
+      end
+
+      def negotiate_protocol_version(requested)
+        SUPPORTED_PROTOCOL_VERSIONS.include?(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS.last
+      end
+
+      def call_tool(params)
+        Timeout.timeout(@tool_call_timeout) do
+          DhanHQ::Agent::ToolRegistry.execute(
             params.fetch("name"),
             params.fetch("arguments", {}),
             policy: @policy
           )
-          { content: [{ type: "text", text: JSON.pretty_generate(serialize(result)) }] }
+        end
+      rescue ArgumentError => e
+        raise InvalidParamsError, e.message
+      rescue Timeout::Error
+        raise "Tool call '#{params["name"]}' timed out after #{@tool_call_timeout}s " \
+              "(likely blocked on rate-limit backoff) — retry shortly"
+      end
+
+      def resources
+        RESOURCES
+      end
+
+      def prompts
+        PROMPTS
+      end
+
+      def resource_definitions
+        RESOURCES.map { |r| r.except(:handler) }
+      end
+
+      def resource_read(resource)
+        handler = resource_handler(resource[:uri])
+        data = handler.call
+        { uri: resource[:uri], mimeType: "application/json", text: JSON.pretty_generate(serialize(data)) }
+      end
+
+      def resource_handler(uri)
+        case uri
+        when "dhanhq://account/profile" then -> { DhanHQ::Models::Profile.fetch }
+        when "dhanhq://account/funds" then -> { DhanHQ::Models::Funds.fetch }
+        when "dhanhq://account/holdings" then -> { DhanHQ::Models::Holding.all }
+        when "dhanhq://account/positions" then -> { DhanHQ::Models::Position.all }
+        when "dhanhq://account/orders" then -> { DhanHQ::Models::Order.all }
+        when "dhanhq://market/capabilities" then -> { DhanHQ::Agent::ToolRegistry.capabilities }
+        else raise ArgumentError, "No handler for resource: #{uri}"
+        end
+      end
+
+      def prompt_definitions
+        PROMPTS.map { |p| { name: p[:name], description: p[:description], arguments: prompt_arguments(p[:name]) } }
+      end
+
+      def prompt_arguments(prompt_name)
+        case prompt_name
+        when "order_preview"
+          [{ name: "transaction_type", description: "BUY or SELL", required: true },
+           { name: "security_id", description: "Dhan security ID", required: true },
+           { name: "quantity", description: "Number of shares/lots", required: true },
+           { name: "exchange_segment", description: "NSE_EQ, NSE_FNO, etc.", required: true },
+           { name: "price", description: "Limit price (optional for MARKET)", required: false }]
+        when "market_analysis"
+          [{ name: "symbol", description: "Ticker symbol (e.g., NIFTY, RELIANCE)", required: false }]
+        else
+          []
+        end
+      end
+
+      def prompt_result(prompt, arguments)
+        case prompt[:name]
+        when "portfolio_summary"
+          holdings = DhanHQ::Models::Holding.all
+          positions = DhanHQ::Models::Position.all
+          funds = DhanHQ::Models::Funds.fetch
+          summary = DhanHQ::AI::PromptHelpers.portfolio_summary(holdings: holdings, positions: positions, funds: funds)
+          { messages: [{ role: "user", content: { type: "text", text: summary } }] }
+        when "market_analysis"
+          symbol = arguments["symbol"] || "NIFTY"
+          instrument = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, symbol)
+          security_id = instrument&.security_id&.to_i
+          if security_id
+            snapshot = DhanHQ::Models::MarketFeed.quote(DhanHQ::Constants::ExchangeSegment::IDX_I => [security_id])
+            text = "Market snapshot for #{symbol}: #{snapshot}"
+          else
+            text = "Could not resolve symbol #{symbol} to a security ID for market data."
+          end
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
+        when "risk_report"
+          positions = DhanHQ::Models::Position.all
+          text = DhanHQ::AI::PromptHelpers.risk_report(positions: positions)
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
+        when "order_preview"
+          preview = DhanHQ::Agent::OrderPreview.new(arguments)
+          text = preview.valid? ? "Order preview: #{preview.to_h[:summary]}" : "Validation errors: #{preview.errors.join(", ")}"
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
+        when "suggest_strategy"
+          positions = DhanHQ::Models::Position.all
+          funds = DhanHQ::Models::Funds.fetch
+          text = "Current portfolio: #{positions.size} open positions, Available: ₹#{funds.available_balance}. Review positions for strategy suggestions."
+          { messages: [{ role: "user", content: { type: "text", text: text } }] }
         else
-          raise ArgumentError, "Unsupported MCP method: #{method}"
+          raise ArgumentError, "Unknown prompt: #{prompt[:name]}"
         end
       end
 

data/lib/DhanHQ/models/instrument.rb

@@ -63,25 +63,55 @@ module DhanHQ
           exact_match = options[:exact_match] || false
           case_sensitive = options[:case_sensitive] || false
 
-          instruments = by_segment(exchange_segment)
-          return nil if instruments.empty?
+          csv_text = resource.by_segment(exchange_segment)
+          return nil unless csv_text.is_a?(String) && !csv_text.empty?
 
+          require "csv"
           search_symbol = case_sensitive ? symbol : symbol.upcase
 
-          instruments.find do |instrument|
+          # Scan raw CSV rows and instantiate only the match — building a full
+          # Instrument for every row in a large segment (NSE_EQ is ~219k rows)
+          # is minutes-slow and can use gigabytes of memory (see #by_segment).
+          row = CSV.parse(csv_text, headers: true).find do |r|
             # For equity instruments, prefer underlying_symbol over symbol_name
-            instrument_symbol = if instrument.instrument == DhanHQ::Constants::InstrumentType::EQUITY && instrument.underlying_symbol
-                                  case_sensitive ? instrument.underlying_symbol : instrument.underlying_symbol.upcase
-                                else
-                                  case_sensitive ? instrument.symbol_name : instrument.symbol_name.upcase
-                                end
-
-            if exact_match
-              instrument_symbol == search_symbol
-            else
-              instrument_symbol.include?(search_symbol)
-            end
+            row_symbol = if r["INSTRUMENT"] == DhanHQ::Constants::InstrumentType::EQUITY && !r["UNDERLYING_SYMBOL"].to_s.empty?
+                           r["UNDERLYING_SYMBOL"]
+                         else
+                           r["SYMBOL_NAME"]
+                         end
+            next false if row_symbol.nil?
+
+            comparable = case_sensitive ? row_symbol : row_symbol.upcase
+            exact_match ? comparable == search_symbol : comparable.include?(search_symbol)
           end
+
+          return nil unless row
+
+          new(normalize_csv_row(row), skip_validation: true)
+        end
+
+        # Find a specific instrument within a segment by its security ID.
+        # @param exchange_segment [String] The exchange segment (e.g., "NSE_EQ", "NSE_FNO")
+        # @param security_id [String, Integer] The Dhan security ID
+        # @return [Instrument, nil] The found instrument or nil if not found
+        # @example
+        #   instrument = DhanHQ::Models::Instrument.find_by_security_id("NSE_EQ", "2885")
+        #   puts instrument.symbol_name  # => "RELIANCE"
+        def find_by_security_id(exchange_segment, security_id)
+          validate_params!({ exchange_segment: exchange_segment }, DhanHQ::Contracts::InstrumentListContract)
+
+          csv_text = resource.by_segment(exchange_segment)
+          return nil unless csv_text.is_a?(String) && !csv_text.empty?
+
+          require "csv"
+          # Scan raw CSV rows and instantiate only the match — building a full
+          # Instrument (and its per-attribute singleton methods) for every row
+          # in a large segment (NSE_EQ is ~219k rows) is minutes-slow and can
+          # use gigabytes of memory. See #by_segment for the bulk path.
+          row = CSV.parse(csv_text, headers: true).find { |r| r["SECURITY_ID"].to_s == security_id.to_s }
+          return nil unless row
+
+          new(normalize_csv_row(row), skip_validation: true)
         end
 
         # Find a specific instrument across all exchange segments.

data/lib/DhanHQ/rate_limiter.rb

@@ -5,10 +5,12 @@ require "concurrent"
 module DhanHQ
   # Coarse-grained in-memory throttler matching the platform rate limits.
   class RateLimiter
-    # Per-interval thresholds keyed by API type.
+    # Per-interval thresholds keyed by API type, matching the published
+    # DhanHQ rate-limit table (Order APIs: 10/sec, 100,000/day;
+    # Data APIs: 5/sec, 7,000/day; Market Quote: 1/sec; Option Chain: 1 per 3 sec).
     RATE_LIMITS = {
-      order_api: { per_second: 25, per_minute: 250, per_hour: 1000, per_day: 7000 },
-      data_api: { per_second: 5, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: 100_000 },
+      order_api: { per_second: 10, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: 100_000 },
+      data_api: { per_second: 5, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: 7_000 },
       quote_api: { per_second: 1, per_minute: Float::INFINITY, per_hour: Float::INFINITY, per_day: Float::INFINITY },
       option_chain: { per_second: 1.0 / 3, per_minute: 20, per_hour: 600, per_day: 4800 },
       non_trading_api: { per_second: 20, per_minute: Float::INFINITY, per_hour: Float::INFINITY,

data/lib/DhanHQ/resources/alert_orders.rb

@@ -13,6 +13,7 @@ module DhanHQ
 
       def create(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_ALERT_ORDER_ATTEMPT", params)
         super
       end

data/lib/DhanHQ/resources/forever_orders.rb

@@ -26,6 +26,7 @@ module DhanHQ
       # @return [Hash]
       def create(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_FOREVER_ORDER_ATTEMPT", params)
         post("/orders", params: params)
       end

data/lib/DhanHQ/resources/iceberg_orders.rb

@@ -24,6 +24,7 @@ module DhanHQ
       # @return [Hash]
       def create(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_ICEBERG_ORDER_ATTEMPT", params)
         post("", params: params)
       end

data/lib/DhanHQ/resources/orders.rb

@@ -17,6 +17,7 @@ module DhanHQ
 
       def create(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_ORDER_ATTEMPT", params)
         validate_place_order!(params)
         post("", params: params)
@@ -31,6 +32,7 @@ module DhanHQ
 
       def slicing(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_ORDER_SLICING_ATTEMPT", params)
         validate_place_order!(params)
         post("/slicing", params: params)

data/lib/DhanHQ/resources/pnl_exit.rb

@@ -19,6 +19,7 @@ module DhanHQ
       # @return [Hash] API response containing pnlExitStatus and message.
       def configure(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_PNL_EXIT_CONFIGURE_ATTEMPT", params)
         post("", params: params)
       end

data/lib/DhanHQ/resources/super_orders.rb

@@ -28,6 +28,7 @@ module DhanHQ
       # @return [Hash]
       def create(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_SUPER_ORDER_ATTEMPT", params)
         post("", params: params)
       end

data/lib/DhanHQ/resources/twap_orders.rb

@@ -24,6 +24,7 @@ module DhanHQ
       # @return [Hash]
       def create(params)
         ensure_live_trading!
+        run_risk_checks!(params)
         log_order_context("DHAN_TWAP_ORDER_ATTEMPT", params)
         post("", params: params)
       end

data/lib/DhanHQ/risk/checks/concentration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces maximum portfolio concentration in any single symbol.
+      class Concentration
+        MAX_CONCENTRATION_PCT = 25.0
+
+        def self.run!(args:, **_unused)
+          symbol = args["trading_symbol"] || args["security_id"]
+          return unless symbol
+
+          funds = DhanHQ::Models::Funds.fetch
+          available = funds.available_balance.to_f
+          return if available <= 0
+
+          positions = DhanHQ::Models::Position.all
+          symbol_positions = positions.select do |p|
+            sym = p.trading_symbol || p.security_id
+            sym.to_s == symbol.to_s
+          end
+
+          current_exposure = symbol_positions.sum do |p|
+            p.net_qty.to_i.abs * p.cost_price.to_f
+          end
+
+          concentration_pct = (current_exposure / available) * 100.0
+          return if concentration_pct <= MAX_CONCENTRATION_PCT
+
+          raise DhanHQ::RiskViolation,
+                "Concentration #{concentration_pct.round(1)}% exceeds #{MAX_CONCENTRATION_PCT}% limit for #{symbol}"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/max_loss.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces daily maximum loss limit across all positions.
+      class MaxLoss
+        DAILY_MAX_LOSS = 50_000
+
+        def self.run!(**_unused)
+          positions = DhanHQ::Models::Position.all
+          total_unrealized_loss = positions.sum do |p|
+            p.unrealized_profit.to_f
+          end
+
+          return if total_unrealized_loss >= -DAILY_MAX_LOSS
+
+          raise DhanHQ::RiskViolation,
+                "Daily loss limit of ₹#{DAILY_MAX_LOSS} exceeded (current: ₹#{total_unrealized_loss.round(0)})"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/checks/position_limits.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Risk
+    module Checks
+      # Enforces maximum number of concurrent open positions.
+      class PositionLimits
+        MAX_OPEN_POSITIONS = 20
+
+        def self.run!(**_unused)
+          positions = DhanHQ::Models::Position.all
+          open_count = positions.count do |p|
+            p.net_qty.to_i != 0
+          end
+
+          return if open_count < MAX_OPEN_POSITIONS
+
+          raise DhanHQ::RiskViolation,
+                "Maximum #{MAX_OPEN_POSITIONS} open positions exceeded (#{open_count} open)"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/risk/pipeline.rb

@@ -30,13 +30,19 @@ module DhanHQ
         Checks::ProductSupport,
         Checks::OrderType,
         Checks::Quantity,
-        Checks::MarketHours
+        Checks::MarketHours,
+        Checks::PositionLimits,
+        Checks::Concentration
       ].freeze
 
       OPTION_CHECKS = [
         Checks::Options
       ].freeze
 
+      DAILY_CHECKS = [
+        Checks::MaxLoss
+      ].freeze
+
       # Run all applicable risk checks.
       #
       # @param instrument [Object] instrument with trading metadata
@@ -49,6 +55,7 @@ module DhanHQ
       def self.run!(instrument:, args:, now: Time.now, type: :equity)
         run_checks!(CHECKS, instrument, args, now)
         run_checks!(OPTION_CHECKS, instrument, args, now) if type == :options
+        run_checks!(DAILY_CHECKS, instrument, args, now)
         true
       end
       # rubocop:enable Naming/PredicateMethod

data/lib/DhanHQ/skills/base.rb

@@ -23,7 +23,7 @@ module DhanHQ
     #     end
     #
     #     def get_spot_price(ctx)
-    #       ctx[:spot_price] = ctx[:instrument].ltp[:ltp]
+    #       ctx[:spot_price] = ctx[:instrument].ltp
     #       ctx
     #     end
     #
@@ -56,6 +56,28 @@ module DhanHQ
           @steps.sort_by! { |s| s[:priority] }
         end
 
+        # MCP risk level for this skill (defaults to the most conservative tier
+        # so a skill that forgets to declare one fails safe/write-gated).
+        #
+        # @param level [String, nil] one of read_only, trade_adjacent_read, live_write, destructive_write
+        def risk(level = nil)
+          level ? (@risk = level) : (@risk || "destructive_write")
+        end
+
+        # MCP policy scope required to invoke this skill.
+        #
+        # @param value [String, nil] e.g. "orders:read", "orders:write"
+        def scope(value = nil)
+          value ? (@scope = value) : (@scope || "orders:write")
+        end
+
+        # Human-readable description shown to MCP/LLM clients in tools/list.
+        #
+        # @param text [String, nil] one-line summary of what the skill does
+        def description(text = nil)
+          text ? (@description = text) : @description
+        end
+
         # Accessor for defined parameters.
         def params
           @params || {}
@@ -104,9 +126,9 @@ module DhanHQ
         self.class.name || self.class.to_s
       end
 
-      # Skill description (override in subclasses).
+      # Skill description (declare via the class-level `description` macro; falls back to class name).
       def description
-        self.class.to_s
+        self.class.description || self.class.to_s
       end
 
       # List of parameter definitions for this skill.
@@ -116,6 +138,35 @@ module DhanHQ
 
       private
 
+      # Real DhanHQ::Models::OptionChain#fetch shape: { last_price:, strikes: [{ strike:, call: {...}, put: {...} }] }.
+      # Nearest strike to a target price — always returns an entry (never nil) unless the chain is empty.
+      def nearest_strike(chain, target_price)
+        strikes = chain[:strikes]
+        return nil if strikes.nil? || strikes.empty?
+
+        strikes.min_by { |s| (s[:strike].to_f - target_price.to_f).abs }
+      end
+
+      # Exact strike match within tolerance — nil if no strike sits on that price.
+      def find_strike(chain, target_price, tolerance: 0.001)
+        strikes = chain[:strikes]
+        return nil if strikes.nil? || strikes.empty?
+
+        strikes.find { |s| (s[:strike].to_f - target_price.to_f).abs < tolerance }
+      end
+
+      def leg_side(strike_entry, option_type)
+        option_type == "CE" ? strike_entry[:call] : strike_entry[:put]
+      end
+
+      def leg_security_id(strike_entry, option_type)
+        leg_side(strike_entry, option_type)[:security_id]
+      end
+
+      def leg_premium(strike_entry, option_type)
+        leg_side(strike_entry, option_type)[:last_price]
+      end
+
       def build_context(args)
         ctx = {}
 

data/lib/DhanHQ/skills/builtin/bear_call_spread.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Skills
+    module Builtin
+      # Skill to build a bear call spread (sell OTM call, buy further OTM call).
+      #
+      # Steps: find instrument → spot price → option chain →
+      # select strikes → build intent.
+      #
+      # @example
+      #   result = DhanHQ::Skills::Registry.call("bear_call_spread",
+      #     symbol: "NIFTY",
+      #     expiry: "2026-01-30",
+      #     quantity: 50
+      #   )
+      #
+      class BearCallSpread < Base
+        risk "trade_adjacent_read"
+        scope "orders:read"
+        description "Build a bear call spread: sell an OTM call, buy a further OTM call for defined risk."
+
+        param :symbol, type: :string, required: true
+        param :expiry, type: :string, required: true
+        param :quantity, type: :integer, default: 50
+        param :spread_width, type: :number, default: 200
+        param :max_loss, type: :number, default: 5000
+
+        step :find_instrument, priority: 1
+        step :get_spot_price, priority: 2
+        step :get_option_chain, priority: 3
+        step :select_strikes, priority: 4
+        step :build_intent, priority: 5
+
+        def find_instrument(ctx)
+          ctx[:instrument] = DhanHQ::Models::Instrument.find(DhanHQ::Constants::ExchangeSegment::IDX_I, ctx[:symbol])
+          ctx
+        end
+
+        def get_spot_price(ctx)
+          ctx[:spot_price] = ctx[:instrument].ltp
+          ctx
+        end
+
+        def get_option_chain(ctx)
+          ctx[:chain] = ctx[:instrument].option_chain(expiry: ctx[:expiry])
+          ctx
+        end
+
+        def select_strikes(ctx)
+          spot = ctx[:spot_price].to_f
+          chain = ctx[:chain]
+          spread = ctx[:spread_width].to_f
+
+          atm_strike_price = nearest_strike(chain, spot)[:strike].to_f
+
+          short_call = find_strike(chain, atm_strike_price + spread)
+          long_call = find_strike(chain, atm_strike_price + (spread * 2))
+
+          raise ArgumentError, "Could not build bear call spread — insufficient strikes in chain" unless short_call && long_call
+
+          ctx[:legs] = [
+            { action: DhanHQ::Constants::TransactionType::SELL, option_type: "CE", strike: short_call[:strike],
+              security_id: leg_security_id(short_call, "CE") },
+            { action: DhanHQ::Constants::TransactionType::BUY, option_type: "CE", strike: long_call[:strike],
+              security_id: leg_security_id(long_call, "CE") }
+          ]
+          ctx
+        end
+
+        def build_intent(ctx)
+          ctx[:intent] = {
+            trade_type: "BEAR_CALL_SPREAD",
+            symbol: ctx[:symbol],
+            expiry: ctx[:expiry],
+            quantity: ctx[:quantity],
+            spread_width: ctx[:spread_width],
+            max_loss: ctx[:max_loss],
+            legs: ctx[:legs],
+            note: "Bear call spread prepared. Await human confirmation before execution."
+          }
+          ctx
+        end
+      end
+    end
+  end
+end