DhanHQ 2.4.0 → 2.5.0

data/docs/WEBSOCKET_PROTOCOL.md

@@ -0,0 +1,154 @@
+# WebSocket Protocol Reference
+
+Low-level protocol details for the DhanHQ WebSocket market feed. For high-level usage, see the [WebSocket Integration Guide](websocket_integration.md).
+
+---
+
+## Subscription Modes
+
+| Mode      | What you get                              | Best for                        |
+| --------- | ----------------------------------------- | ------------------------------- |
+| `:ticker` | LTP + LTT                                | Lightweight price monitoring    |
+| `:quote`  | LTP + LTT + OHLCV + totals               | Most trading strategies         |
+| `:full`   | Quote + OI + best-5 depth (bid/ask)       | Order book analysis, depth-based strategies |
+
+---
+
+## Request Codes
+
+Per Dhan documentation:
+
+| Action       | Ticker | Quote | Full |
+| ------------ | ------ | ----- | ---- |
+| Subscribe    | 15     | 17    | 21   |
+| Unsubscribe  | 16     | 18    | 22   |
+| Disconnect   | 12     | 12    | 12   |
+
+---
+
+## Packet Parsing
+
+### Response Header (8 bytes)
+
+| Field                | Size   | Encoding | Description                   |
+| -------------------- | ------ | -------- | ----------------------------- |
+| `feed_response_code` | 1 byte | u8, BE   | Identifies the packet type    |
+| `message_length`     | 2 bytes| u16, BE  | Total message length in bytes |
+| `exchange_segment`   | 1 byte | u8, BE   | Exchange segment identifier   |
+| `security_id`        | 4 bytes| i32, LE  | Security identifier           |
+
+### Packet Types
+
+| Code | Type          | Fields                                                        |
+| ---- | ------------- | ------------------------------------------------------------- |
+| 1    | Index         | Surfaced as raw/misc unless documented                       |
+| 2    | Ticker        | `ltp`, `ltt`                                                 |
+| 4    | Quote         | `ltp`, `ltt`, `atp`, `volume`, totals, `day_*`               |
+| 5    | OI            | `open_interest`                                              |
+| 6    | Prev Close    | `prev_close`, `oi_prev`                                      |
+| 7    | Market Status | Raw/misc unless documented                                   |
+| 8    | Full          | Quote fields + `open_interest` + 5× depth (bid/ask)         |
+| 50   | Disconnect    | Reason code                                                  |
+
+---
+
+## Normalized Tick Schema
+
+All ticks are delivered as a Ruby Hash with consistent keys:
+
+```ruby
+{
+  kind: :quote,               # :ticker | :quote | :full | :oi | :prev_close | :misc
+  segment: "NSE_FNO",         # string enum
+  security_id: "12345",
+  ltp: 101.5,
+  ts:  1723791300,            # LTT epoch (sec) if present
+  vol: 123456,                # quote/full only
+  atp: 100.9,                 # quote/full only
+  day_open: 100.1,
+  day_high: 102.4,
+  day_low: 99.5,
+  day_close: nil,
+  oi: 987654,                 # full or OI packet
+  bid: 101.45,                # from depth (mode :full)
+  ask: 101.55                 # from depth (mode :full)
+}
+```
+
+---
+
+## Connection Limits & Behavior
+
+### Limits
+
+- **100 instruments** per subscribe/unsubscribe frame (auto-chunked by the client)
+- **5 WebSocket connections** per user (per Dhan)
+
+### Backoff & 429 Cool-Off
+
+- Exponential backoff with jitter on connection failure
+- Handshake **429** triggers a **60-second cool-off** before retry
+- The client handles this automatically — avoid manual rapid reconnect loops
+
+### Reconnect & Resubscribe
+
+- On reconnect, the client resends the **current subscription snapshot** (idempotent)
+- No manual re-subscribe needed after automatic reconnection
+
+### Graceful Shutdown
+
+- `ws.disconnect!` — sends broker disconnect code 12, prevents reconnects
+- `ws.stop` — hard stop (no broker message, just closes and halts loop)
+- `DhanHQ::WS.disconnect_all_local!` — kills all registered WS clients
+- An `at_exit` hook stops all registered clients to avoid leaked sockets
+
+---
+
+## Exchange Segment Enums
+
+Use these string enums in WebSocket `subscribe_*` calls and REST parameters:
+
+| Enum           | Exchange | Segment           |
+| -------------- | -------- | ----------------- |
+| `IDX_I`        | Index    | Index Value       |
+| `NSE_EQ`       | NSE      | Equity Cash       |
+| `NSE_FNO`      | NSE      | Futures & Options |
+| `NSE_CURRENCY` | NSE      | Currency          |
+| `BSE_EQ`       | BSE      | Equity Cash       |
+| `BSE_FNO`      | BSE      | Futures & Options |
+| `BSE_CURRENCY` | BSE      | Currency          |
+| `MCX_COMM`     | MCX      | Commodity         |
+
+---
+
+## Tick Access Patterns
+
+### Direct Handler
+
+```ruby
+ws.on(:tick) { |t| do_something_fast(t) }  # avoid heavy work here
+```
+
+### Shared TickCache (Recommended)
+
+```ruby
+# app/services/live/tick_cache.rb
+class TickCache
+  MAP = Concurrent::Map.new
+  def self.put(t)  = MAP["#{t[:segment]}:#{t[:security_id]}"] = t
+  def self.get(seg, sid) = MAP["#{seg}:#{sid}"]
+  def self.ltp(seg, sid) = get(seg, sid)&.dig(:ltp)
+end
+
+ws.on(:tick) { |t| TickCache.put(t) }
+ltp = TickCache.ltp("NSE_FNO", "12345")
+```
+
+### Filtered Callback
+
+```ruby
+def on_tick_for(ws, segment:, security_id:, &blk)
+  key = "#{segment}:#{security_id}"
+  ws.on(:tick) { |t| blk.call(t) if "#{t[:segment]}:#{t[:security_id]}" == key }
+end
+```

