DhanHQ 2.8.0 → 3.0.1

data/lib/DhanHQ/market_data/ohlc_series.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module MarketData
+    # A time series of OHLCV candles for a single instrument.
+    #
+    # Wraps historical data responses into a convenient array-like structure
+    # with helper methods for analysis.
+    #
+    # @example Build a series from historical data response
+    #   response = DhanHQ::Models::HistoricalData.daily(
+    #     security_id: "11536",
+    #     exchange_segment: "NSE_EQ",
+    #     instrument: "EQUITY",
+    #     from_date: "2024-01-01",
+    #     to_date: "2024-12-31"
+    #   )
+    #   series = DhanHQ::MarketData::OHLCSeries.from_response(response)
+    #   series.closes #=> [2800.0, 2810.5, ...]
+    #   series.volumes #=> [123456, 234567, ...]
+    #
+    class OHLCSeries
+      include Enumerable
+
+      Candle = Struct.new(:timestamp, :open, :high, :low, :close, :volume, :open_interest) do
+        def body_size
+          (close - open).abs
+        end
+
+        def upper_shadow
+          high - [open, close].max
+        end
+
+        def lower_shadow
+          [open, close].min - low
+        end
+
+        def bullish?
+          close > open
+        end
+
+        def bearish?
+          close < open
+        end
+
+        def doji?
+          (close - open).abs < (high - low) * 0.1
+        end
+      end
+
+      attr_reader :candles, :security_id, :exchange_segment
+
+      def initialize(candles = [], metadata = {})
+        @candles = candles
+        @security_id = metadata[:security_id]
+        @exchange_segment = metadata[:exchange_segment]
+      end
+
+      # Build an OHLCSeries from a raw historical data API response.
+      def self.from_response(response)
+        data = response.is_a?(Hash) ? (response[:data] || response["data"] || response) : response
+        data = [data] unless data.is_a?(Array)
+
+        candles = data.map do |candle|
+          Candle.new(
+            timestamp: candle[:timestamp] || candle["timestamp"],
+            open: (candle[:open] || candle["open"]).to_f,
+            high: (candle[:high] || candle["high"]).to_f,
+            low: (candle[:low] || candle["low"]).to_f,
+            close: (candle[:close] || candle["close"]).to_f,
+            volume: (candle[:volume] || candle["volume"]).to_i,
+            open_interest: candle[:open_interest] || candle["open_interest"]
+          )
+        end
+
+        new(candles)
+      end
+
+      def each(&)
+        @candles.each(&)
+      end
+
+      def size
+        @candles.size
+      end
+
+      def empty?
+        @candles.empty?
+      end
+
+      # Get all close prices.
+      def closes
+        @candles.map(&:close)
+      end
+
+      # Get all open prices.
+      def opens
+        @candles.map(&:open)
+      end
+
+      # Get all high prices.
+      def highs
+        @candles.map(&:high)
+      end
+
+      # Get all low prices.
+      def lows
+        @candles.map(&:low)
+      end
+
+      # Get all volumes.
+      def volumes
+        @candles.map(&:volume)
+      end
+
+      # Get the most recent candle.
+      def last
+        @candles.last
+      end
+
+      # Get the oldest candle.
+      def first
+        @candles.first
+      end
+
+      # Get the date range of the series.
+      def date_range
+        return nil if empty?
+
+        [first.timestamp, last.timestamp]
+      end
+
+      # Calculate the total volume across all candles.
+      def total_volume
+        @candles.sum(&:volume)
+      end
+
+      # Calculate the average close price.
+      def average_close
+        return nil if empty?
+
+        closes.sum / size
+      end
+
+      # Calculate the price range (highest high - lowest low).
+      def price_range
+        return nil if empty?
+
+        highs.max - lows.min
+      end
+
+      # Slice the series by date range (requires timestamps).
+      def slice_range(from_timestamp, to_timestamp)
+        self.class.new(
+          @candles.select { |c| c.timestamp.between?(from_timestamp, to_timestamp) },
+          { security_id: @security_id, exchange_segment: @exchange_segment }
+        )
+      end
+
+      # Take the last N candles.
+      def tail(count)
+        self.class.new(
+          @candles.last(count),
+          { security_id: @security_id, exchange_segment: @exchange_segment }
+        )
+      end
+    end
+  end
+end

