DhanHQ 3.0.0 → 3.1.0

data/lib/DhanHQ/strategy/base.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Strategy framework for building and backtesting trading strategies.
+  #
+  # Provides a DSL for defining entry/exit rules, risk management,
+  # and signal generation.
+  #
+  # @example Define a simple strategy
+  #   class MyStrategy < DhanHQ::Strategy::Base
+  #     entry_rule :golden_cross do |data|
+  #       data.sma(20).last > data.sma(50).last &&
+  #         data.sma(20).last(2) <= data.sma(50).last(2)
+  #     end
+  #
+  #     exit_rule :death_cross do |data|
+  #       data.sma(20).last < data.sma(50).last
+  #     end
+  #   end
+  #
+  module Strategy
+    # Signal represents a trading signal generated by a strategy.
+    #
+    # @attr_reader [Symbol] type Signal type (:buy, :sell, :hold)
+    # @attr_reader [Float] strength Signal strength (0.0 to 1.0)
+    # @attr_reader [Hash] metadata Additional signal metadata
+    Signal = Struct.new(:type, :strength, :metadata) do
+      def buy?
+        type == :buy
+      end
+
+      def sell?
+        type == :sell
+      end
+
+      def hold?
+        type == :hold
+      end
+
+      def to_prompt
+        parts = ["signal=#{type}", "strength=#{strength}"]
+        parts << "reason=#{metadata[:reason]}" if metadata[:reason]
+        parts.join(", ")
+      end
+    end
+
+    # Base class for all strategies.
+    #
+    # Provides DSL for defining entry/exit rules and risk management.
+    class Base
+      attr_reader :name, :params, :position
+
+      def initialize(name: self.class.name, params: {})
+        @name = name
+        @params = params
+        @position = nil
+        @entry_rules = {}
+        @exit_rules = {}
+        @risk_rules = {}
+        @signals = []
+      end
+
+      # Define an entry rule.
+      #
+      # @param name [Symbol] Rule name
+      # @param priority [Integer] Rule priority (lower = higher priority)
+      # @param block [Proc] Rule condition block
+      def self.entry_rule(name, priority: 10, &block)
+        @entry_rules ||= {}
+        @entry_rules[name] = { priority: priority, block: block }
+      end
+
+      # Define an exit rule.
+      #
+      # @param name [Symbol] Rule name
+      # @param priority [Integer] Rule priority (lower = higher priority)
+      # @param block [Proc] Rule condition block
+      def self.exit_rule(name, priority: 10, &block)
+        @exit_rules ||= {}
+        @exit_rules[name] = { priority: priority, block: block }
+      end
+
+      # Define a risk rule.
+      #
+      # @param name [Symbol] Rule name
+      # @param block [Proc] Risk check block
+      def self.risk_rule(name, &block)
+        @risk_rules ||= {}
+        @risk_rules[name] = block
+      end
+
+      # Get all entry rules for this strategy class.
+      def self.entry_rules
+        @entry_rules || {}
+      end
+
+      # Get all exit rules for this strategy class.
+      def self.exit_rules
+        @exit_rules || {}
+      end
+
+      # Get all risk rules for this strategy class.
+      def self.risk_rules
+        @risk_rules || {}
+      end
+
+      # Evaluate entry rules against market data.
+      #
+      # @param data [DhanHQ::MarketData::OHLCSeries] Market data series
+      # @return [DhanHQ::Strategy::Signal] Generated signal
+      def evaluate_entry(data)
+        sorted_rules = self.class.entry_rules.sort_by { |_, v| v[:priority] }
+
+        sorted_rules.each do |rule_name, rule|
+          result = rule[:block].call(data, params)
+          next unless result
+
+          signal = Signal.new(
+            type: :buy,
+            strength: calculate_strength(result),
+            metadata: { rule: rule_name, data: data }
+          )
+          @signals << signal
+          return signal
+        end
+
+        Signal.new(type: :hold, strength: 0.0, metadata: { reason: :no_entry_signal })
+      end
+
+      # Evaluate exit rules against market data.
+      #
+      # @param data [DhanHQ::MarketData::OHLCSeries] Market data series
+      # @return [DhanHQ::Strategy::Signal] Generated signal
+      def evaluate_exit(data)
+        sorted_rules = self.class.exit_rules.sort_by { |_, v| v[:priority] }
+
+        sorted_rules.each do |rule_name, rule|
+          result = rule[:block].call(data, params)
+          next unless result
+
+          signal = Signal.new(
+            type: :sell,
+            strength: calculate_strength(result),
+            metadata: { rule: rule_name, data: data }
+          )
+          @signals << signal
+          return signal
+        end
+
+        Signal.new(type: :hold, strength: 0.0, metadata: { reason: :no_exit_signal })
+      end
+
+      # Check all risk rules.
+      #
+      # @param context [Hash] Risk check context
+      # @return [Array<Symbol>] List of violated rule names
+      def check_risks(context)
+        violations = []
+
+        self.class.risk_rules.each do |rule_name, block|
+          result = block.call(context, params)
+          violations << rule_name unless result
+        end
+
+        violations
+      end
+
+      # Get all signals generated by this strategy.
+      def signals
+        @signals.dup
+      end
+
+      # Get the last signal.
+      def last_signal
+        @signals.last
+      end
+
+      private
+
+      def calculate_strength(result)
+        case result
+        when true then 1.0
+        when Numeric then result.clamp(0.0, 1.0)
+        else 0.5
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/strategy.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "strategy/base"
+
+module DhanHQ
+  # Strategy framework for building and backtesting trading strategies.
+  #
+  # Provides a DSL for defining entry/exit rules, risk management,
+  # and signal generation.
+  #
+  # @example Define a simple strategy
+  #   class GoldenCross < DhanHQ::Strategy::Base
+  #     entry_rule :golden_cross do |data, _params|
+  #       sma_20 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 20)
+  #       sma_50 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 50)
+  #
+  #       sma_20.last && sma_50.last &&
+  #         sma_20.last > sma_50.last &&
+  #         sma_20[-2] && sma_50[-2] &&
+  #         sma_20[-2] <= sma_50[-2]
+  #     end
+  #
+  #     exit_rule :death_cross do |data, _params|
+  #       sma_20 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 20)
+  #       sma_50 = DhanHQ::Indicators::SMA.calculate(data.closes, period: 50)
+  #
+  #       sma_20.last && sma_50.last && sma_20.last < sma_50.last
+  #     end
+  #
+  #     risk_rule :max_drawdown do |context, _params|
+  #       context[:drawdown].abs < 0.1
+  #     end
+  #   end
+  #
+  #   strategy = GoldenCross.new
+  #   signal = strategy.evaluate_entry(data)
+  #
+  module Strategy
+  end
+end

