DhanHQ 3.0.1 → 3.2.0

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/global_stocks/funds.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks fund limit.
+      #
+      #   GET /v2/globalstocks/fundlimit
+      #
+      # Global Stocks funds are held in USD and are reported separately from the
+      # domestic INR fund limit exposed by {DhanHQ::Resources::Funds}.
+      class Funds < BaseAPI
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/fundlimit"
+
+        # Retrieves the authenticated user's US stock fund limit details.
+        #
+        # @return [Hash]
+        def fetch
+          get("")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/holdings.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for Global Stocks holdings.
+      #
+      #   GET /v2/globalstocks/holdings
+      class Holdings < BaseAPI
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/holdings"
+
+        # Retrieves the authenticated user's US stock holdings.
+        #
+        # @return [Array<Hash>]
+        def all
+          get("")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/margin_calculator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks pre-trade calculators.
+      #
+      #   POST /v2/globalstocks/margincalculator  — margin required for an order
+      #   POST /v2/globalstocks/transEstimate     — charges applicable to an order
+      #
+      # Both endpoints take the same request body. The API documents +price+ and
+      # +quantity+ as strings, so numeric input is stringified before sending.
+      class MarginCalculator < BaseAPI
+        API_TYPE = :non_trading_api
+        HTTP_PATH = "/v2/globalstocks"
+
+        # Calculates the margin required for a Global Stocks order.
+        #
+        # @param params [Hash] `:security_id`, `:transaction_type`, `:price`, `:quantity`
+        # @return [Hash] Margin breakdown.
+        def calculate(params)
+          post("/margincalculator", params: wire_params(params))
+        end
+
+        # Estimates the charges applicable to a Global Stocks order.
+        #
+        # @param params [Hash] `:security_id`, `:transaction_type`, `:price`, `:quantity`
+        # @return [Hash] Charge breakdown.
+        def estimate(params)
+          post("/transEstimate", params: wire_params(params))
+        end
+
+        private
+
+        # Validates against the shared estimator contract, then renders the numeric
+        # fields as strings the way the API expects them.
+        def wire_params(params)
+          validated = validate!(params)
+          validated.merge(
+            price: format_number(validated[:price]),
+            quantity: format_number(validated[:quantity])
+          )
+        end
+
+        # Fields the API documents as strings but which are validated as numbers.
+        NUMERIC_KEYS = %i[price quantity].freeze
+        private_constant :NUMERIC_KEYS
+
+        def validate!(params)
+          attrs = snake_case(params).each_with_object({}) do |(key, value), out|
+            out[key] = NUMERIC_KEYS.include?(key) ? Float(value) : value
+          end
+          result = Contracts::GlobalStocksEstimatorContract.new.call(attrs)
+          raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}" unless result.success?
+
+          result.to_h
+        rescue ArgumentError, TypeError => e
+          raise DhanHQ::ValidationError, "Invalid parameters: price and quantity must be numeric (#{e.message})"
+        end
+
+        # Renders 180.0 as "180" and 1.5 as "1.5" so the payload matches the
+        # documented examples rather than leaking Ruby float formatting.
+        def format_number(value)
+          float = Float(value)
+          float == float.to_i ? float.to_i.to_s : float.to_s
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/market_status.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the US market session status.
+      #
+      #   GET /v2/globalstocks/marketstatus
+      class MarketStatus < BaseAPI
+        API_TYPE = :non_trading_api
+        HTTP_PATH = "/v2/globalstocks/marketstatus"
+
+        # Retrieves the current US market status and session timings.
+        #
+        # @return [Hash] `{ status:, marketOpenTime:, marketCloseTime:, holidayFlag: }`
+        def fetch
+          get("")
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/orders.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "../../concerns/order_audit"
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks (US equities) order endpoints.
+      #
+      #   POST   /v2/globalstocks/orders
+      #   PUT    /v2/globalstocks/orders/{order-id}
+      #   DELETE /v2/globalstocks/orders/{order-id}
+      #   GET    /v2/globalstocks/orders
+      #   GET    /v2/globalstocks/orders/{order-id}
+      #
+      # Writes go through the same {DhanHQ::Concerns::OrderAudit} guardrails as
+      # domestic orders: +ENV["LIVE_TRADING"]="true"+ is required, and every attempt
+      # emits a structured audit log line.
+      #
+      # The pre-trade {DhanHQ::Risk::Pipeline} is intentionally *not* run here. Its
+      # checks (lot-size multiples, ASM/GSM surveillance lists, F&O product support,
+      # NSE/BSE market hours) resolve instruments from the Indian scrip master, which
+      # does not contain US securities.
+      #
+      # @see https://dhanhq.co/docs/v2/ Global Stocks section
+      class Orders < BaseAPI
+        include DhanHQ::Concerns::OrderAudit
+
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/orders"
+
+        # Places a new Global Stocks order.
+        #
+        # @param params [Hash] Order attributes in snake_case. See
+        #   {DhanHQ::Contracts::GlobalStocksPlaceOrderContract} for the accepted keys.
+        # @return [Hash] `{ orderId:, orderStatus: }`
+        # @raise [DhanHQ::LiveTradingDisabledError] Unless LIVE_TRADING is enabled.
+        # @raise [DhanHQ::ValidationError] When the payload fails validation.
+        def create(params)
+          ensure_live_trading!
+          log_order_context("DHAN_GLOBAL_ORDER_ATTEMPT", params)
+          validate_place_order!(params)
+          post("", params: params)
+        end
+
+        # Modifies a pending Global Stocks order.
+        #
+        # @param order_id [String]
+        # @param params [Hash] Fields to change, in snake_case.
+        # @return [Hash] `{ orderId:, orderStatus: }`
+        def update(order_id, params)
+          ensure_live_trading!
+          log_order_context("DHAN_GLOBAL_ORDER_MODIFY_ATTEMPT", params.merge(order_id: order_id))
+          validate_modify_order!(params.merge(order_id: order_id))
+          put("/#{order_id}", params: params)
+        end
+
+        # Cancels a pending Global Stocks order.
+        #
+        # @param order_id [String]
+        # @return [Hash] `{ orderId:, orderStatus: }`
+        def cancel(order_id)
+          ensure_live_trading!
+          log_order_context("DHAN_GLOBAL_ORDER_CANCEL_ATTEMPT", { order_id: order_id })
+          delete("/#{order_id}")
+        end
+
+        # Retrieves the current trading day's Global Stocks order book.
+        #
+        # @return [Array<Hash>]
+        def all
+          get("")
+        end
+
+        # Retrieves a single Global Stocks order by its Dhan order id.
+        #
+        # @param order_id [String]
+        # @return [Hash]
+        def find(order_id)
+          get("/#{order_id}")
+        end
+
+        private
+
+        def validate_place_order!(params)
+          result = Contracts::GlobalStocksPlaceOrderContract.new.call(coerce_for_validation(params))
+          raise_validation_error!(result) unless result.success?
+        end
+
+        def validate_modify_order!(params)
+          result = Contracts::GlobalStocksModifyOrderContract.new.call(coerce_for_validation(params))
+          raise_validation_error!(result) unless result.success?
+        end
+
+        # Global Stocks quantities and prices are floats (fractional shares are
+        # supported), so integers handed in by callers are widened before validation.
+        def coerce_for_validation(params)
+          snake_case(params).each_with_object({}) do |(key, value), out|
+            out[key] = FLOAT_KEYS.include?(key) && value.is_a?(Integer) ? value.to_f : value
+          end
+        end
+
+        FLOAT_KEYS = %i[quantity price trigger_price stop_loss_price target_price amount].freeze
+        private_constant :FLOAT_KEYS
+
+        def raise_validation_error!(result)
+          raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}"
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/global_stocks/trades.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    module GlobalStocks
+      # Resource client for the Global Stocks trade book.
+      #
+      #   GET /v2/globalstocks/trades
+      #   GET /v2/globalstocks/trades/{security-id}
+      class Trades < BaseAPI
+        API_TYPE = :order_api
+        HTTP_PATH = "/v2/globalstocks/trades"
+
+        # Retrieves the current trading day's executed Global Stocks trades.
+        #
+        # @return [Array<Hash>]
+        def all
+          get("")
+        end
+
+        # Retrieves executed Global Stocks trades for a single security.
+        #
+        # @param security_id [String]
+        # @return [Array<Hash>]
+        def by_security_id(security_id)
+          get("/#{security_id}")
+        end
+      end
+    end
+  end
+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/multi_orders.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../concerns/order_audit"
+
+module DhanHQ
+  module Resources
+    # Resource for basket orders: POST /v2/alerts/multi/orders.
+    #
+    # Places up to {DhanHQ::Contracts::MultiOrderContract::MAX_ORDERS} unconditional
+    # orders in a single request. Unlike {AlertOrders} there is no trigger condition —
+    # every leg is sent to the exchange immediately.
+    #
+    # @see https://dhanhq.co/docs/v2/ Conditional and Multi Order section
+    class MultiOrders < BaseAPI
+      include DhanHQ::Concerns::OrderAudit
+
+      API_TYPE  = :order_api
+      HTTP_PATH = "/v2/alerts/multi/orders"
+
+      # Places a basket of orders.
+      #
+      # @param orders [Array<Hash>] Order legs in snake_case. Each leg requires
+      #   +:sequence+, +:transaction_type+ and +:exchange_segment+.
+      # @param dhan_client_id [String, nil] Defaults to the configured client id.
+      # @return [Hash] `{ orders: [{ orderId:, sequence:, orderStatus: }, ...] }`
+      # @raise [DhanHQ::LiveTradingDisabledError] Unless LIVE_TRADING is enabled.
+      # @raise [DhanHQ::ValidationError] When any leg fails validation.
+      def create(orders, dhan_client_id: nil)
+        ensure_live_trading!
+
+        legs = Array(orders).map { |leg| snake_case(leg) }
+        payload = { dhan_client_id: dhan_client_id || DhanHQ.configuration&.client_id, orders: legs }.compact
+
+        validate!(payload)
+        legs.each { |leg| run_risk_checks!(leg) }
+        log_multi_order_context(legs)
+
+        # BaseAPI camelizes only the top level, which would leave the leg fields as
+        # `transaction_type`/`security_id` inside `orders` and get the basket rejected.
+        post("", params: payload.merge(orders: deep_camelize_keys(legs)))
+      end
+
+      private
+
+      def validate!(payload)
+        result = Contracts::MultiOrderContract.new.call(payload)
+        raise DhanHQ::ValidationError, "Invalid parameters: #{result.errors.to_h}" unless result.success?
+      end
+
+      # Emits one audit line per leg so each order in the basket is traceable.
+      def log_multi_order_context(legs)
+        legs.each do |leg|
+          log_order_context("DHAN_MULTI_ORDER_ATTEMPT", leg)
+        end
+      end
+    end
+  end
+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 = {}