DhanHQ 3.0.1 → 3.2.0

data/docs/WEBSOCKET_INTEGRATION.md

@@ -317,12 +317,10 @@ end
 client = DhanHQ::WS::MarketDepth.client
 
 # Event handlers
+# Note: the current implementation only ever emits :depth_update (never :depth_snapshot),
+# and update_data has no :side key — inspect update_data[:bids]/[:asks] directly instead.
 client.on(:depth_update) do |update_data|
-  puts "📊 Depth Update: #{update_data[:symbol]} - #{update_data[:side]} side updated"
-end
-
-client.on(:depth_snapshot) do |snapshot_data|
-  puts "📸 Depth Snapshot: #{snapshot_data[:symbol]} - Full order book received"
+  puts "📊 Depth Update: #{update_data[:symbol]} - bids/asks refreshed"
 end
 
 client.on(:error) do |error|
@@ -771,8 +769,7 @@ puts "Orders connected: #{orders_client.connected?}"
 puts "Market connected: #{market_client.connected?}"
 puts "Depth connected: #{depth_client.connected?}"
 
-# Get subscription info
-puts "Market subscriptions: #{market_client.subscriptions}"
+# Get subscription info (only DhanHQ::WS::MarketDepth::Client exposes this)
 puts "Depth subscriptions: #{depth_client.subscriptions}"
 ```
 
@@ -890,30 +887,26 @@ puts "Orders connected: #{orders_client.connected?}"
 puts "Market connected: #{market_client.connected?}"
 puts "Depth connected: #{depth_client.connected?}"
 
-# Get subscription info
-puts "Market subscriptions: #{market_client.subscriptions}"
+# Get subscription info (only DhanHQ::WS::MarketDepth::Client exposes this)
 puts "Depth subscriptions: #{depth_client.subscriptions}"
 ```
 
 ## Testing
 
-For comprehensive testing examples and interactive console helpers, see the [Testing Guide](TESTING_GUIDE.md). The guide includes:
-
-- **WebSocket Testing**: Market feed, order updates, and market depth examples
-- **Interactive Console Helpers**: Load `bin/test_helpers.rb` for quick test functions
-- **Complete Examples**: Copy-paste examples for all WebSocket features
+For comprehensive testing examples, see the [Testing Guide](TESTING_GUIDE.md).
 
 **Quick start in console:**
 ```ruby
 # Start console
 bin/console
 
-# Load test helpers
-load 'bin/test_helpers.rb'
-
-# Test WebSocket connections
-test_websocket(:ticker, 5)      # Test market feed for 5 seconds
-test_order_websocket(5)        # Test order updates for 5 seconds
+# Test market feed for 5 seconds
+ticks = []
+client = DhanHQ::WS.connect(mode: :ticker) { |tick| ticks << tick }
+client.subscribe_one(segment: "IDX_I", security_id: 13)
+sleep 5
+client.disconnect!
+p ticks
 ```
 
 ## Examples

data/docs/WEBSOCKET_PROTOCOL.md

@@ -16,14 +16,16 @@ Low-level protocol details for the DhanHQ WebSocket market feed. For high-level
 
 ## Request Codes
 
-Per Dhan documentation:
+Per the actual implementation (`lib/DhanHQ/ws/connection.rb`):
 
 | Action       | Ticker | Quote | Full |
 | ------------ | ------ | ----- | ---- |
-| Subscribe    | 15     | 17    | 21   |
-| Unsubscribe  | 16     | 18    | 22   |
+| Subscribe    | 15     | 15    | 15   |
+| Unsubscribe  | 12     | 12    | 12   |
 | Disconnect   | 12     | 12    | 12   |
 
+All three modes send request code `15` to subscribe (per the official API — mode is set at connection time via the WebSocket URL, not per-message). "Unsubscribe" reuses the disconnect code `12` for all modes rather than distinct per-mode codes.
+
 ---
 
 ## Packet Parsing
@@ -48,7 +50,9 @@ Per Dhan documentation:
 | 6    | Prev Close    | `prev_close`, `oi_prev`                                      |
 | 7    | Market Status | Raw/misc unless documented                                   |
 | 8    | Full          | Quote fields + `open_interest` + 5× depth (bid/ask)         |
+| 41   | Depth Bid     | Market depth bid levels (20-level depth feed)                |
 | 50   | Disconnect    | Reason code                                                  |
