DhanHQ 3.2.1 → 3.4.0

data/lib/DhanHQ/backtest/runner.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Backtest
+    # Replays a DhanHQ::Strategy::Base against historical OHLC candles and
+    # returns a Result.
+    #
+    # Both entries and exits fill at the *next* candle's open, never the
+    # signal candle's own price — evaluating a signal on a candle and then
+    # filling somewhere inside that same candle is look-ahead bias, since the
+    # fill price would have to come from before the candle closed (and so
+    # before the signal could have fired live). The one exception is the end
+    # of the dataset: an open position with no next candle to fill against is
+    # force-closed at the last candle's close.
+    #
+    # Only one position is held at a time, matching DhanHQ::Strategy::Base's
+    # single `@position` / entry-then-exit model — no pyramiding, no shorting.
+    class Runner
+      DEFAULT_QUANTITY = ->(equity, price) { price.positive? ? (equity / price).floor : 0 }
+      NO_FEES = ->(_trade_value) { 0.0 }
+
+      # @param strategy [DhanHQ::Strategy::Base]
+      # @param data [DhanHQ::MarketData::OHLCSeries]
+      # @param initial_capital [Float]
+      # @param quantity [#call, Integer] `->(equity, price) { ... }`, or a fixed integer
+      # @param fees [#call] `->(trade_value) { ... }`, charged once per leg (entry, exit)
+      # @param max_bars_held [Integer, nil] force-exit a position held this many bars or longer
+      def initialize(strategy:, data:, initial_capital:, quantity: DEFAULT_QUANTITY, fees: NO_FEES, max_bars_held: nil)
+        @strategy = strategy
+        @candles = data.respond_to?(:candles) ? data.candles : Array(data)
+        @initial_capital = initial_capital.to_f
+        @quantity = quantity.respond_to?(:call) ? quantity : ->(_equity, _price) { quantity }
+        @fees = fees
+        @max_bars_held = max_bars_held
+      end
+
+      # @return [DhanHQ::Backtest::Result]
+      def run
+        return Result.new(trades: [], equity_curve: [], initial_capital: @initial_capital) if @candles.empty?
+
+        equity = @initial_capital
+        equity_curve = []
+        trades = []
+        window_candles = []
+        open_trade = nil
+        entry_index = nil
+
+        @candles.each_with_index do |candle, index|
+          window_candles << candle
+          window = DhanHQ::MarketData::OHLCSeries.new(window_candles)
+          has_next = index < @candles.size - 1
+
+          if open_trade && has_next
+            trade = maybe_exit(open_trade, window, index, entry_index, equity, equity_curve, @candles[index + 1])
+
+            if trade
+              trades << trade
+              equity += trade.pnl
+              open_trade = nil
+              entry_index = nil
+            end
+          elsif open_trade.nil? && has_next
+            open_trade, entry_index = maybe_enter(window, @candles[index + 1], equity, index)
+          end
+
+          # A position opened this very iteration (via maybe_enter) isn't filled until the
+          # *next* candle — mark-to-market must stay flat until index reaches entry_index,
+          # or the equity curve would price the position off a fill that hasn't happened yet.
+          filled = open_trade && index >= entry_index
+          equity_curve << mark_to_market(equity, filled ? open_trade : nil, candle.close)
+        end
+
+        if open_trade
+          last = @candles.last
+          trade = close_trade(open_trade, last.timestamp, last.close, :end_of_data)
+          trades << trade
+          equity += trade.pnl
+          equity_curve[-1] = equity
+        end
+
+        Result.new(trades: trades, equity_curve: equity_curve, initial_capital: @initial_capital)
+      end
+
+      private
+
+      def maybe_enter(window, next_candle, equity, index)
+        signal = @strategy.evaluate_entry(window)
+        return [nil, nil] unless signal.buy?
+
+        qty = @quantity.call(equity, next_candle.open)
+        return [nil, nil] unless qty.positive?
+
+        [{ entry_time: next_candle.timestamp, entry_price: next_candle.open, quantity: qty }, index + 1]
+      end
+
+      def maybe_exit(open_trade, window, index, entry_index, equity, equity_curve, next_candle)
+        bars_held = index - entry_index
+        forced = @max_bars_held && bars_held >= @max_bars_held
+        drawdown = drawdown_pct(equity_curve, equity)
+        violations = @strategy.check_risks(equity: equity, position: open_trade, drawdown: drawdown)
+        signal = @strategy.evaluate_exit(window)
+
+        return unless forced || violations.any? || signal.sell?
+
+        reason = if forced
+                   :max_bars_held
+                 elsif violations.any?
+                   :risk_violation
+                 else
+                   :signal
+                 end
+        close_trade(open_trade, next_candle.timestamp, next_candle.open, reason)
+      end
+
+      def close_trade(open_trade, exit_time, exit_price, reason)
+        entry_value = open_trade[:entry_price] * open_trade[:quantity]
+        exit_value = exit_price * open_trade[:quantity]
+
+        Trade.new(
+          entry_time: open_trade[:entry_time],
+          entry_price: open_trade[:entry_price],
+          exit_time: exit_time,
+          exit_price: exit_price,
+          quantity: open_trade[:quantity],
+          exit_reason: reason,
+          fees: @fees.call(entry_value) + @fees.call(exit_value)
+        )
+      end
+
+      def mark_to_market(equity, open_trade, close_price)
+        return equity unless open_trade
+
+        equity + ((close_price - open_trade[:entry_price]) * open_trade[:quantity])
+      end
+
+      def drawdown_pct(equity_curve, current_equity)
+        peak = (equity_curve + [current_equity]).max
+        return 0.0 if peak.nil? || peak.zero?
+
+        [((peak - current_equity) / peak) * 100, 0.0].max
+      end
+    end
+  end
+end