data/lib/DhanHQ/version.rb

@@ -2,5 +2,5 @@
 
 module DhanHQ
   # Semantic version of the DhanHQ client gem.
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

data/lib/DhanHQ/ws/decoder.rb

@@ -26,21 +26,45 @@ module DhanHQ
         segstr = Segments.from_code(pkt[:exchange_segment])
         sid    = pkt[:security_id].to_s
 
-        # pp pkt
-        case kind
-        when :ticker
+        dispatch(pkt, kind, segstr, sid)
+      rescue StandardError => e
+        DhanHQ.logger&.debug("[DhanHQ::WS::Decoder] #{e.class}: #{e.message}")
+        nil
+      end
+
+      class << self
+        private
+
+        def dispatch(pkt, kind, segstr, sid)
+          case kind
+          when :ticker      then decode_ticker(pkt, segstr, sid)
+          when :quote       then decode_quote(pkt, segstr, sid)
+          when :full        then decode_full(pkt, segstr, sid)
+          when :oi          then decode_oi(pkt, segstr, sid)
+          when :prev_close  then decode_prev_close(pkt, segstr, sid)
+          when :depth_bid, :depth_ask then decode_depth(pkt, kind, segstr, sid)
+          when :disconnect then handle_disconnect(pkt, segstr, sid)
+          else handle_unknown(pkt)
+          end
+        end
+
+        def decode_ticker(pkt, segstr, sid)
           {
             kind: :ticker, segment: segstr, security_id: sid,
             ltp: pkt[:ltp].to_f, ts: pkt[:ltt]&.to_i
           }