data/lib/DhanHQ/market_data/option_snapshot.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module MarketData
+    # A snapshot of option chain data for a single underlying.
+    #
+    # Wraps the raw OptionChain response into a convenient structure
+    # with typed accessors and helper methods for option analysis.
+    #
+    # @example Build a snapshot from OptionChain response
+    #   response = DhanHQ::Models::OptionChain.fetch(
+    #     underlying_scrip: 13,
+    #     underlying_seg: "IDX_I",
+    #     expiry: "2024-07-25"
+    #   )
+    #   snapshot = DhanHQ::MarketData::OptionSnapshot.from_response(response)
+    #   snapshot.calls_at(24000) #=> Array of call option data
+    #   snapshot.puts_at(24000) #=> Array of put option data
+    #
+    class OptionSnapshot
+      OptionLeg = Struct.new(:strike_price, :option_type, :ltp, :bid, :ask,
+                             :volume, :open_interest, :implied_volatility,
+                             :delta, :gamma, :theta, :vega) do
+        def call?
+          option_type == DhanHQ::Constants::OptionType::CALL
+        end
+
+        def put?
+          option_type == DhanHQ::Constants::OptionType::PUT
+        end
+
+        def itm?(spot_price)
+          return false unless spot_price
+
+          call? ? strike_price < spot_price : strike_price > spot_price
+        end
+
+        def otm?(spot_price)
+          return false unless spot_price
+
+          call? ? strike_price > spot_price : strike_price < spot_price
+        end
+
+        def atm?(spot_price)
+          return false unless spot_price
+
+          (strike_price - spot_price).abs < 1
+        end
+      end
+
+      attr_reader :underlying_scrip, :underlying_seg, :expiry, :legs, :spot_price, :fetched_at
+
+      def initialize(legs = [], metadata = {})
+        @underlying_scrip = metadata[:underlying_scrip]
+        @underlying_seg = metadata[:underlying_seg]
+        @expiry = metadata[:expiry]
+        @spot_price = metadata[:spot_price]
+        @legs = legs
+        @fetched_at = Time.now
+      end
+
+      # Build an OptionSnapshot from a raw OptionChain API response.
+      def self.from_response(response)
+        data = response.is_a?(Hash) ? (response[:data] || response["data"] || response) : response
+        return new([], {}) unless data.is_a?(Hash)
+
+        legs = parse_legs(data)
+        metadata = {
+          underlying_scrip: data[:underlyingScrip] || data["underlyingScrip"],
+          underlying_seg: data[:underlyingSeg] || data["underlyingSeg"],
+          expiry: data[:expiry] || data["expiry"],
+          spot_price: data[:spot] || data["spot"]
+        }
+
+        new(legs, metadata)
+      end
+
+      # Get all call option legs.
+      def calls
+        @legs.select(&:call?)
+      end
+
+      # Get all put option legs.
+      def puts
+        @legs.select(&:put?)
+      end
+
+      # Get all unique strike prices.
+      def strikes
+        @legs.map(&:strike_price).uniq.sort
+      end
+
+      # Get option legs at a specific strike price.
+      def at_strike(strike_price)
+        @legs.select { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get call option at a specific strike price.
+      def call_at(strike_price)
+        calls.find { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get put option at a specific strike price.
+      def put_at(strike_price)
+        puts.find { |leg| leg.strike_price == strike_price }
+      end
+
+      # Get all ITM calls (calls with strike below spot).
+      def itm_calls
+        return [] unless @spot_price
+
+        calls.select { |leg| leg.itm?(@spot_price) }
+      end
+
+      # Get all OTM calls (calls with strike above spot).
+      def otm_calls
+        return [] unless @spot_price
+
+        calls.select { |leg| leg.otm?(@spot_price) }
+      end
+
+      # Get all ITM puts (puts with strike above spot).
+      def itm_puts
+        return [] unless @spot_price
+
+        puts.select { |leg| leg.itm?(@spot_price) }
+      end
+
+      # Get all OTM puts (puts with strike below spot).
+      def otm_puts
+        return [] unless @spot_price
+
+        puts.select { |leg| leg.otm?(@spot_price) }
+      end
+
+      # Find the ATM strike (closest to spot price).
+      def atm_strike
+        return nil unless @spot_price || strikes.any?
+
+        spot = @spot_price || strikes.first
+        strikes.min_by { |strike| (strike - spot).abs }
+      end
+
+      # Get the total open interest across all legs.
+      def total_oi
+        @legs.sum { |leg| leg.open_interest.to_i }
+      end
+
+      # Get the total volume across all legs.
+      def total_volume
+        @legs.sum { |leg| leg.volume.to_i }
+      end
+
+      # Calculate put-call ratio by open interest.
+      def pcr_by_oi
+        call_oi = calls.sum { |leg| leg.open_interest.to_i }
+        put_oi = puts.sum { |leg| leg.open_interest.to_i }
+        return 0.0 if call_oi.zero?
+
+        put_oi.to_f / call_oi
+      end
+
+      # Calculate put-call ratio by volume.
+      def pcr_by_volume
+        call_vol = calls.sum { |leg| leg.volume.to_i }
+        put_vol = puts.sum { |leg| leg.volume.to_i }
+        return 0.0 if call_vol.zero?
+
+        put_vol.to_f / call_vol
+      end
+
+      def self.parse_legs(data)
+        # Parse from the option chain structure
+        ce_data = data[:ce] || data["ce"] || {}
+        pe_data = data[:pe] || data["pe"] || {}
+
+        ce_strikes = ce_data[:strike] || ce_data["strike"] || []
+        pe_strikes = pe_data[:strike] || pe_data["strike"] || []
+
+        # Parse CE (call) and PE (put) legs
+        parse_option_legs(ce_data, DhanHQ::Constants::OptionType::CALL, ce_strikes) +
+          parse_option_legs(pe_data, DhanHQ::Constants::OptionType::PUT, pe_strikes)
+      end
+      private_class_method :parse_legs
+
+      def self.parse_option_legs(data, option_type, strikes)
+        return [] unless data.is_a?(Hash)
+
+        strikes.each_with_index.map do |strike, i|
+          build_leg(data, option_type, strike, i)
+        end
+      end
+      private_class_method :parse_option_legs
+
+      def self.build_leg(data, option_type, strike, index)
+        OptionLeg.new(
+          strike_price: strike.to_f,
+          option_type: option_type,
+          ltp: extract_value(data, :ltp, index),
+          bid: extract_value(data, :bid, index),
+          ask: extract_value(data, :ask, index),
+          volume: extract_value(data, :volume, index, as_integer: true),
+          open_interest: extract_value(data, :oi, index, as_integer: true),
+          implied_volatility: extract_value(data, :iv, index),
+          delta: extract_value(data, :delta, index),
+          gamma: extract_value(data, :gamma, index),
+          theta: extract_value(data, :theta, index),
+          vega: extract_value(data, :vega, index)
+        )
+      end
+      private_class_method :build_leg
+
+      def self.extract_value(data, key, index, as_integer: false)
+        values = data[key] || data[key.to_s] || []
+        value = values[index]
+        return nil if value.nil?
+
+        as_integer ? value.to_i : value.to_f
+      end
+      private_class_method :extract_value
+    end
+  end
+end

data/lib/DhanHQ/market_data.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "market_data/market_snapshot"
+require_relative "market_data/ohlc_series"
+require_relative "market_data/option_snapshot"
+
+module DhanHQ
+  # Higher-level abstractions for market data consumption.
+  #
+  # Provides typed wrappers around raw API responses for more convenient
+  # market data analysis and consumption.
+  #
+  # @example Quick market snapshot
+  #   response = DhanHQ::Models::MarketFeed.ltp("NSE_EQ" => [11536])
+  #   snapshot = DhanHQ::MarketData::MarketSnapshot.from_response(response)
+  #   puts snapshot.ltp("NSE_EQ", "11536")
+  #
+  # @example Historical OHLC series
+  #   response = DhanHQ::Models::HistoricalData.daily(...)
+  #   series = DhanHQ::MarketData::OHLCSeries.from_response(response)
+  #   puts series.average_close
+  #
+  module MarketData
+  end
+end

data/lib/DhanHQ/mcp/server.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../agent"
+
+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)
+        @input = input
+        @output = output
+        @policy = policy
+      end
+
+      def run
+        @input.each_line { |line| handle_line(line) }
+      end
+
+      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)
+      end
+
+      private
+
+      def dispatch(method, params)
+        case method
+        when "initialize"
+          {
+            protocolVersion: "2024-11-05",
+            serverInfo: { name: "dhanhq-ruby", version: DhanHQ::VERSION },
+            capabilities: { tools: {} }
+          }
+        when "tools/list"
+          { tools: DhanHQ::Agent::ToolRegistry.list.map { |t| mcp_tool(t) } }
+        when "tools/call"
+          result = DhanHQ::Agent::ToolRegistry.execute(
+            params.fetch("name"),
+            params.fetch("arguments", {}),
+            policy: @policy
+          )
+          { content: [{ type: "text", text: JSON.pretty_generate(serialize(result)) }] }
+        else
+          raise ArgumentError, "Unsupported MCP method: #{method}"
+        end
+      end
+
+      def mcp_tool(tool)
+        { name: tool[:name], description: "[#{tool[:risk]}] #{tool[:description]}", inputSchema: tool[:input_schema] }
+      end
+
+      def serialize(value)
+        case value
+        when Array then value.map { |v| serialize(v) }
+        when Hash then value.transform_values { |v| serialize(v) }
+        else
+          value.respond_to?(:attributes) ? value.attributes : value
+        end
+      end
+
+      def respond(id, result, code: nil, message: nil)
+        payload = { jsonrpc: "2.0", id: id }
+        code ? payload[:error] = { code: code, message: message } : payload[:result] = result
+        @output.puts(JSON.generate(payload))
+        @output.flush
+      end
+    end
+  end
+end