data/lib/DhanHQ/backtest/trade.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Backtest
+    # A single completed long round-trip trade produced by Runner.
+    #
+    # `fees` is the total cost charged across both legs (entry + exit), already
+    # netted into `pnl` — it is not deducted again by callers.
+    Trade = Struct.new(
+      :entry_time, :entry_price, :exit_time, :exit_price, :quantity, :exit_reason, :fees
+    ) do
+      # Net profit/loss for this trade, after fees.
+      #
+      # @return [Float]
+      def pnl
+        ((exit_price - entry_price) * quantity) - fees.to_f
+      end
+
+      # Net profit/loss as a percentage of the entry value.
+      #
+      # @return [Float]
+      def pnl_pct
+        entry_value = entry_price.to_f * quantity.to_f
+        return 0.0 if entry_value.zero?
+
+        (pnl / entry_value) * 100
+      end
+
+      # @return [Boolean] whether this trade closed profitably after fees
+      def win?
+        pnl.positive?
+      end
+    end
+  end
+end

data/lib/DhanHQ/backtest.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Backtesting engine that replays a DhanHQ::Strategy::Base against historical
+  # OHLC data and reports trades, an equity curve, and summary performance stats.
+  #
+  # @example Backtest a strategy against daily candles
+  #   data = DhanHQ::Models::HistoricalData.daily(
+  #     security_id: "1333", exchange_segment: "NSE_EQ",
+  #     instrument: "EQUITY", from_date: "2024-01-01", to_date: "2024-12-31"
+  #   )
+  #   series = DhanHQ::MarketData::OHLCSeries.from_response(data)
+  #
+  #   result = DhanHQ::Backtest::Runner.new(
+  #     strategy: MyStrategy.new,
+  #     data: series,
+  #     initial_capital: 100_000.0
+  #   ).run
+  #
+  #   result.summary #=> { total_return_pct: 12.4, num_trades: 8, win_rate: 62.5, ... }
+  #
+  module Backtest
+  end
+end