-        when :quote
+        end
+
+        def decode_quote(pkt, segstr, sid)
           {
             kind: :quote, segment: segstr, security_id: sid,
             ltp: pkt[:ltp].to_f, ts: pkt[:ltt]&.to_i, atp: pkt[:atp].to_f,
             vol: pkt[:volume].to_i, ts_buy_qty: pkt[:total_buy_qty].to_i, ts_sell_qty: pkt[:total_sell_qty].to_i,
             day_open: pkt[:day_open]&.to_f, day_high: pkt[:day_high]&.to_f, day_low: pkt[:day_low]&.to_f, day_close: pkt[:day_close]&.to_f
           }
-        when :full
+        end
+
+        def decode_full(pkt, segstr, sid)
           out = {
             kind: :full, segment: segstr, security_id: sid,
             ltp: pkt[:ltp].to_f, ts: pkt[:ltt]&.to_i, atp: pkt[:atp].to_f,
@@ -48,35 +72,49 @@ module DhanHQ
             oi: pkt[:open_interest]&.to_i, oi_high: pkt[:highest_open_interest]&.to_i, oi_low: pkt[:lowest_open_interest]&.to_i,
             day_open: pkt[:day_open]&.to_f, day_high: pkt[:day_high]&.to_f, day_low: pkt[:day_low]&.to_f, day_close: pkt[:day_close]&.to_f
           }
-          # First depth level (if present)
-          if (md = pkt[:market_depth]).respond_to?(:[]) && md[0]
-            lvl = md[0]
-            out[:bid] = lvl.respond_to?(:bid_price) ? lvl.bid_price.to_f : nil
-            out[:ask] = lvl.respond_to?(:ask_price) ? lvl.ask_price.to_f : nil
-          end
+          merge_depth(out, pkt[:market_depth])
           out
-        when :oi
+        end
+
+        def decode_oi(pkt, segstr, sid)
           { kind: :oi, segment: segstr, security_id: sid, oi: pkt[:open_interest].to_i }
-        when :prev_close
+        end
+
+        def decode_prev_close(pkt, segstr, sid)
           { kind: :prev_close, segment: segstr, security_id: sid, prev_close: pkt[:prev_close].to_f,
             oi_prev: pkt[:oi_prev].to_i }
-        when :depth_bid, :depth_ask
+        end
+
+        def decode_depth(pkt, kind, segstr, sid)
           {
             kind: kind, segment: segstr, security_id: sid,
             bid_quantity: pkt[:bid_quantity], ask_quantity: pkt[:ask_quantity],
             no_of_bid_orders: pkt[:no_of_bid_orders], no_of_ask_orders: pkt[:no_of_ask_orders],
             bid: pkt[:bid_price], ask: pkt[:ask_price]
           }
-        when :disconnect
+        end
+
+        def handle_disconnect(pkt, segstr, sid)
           DhanHQ.logger&.warn("[DhanHQ::WS] disconnect code=#{pkt[:disconnection_code]} seg=#{segstr} sid=#{sid}")
           nil
-        else
+        end
+
+        def handle_unknown(pkt)
           DhanHQ.logger&.debug("[DhanHQ::WS] unknown feed kind code=#{pkt[:feed_response_code]}")
           nil
         end
-      rescue StandardError => e
-        DhanHQ.logger&.debug("[DhanHQ::WS::Decoder] #{e.class}: #{e.message}")
-        nil
+
+        def merge_depth(out, market_depth)
+          return unless market_depth.respond_to?(:[]) && market_depth[0]
+
+          lvl = market_depth[0]
+          out[:bid] = lvl.respond_to?(:bid_price) ? lvl.bid_price.to_f : nil
+          out[:ask] = lvl.respond_to?(:ask_price) ? lvl.ask_price.to_f : nil
+          return unless lvl.respond_to?(:bid_quantity) && lvl.respond_to?(:ask_quantity)
+
+          out[:bid_qty] = lvl.bid_quantity.to_i
+          out[:ask_qty] = lvl.ask_quantity.to_i
+        end
       end
     end
   end

data/lib/DhanHQ.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "dhan_hq"

data/lib/dhan_hq/agent.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../DhanHQ/agent"

data/lib/dhan_hq/mcp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../DhanHQ/mcp"

data/lib/dhan_hq.rb