data/lib/DhanHQ/models/alert_order.rb

@@ -48,6 +48,28 @@ module DhanHQ
 
           find(response["alertId"])
         end
+
+        ##
+        # Modify an existing conditional trigger/alert order.
+        #
+        # @param alert_id [String] The alert ID to modify
+        # @param params [Hash] Updated parameters (condition, orders, etc.)
+        #
+        # @return [AlertOrder, nil] Updated AlertOrder instance, or nil on failure
+        #
+        # @example Modify an alert order's condition
+        #   updated = DhanHQ::Models::AlertOrder.modify("12345",
+        #     condition: { comparing_value: 300 },
+        #     orders: [{ quantity: 20 }]
+        #   )
+        #
+        def modify(alert_id, params)
+          normalized = snake_case(params)
+          response = resource.update(alert_id, camelize_keys(normalized))
+          return nil unless success_response?(response)
+
+          find(alert_id)
+        end
       end
 
       def id

data/lib/DhanHQ/models/edis.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Model for EDIS (Electronic Delivery Instruction Slip) operations.
+    #
+    # EDIS is used for selling holdings from your demat account. The API provides
+    # endpoints to generate T-PIN, create eDIS forms, and check authorization status.
+    #
+    # @example Generate T-PIN
+    #   DhanHQ::Models::Edis.generate_tpin
+    #
+    # @example Generate eDIS form
+    #   response = DhanHQ::Models::Edis.generate_form(
+    #     isin: "INE155A01022",
+    #     qty: 10,
+    #     exchange: "NSE",
+    #     segment: "E",
+    #     bulk: false
+    #   )
+    #
+    # @example Check EDIS status for a security
+    #   status = DhanHQ::Models::Edis.inquire(isin: "INE155A01022")
+    #
+    class Edis < BaseModel
+      HTTP_PATH = "/edis"
+
+      class << self
+        ##
+        # Provides a shared instance of the Edis resource.
+        #
+        # @return [DhanHQ::Resources::Edis] The Edis resource client instance
+        def resource
+          @resource ||= DhanHQ::Resources::Edis.new
+        end
+
+        ##
+        # Generate T-PIN for eDIS authorization.
+        #
+        # Triggers T-PIN generation which is sent to the user's registered mobile/email.
+        #
+        # @return [Hash] API response
+        #
+        # @example Generate T-PIN before selling holdings
+        #   DhanHQ::Models::Edis.generate_tpin
+        #
+        def generate_tpin
+          resource.tpin
+        end
+
+        ##
+        # Generate an eDIS form for authorizing sale of holdings.
+        #
+        # @param isin [String] ISIN of the security (e.g., "INE155A01022")
+        # @param qty [Integer] Quantity to authorize for sale
+        # @param exchange [String] Exchange name (e.g., "NSE", "BSE")
+        # @param segment [String] Segment identifier (e.g., "E")
+        # @param bulk [Boolean] Whether this is a bulk authorization (default: false)
+        #
+        # @return [Hash] API response containing the eDIS form data
+        #
+        # @example Authorize sale of 10 shares
+        #   DhanHQ::Models::Edis.generate_form(
+        #     isin: "INE155A01022",
+        #     qty: 10,
+        #     exchange: "NSE",
+        #     segment: "E"
+        #   )
+        #
+        def generate_form(isin:, qty:, exchange:, segment:, bulk: false)
+          resource.form({ isin: isin, qty: qty, exchange: exchange, segment: segment, bulk: bulk })
+        end
+
+        ##
+        # Generate a bulk eDIS form for multiple securities.
+        #
+        # @param params [Hash] Bulk form parameters
+        # @return [Hash] API response
+        #
+        def generate_bulk_form(params)
+          resource.bulk_form(params)
+        end
+
+        ##
+        # Check EDIS authorization status for a security.
+        #
+        # @param isin [String] ISIN of the security to check
+        #
+        # @return [Hash] API response containing authorization status
+        #
+        # @example Check if EDIS is authorized
+        #   status = DhanHQ::Models::Edis.inquire(isin: "INE155A01022")
+        #
+        def inquire(isin:)
+          resource.inquire(isin)
+        end
+      end
+
+      ##
+      # No validation contract needed — EDIS operations are simple API calls.
+      #
+      # @return [nil]
+      # @api private
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/kill_switch.rb