+| 51   | Depth Ask     | Market depth ask levels (20-level depth feed)                |
 
 ---
 

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/key_coercion.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # Recursive key coercion for arguments crossing the agent boundary.
+    #
+    # MCP delivers arguments as JSON, so keys arrive as strings; handlers and the risk
+    # pipeline expect symbols and strings respectively.
+    #
+    # Called explicitly (`KeyCoercion.symbolize(...)`) rather than mixed in, so there is
+    # no question about method visibility at the call site.
+    module KeyCoercion
+      module_function
+
+      # @param value [Hash, Array, Object]
+      # @return [Hash, Array, Object] Same shape with symbol keys throughout.
+      def symbolize(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, val), hash| hash[key.to_sym] = symbolize(val) }
+        when Array then value.map { |val| symbolize(val) }
+        else value
+        end
+      end
+
+      # @param value [Hash, Array, Object]
+      # @return [Hash, Array, Object] Same shape with string keys throughout.
+      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
+  end
+end

data/lib/DhanHQ/agent/tool.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # A single tool exposed to MCP clients and agent skills.
+    #
+    # - +name+, +description+ — what a client sees in `tools/list`
+    # - +scope+ — the {DhanHQ::Agent::Policy} scope required to call it
+    # - +risk+ — +read_only+, +trade_adjacent_read+, +live_write+ or +destructive_write+;
+    #   anything ending in +write+ goes through `Policy#require_write!`
+    # - +schema+, +output_schema+ — JSON Schema for input and return value
+    # - +handler+ — callable invoked with symbolized arguments
+    # - +version+ — semantic version of this tool definition
+    # - +examples+ — optional input/output pairs shown to clients
+    Tool = Struct.new(:name, :description, :scope, :risk, :schema, :handler,
+                      :version, :output_schema, :examples) do
+      # @return [Hash] Client-facing metadata, omitting unset optional fields.
+      def to_h
+        {
+          name: name,
+          description: description,
+          scope: scope,
+          risk: risk,
+          input_schema: schema,
+          output_schema: output_schema,
+          version: version,
+          examples: examples
+        }.compact
+      end
+
+      # @return [Boolean] True when calling this tool changes account state.
+      def write?
+        risk.to_s.end_with?("write")
+      end
+    end
+  end
+end

