DhanHQ 2.1.0

data/lib/DhanHQ/models/trade.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Represents a single trade.
+    # The API docs show an array of trades from GET /v2/trades/{from-date}/{to-date}/{page}
+    class Trade < BaseModel
+      # No explicit HTTP_PATH if we rely on the statements resource
+      # but we can define it if needed
+      HTTP_PATH = "/v2/trades"
+
+      attributes :dhan_client_id, :order_id, :exchange_order_id, :exchange_trade_id,
+                 :transaction_type, :exchange_segment, :product_type, :order_type,
+                 :trading_symbol, :custom_symbol, :security_id, :traded_quantity,
+                 :traded_price, :isin, :instrument, :sebi_tax, :stt, :brokerage_charges,
+                 :service_tax, :exchange_transaction_charges, :stamp_duty,
+                 :create_time, :update_time, :exchange_time, :drv_expiry_date,
+                 :drv_option_type, :drv_strike_price
+
+      class << self
+        ##
+        # Provide a **shared instance** of the `Statements` resource,
+        # where we have `trade_history(from_date:, to_date:, page:)`.
+        # used for fetching historical trades.
+        def resource
+          @resource ||= DhanHQ::Resources::Statements.new
+        end
+
+        ##
+        # Resource for current day tradebook APIs
+        def tradebook_resource
+          @tradebook_resource ||= DhanHQ::Resources::Trades.new
+        end
+
+        ##
+        # Fetch trades within the given date range and page.
+        # GET /v2/trades/{from-date}/{to-date}/{page}
+        #
+        # @param from_date [String]
+        # @param to_date   [String]
+        # @param page      [Integer] Default 0
+        # @return [Array<Trade>]
+        # Retrieve historical trades
+        def history(from_date:, to_date:, page: 0)
+          # The resource call returns an Array<Hash>.
+          response = resource.trade_history(from_date: from_date, to_date: to_date, page: page)
+          return [] unless response.is_a?(Array)
+
+          response.map { |t| new(t, skip_validation: true) }
+        end
+
+        alias all history
+
+        # Retrieve current day trades
+        def today
+          response = tradebook_resource.all
+          return [] unless response.is_a?(Array)
+
+          response.map { |t| new(t, skip_validation: true) }
+        end
+
+        # Fetch trades for a specific order id for the current day
+        def find_by_order_id(order_id)
+          response = tradebook_resource.find(order_id)
+          return nil unless response.is_a?(Hash) || (response.is_a?(Array) && response.any?)
+
+          data = response.is_a?(Array) ? response.first : response
+          new(data, skip_validation: true)
+        end
+      end
+
+      # If you want custom validations, you'd set a contract or skip for read-only
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/rate_limiter.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module DhanHQ
+  # Coarse-grained in-memory throttler matching the platform rate limits.
+  class RateLimiter
+    # Per-interval thresholds keyed by API type.
+    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 },
+      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,
+                         per_day: Float::INFINITY }
+    }.freeze
+
+    # Creates a rate limiter for a given API type.
+    #
+    # @param api_type [Symbol] One of the keys from {RATE_LIMITS}.
+    def initialize(api_type)
+      @api_type = api_type
+      @buckets = Concurrent::Hash.new
+      @buckets[:last_request_time] = Time.at(0) if api_type == :option_chain
+      initialize_buckets
+      start_cleanup_threads
+    end
+
+    # Blocks until the current request is allowed by the configured limits.
+    #
+    # @return [void]
+    def throttle!
+      if @api_type == :option_chain
+        last_request_time = @buckets[:last_request_time]
+
+        sleep_time = 4 - (Time.now - last_request_time)
+        if sleep_time.positive?
+          puts "Sleeping for #{sleep_time.round(2)} seconds due to option_chain rate limit"
+          sleep(sleep_time)
+        end
+
+        @buckets[:last_request_time] = Time.now
+        return
+      end
+
+      loop do
+        break if allow_request?
+
+        sleep(0.1)
+      end
+      record_request
+    end
+
+    private
+
+    # Prepares the counters used for each interval in {RATE_LIMITS}.
+    def initialize_buckets
+      RATE_LIMITS[@api_type].each_key do |interval|
+        @buckets[interval] = Concurrent::AtomicFixnum.new(0)
+      end
+    end
+
+    # Determines whether a request can be made without exceeding limits.
+    #
+    # @return [Boolean]
+    def allow_request?
+      RATE_LIMITS[@api_type].all? do |interval, limit|
+        @buckets[interval].value < limit
+      end
+    end
+
+    # Increments the counters for each time window once a request is made.
+    def record_request
+      RATE_LIMITS[@api_type].each_key do |interval|
+        @buckets[interval].increment
+      end
+    end
+
+    # Spawns background threads to reset counters after each interval elapses.
+    def start_cleanup_threads
+      Thread.new do
+        loop do
+          sleep(1)
+          @buckets[:per_second].value = 0
+        end
+      end
+      Thread.new do
+        loop do
+          sleep(60)
+          @buckets[:per_minute].value = 0
+        end
+      end
+      Thread.new do
+        loop do
+          sleep(3600)
+          @buckets[:per_hour].value = 0
+        end
+      end
+      Thread.new do
+        loop do
+          sleep(86_400)
+          @buckets[:per_day].value = 0
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/requests/optionchain/nifty.json