@@ -132,6 +132,28 @@ module DhanHQ
         def deactivate
           update("DEACTIVATE")
         end
+
+        ##
+        # Fetches the current kill switch status for your account.
+        #
+        # Checks whether the kill switch is currently active or inactive for
+        # the current trading day.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing kill switch status.
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:kill_switch_status** [String] Current status: "ACTIVATE" or "DEACTIVATE"
+        #
+        # @example Check if kill switch is active
+        #   response = DhanHQ::Models::KillSwitch.status
+        #   if response[:kill_switch_status] == "ACTIVATE"
+        #     puts "Kill switch is active — trading disabled"
+        #   else
+        #     puts "Kill switch is inactive — trading enabled"
+        #   end
+        #
+        def status
+          resource.status
+        end
       end
 
       ##

data/lib/DhanHQ/models/margin.rb

@@ -139,6 +139,55 @@ module DhanHQ
           response = resource.calculate(formatted_params)
           new(response, skip_validation: true)
         end
+
+        ##
+        # Calculates margin requirements for multiple scripts in a single request.
+        #
+        # Provides combined margin calculation including hedge benefit across multiple
+        # instruments. Useful for portfolio-level margin analysis.
+        #
+        # @param params [Hash{Symbol => Object}] Request parameters
+        #   @option params [Boolean] :include_position Whether to include existing positions
+        #   @option params [Boolean] :include_order Whether to include existing orders
+        #   @option params [String] :dhan_client_id User-specific identification
+        #   @option params [Array<Hash>] :scrip_list Array of instrument margin params, each with:
+        #     - :exchange_segment [String]
+        #     - :transaction_type [String]
+        #     - :quantity [Integer]
+        #     - :product_type [String]
+        #     - :security_id [String]
+        #     - :price [Float]
+        #     - :trigger_price [Float] (optional)
+        #
+        # @return [Hash{Symbol => String}] Response hash containing:
+        #   - **:total_margin** [String] Total margin required
+        #   - **:span_margin** [String] SPAN margin
+        #   - **:exposure_margin** [String] Exposure margin
+        #   - **:equity_margin** [String] Equity margin
+        #   - **:fo_margin** [String] F&O margin
+        #   - **:commodity_margin** [String] Commodity margin
+        #   - **:currency** [String] Currency (e.g., "INR")
+        #   - **:hedge_benefit** [String] Hedge benefit amount
+        #
+        # @example Calculate margin for multiple scripts
+        #   result = DhanHQ::Models::Margin.calculate_multi(
+        #     include_position: true,
+        #     include_order: true,
+        #     dhan_client_id: "1000000132",
+        #     scrip_list: [
+        #       { exchange_segment: "NSE_EQ", transaction_type: "BUY",
+        #         quantity: 100, product_type: "CNC", security_id: "1333", price: 1428.0 },
+        #       { exchange_segment: "NSE_FNO", transaction_type: "SELL",
+        #         quantity: 50, product_type: "INTRADAY", security_id: "43492", price: 200.0 }
+        #     ]
+        #   )
+        #   puts "Total margin: #{result[:total_margin]}"
+        #   puts "Hedge benefit: #{result[:hedge_benefit]}"
+        #
+        def calculate_multi(params)
+          formatted_params = camelize_keys(params)
+          resource.calculate_multi(formatted_params)
+        end
       end
 
       ##