@@ -38,10 +38,39 @@ module DhanHQ
   LOADER.collapse(File.join(__dir__, "DhanHQ", "helpers"))
   LOADER.ignore(
     File.join(__dir__, "DhanHQ", "errors.rb"),
-    File.join(__dir__, "DhanHQ", "version.rb")
+    File.join(__dir__, "DhanHQ", "version.rb"),
+    File.join(__dir__, "DhanHQ", "risk.rb")
   )
   LOADER.setup
 
+  # Eager-load risk utilities (PositionSizer, SLCalculator, TrailManager)
+  # and the pre-execution risk pipeline so they are available immediately.
+  require_relative "DhanHQ/risk"
+  require_relative "DhanHQ/risk/checks/trading_permission"
+  require_relative "DhanHQ/risk/checks/asm_gsm"
+  require_relative "DhanHQ/risk/checks/product_support"
+  require_relative "DhanHQ/risk/checks/order_type"
+  require_relative "DhanHQ/risk/checks/quantity"
+  require_relative "DhanHQ/risk/checks/market_hours"
+  require_relative "DhanHQ/risk/checks/options"
+  require_relative "DhanHQ/risk/checks/position_limits"
+  require_relative "DhanHQ/risk/checks/concentration"
+  require_relative "DhanHQ/risk/checks/max_loss"
+  require_relative "DhanHQ/risk/pipeline"
+
+  # Skills layer: multi-step trading workflows
+  require_relative "DhanHQ/skills"
+  require_relative "DhanHQ/skills/base"
+  require_relative "DhanHQ/skills/registry"
+  require_relative "DhanHQ/skills/workflow"
+  require_relative "DhanHQ/skills/builtin/buy_atm_call"
+  require_relative "DhanHQ/skills/builtin/square_off_all"
+  require_relative "DhanHQ/skills/builtin/square_off_position"
+  require_relative "DhanHQ/skills/builtin/iron_condor"
+  require_relative "DhanHQ/skills/builtin/strangle"
+  require_relative "DhanHQ/skills/builtin/market_data_summarizer"
+  DhanHQ::Skills::Registry.load_builtins
+
   class Error < StandardError; end
 
   class << self
@@ -131,7 +160,7 @@ module DhanHQ
 
       url = "#{base_url.to_s.chomp("/")}/auth/dhan/token"
       conn = ::Faraday.new(url: url) do |c|
-        c.response :json, content_type: /\bjson$/
+        c.request :url_encoded
         c.adapter ::Faraday.default_adapter
       end
 
@@ -161,6 +190,49 @@ module DhanHQ
       configuration
     end
 
+    # Configures the DhanHQ client by fetching credentials from a dashboard API.
+    #
+    # @param bearer_token [String] Secret dashboard token (e.g. YOUR_DASHBOARD_TOKEN)
+    # @param url [String] The full URL of the dashboard API
+    # @return [DhanHQ::Configuration] The configured configuration
+    # @raise [DhanHQ::TokenEndpointError] On HTTP error or missing credentials
+    def configure_from_dashboard(bearer_token:, url: "http://localhost:3011/api/dhan_access_token")
+      raise DhanHQ::TokenEndpointError, "bearer_token is required" if bearer_token.to_s.empty?
+
+      conn = ::Faraday.new(url: url) do |c|
+        c.request :url_encoded
+        c.adapter ::Faraday.default_adapter
+      end
+
+      response = conn.get("") do |req|
+        req.headers["Authorization"] = "Bearer #{bearer_token}"
+        req.headers["Accept"] = "application/json"
+      end
+
+      unless response.success?
+        body = parse_json_body(response.body)
+        msg = body["error"] || body["message"] || body["errorMessage"] || response.body.to_s
+        raise DhanHQ::TokenEndpointError, "Dashboard returned #{response.status}: #{msg}"
+      end
+
+      data = parse_json_body(response.body)
+      data = data.transform_keys(&:to_s) if data.is_a?(Hash)
+
+      access_token = data["access_token"] || data["accessToken"] || data["dhan_access_token"] || data["dhanaccesstoken"]
+      client_id = data["client_id"] || data["clientId"] || data["dhan_client_id"] || data["dhanClientId"]
+      client_id ||= self.configuration&.client_id || ENV.fetch("DHAN_CLIENT_ID", nil)
+
+      raise DhanHQ::TokenEndpointError, "Dashboard response missing access_token (tried access_token, dhan_access_token, dhanaccesstoken)" if access_token.to_s.empty?
+      raise DhanHQ::TokenEndpointError, "Dashboard response missing client_id, and no fallback client_id was found in config or ENV['DHAN_CLIENT_ID']" if client_id.to_s.empty?
+
+      self.configuration ||= Configuration.new
+      configuration.access_token = access_token.to_s
+      configuration.client_id = client_id.to_s
+      dhan_base = data["base_url"] || data["baseUrl"]
+      configuration.base_url = dhan_base.to_s if dhan_base.to_s != ""
+      configuration
+    end
+
     # @param body [String, Hash] Raw response body
     # @return [Hash] Parsed hash; empty hash on parse failure or empty string
     def parse_json_body(body)