data/lib/DhanHQ/concerns/bang_writes.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../write_result"
+
+module DhanHQ
+  module Concerns
+    # Generates bang variants of write methods that raise instead of returning a falsy
+    # value or an {DhanHQ::ErrorObject}.
+    #
+    # Each generated method calls its non-bang counterpart and passes the result through
+    # {DhanHQ::WriteResult.unwrap!}, so the two cannot drift: there is no duplicated
+    # request building, validation or logging. The non-bang methods are untouched, which
+    # is what makes this additive — existing callers keep the return values they were
+    # written against.
+    #
+    # @example
+    #   class Order < BaseModel
+    #     extend DhanHQ::Concerns::BangWrites
+    #
+    #     bang_class_writes :place        # defines Order.place!
+    #     bang_writes :modify, :cancel    # defines #modify! and #cancel!
+    #   end
+    #
+    #   Order.place!(params)   # => Order, or raises DhanHQ::OrderError
+    #   order.cancel!          # => true,  or raises DhanHQ::OrderError
+    module BangWrites
+      # Defines `<name>!` instance methods.
+      #
+      # @param names [Array<Symbol>] Existing instance write methods to wrap.
+      # @param error_class [Class] Exception the generated methods raise.
+      # @return [void]
+      def bang_writes(*names, error_class: DhanHQ::OrderError)
+        names.each { |name| include bang_write_module(name, error_class) }
+      end
+
+      # Defines `<name>!` class methods.
+      #
+      # @param names [Array<Symbol>] Existing class write methods to wrap.
+      # @param error_class [Class] Exception the generated methods raise.
+      # @return [void]
+      def bang_class_writes(*names, error_class: DhanHQ::OrderError)
+        names.each { |name| singleton_class.include bang_write_module(name, error_class) }
+      end
+
+      private
+
+      # Built as a module rather than defined directly, so a hand-written `place!` in
+      # the class body still overrides the generated one and can call `super`.
+      def bang_write_module(name, error_class)
+        Module.new do
+          define_method(:"#{name}!") do |*args, **kwargs, &block|
+            # A caller already using the bang variant does not need a deprecation
+            # notice telling them to use the bang variant.
+            result = DhanHQ::WriteResult.suppressing_deprecation do
+              public_send(name, *args, **kwargs, &block)
+            end
+
+            DhanHQ::WriteResult.unwrap!(
+              result,
+              operation: DhanHQ::WriteResult.operation_label(self, name),
+              error_class: error_class,
+              errors: DhanHQ::WriteResult.errors_from(self)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/concerns/tracked_writes.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../write_result"
+
+module DhanHQ
+  module Concerns
+    # Observes non-bang write methods and reports, once per call site, when one returns
+    # a failure shape that 4.0.0 will change.
+    #
+    # Uses +prepend+ rather than +include+ because these methods are defined directly on
+    # the model classes: an included module sits behind the class in the ancestor chain
+    # and would never be reached. A prepended one sits in front, so +super+ runs the real
+    # method and the result passes through untouched.
+    #
+    # This layer only observes. It never changes a return value, never raises, and goes
+    # quiet once a call site has been migrated to the bang variant.
+    #
+    # @example
+    #   class Order < BaseModel
+    #     extend DhanHQ::Concerns::TrackedWrites
+    #
+    #     track_class_writes :place        # warns when Order.place returns nil
+    #     track_writes :modify, :cancel    # warns when #cancel returns false
+    #   end
+    module TrackedWrites
+      # Observes `<name>` instance methods.
+      #
+      # @param names [Array<Symbol>] Existing instance write methods to observe.
+      # @return [void]
+      def track_writes(*names)
+        names.each { |name| prepend tracking_module(name) }
+      end
+
+      # Observes `<name>` class methods.
+      #
+      # @param names [Array<Symbol>] Existing class write methods to observe.
+      # @return [void]
+      def track_class_writes(*names)
+        names.each { |name| singleton_class.prepend tracking_module(name) }
+      end
+
+      private
+
+      def tracking_module(name)
+        Module.new do
+          define_method(name) do |*args, **kwargs, &block|
+            DhanHQ::WriteResult.report_ambiguous_failure(
+              super(*args, **kwargs, &block),
+              operation: DhanHQ::WriteResult.operation_label(self, name)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/configuration.rb

@@ -60,7 +60,7 @@ module DhanHQ
     # /v2/orders that times out may well have reached the exchange, and retrying it
     # can place a second, duplicate order. With this off, the transient error is
     # raised to the caller, who can reconcile using the correlation id (see
-    # {#auto_correlation_id} and +DhanHQ::Models::Order.find_by_correlation_id+)
+    # {#auto_correlation_id} and +DhanHQ::Models::Order.find_by_correlation+)
     # before deciding to resubmit.
     #
     # Read requests are always retried regardless of this setting.
@@ -69,6 +69,19 @@ module DhanHQ
     # @return [Boolean]
     attr_accessor :retry_non_idempotent_writes
 
+    # Whether to log a deprecation notice, once per call site, when a non-bang write
+    # method reports failure through +nil+, +false+ or a {DhanHQ::ErrorObject}.
+    #
+    # Those contracts disagree today and will unify on {DhanHQ::ErrorObject} in 4.0.0,
+    # which is truthy — so an `if result` failure branch written against +nil+ or
+    # +false+ will silently invert. The notice names the call sites that need moving to
+    # a bang variant before then.
+    #
+    # Defaults to +true+: a notice nobody sees finds nothing. Set to +false+ once the
+    # call sites are migrated, or via +DHAN_WARN_AMBIGUOUS_WRITE_FAILURE=false+.
+    # @return [Boolean]
+    attr_accessor :warn_on_ambiguous_write_failure
+
     # Whether to generate a +correlationId+ for order placements that do not carry
     # one. The correlation id is the only way to answer "did my order actually go
     # through?" after a timeout, via GET /v2/orders/external/{correlation-id}.
@@ -119,6 +132,15 @@ module DhanHQ
     # @return [Integer]
     attr_accessor :market_depth_level
 
+    # When true, every raw inbound WebSocket frame (market feed, order updates,
+    # market depth) is logged as a hex dump at debug level before it's parsed.
+    # Off by default -- high volume, and the check happens before any hex
+    # encoding work so there's no cost when disabled.
+    #
+    # Set via +DHAN_WS_DEBUG=true+ or in {DhanHQ.configure}.
+    # @return [Boolean]
+    attr_accessor :ws_debug
+
     # Setters for websocket URLs
     attr_writer :ws_order_url, :ws_market_feed_url, :ws_market_depth_url
 
@@ -175,11 +197,21 @@ module DhanHQ
       @retry_non_idempotent_writes == true
     end
 
+    # @return [Boolean] True when ambiguous write failures should be reported.
+    def warn_on_ambiguous_write_failure?
+      @warn_on_ambiguous_write_failure == true
+    end
+
     # @return [Boolean] True when a correlation id should be generated for orders.
     def auto_correlation_id?
       @auto_correlation_id == true
     end
 
+    # @return [Boolean] True when raw WebSocket frames should be hex-logged.
+    def ws_debug?
+      @ws_debug == true
+    end
+
     # Initializes a new configuration instance with default values.
     #
     # @example
@@ -193,12 +225,14 @@ module DhanHQ
       @dry_run        = env_flag("DHAN_DRY_RUN", default: false)
       @retry_non_idempotent_writes = env_flag("DHAN_RETRY_WRITES", default: false)
       @auto_correlation_id = env_flag("DHAN_AUTO_CORRELATION_ID", default: false)
+      @warn_on_ambiguous_write_failure = env_flag("DHAN_WARN_AMBIGUOUS_WRITE_FAILURE", default: true)
       @base_url       = ENV.fetch("DHAN_BASE_URL", nil)
       @ws_version     = ENV.fetch("DHAN_WS_VERSION", 2).to_i
       @ws_order_url = ENV.fetch("DHAN_WS_ORDER_URL", nil)
       @ws_market_feed_url = ENV.fetch("DHAN_WS_MARKET_FEED_URL", nil)
       @ws_market_depth_url = ENV.fetch("DHAN_WS_MARKET_DEPTH_URL", nil)
       @market_depth_level = ENV.fetch("DHAN_MARKET_DEPTH_LEVEL", "20").to_i
+      @ws_debug       = env_flag("DHAN_WS_DEBUG", default: false)
       @ws_user_type   = ENV.fetch("DHAN_WS_USER_TYPE", "SELF")
       @partner_id     = ENV.fetch("DHAN_PARTNER_ID", nil)
       @partner_secret = ENV.fetch("DHAN_PARTNER_SECRET", nil)

data/lib/DhanHQ/core/base_model.rb

@@ -193,19 +193,12 @@ module DhanHQ
     # @return [DhanHQ::BaseModel]
     # @raise [DhanHQ::Error] When the record cannot be saved.
     def save!
-      result = save
-      return result unless result == false || result.nil? || result.is_a?(DhanHQ::ErrorObject)
-
-      error_details =
-        if result.is_a?(DhanHQ::ErrorObject)
-          result.errors
-        elsif @errors && !@errors.empty?
-          @errors
-        else
-          "Unknown error"
-        end
-
-      raise DhanHQ::Error, "Failed to save the record: #{error_details}"
+      DhanHQ::WriteResult.unwrap!(
+        save,
+        operation: "#{self.class}#save",
+        error_class: DhanHQ::Error,
+        errors: @errors
+      )
     end
 
     # Delete the resource

data/lib/DhanHQ/deprecation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  # Emits a deprecation notice once per call site per process.
+  #
+  # A trading process can reject hundreds of orders in a session. A notice that fires
+  # on every one of them is noise that gets filtered out, which defeats the purpose —
+  # the point is for a maintainer to find the handful of call sites still relying on
+  # behaviour that is going to change, then fix them.
+  module Deprecation
+    @warned = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Logs +message+ the first time this +key+ is seen in this process.
+      #
+      # A command, not a query: callers that need to know whether a notice was emitted
+      # should consult {.warned_keys}.
+      #
+      # @param key [String, Symbol] Identifies the call site, e.g. the operation name.
+      # @param message [String] What is deprecated and what to do instead.
+      # @return [void]
+      def warn_once(key, message)
+        return unless first_warning_for?(key)
+
+        DhanHQ.logger&.warn("[DhanHQ] DEPRECATION: #{message}")
+        nil
+      end
+
+      # Keys already warned about, for assertions and diagnostics.
+      #
+      # @return [Array<String>]
+      def warned_keys
+        @mutex.synchronize { @warned.keys }
+      end
+
+      # Forgets every emitted notice, so the next occurrence warns again.
+      # Intended for test isolation.
+      #
+      # @return [void]
+      def reset!
+        @mutex.synchronize { @warned.clear }
+      end
+
+      private
+
+      # Whether this is the first time +key+ has been seen, recording it either way.
+      #
+      # The check and the record happen under one lock so two threads hitting the same
+      # call site at once cannot both decide they are first.
+      #
+      # @return [Boolean]
+      def first_warning_for?(key)
+        @mutex.synchronize do
+          next false if @warned.key?(key.to_s)
+
+          @warned[key.to_s] = true
+        end
+      end
+    end
+  end
+end

data/lib/DhanHQ/jobs/place_order_job.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DhanHQ
+  module Jobs
+    # Places a Dhan order via ActiveJob, without ever letting a queue adapter
+    # (Sidekiq, Resque, ...) retry it.
+    #
+    # DhanHQ order writes are not idempotent -- a timed-out POST /v2/orders may
+    # already have reached the exchange, so retrying it can place a duplicate
+    # order (see the README's "Order Retries and Duplicate Protection"). Most
+    # adapters retry unhandled exceptions at the backend level by default
+    # (Sidekiq's own retry, independent of ActiveJob's opt-in `retry_on`), so
+    # the only adapter-agnostic way to guarantee this write is never silently
+    # retried is to make sure the exception never reaches the adapter at all.
+    # `discard_on` does exactly that: it's handled inside ActiveJob's own
+    # `execute`, so from the adapter's point of view the job completed, not
+    # failed -- there is nothing left for the adapter's own retry logic to
+    # act on.
+    #
+    # @example
+    #   DhanHQ::Jobs::PlaceOrderJob.perform_later(
+    #     transaction_type: DhanHQ::Constants::TransactionType::BUY,
+    #     exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+    #     product_type:     DhanHQ::Constants::ProductType::INTRADAY,
+    #     order_type:       DhanHQ::Constants::OrderType::LIMIT,
+    #     validity:         DhanHQ::Constants::Validity::DAY,
+    #     security_id:      "11536",
+    #     quantity:         5,
+    #     price:            1500.0
+    #   )
+    class PlaceOrderJob < ActiveJob::Base
+      discard_on DhanHQ::OrderError do |_job, error|
+        DhanHQ.logger&.error("[DhanHQ::Jobs::PlaceOrderJob] order rejected: #{error.message}")
+      end
+
+      discard_on DhanHQ::RiskViolation do |_job, error|
+        DhanHQ.logger&.warn("[DhanHQ::Jobs::PlaceOrderJob] risk check blocked the order: #{error.message}")
+      end
+
+      # @param params [Hash] Same params accepted by DhanHQ::Models::Order.place.
+      # @return [DhanHQ::Models::Order]
+      def perform(params)
+        DhanHQ::Models::Order.place!(params)
+      end
+    end
+  end
+end

data/lib/DhanHQ/models/alert_order.rb

@@ -6,6 +6,13 @@ module DhanHQ
   module Models
     # Model for alert/conditional orders. CRUD via AlertOrders resource; validated by AlertOrderContract.
     class AlertOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create, :modify
+
+      bang_class_writes :create, :modify
+
       include Concerns::ApiResponseHandler
 
       HTTP_PATH = "/v2/alerts/orders"

data/lib/DhanHQ/models/forever_order.rb

@@ -66,6 +66,15 @@ module DhanHQ
     #   orders.each { |order| puts order.order_status }
     #
     class ForeverOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :create
+      bang_writes :modify, :cancel
+
       include Concerns::ApiResponseHandler
 
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,

data/lib/DhanHQ/models/global_stocks/order.rb

@@ -36,6 +36,15 @@ module DhanHQ
       #   end
       #
       class Order < BaseModel
+        extend DhanHQ::Concerns::BangWrites
+        extend DhanHQ::Concerns::TrackedWrites
+
+        track_class_writes :place
+        track_writes :modify, :cancel
+
+        bang_class_writes :place
+        bang_writes :modify, :cancel
+
         HTTP_PATH = "/v2/globalstocks/orders"
 
         attributes :dhan_client_id, :order_id, :exchange_order_id, :correlation_id,

data/lib/DhanHQ/models/iceberg_order.rb

@@ -48,6 +48,15 @@ module DhanHQ
     #   orders = DhanHQ::Models::IcebergOrder.all
     #
     class IcebergOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :create
+      bang_writes :modify, :cancel
+
       include Concerns::ApiResponseHandler
 
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,

data/lib/DhanHQ/models/multi_order.rb

@@ -26,6 +26,13 @@ module DhanHQ
     #   result.for_sequence("1").order_id
     #
     class MultiOrder < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :place
+
+      bang_class_writes :place
+
       HTTP_PATH = "/v2/alerts/multi/orders"
 
       attributes :orders

data/lib/DhanHQ/models/order.rb

@@ -46,6 +46,15 @@ module DhanHQ
     #   puts "Pending orders: #{pending_orders.count}"
     #
     class Order < BaseModel
+      extend DhanHQ::Concerns::BangWrites
+      extend DhanHQ::Concerns::TrackedWrites
+
+      track_class_writes :place, :create
+      track_writes :modify, :cancel
+
+      bang_class_writes :place, :create
+      bang_writes :modify, :cancel, :refresh
+
       include Concerns::ApiResponseHandler
 
       # Attributes eligible for modification requests.
@@ -430,6 +439,25 @@ module DhanHQ
           order.save # calls resource create or update
           order
         end
+
+        # `create` always returns the built `Order`, even when `#save` returned
+        # `false` -- existing callers rely on that to inspect an unsaved order's
+        # `errors`, so `create` cannot change. The generated `create!` would
+        # therefore call `unwrap!` on an object that is truthy regardless of
+        # whether the placement actually succeeded, and never raise. This
+        # hand-written override supersedes it (see {BangWrites} for why a
+        # class-body definition takes precedence) and unwraps on `persisted?`
+        # instead, which reflects whether the API actually accepted the order.
+        def create!(params)
+          order = DhanHQ::WriteResult.suppressing_deprecation { create(params) }
+
+          DhanHQ::WriteResult.unwrap!(
+            order.persisted? ? order : false,
+            operation: DhanHQ::WriteResult.operation_label(self, :create),
+            error_class: DhanHQ::OrderError,
+            errors: DhanHQ::WriteResult.errors_from(order)
+          )
+        end
       end
 
       ##