data/lib/DhanHQ/models/pnl_exit.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Model for managing P&L-based automatic position exit.
+    #
+    # The P&L Based Exit API allows users to configure automatic exit rules based on
+    # cumulative profit or loss thresholds. When the defined limits are breached, all
+    # applicable positions are exited automatically.
+    #
+    # @note The configured P&L based exit remains active for the current day and is
+    #   reset at the end of the trading session.
+    #
+    # @example Configure P&L-based exit
+    #   response = DhanHQ::Models::PnlExit.configure(
+    #     profit_value: 1500.0,
+    #     loss_value: 500.0,
+    #     product_type: ["INTRADAY", "DELIVERY"],
+    #     enable_kill_switch: true
+    #   )
+    #   puts response[:pnl_exit_status] # => "ACTIVE"
+    #
+    # @example Check current P&L exit configuration
+    #   config = DhanHQ::Models::PnlExit.status
+    #   puts "Status: #{config.pnl_exit_status}"
+    #   puts "Profit threshold: ₹#{config.profit}"
+    #   puts "Loss threshold: ₹#{config.loss}"
+    #
+    # @example Stop P&L-based exit
+    #   response = DhanHQ::Models::PnlExit.stop
+    #   puts response[:pnl_exit_status] # => "DISABLED"
+    #
+    class PnlExit < BaseModel
+      HTTP_PATH = "/v2/pnlExit"
+
+      attributes :pnl_exit_status, :profit, :loss, :segments, :enable_kill_switch
+
+      class << self
+        ##
+        # Provides a shared instance of the PnlExit resource.
+        #
+        # @return [DhanHQ::Resources::PnlExit] The PnlExit resource client instance
+        def resource
+          @resource ||= DhanHQ::Resources::PnlExit.new
+        end
+
+        ##
+        # Configure automatic P&L-based position exit.
+        #
+        # When the defined profit or loss thresholds are breached during the trading day,
+        # all applicable positions are exited automatically.
+        #
+        # @param profit_value [Float] Profit threshold that triggers exit (e.g., 1500.0)
+        # @param loss_value [Float] Loss threshold that triggers exit (e.g., 500.0)
+        # @param product_type [Array<String>] Product types to apply. e.g., ["INTRADAY", "DELIVERY"]
+        # @param enable_kill_switch [Boolean] Whether to activate kill switch after exit
+        #
+        # @return [Hash{Symbol => String}] Response hash containing:
+        #   - **:pnl_exit_status** [String] "ACTIVE" on success
+        #   - **:message** [String] Confirmation message
+        #
+        # @example Configure with kill switch
+        #   DhanHQ::Models::PnlExit.configure(
+        #     profit_value: 2000.0,
+        #     loss_value: 1000.0,
+        #     product_type: ["INTRADAY"],
+        #     enable_kill_switch: true
+        #   )
+        #
+        def configure(profit_value:, loss_value:, product_type:, enable_kill_switch: false)
+          params = {
+            profitValue: profit_value.to_s,
+            lossValue: loss_value.to_s,
+            productType: product_type,
+            enableKillSwitch: enable_kill_switch
+          }
+          resource.configure(params)
+        end
+
+        ##
+        # Stop/disable the active P&L-based exit configuration.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing:
+        #   - **:pnl_exit_status** [String] "DISABLED"
+        #   - **:message** [String] Confirmation message
+        #
+        # @example Disable P&L exit
+        #   response = DhanHQ::Models::PnlExit.stop
+        #   puts response[:pnl_exit_status] # => "DISABLED"
+        #
+        def stop
+          resource.stop
+        end
+
+        ##
+        # Fetch the currently active P&L-based exit configuration.
+        #
+        # @return [PnlExit] PnlExit object with current configuration.
+        #   - **:pnl_exit_status** [String] "ACTIVE" or "DISABLED"
+        #   - **:profit** [String] Configured profit threshold
+        #   - **:loss** [String] Configured loss threshold
+        #   - **:segments** [Array<String>] Active product types
+        #   - **:enable_kill_switch** [Boolean] Whether kill switch is enabled
+        #
+        # @example Check configuration
+        #   config = DhanHQ::Models::PnlExit.status
+        #   if config.pnl_exit_status == "ACTIVE"
+        #     puts "P&L exit active: profit=₹#{config.profit}, loss=₹#{config.loss}"
+        #   end
+        #
+        def status
+          response = resource.status
+          return nil unless response.is_a?(Hash)
+
+          new(response, skip_validation: true)
+        end
+      end
+
+      ##
+      # No validation contract needed — server-side validation handles it.
+      #
+      # @return [nil]
+      # @api private
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/position.rb