data/lib/DhanHQ/mcp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "mcp/server"
+
+module DhanHQ
+  # MCP namespace provides Model Context Protocol server for AI agent integration.
+  # Enables stdio-based JSON-RPC communication with AI tools and agents.
+  module MCP
+  end
+end

data/lib/DhanHQ/models/funds.rb

@@ -29,6 +29,18 @@ module DhanHQ
       attributes :available_balance, :sod_limit, :collateral_amount, :receiveable_amount, :utilized_amount,
                  :blocked_payout_amount, :withdrawable_balance
 
+      # Returns a concise prompt-friendly summary of funds.
+      def to_prompt
+        parts = []
+        parts << "available=₹#{available_balance}" if available_balance
+        parts << "utilized=₹#{utilized_amount}" if utilized_amount
+        parts << "withdrawable=₹#{withdrawable_balance}" if withdrawable_balance
+        parts << "collateral=₹#{collateral_amount}" if collateral_amount&.positive?
+        parts << "sod_limit=₹#{sod_limit}" if sod_limit
+        parts << "blocked_payout=₹#{blocked_payout_amount}" if blocked_payout_amount&.positive?
+        parts.join(", ")
+      end
+
       ##
       # Normalizes the typo'd `availabelBalance` key from the API response to `available_balance`.
       #