data/lib/ta/technical_analysis.rb

@@ -125,7 +125,9 @@ module TA
     def normalize_from_date(from_date, to_date, days_back)
       if (from_date.nil? || from_date.to_s.strip.empty?) && days_back&.to_i&.positive?
         to_d = Date.parse(to_date)
-        n_back = [days_back.to_i - 1, 0].max
+        # Dhan historical API to_date is non-inclusive. To get N trading days,
+        # we must go back N trading days from the non-inclusive to_date.
+        n_back = days_back.to_i
         return MarketCalendar.trading_days_ago(to_d, n_back).strftime("%Y-%m-%d")
       end
       if from_date && !from_date.to_s.strip.empty?

data/skills/dhanhq-ruby/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: dhanhq-ruby
+description: >
+  Use when the user mentions DhanHQ, Dhan API, or wants to trade on
+  Indian exchanges (NSE, BSE, MCX) using Ruby. Triggers for: place, modify, or
+  cancel stock/F&O/commodity orders on Dhan using Ruby; fetch portfolio holdings
+  or positions; get live or historical market data; access option
+  chains with Greeks; check fund limits or margin; build any trading
+  automation for Indian markets; resolve NSE/BSE instrument IDs;
+  stream live WebSocket market feeds or order updates. Also trigger
+  for general questions about programmatic trading on Indian exchanges
+  if Dhan is the user's broker.
+compatibility: >
+  Requires Ruby and the dhanhq gem.
+  Order placement, modification, and cancellation require static IP
+  whitelisting on Dhan. Data APIs (quotes, history, option chain,
+  live feed) require an active Dhan Data Plan.
+---
+
+# DhanHQ — Indian Market Trading Skill (Ruby SDK)
+
+Use this skill when an agent needs to write, review, or operate Ruby code using the `DhanHQ` gem.
+
+## Safety Rules — Always Enforce
+
+1. Confirm before placing live orders.
+2. Show a readable order preview before execution.
+3. Default to `LIMIT` orders unless the user explicitly wants `MARKET`.
+4. Warn when notional exceeds `Rs. 50,000`.
+5. For F&O, validate lot size before placement.
+6. Never use `CNC` or `MTF` for F&O, commodity, or currency segments.
+7. Never hardcode credentials in generated code.
+8. Ask for confirmation before modifying or cancelling orders, or performing multi-leg live execution.
+
+## Setup
+
+Require the core library and configure using environment variables or a configuration block:
+
+```ruby
+require "dhan_hq"
+
+# Configures from environment variables: DHAN_CLIENT_ID, DHAN_ACCESS_TOKEN
+DhanHQ.configure_with_env
+```
+
+Or configure explicitly:
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = "YOUR_CLIENT_ID"
+  config.access_token = "YOUR_ACCESS_TOKEN"
+end
+```
+
+If generating scripts inside this repo, prefer using the helper script:
+
+```ruby
+require_relative "scripts/dhan_helpers"
+get_client
+```
+
+## Current SDK Constants
+
+Use constants from the `DhanHQ::Constants` module for segments, order types, validity, product types, and transactions:
+
+| Category | Constant | Value |
+|----------|----------|-------|
+| Exchange Segment | `DhanHQ::Constants::ExchangeSegment::NSE_EQ` (or `DhanHQ::Constants::NSE`) | `"NSE_EQ"` |
+| | `DhanHQ::Constants::ExchangeSegment::BSE_EQ` (or `DhanHQ::Constants::BSE`) | `"BSE_EQ"` |
+| | `DhanHQ::Constants::ExchangeSegment::NSE_FNO` (or `DhanHQ::Constants::NSE_FNO` / `DhanHQ::Constants::FNO`) | `"NSE_FNO"` |
+| | `DhanHQ::Constants::ExchangeSegment::BSE_FNO` (or `DhanHQ::Constants::BSE_FNO`) | `"BSE_FNO"` |
+| | `DhanHQ::Constants::ExchangeSegment::MCX_COMM` (or `DhanHQ::Constants::MCX`) | `"MCX_COMM"` |
+| | `DhanHQ::Constants::ExchangeSegment::IDX_I` (or `DhanHQ::Constants::INDEX`) | `"IDX_I"` |
+| Transaction Type | `DhanHQ::Constants::TransactionType::BUY` (or `DhanHQ::Constants::BUY`) | `"BUY"` |
+| | `DhanHQ::Constants::TransactionType::SELL` (or `DhanHQ::Constants::SELL`) | `"SELL"` |
+| Order Type | `DhanHQ::Constants::OrderType::LIMIT` (or `DhanHQ::Constants::LIMIT`) | `"LIMIT"` |
+| | `DhanHQ::Constants::OrderType::MARKET` (or `DhanHQ::Constants::MARKET`) | `"MARKET"` |
+| | `DhanHQ::Constants::OrderType::STOP_LOSS` (or `DhanHQ::Constants::SL`) | `"STOP_LOSS"` |
+| | `DhanHQ::Constants::OrderType::STOP_LOSS_MARKET` (or `DhanHQ::Constants::SLM`) | `"STOP_LOSS_MARKET"` |
+| Product Type | `DhanHQ::Constants::ProductType::CNC` (or `DhanHQ::Constants::CNC`) | `"CNC"` |
+| | `DhanHQ::Constants::ProductType::INTRADAY` (or `DhanHQ::Constants::INTRA`) | `"INTRADAY"` |
+| | `DhanHQ::Constants::ProductType::MARGIN` (or `DhanHQ::Constants::MARGIN`) | `"MARGIN"` |
+| | `DhanHQ::Constants::ProductType::MTF` (or `DhanHQ::Constants::MTF`) | `"MTF"` |
+| Validity | `DhanHQ::Constants::Validity::DAY` (or `DhanHQ::Constants::DAY`) | `"DAY"` |
+| | `DhanHQ::Constants::Validity::IOC` (or `DhanHQ::Constants::IOC`) | `"IOC"` |
+
+## Preferred SDK Methods (ActiveRecord-Style Models)
+
+| Task | Method |
+|------|--------|
+| Place order | `DhanHQ::Models::Order.place(params)` |
+| List all orders | `DhanHQ::Models::Order.all` |
+| Order by ID | `DhanHQ::Models::Order.find(order_id)` |
+| Order by correlation ID | `DhanHQ::Models::Order.find_by_correlation(correlation_id)` |
+| Today's trades | `DhanHQ::Models::Trade.today` |
+| Historical trades | `DhanHQ::Models::Trade.history(from_date:, to_date:, page:)` |
+| Holdings | `DhanHQ::Models::Holding.all` |
+| Positions | `DhanHQ::Models::Position.all` |
+| Fund limits | `DhanHQ::Models::Funds.fetch` |
+| Margin calculator | `DhanHQ::Models::Margin.calculate(params)` |
+| Multi-instrument margin | `DhanHQ::Models::Margin.calculate_multi(params)` |
+| Daily charts | `DhanHQ::Models::HistoricalData.daily(params)` |
+| Intraday charts | `DhanHQ::Models::HistoricalData.intraday(params)` |
+| Option chain | `DhanHQ::Models::OptionChain.fetch(params)` |
+| Expiry list | `DhanHQ::Models::OptionChain.fetch_expiry_list(params)` |
+| Search instruments | `DhanHQ::Models::Instrument.search(query, options)` |
+| Find specific instrument | `DhanHQ::Models::Instrument.find(exchange_segment, symbol, options)` |
+| Find instrument anywhere | `DhanHQ::Models::Instrument.find_anywhere(symbol, options)` |
+| Super orders | `DhanHQ::Models::SuperOrder.create(params)` |
+| Forever orders | `DhanHQ::Models::ForeverOrder.create(params)` |
+| Live market feed | `DhanHQ::WS.connect(mode: :ticker) { |tick| ... }` |
+| Live order updates | `DhanHQ::WS::Orders.connect { |update| ... }` |
+| Live market depth | `DhanHQ::WS::MarketDepth.connect(symbols: [{...}]) { |depth| ... }` |
+
+## High-Value Gotchas
+
+- **Return values are model instances:** Most class methods return `DhanHQ::Models` objects rather than raw HTTP hashes.
+- **Instrument search is segment-specific:** `DhanHQ::Models::Instrument.by_segment(exchange_segment)` downloads the CSV for a single segment, which is more token-efficient than downloading the entire master CSV.
+- **Spelling fixes in models:** Typos from the Dhan API are normalized in model attributes (e.g. `availabelBalance` is normalized to `available_balance` or `availabel_balance`).
+- **Timestamps:** Timestamps returned by `HistoricalData` are automatically normalized into Ruby `Time` objects.
+- **WebSocket connection management:** Use sequential connections or single connection pools to avoid 429 rate limiting. Dhan allows up to 5 concurrent WebSocket connections.
+
+## Core Patterns
+
+### 1. Check account access before data calls
+
+```ruby
+funds = DhanHQ::Models::Funds.fetch
+puts "Available Balance: Rs. #{funds.availabel_balance}"
+```
+
+### 2. Fetch historical data
+
+```ruby
+candles = DhanHQ::Models::HistoricalData.daily(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  instrument: "EQUITY",
+  from_date: "2024-01-01",
+  to_date: "2024-12-31"
+)
+
+candles.each do |candle|
+  puts "Date: #{candle[:timestamp].to_date}, Close: #{candle[:close]}"
+end
+```
+
+### 3. Option-chain data
+
+```ruby
+chain = DhanHQ::Models::OptionChain.fetch(
+  underlying_scrip: 13,
+  underlying_seg: "IDX_I",
+  expiry: "2025-03-27"
+)
+
+puts "Underlying spot: #{chain[:last_price]}"
+chain[:strikes].each do |strike_data|
+  puts "Strike: #{strike_data[:strike]}, Call LTP: #{strike_data[:call][:last_price]}"
+end
+```
+
+### 4. Margin check before live order placement
+
+```ruby
+margin = DhanHQ::Models::Margin.calculate(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  quantity: 10,
+  product_type: "CNC",
+  price: 2450.0
+)
+
+puts "Sufficient balance? #{margin.available_balance >= margin.total_margin}"
+```
+
+### 5. Live market feed
+
+```ruby
+market_client = DhanHQ::WS.connect(mode: :ticker) do |tick|
+  puts "Market Tick: #{tick[:security_id]} = #{tick[:ltp]}"
+end
+
+market_client.subscribe_one(segment: "NSE_EQ", security_id: "2885")
+sleep(10)
+market_client.stop
+```
+
+## Reference Files
+
+Refer to the documents in the references directory for focused workflows:
+
+| Need | File |
+|------|------|
+| Orders, super orders, forever orders | [references/orders.md](references/orders.md) |
+| Holdings, positions, eDIS | [references/portfolio.md](references/portfolio.md) |
+| Daily/minute history, quotes, expired options | [references/market-data.md](references/market-data.md) |
+| Option-chain usage | [references/option-chain.md](references/option-chain.md) |
+| Fund limits and margin checks | [references/funds.md](references/funds.md) |
+| Live feeds and depth | [references/live-feed.md](references/live-feed.md) |
+| Error handling | [references/error-codes.md](references/error-codes.md) |
+| Instrument resolution | [references/instruments.md](references/instruments.md) |
+| Multi-step execution patterns | [references/common-workflows.md](references/common-workflows.md) |
+| Options analytics | [references/options-analysis-patterns.md](references/options-analysis-patterns.md) |
+| Backtesting patterns | [references/backtesting-with-dhan.md](references/backtesting-with-dhan.md) |
+| Extranal data sources (RSI, PE ratios, screener) | [references/scanx-data.md](references/scanx-data.md) |