@@ -205,6 +205,28 @@ module DhanHQ
           response = resource.convert(formatted_params)
           success_response?(response) ? response : DhanHQ::ErrorObject.new(response)
         end
+
+        ##
+        # Exits all active positions and cancels all open orders for the current trading day.
+        #
+        # This is a safety endpoint for emergency position closure. It sends a DELETE request
+        # to close all positions and cancel all pending orders in one call.
+        #
+        # @return [Hash{Symbol => String}] Response hash containing operation result.
+        #   - **:status** [String] "SUCCESS" or "ERROR"
+        #   - **:message** [String] Description of the result
+        #
+        # @example Emergency exit all positions
+        #   response = DhanHQ::Models::Position.exit_all!
+        #   if response[:status] == "SUCCESS"
+        #     puts "✓ All positions exited and orders cancelled"
+        #   else
+        #     puts "✗ Failed: #{response[:message]}"
+        #   end
+        #
+        def exit_all!
+          resource.exit_all
+        end
       end
     end
   end

data/lib/DhanHQ/models/postback.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Models
+    ##
+    # Utility model for parsing Dhan postback (webhook) payloads.
+    #
+    # Postback is a webhook mechanism where Dhan pushes order status updates to your
+    # configured URL. This model provides a convenient way to parse the incoming JSON
+    # payload into a typed, attribute-accessible object.
+    #
+    # @note Postback URL is configured in the Dhan web console when generating an access
+    #   token. It will NOT work with localhost or 127.0.0.1.
+    #
+    # @example Parse postback payload in a Rails controller
+    #   class DhanWebhooksController < ApplicationController
+    #     skip_before_action :verify_authenticity_token
+    #
+    #     def create
+    #       postback = DhanHQ::Models::Postback.parse(request.body.read)
+    #       case postback.order_status
+    #       when "TRADED"
+    #         handle_fill(postback)
+    #       when "REJECTED"
+    #         handle_rejection(postback)
+    #       end
+    #       head :ok
+    #     end
+    #   end
+    #
+    # @example Parse postback payload from a hash
+    #   postback = DhanHQ::Models::Postback.parse(params)
+    #   puts "Order #{postback.order_id} is now #{postback.order_status}"
+    #   puts "Filled: #{postback.filled_qty}/#{postback.quantity}"
+    #
+    class Postback < BaseModel
+      HTTP_PATH = nil # No API endpoint — postback is pushed to the user
+
+      attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
+                 :transaction_type, :exchange_segment, :product_type, :order_type,
+                 :validity, :trading_symbol, :security_id, :quantity,
+                 :disclosed_quantity, :price, :trigger_price, :after_market_order,
+                 :bo_profit_value, :bo_stop_loss_value, :leg_name,
+                 :create_time, :update_time, :exchange_time,
+                 :drv_expiry_date, :drv_option_type, :drv_strike_price,
+                 :oms_error_code, :oms_error_description, :filled_qty, :algo_id
+
+      class << self
+        ##
+        # Parse a postback webhook payload into a Postback model instance.
+        #
+        # Accepts either a JSON string (from request body) or a Hash (from parsed params).
+        # Keys are normalized to snake_case automatically.
+        #
+        # @param payload [String, Hash] Raw JSON string or Hash from the webhook
+        #
+        # @return [Postback] Parsed Postback object with typed attributes
+        #
+        # @example From raw JSON string
+        #   postback = DhanHQ::Models::Postback.parse('{"orderId":"123","orderStatus":"TRADED"}')
+        #   puts postback.order_status # => "TRADED"
+        #
+        # @example From a hash
+        #   postback = DhanHQ::Models::Postback.parse(order_id: "123", order_status: "TRADED")
+        #   puts postback.order_id # => "123"
+        #
+        def parse(payload)
+          data = case payload
+                 when String
+                   JSON.parse(payload)
+                 when Hash
+                   payload
+                 else
+                   raise ArgumentError, "Expected String or Hash, got #{payload.class}"
+                 end
+
+          new(data, skip_validation: true)
+        end
+      end
+
+      ##
+      # Whether the order has been fully traded.
+      #
+      # @return [Boolean]
+      def traded?
+        order_status == "TRADED"
+      end
+
+      ##
+      # Whether the order was rejected.
+      #
+      # @return [Boolean]
+      def rejected?
+        order_status == "REJECTED"
+      end
+
+      ##
+      # Whether the order is still pending.
+      #
+      # @return [Boolean]
+      def pending?
+        order_status == "PENDING"
+      end
+
+      ##
+      # Whether the order was cancelled.
+      #
+      # @return [Boolean]
+      def cancelled?
+        order_status == "CANCELLED"
+      end
+
+      ##
+      # No validation contract — postback payloads are parsed as-is.
+      #
+      # @return [nil]
+      # @api private
+      def validation_contract
+        nil
+      end
+    end
+  end
+end

data/lib/DhanHQ/resources/kill_switch.rb

@@ -16,6 +16,14 @@ module DhanHQ
       def update(params)
         post("", params: params)
       end
+
+      ##
+      # Fetches the current kill switch status.
+      #
+      # @return [Hash] API response containing dhan_client_id and kill_switch_status.
+      def status
+        get("")
+      end
     end
   end
 end

data/lib/DhanHQ/resources/margin_calculator.rb

@@ -17,6 +17,15 @@ module DhanHQ
       def calculate(params)
         post("", params: params)
       end
+
+      ##
+      # Calculate margin requirements for multiple scripts in one request.
+      #
+      # @param params [Hash] Request parameters including scripList, includePosition, includeOrder.
+      # @return [Hash] API response containing combined margin details with hedge benefit.
+      def calculate_multi(params)
+        post("/multi", params: params)
+      end
     end
   end
 end