data/lib/DhanHQ/agent/tool_catalogue.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # The catalogue of tools exposed to MCP clients and agent skills: what exists, at
+    # what scope, at what risk, and which handler carries it out.
+    #
+    # Declarative on purpose — adding an endpoint means adding an entry here, a schema
+    # in {DhanHQ::Agent::ToolSchemas} and a handler in {DhanHQ::Agent::ToolHandlers}.
+    # {DhanHQ::Agent::ToolRegistry} consumes this and is left responsible only for
+    # lookup, policy enforcement and dispatch.
+    module ToolCatalogue
+      extend ToolSchemas
+      extend ToolHandlers
+
+      # Version stamped on a tool definition that does not declare its own.
+      DEFAULT_TOOL_VERSION = "1.0.0"
+
+      module_function
+
+      # Every tool, keyed by name.
+      #
+      # @return [Hash{String => DhanHQ::Agent::Tool}]
+      def all
+        build_tools
+      end
+
+      def build_tools
+        (primitive_tools + global_stocks_tools + skill_tools).to_h { |tool_item| [tool_item.name, tool_item] }
+      end
+
+      def primitive_tools
+        [
+          tool(name: "dhan_profile", description: "Fetch Dhan profile",
+               scope: "portfolio:read", risk: "read_only",
+               schema: object_schema, handler: profile_handler,
+               output_schema: { type: "object", properties: { client_id: { type: "string" } } }),
+          tool(name: "dhan_funds", description: "Fetch fund limits",
+               scope: "portfolio:read", risk: "read_only",
+               schema: object_schema, handler: funds_handler,
+               output_schema: { type: "object", properties: { available_balance: { type: "number" } } }),
+          tool(name: "dhan_holdings", description: "List holdings",
+               scope: "portfolio:read", risk: "read_only",
+               schema: object_schema, handler: holdings_handler,
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool(name: "dhan_positions", description: "List positions",
+               scope: "portfolio:read", risk: "read_only",
+               schema: object_schema, handler: positions_handler,
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool(name: "dhan_orders", description: "List orders",
+               scope: "orders:read", risk: "read_only",
+               schema: object_schema, handler: orders_handler,
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool(name: "dhan_trades", description: "List trades",
+               scope: "orders:read", risk: "read_only",
+               schema: object_schema, handler: trades_handler,
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool(name: "dhan_search_instruments", description: "Resolve symbols to security IDs",
+               scope: "market:read", risk: "read_only",
+               schema: search_schema, handler: search_handler,
+               output_schema: { type: "array", items: { type: "object" } },
+               examples: [
+                 { input: { query: "RELIANCE" }, output: "[{security_id: '2885', symbol_name: 'RELIANCE'}]" }
+               ]),
+          tool(name: "dhan_ltp", description: "Fetch last traded prices",
+               scope: "market:read", risk: "read_only",
+               schema: feed_schema, handler: ltp_handler,
+               output_schema: { type: "object", additionalProperties: { type: "number" } }),
+          tool(name: "dhan_quote", description: "Fetch market quotes",
+               scope: "market:read", risk: "read_only",
+               schema: feed_schema, handler: quote_handler,
+               output_schema: { type: "object", additionalProperties: { type: "object" } }),
+          tool(name: "dhan_order_preview", description: "Validate and summarize an order without placing it",
+               scope: "orders:read", risk: "trade_adjacent_read",
+               schema: order_schema, handler: preview_handler,
+               output_schema: {
+                 type: "object",
+                 properties: {
+                   valid: { type: "boolean" },
+                   errors: { type: "array" },
+                   summary: { type: "string" }
+                 }
+               }),
+          tool(name: "dhan_place_order", description: "Place an order after external confirmation",
+               scope: "orders:write", risk: "live_write",
+               schema: order_schema, handler: place_order_handler,
+               output_schema: { type: "object", properties: { order_id: { type: "string" } } }),
+          tool(name: "dhan_cancel_order", description: "Cancel an order",
+               scope: "orders:cancel", risk: "destructive_write",
+               schema: cancel_schema, handler: cancel_order_handler,
+               output_schema: {
+                 type: "object",
+                 properties: { order_id: { type: "string" }, status: { type: "string" } }
+               })
+        ]
+      end
+
+      # Tools for the Global Stocks (US equities) book, plus basket orders.
+      #
+      # Global Stocks are a separate book from domestic NSE/BSE trading, so they get
+      # their own tools rather than extra flags on the domestic ones — an agent asked
+      # for "my holdings" should not silently mix INR and USD positions.
+      def global_stocks_tools
+        [
+          tool(name: "dhan_global_holdings", description: "List US stock holdings",
+               scope: "portfolio:read", risk: "read_only",
+               schema: object_schema, handler: global_holdings_handler,
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool(name: "dhan_global_funds", description: "Fetch US (USD) fund limits",
+               scope: "portfolio:read", risk: "read_only",
+               schema: object_schema, handler: global_funds_handler,
+               output_schema: { type: "object", properties: { available_cash: { type: "number" } } }),
+          tool(name: "dhan_global_orders", description: "List US stock orders",
+               scope: "orders:read", risk: "read_only",
+               schema: object_schema, handler: global_orders_handler,
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool(name: "dhan_global_trades", description: "List US stock trades",
+               scope: "orders:read", risk: "read_only",
+               schema: object_schema, handler: global_trades_handler,
+               output_schema: { type: "array", items: { type: "object" } }),
+          tool(name: "dhan_global_market_status", description: "Check whether the US market is open",
+               scope: "market:read", risk: "read_only",
+               schema: object_schema, handler: global_market_status_handler,
+               output_schema: {
+                 type: "object",
+                 properties: { status: { type: "string" }, open: { type: "boolean" } }
+               }),
+          tool(name: "dhan_global_order_estimate",
+               description: "Estimate charges and margin for a US stock order without placing it",
+               scope: "orders:read", risk: "trade_adjacent_read",
+               schema: global_estimate_schema, handler: global_estimate_handler,
+               output_schema: {
+                 type: "object",
+                 properties: { total_charges: { type: "number" }, total_margin: { type: "number" } }
+               }),
+          tool(name: "dhan_global_place_order", description: "Place a US stock order after external confirmation",
+               scope: "orders:write", risk: "live_write",
+               schema: global_order_schema, handler: global_place_order_handler,
+               output_schema: { type: "object", properties: { order_id: { type: "string" } } }),
+          tool(name: "dhan_global_cancel_order", description: "Cancel a US stock order",
+               scope: "orders:cancel", risk: "destructive_write",
+               schema: cancel_schema, handler: global_cancel_order_handler,
+               output_schema: { type: "object", properties: { order_id: { type: "string" } } }),
+          tool(name: "dhan_multi_order", description: "Place a basket of up to 15 domestic orders in one request",
+               scope: "orders:write", risk: "live_write",
+               schema: multi_order_schema, handler: multi_order_handler,
+               output_schema: {
+                 type: "object",
+                 properties: { orders: { type: "array", items: { type: "object" } } }
+               })
+        ]
+      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(name: "dhan_skill_#{skill[:name]}", description: skill[:description],
+               scope: klass.scope, risk: klass.risk,
+               schema: skill_input_schema(skill[:params]),
+               handler: ->(arguments) { DhanHQ::Skills::Registry.call(skill[:name], arguments) })
+        end
+      end
+
+      # Builds a {DhanHQ::Agent::Tool}.
+      #
+      # Keyword-only: with nine attributes, positional order was a memory test, and a
+      # transposed scope and risk would have produced a silently mis-gated tool.
+      # An unknown attribute raises, so a typo cannot create a half-built tool.
+      #
+      # @param attributes [Hash] Any {DhanHQ::Agent::Tool} member. +version+ defaults
+      #   to {DEFAULT_TOOL_VERSION}.
+      # @return [DhanHQ::Agent::Tool]
+      def tool(**attributes)
+        Tool.new(version: DEFAULT_TOOL_VERSION, **attributes)
+      end
+    end
+  end
+end

data/lib/DhanHQ/agent/tool_handlers.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Agent
+    # Callables that carry out each agent tool, one per tool.
+    #
+    # Every handler takes a hash of symbolized arguments and returns a model, a plain
+    # hash, or a boolean. Policy enforcement happens before a handler is reached — see
+    # {DhanHQ::Agent::ToolRegistry#execute} — so handlers here contain no scope or
+    # live-trading checks of their own; the resources they call apply the
+    # `LIVE_TRADING` gate and audit logging.
+    module ToolHandlers
+      module_function
+
+      def profile_handler = ->(_) { DhanHQ::Models::Profile.fetch }
+
+      def funds_handler = ->(_) { DhanHQ::Models::Funds.fetch }
+
+      def holdings_handler = ->(_) { DhanHQ::Models::Holding.all }
+
+      def positions_handler = ->(_) { DhanHQ::Models::Position.all }
+
+      def orders_handler = ->(_) { DhanHQ::Models::Order.all }
+
+      def trades_handler = ->(_) { DhanHQ::Models::Trade.today }
+
+      def search_handler
+        lambda do |arguments|
+          query = arguments.fetch(:query)
+          options = arguments.except(:query)
+          DhanHQ::Models::Instrument.search(query, **options)
+        end
+      end
+
+      def ltp_handler = ->(arguments) { DhanHQ::Models::MarketFeed.ltp(arguments[:instruments]) }
+
+      def quote_handler = ->(arguments) { DhanHQ::Models::MarketFeed.quote(arguments[:instruments]) }
+
+      def preview_handler = ->(arguments) { OrderPreview.new(arguments).to_h }
+
+      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: KeyCoercion.stringify(arguments), type: risk_type)
+
+          DhanHQ::Models::Order.place(arguments)
+        end
+      end
+
+      def cancel_order_handler
+        lambda do |arguments|
+          order = DhanHQ::Models::Order.find(arguments[:order_id])
+          order&.cancel || false
+        end
+      end
+
+      def global_holdings_handler = ->(_) { DhanHQ::Models::GlobalStocks::Holding.all }
+
+      def global_funds_handler = ->(_) { DhanHQ::Models::GlobalStocks::Funds.fetch }
+
+      def global_orders_handler = ->(_) { DhanHQ::Models::GlobalStocks::Order.all }
+
+      def global_trades_handler = ->(_) { DhanHQ::Models::GlobalStocks::Trade.all }
+
+      def global_market_status_handler
+        lambda do |_|
+          status = DhanHQ::Models::GlobalStocks::MarketStatus.fetch
+          {
+            status: status.status,
+            open: status.open?,
+            holiday: status.holiday?,
+            market_open_time: status.market_open_time,
+            market_close_time: status.market_close_time
+          }
+        end
+      end
+
+      # Combines the charge estimate and the margin requirement so an agent can decide
+      # affordability in one call rather than two.
+      def global_estimate_handler
+        lambda do |arguments|
+          estimate = DhanHQ::Models::GlobalStocks::OrderEstimate.calculate(arguments)
+          margin = DhanHQ::Models::GlobalStocks::Margin.calculate(arguments)
+          {
+            total_charges: estimate.total_charges,
+            brokerage: estimate.brokerage,
+            total_margin: margin.total_margin,
+            available_balance: margin.available_bal,
+            sufficient: margin.sufficient?
+          }
+        end
+      end
+
+      # No {DhanHQ::Risk::Pipeline} run here: its checks resolve instruments from the
+      # Indian scrip master and encode NSE/BSE rules, neither of which applies to US
+      # equities. The LIVE_TRADING gate and audit logging in the resource still apply,
+      # as does {Policy#require_write!}.
+      def global_place_order_handler = ->(arguments) { DhanHQ::Models::GlobalStocks::Order.place(arguments) }
+
+      def global_cancel_order_handler
+        lambda do |arguments|
+          order_id = arguments[:order_id]
+          { order_id: order_id, cancelled: DhanHQ::Models::GlobalStocks::Order.cancel(order_id) }
+        end
+      end
+
+      def multi_order_handler = ->(arguments) { DhanHQ::Models::MultiOrder.place(arguments[:orders]) }
+    end
+  end
+end