data/lib/DhanHQ/models/holding.rb

@@ -33,6 +33,48 @@ module DhanHQ
       attributes :exchange, :trading_symbol, :security_id, :isin, :total_qty,
                  :dp_qty, :t1_qty, :available_qty, :collateral_qty, :avg_cost_price
 
+      # Returns a concise prompt-friendly summary of the holding.
+      def to_prompt
+        parts = [
+          "#{total_qty}x #{trading_symbol || security_id}",
+          "on #{exchange}"
+        ]
+        parts << "avg_cost=#{avg_cost_price}" if avg_cost_price&.positive?
+        parts << "available=#{available_qty}" if available_qty
+        parts << "dp=#{dp_qty}" if dp_qty&.positive?
+        parts << "t1=#{t1_qty}" if t1_qty&.positive?
+        parts << "collateral=#{collateral_qty}" if collateral_qty&.positive?
+        parts << "isin=#{isin}" if isin
+        parts.join(", ")
+      end
+
+      # Returns true if this holding has pending T1 delivery.
+      def pending_delivery?
+        t1_qty.to_i.positive?
+      end
+
+      # Returns true if this holding is fully delivered (no T1).
+      def delivered?
+        t1_qty.to_i.zero?
+      end
+
+      # Returns true if any quantity is pledged as collateral.
+      def pledged?
+        collateral_qty.to_i.positive?
+      end
+
+      # Returns the percentage of holding that is pledged.
+      def pledge_percentage
+        return 0.0 if total_qty.to_i.zero?
+
+        (collateral_qty.to_i.to_f / total_qty.to_i * 100).round(2)
+      end
+
+      # Returns true if this holding is partially pledged.
+      def partially_pledged?
+        pledged? && collateral_qty.to_i < total_qty.to_i
+      end
+
       class << self
         ##
         # Provides a shared instance of the Holdings resource.