@@ -0,0 +1,5 @@
+{
+  "UnderlyingScrip": 13,
+  "UnderlyingSeg": "IDX_I",
+  "Expiry": "2025-02-27"
+}

data/lib/DhanHQ/requests/optionchain/nifty_expiries.json

@@ -0,0 +1,4 @@
+{
+  "UnderlyingScrip": 13,
+  "UnderlyingSeg": "IDX_I"
+}

data/lib/DhanHQ/resources/edis.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client for electronic DIS flows.
+    class Edis < BaseAPI
+      # EDIS endpoints are served from the trading API.
+      API_TYPE = :order_api
+      # Base path for EDIS endpoints.
+      HTTP_PATH = "/v2/edis"
+
+      # Creates a TPIN request form.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def form(params)
+        post("/form", params: params)
+      end
+
+      # Bulk EDIS form submission.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def bulk_form(params)
+        post("/bulkform", params: params)
+      end
+
+      # Generates a TPIN for the client.
+      #
+      # @return [Hash]
+      def tpin
+        get("/tpin")
+      end
+
+      # Checks the EDIS status for a given ISIN.
+      #
+      # @param isin [String]
+      # @return [Hash]
+      def inquire(isin)
+        get("/inquire/#{isin}")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/forever_orders.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client for GTT/forever order management.
+    class ForeverOrders < BaseAPI
+      # Uses the trading API tier.
+      API_TYPE = :order_api
+      # Root path for forever order operations.
+      HTTP_PATH = "/v2/forever"
+
+      # Lists all forever orders for the account.
+      #
+      # @return [Array<Hash>]
+      def all
+        get("/orders")
+      end
+
+      # Creates a new forever order configuration.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def create(params)
+        post("/orders", params: params)
+      end
+
+      # Fetches a forever order by identifier.
+      #
+      # @param order_id [String]
+      # @return [Hash]
+      def find(order_id)
+        get("/orders/#{order_id}")
+      end
+
+      # Updates a forever order.
+      #
+      # @param order_id [String]
+      # @param params [Hash]
+      # @return [Hash]
+      def update(order_id, params)
+        put("/orders/#{order_id}", params: params)
+      end
+
+      # Cancels a forever order.
+      #
+      # @param order_id [String]
+      # @return [Hash]
+      def cancel(order_id)
+        delete("/orders/#{order_id}")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/funds.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client that exposes funds and limits endpoints.
+    class Funds < BaseAPI
+      # Funds data comes from the trading API tier.
+      API_TYPE = :order_api
+      # Base path for fund limit endpoints.
+      HTTP_PATH = "/v2/fundlimit"
+
+      ##
+      # Fetch fund limit details.
+      #
+      # @return [Hash] API response containing fund details.
+      def fetch
+        get("")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/historical_data.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    ##
+    # Resource class for fetching Daily & Intraday historical data.
+    # Based on the official docs:
+    # - POST /v2/charts/historical  (daily timeframe)
+    # - POST /v2/charts/intraday   (minute timeframe)
+    #
+    class HistoricalData < BaseAPI
+      API_TYPE = :data_api     # Because we are fetching market data
+      HTTP_PATH = "/v2/charts" # The base path for historical endpoints
+
+      ##
+      # POST /v2/charts/historical
+      # "Daily Historical Data"
+      # @param params [Hash]
+      # @return [Hash] The parsed API response containing arrays of open, high, low, close, volume, timestamp
+      def daily(params)
+        post("/historical", params: params)
+      end
+
+      ##
+      # POST /v2/charts/intraday
+      # "Intraday Historical Data"
+      # @param params [Hash]
+      # @return [Hash] The parsed API response containing arrays for candle data
+      def intraday(params)
+        post("/intraday", params: params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/holdings.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client exposing portfolio holdings.
+    class Holdings < BaseAPI
+      # Holdings are exposed via the trading API.
+      API_TYPE = :order_api
+      # Base path for holdings queries.
+      HTTP_PATH = "/v2/holdings"
+
+      ##
+      # Fetch all holdings.
+      #
+      # @return [Array<Hash>] API response containing holdings data.
+      def all
+        get("")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/kill_switch.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client to control the trading kill switch feature.
+    class KillSwitch < BaseAPI
+      # Kill switch operations execute on the trading API tier.
+      API_TYPE = :order_api
+      # Base path for kill switch operations.
+      HTTP_PATH = "/v2/killswitch"
+
+      # Enables or disables the kill switch.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def update(params)
+        post("", params: params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/margin_calculator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client for invoking the margin calculator endpoint.
+    class MarginCalculator < BaseAPI
+      # Calculator results are served via the trading API.
+      API_TYPE = :order_api
+      # Base path for the calculator endpoint.
+      HTTP_PATH = "/v2/margincalculator"
+
+      ##
+      # Calculate margin requirements for an order.
+      #
+      # @param params [Hash] Request parameters for margin calculation.
+      # @return [Hash] API response containing margin details.
+      def calculate(params)
+        post("", params: params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/market_feed.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client for fetching on-demand market data snapshots.
+    class MarketFeed < BaseAPI
+      # Market feed requests hit the data API tier.
+      API_TYPE = :data_api
+      # Root path for market feed endpoints.
+      HTTP_PATH = "/v2"
+
+      ##
+      # POST /v2/marketfeed/ltp
+      # Returns the LTP (Last Traded Price) of up to 1000 instruments.
+      #
+      # @param params [Hash] Example:
+      #   {
+      #     "NSE_EQ": [11536, 3456],
+      #     "NSE_FNO": [49081, 49082]
+      #   }
+      # @return [HashWithIndifferentAccess]
+      def ltp(params)
+        post("/marketfeed/ltp", params: params)
+      end
+
+      ##
+      # POST /v2/marketfeed/ohlc
+      # Returns open-high-low-close for up to 1000 instruments.
+      #
+      # @param params [Hash]
+      # @return [HashWithIndifferentAccess]
+      def ohlc(params)
+        post("/marketfeed/ohlc", params: params)
+      end
+
+      ##
+      # POST /v2/marketfeed/quote
+      # Returns market depth, OI, and other details for up to 1000 instruments.
+      #
+      # @param params [Hash]
+      # @return [HashWithIndifferentAccess]
+      def quote(params)
+        quote_resource.post("/marketfeed/quote", params: params)
+      end
+
+      private
+
+      # Lazily builds a `:quote_api` scoped client for quote depth requests.
+      #
+      # @return [MarketFeed]
+      def quote_resource
+        @quote_resource ||= self.class.new(api_type: :quote_api)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/option_chain.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client for querying option chain data APIs.
+    class OptionChain < BaseAPI
+      # Option chain queries have bespoke rate limits, hence their own API type.
+      API_TYPE = :option_chain
+      # Base path for option chain endpoints.
+      HTTP_PATH = "/v2/optionchain"
+
+      ##
+      # Fetch option chain data based on provided parameters.
+      #
+      # @param params [Hash] Query parameters for the request.
+      # @return [Hash] API response containing option chain data.
+      def fetch(params)
+        post("", params: params)
+      end
+
+      ##
+      # Fetch expiry dates list based on provided parameters.
+      #
+      # @param params [Hash] Query parameters for the request.
+      # @return [Hash] API response containing option chain data.
+      def expirylist(params)
+        post("/expirylist", params: params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/orders.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # REST API wrappers grouped by resource type.
+  module Resources
+    # Resource client for managing equity and F&O orders.
+    class Orders < BaseAPI
+      # Orders are routed through the trading API tier.
+      API_TYPE = :order_api
+      # Base path for order endpoints.
+      HTTP_PATH = "/v2/orders"
+
+      # Retrieve all orders for the current trading day.
+      #
+      # @return [Array<Hash>]
+      def all
+        get("")
+      end
+
+      # Places a new order using the provided payload.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def create(params)
+        post("", params: params)
+      end
+
+      # Fetches a single order by broker order id.
+      #
+      # @param order_id [String]
+      # @return [Hash]
+      def find(order_id)
+        get("/#{order_id}")
+      end
+
+      # Modifies an existing order.
+      #
+      # @param order_id [String]
+      # @param params [Hash]
+      # @return [Hash]
+      def update(order_id, params)
+        put("/#{order_id}", params: params)
+      end
+
+      # Cancels an existing order.
+      #
+      # @param order_id [String]
+      # @return [Hash]
+      def cancel(order_id)
+        delete("/#{order_id}")
+      end
+
+      # Places a slicing order request.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def slicing(params)
+        post("/slicing", params: params)
+      end
+
+      # Retrieve an order by client-supplied correlation id.
+      #
+      # @param correlation_id [String]
+      # @return [Hash]
+      def by_correlation(correlation_id)
+        get("/external/#{correlation_id}")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/positions.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    # Resource client managing intraday and carry-forward positions.
+    class Positions < BaseAPI
+      # Position endpoints are exposed via the trading API.
+      API_TYPE = :order_api
+      # Base path for position management endpoints.
+      HTTP_PATH = "/v2/positions"
+
+      ##
+      # Fetch all open positions for the day.
+      #
+      # @return [Array<Hash>] API response containing position data.
+      def all
+        get("")
+      end
+
+      # Converts a position between eligible product types.
+      #
+      # @param params [Hash]
+      # @return [Hash]
+      def convert(params)
+        post("/convert", params: params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/profile.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    ##
+    # Provides access to the user profile endpoint.
+    #
+    # The endpoint is a simple GET request to `/v2/profile` that returns
+    # account level metadata (token validity, active segments, etc.).
+    class Profile < BaseAPI
+      # Profile metadata is served from the non-trading API tier.
+      API_TYPE = :non_trading_api
+      # Base path for profile lookups.
+      HTTP_PATH = "/v2/profile"
+
+      ##
+      # Fetch the authenticated user's profile information.
+      #
+      # @return [Hash] Parsed response from the profile endpoint.
+      def fetch
+        get("")
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/statements.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Resources
+    ##
+    # Provides methods to retrieve Ledger and Trade History.
+    #
+    # GET /v2/ledger?from-date=YYYY-MM-DD&to-date=YYYY-MM-DD
+    # GET /v2/trades/{from-date}/{to-date}/{page}
+    #
+    class Statements < BaseAPI
+      # Statement history is fetched from the non-trading API tier.
+      API_TYPE = :non_trading_api
+      # Base path for ledger and trade history.
+      HTTP_PATH = "/v2"
+
+      ##
+      # GET /v2/ledger?from-date=YYYY-MM-DD&to-date=YYYY-MM-DD
+      # @param from_date [String] e.g. "2023-01-01"
+      # @param to_date   [String] e.g. "2023-01-31"
+      # @return [Array<Hash>] An array of ledger entries
+      def ledger(from_date:, to_date:)
+        # Because the docs say "from-date" & "to-date" (with dashes),
+        # pass them as snake case or match them exactly:
+        get("/ledger", params: { "from-date": from_date, "to-date": to_date })
+      end
+
+      ##
+      # GET /v2/trades/{from-date}/{to-date}/{page}
+      # @param from_date [String]
+      # @param to_date   [String]
+      # @param page      [Integer] Defaults to 0
+      # @return [Array<Hash>] An array of trades
+      #
+      def trade_history(from_date:, to_date:, page: 0)
+        # docs show this path style:
+        # /v2/trades/{from-date}/{to-date}/{page}
+        get("/trades/#{from_date}/#{to_date}/#{page}")
+      end
+    end
+  end
+end