DhanHQ 2.1.7 → 2.1.10

data/lib/DhanHQ/models/position.rb

@@ -2,7 +2,36 @@
 
 module DhanHQ
   module Models
-    # Model representing an intraday or carry-forward position snapshot.
+    ##
+    # Model for managing intraday and carry-forward positions.
+    #
+    # The Positions API lets you retrieve a list of all open positions for the day.
+    # This includes all F&O carryforward positions as well. You can also convert
+    # positions between product types (e.g., intraday to delivery or vice versa).
+    #
+    # @example Fetch all positions
+    #   positions = DhanHQ::Models::Position.all
+    #   positions.each do |position|
+    #     puts "#{position.trading_symbol}: #{position.net_qty} @ ₹#{position.buy_avg}"
+    #     puts "Unrealized P&L: ₹#{position.unrealized_profit}"
+    #   end
+    #
+    # @example Fetch only active (open) positions
+    #   open_positions = DhanHQ::Models::Position.active
+    #   long_positions = open_positions.select { |p| p.position_type == "LONG" }
+    #   puts "Open long positions: #{long_positions.count}"
+    #
+    # @example Convert intraday position to delivery
+    #   response = DhanHQ::Models::Position.convert(
+    #     dhan_client_id: "1000000009",
+    #     from_product_type: "INTRADAY",
+    #     to_product_type: "CNC",
+    #     exchange_segment: "NSE_EQ",
+    #     position_type: "LONG",
+    #     security_id: "11536",
+    #     convert_qty: 40
+    #   )
+    #
     class Position < BaseModel
       # Base path used by the positions resource.
       HTTP_PATH = "/v2/positions"
@@ -17,17 +46,68 @@ module DhanHQ
 
       class << self
         ##
-        # Provides a **shared instance** of the `Positions` resource.
+        # Provides a shared instance of the Positions resource.
         #
-        # @return [DhanHQ::Resources::Positions]
+        # @return [DhanHQ::Resources::Positions] The Positions resource client instance
         def resource
           @resource ||= DhanHQ::Resources::Positions.new
         end
 
         ##
-        # Fetch all positions for the day.
+        # Retrieves all positions for the current trading day.
+        #
+        # Fetches a list of all open positions including F&O carryforward positions.
+        # Returns both active (LONG/SHORT) and closed positions. Use {active} if you
+        # only need open positions.
+        #
+        # @return [Array<Position>] Array of Position objects. Returns empty array if no positions exist.
+        #   Each Position object contains (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:trading_symbol** [String] Trading symbol of the instrument
+        #   - **:security_id** [String] Exchange standard ID for each scrip
+        #   - **:position_type** [String] Position type. Valid values: "LONG", "SHORT", "CLOSED"
+        #   - **:exchange_segment** [String] Exchange and segment.
+        #     Valid values: "NSE_EQ", "NSE_FNO", "NSE_CURRENCY", "BSE_EQ", "BSE_FNO",
+        #     "BSE_CURRENCY", "MCX_COMM"
+        #   - **:product_type** [String] Product type. Valid values: "CNC", "INTRADAY",
+        #     "MARGIN", "MTF", "CO", "BO"
+        #   - **:buy_avg** [Float] Average buy price mark to market
+        #   - **:buy_qty** [Integer] Total quantity bought
+        #   - **:cost_price** [Float] Actual cost price
+        #   - **:sell_avg** [Float] Average sell price mark to market
+        #   - **:sell_qty** [Integer] Total quantities sold
+        #   - **:net_qty** [Integer] Net quantity (buy_qty - sell_qty)
+        #   - **:realized_profit** [Float] Profit or loss booked
+        #   - **:unrealized_profit** [Float] Profit or loss standing for open position
+        #   - **:rbi_reference_rate** [Float] RBI mandated reference rate for forex
+        #   - **:multiplier** [Integer] Multiplying factor for currency F&O
+        #   - **:carry_forward_buy_qty** [Integer] Carry forward F&O long quantities
+        #   - **:carry_forward_sell_qty** [Integer] Carry forward F&O short quantities
+        #   - **:carry_forward_buy_value** [Float] Carry forward F&O long value
+        #   - **:carry_forward_sell_value** [Float] Carry forward F&O short value
+        #   - **:day_buy_qty** [Integer] Quantities bought today
+        #   - **:day_sell_qty** [Integer] Quantities sold today
+        #   - **:day_buy_value** [Float] Value of quantities bought today
+        #   - **:day_sell_value** [Float] Value of quantities sold today
+        #   - **:drv_expiry_date** [String] For F&O, expiry date of contract (format: "YYYY-MM-DD")
+        #   - **:drv_option_type** [String, nil] Type of Option. "CALL" or "PUT"
+        #   - **:drv_strike_price** [Float] For Options, Strike Price
+        #   - **:cross_currency** [Boolean] Check for non INR currency pair
+        #
+        # @example Fetch and analyze positions
+        #   positions = DhanHQ::Models::Position.all
+        #   total_unrealized = positions.sum(&:unrealized_profit)
+        #   total_realized = positions.sum(&:realized_profit)
+        #   puts "Total Unrealized P&L: ₹#{total_unrealized}"
+        #   puts "Total Realized P&L: ₹#{total_realized}"
+        #
+        # @example Analyze F&O positions
+        #   positions = DhanHQ::Models::Position.all
+        #   fno_positions = positions.select { |p| p.exchange_segment.include?("FNO") }
+        #   fno_positions.each do |pos|
+        #     puts "#{pos.trading_symbol} - Net: #{pos.net_qty}, P&L: ₹#{pos.unrealized_profit}"
+        #   end
         #
-        # @return [Array<Position>]
         def all
           response = resource.all
           return [] unless response.is_a?(Array)
@@ -37,16 +117,87 @@ module DhanHQ
           end
         end
 
-        # Filters the position list down to non-closed entries.
+        ##
+        # Filters the position list to return only active (open) positions.
+        #
+        # Removes positions with "CLOSED" status, returning only positions that are
+        # currently open (LONG or SHORT positions).
+        #
+        # @return [Array<Position>] Array of active Position objects. Excludes positions
+        #   with position_type "CLOSED"
+        #
+        # @example Fetch only open positions
+        #   open_positions = DhanHQ::Models::Position.active
+        #   puts "Open positions: #{open_positions.count}"
+        #   open_positions.each do |position|
+        #     puts "#{position.trading_symbol}: #{position.net_qty} (#{position.position_type})"
+        #   end
+        #
+        # @example Calculate total open position value
+        #   open_positions = DhanHQ::Models::Position.active
+        #   total_value = open_positions.sum { |p| p.net_qty * p.buy_avg }
+        #   puts "Total open position value: ₹#{total_value}"
         #
-        # @return [Array<Position>]
         def active
           all.reject { |position| position.position_type == "CLOSED" }
         end
 
-        # Convert an existing position (intraday <-> delivery)
-        # @param params [Hash] parameters as required by the API
-        # @return [Hash, DhanHQ::ErrorObject]
+        ##
+        # Converts an existing position from one product type to another.
+        #
+        # Allows conversion between eligible product types, most commonly between intraday
+        # (INTRADAY) and delivery (CNC) positions. This is useful when you want to hold
+        # an intraday position overnight or convert a delivery position to intraday.
+        #
+        # @param params [Hash{Symbol => String, Integer}] Position conversion parameters
+        #   @option params [String] :dhan_client_id (required) User-specific identification generated by Dhan.
+        #     Must be explicitly provided in the params hash
+        #   @option params [String] :from_product_type (required) Current product type of the position.
+        #     Valid values: "CNC", "INTRADAY", "MARGIN", "CO", "BO"
+        #   @option params [String] :to_product_type (required) Desired product type after conversion.
+        #     Valid values: "CNC", "INTRADAY", "MARGIN", "CO", "BO"
+        #     Must be different from from_product_type
+        #   @option params [String] :exchange_segment (required) Exchange and segment in which position is created.
+        #     Valid values: See {DhanHQ::Constants::EXCHANGE_SEGMENTS}
+        #   @option params [String] :position_type (required) Position type to convert.
+        #     Valid values: "LONG", "SHORT", "CLOSED"
+        #   @option params [String] :security_id (required) Exchange standard ID for each scrip
+        #   @option params [String] :trading_symbol (optional) Trading symbol of the instrument
+        #   @option params [Integer] :convert_qty (required) Number of shares for which conversion is desired.
+        #     Must be greater than 0
+        #
+        # @return [Hash, DhanHQ::ErrorObject] API response hash (typically HTTP 202 Accepted) on success,
+        #   ErrorObject on failure
+        #
+        # @example Convert intraday position to delivery
+        #   response = DhanHQ::Models::Position.convert(
+        #     dhan_client_id: "1000000009",
+        #     from_product_type: "INTRADAY",
+        #     to_product_type: "CNC",
+        #     exchange_segment: "NSE_EQ",
+        #     position_type: "LONG",
+        #     security_id: "11536",
+        #     convert_qty: 40
+        #   )
+        #   if response.is_a?(DhanHQ::ErrorObject)
+        #     puts "Conversion failed: #{response.errors}"
+        #   else
+        #     puts "Position converted successfully"
+        #   end
+        #
+        # @example Convert delivery position to intraday
+        #   response = DhanHQ::Models::Position.convert(
+        #     dhan_client_id: "1000000009",
+        #     from_product_type: "CNC",
+        #     to_product_type: "INTRADAY",
+        #     exchange_segment: "NSE_EQ",
+        #     position_type: "LONG",
+        #     security_id: "11536",
+        #     convert_qty: 10
+        #   )
+        #
+        # @raise [DhanHQ::ValidationError] If validation fails for any parameter
+        # @note The API returns HTTP 202 Accepted on successful conversion
         def convert(params)
           formatted_params = camelize_keys(params)
           validate_params!(formatted_params, DhanHQ::Contracts::PositionConversionContract)

data/lib/DhanHQ/models/profile.rb

@@ -3,8 +3,42 @@
 module DhanHQ
   module Models
     ##
-    # Ruby wrapper around the `/v2/profile` endpoint. Provides typed accessors
-    # and snake_case keys while leaving the underlying response untouched.
+    # Model for retrieving authenticated user profile and account information.
+    #
+    # The User Profile API can be used to check the validity of access token and account setup.
+    # It is a simple GET request and serves as a great test API to start integration with DhanHQ.
+    # The profile contains account-level metadata including token validity, active segments,
+    # DDPI status, MTF consent, and Data API subscription status.
+    #
+    # @example Fetch user profile to verify token validity
+    #   profile = DhanHQ::Models::Profile.fetch
+    #   if profile
+    #     puts "Client ID: #{profile.dhan_client_id}"
+    #     puts "Token Valid Until: #{profile.token_validity}"
+    #     puts "Active Segments: #{profile.active_segment}"
+    #     puts "DDPI: #{profile.ddpi}"
+    #     puts "MTF: #{profile.mtf}"
+    #     puts "Data Plan: #{profile.data_plan}"
+    #   end
+    #
+    # @example Check account status
+    #   profile = DhanHQ::Models::Profile.fetch
+    #   if profile
+    #     if profile.ddpi == "Active" && profile.mtf == "Active"
+    #       puts "Account is fully active"
+    #     else
+    #       puts "Some features may be inactive"
+    #     end
+    #   end
+    #
+    # @example Verify data API subscription
+    #   profile = DhanHQ::Models::Profile.fetch
+    #   if profile && profile.data_plan == "Active"
+    #     puts "Data API subscription is active until: #{profile.data_validity}"
+    #   else
+    #     puts "Data API subscription is not active"
+    #   end
+    #
     class Profile < BaseModel
       # Base path for profile retrieval.
       HTTP_PATH = "/v2/profile"
@@ -14,17 +48,73 @@ module DhanHQ
 
       class << self
         ##
-        # Provides a shared instance of the profile resource.
+        # Provides a shared instance of the Profile resource.
         #
-        # @return [DhanHQ::Resources::Profile]
+        # @return [DhanHQ::Resources::Profile] The Profile resource client instance
         def resource
           @resource ||= DhanHQ::Resources::Profile.new
         end
 
         ##
-        # Fetch the authenticated user's profile details.
+        # Fetches the authenticated user's profile details and account information.
+        #
+        # Retrieves account-level metadata including token validity, active segments,
+        # DDPI status, MTF consent status, and Data API subscription status. This is a
+        # simple GET request that serves as a great test API to verify your access token
+        # and account setup before starting integration.
+        #
+        # @return [Profile, nil] Profile object with account details if fetch succeeds, nil otherwise.
+        #   Response structure (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:token_validity** [String] Validity date and time for access token.
+        #     Format: "DD/MM/YYYY HH:MM" (e.g., "30/03/2025 15:37")
+        #   - **:active_segment** [String] All active segments in user account.
+        #     Comma-separated list (e.g., "Equity, Derivative, Currency, Commodity")
+        #   - **:ddpi** [String] DDPI (Demat Debit Power of Attorney) status of the user.
+        #     Valid values: "Active", "Deactive"
+        #   - **:mtf** [String] MTF (Margin Trading Facility) consent status of the user.
+        #     Valid values: "Active", "Deactive"
+        #   - **:data_plan** [String] Data API subscription status.
+        #     Valid values: "Active", "Deactive"
+        #   - **:data_validity** [String] Validity date and time for Data API Subscription.
+        #     Format: "YYYY-MM-DD HH:MM:SS.S" (e.g., "2024-12-05 09:37:52.0")
+        #
+        # @example Fetch profile to verify integration
+        #   profile = DhanHQ::Models::Profile.fetch
+        #   if profile
+        #     puts "✓ Access token is valid"
+        #     puts "✓ Account setup complete"
+        #     puts "Client ID: #{profile.dhan_client_id}"
+        #   else
+        #     puts "✗ Failed to fetch profile - check access token"
+        #   end
+        #
+        # @example Check account features
+        #   profile = DhanHQ::Models::Profile.fetch
+        #   if profile
+        #     puts "Token valid until: #{profile.token_validity}"
+        #     puts "Active segments: #{profile.active_segment}"
+        #     puts "DDPI: #{profile.ddpi}"
+        #     puts "MTF: #{profile.mtf}"
+        #     puts "Data Plan: #{profile.data_plan}"
+        #     if profile.data_plan == "Active"
+        #       puts "Data API valid until: #{profile.data_validity}"
+        #     end
+        #   end
+        #
+        # @example Verify account is ready for trading
+        #   profile = DhanHQ::Models::Profile.fetch
+        #   if profile
+        #     ready = profile.ddpi == "Active" && profile.mtf == "Active"
+        #     if ready
+        #       puts "Account is ready for trading"
+        #     else
+        #       puts "Account may have restrictions:"
+        #       puts "  DDPI: #{profile.ddpi}"
+        #       puts "  MTF: #{profile.mtf}"
+        #     end
+        #   end
         #
-        # @return [DhanHQ::Models::Profile, nil]
         def fetch
           response = resource.fetch
           return nil unless response.is_a?(Hash)
@@ -33,9 +123,15 @@ module DhanHQ
         end
       end
 
+      ##
       # Profile responses are informational and not validated locally.
       #
-      # @return [nil]
+      # Since profile data is read-only account metadata, no validation contract
+      # is needed. The API response is trusted as-is.
+      #
+      # @return [nil] Always returns nil as profiles are read-only and informational
+      #
+      # @api private
       def validation_contract
         nil
       end

data/lib/DhanHQ/models/super_order.rb

@@ -2,7 +2,51 @@
 
 module DhanHQ
   module Models
-    # Model wrapping multi-leg super order payloads.
+    ##
+    # Model for managing multi-leg super orders with smart execution.
+    #
+    # Super orders are built for smart execution of trades. They are a collection of orders
+    # clubbed into a single order request, which includes an entry leg, target leg, and
+    # stop loss leg along with the option to add trailing stop loss. This allows for
+    # server-side risk management immediately after entry.
+    #
+    # Super orders can be placed across all exchanges and segments, supporting intraday,
+    # carry forward, or MTF orders.
+    #
+    # @note **Static IP Whitelisting**: Super order creation, modification, and cancellation
+    #   APIs require Static IP whitelisting. Ensure your IP is whitelisted before using these endpoints.
+    #
+    # @example Create a super order
+    #   order = DhanHQ::Models::SuperOrder.create(
+    #     dhan_client_id: "1000000003",
+    #     transaction_type: "BUY",
+    #     exchange_segment: "NSE_EQ",
+    #     product_type: "CNC",
+    #     order_type: "LIMIT",
+    #     security_id: "11536",
+    #     quantity: 5,
+    #     price: 1500,
+    #     target_price: 1600,
+    #     stop_loss_price: 1400,
+    #     trailing_jump: 10
+    #   )
+    #   puts "Super Order ID: #{order.order_id} - #{order.order_status}"
+    #
+    # @example Modify a super order
+    #   order = DhanHQ::Models::SuperOrder.all.first
+    #   order.modify(
+    #     leg_name: "ENTRY_LEG",
+    #     price: 1300,
+    #     quantity: 40,
+    #     target_price: 1450,
+    #     stop_loss_price: 1350,
+    #     trailing_jump: 20
+    #   )
+    #
+    # @example Cancel a specific leg
+    #   order = DhanHQ::Models::SuperOrder.all.first
+    #   order.cancel("STOP_LOSS_LEG")
+    #
     class SuperOrder < BaseModel
       attributes :dhan_client_id, :order_id, :correlation_id, :order_status,
                  :transaction_type, :exchange_segment, :product_type, :order_type,
@@ -14,16 +58,78 @@ module DhanHQ
                  :trailing_jump
 
       class << self
-        # Shared resource instance used for API calls.
+        ##
+        # Provides a shared instance of the SuperOrders resource.
         #
-        # @return [DhanHQ::Resources::SuperOrders]
+        # @return [DhanHQ::Resources::SuperOrders] The SuperOrders resource client instance
         def resource
           @resource ||= DhanHQ::Resources::SuperOrders.new
         end
 
-        # Fetches all configured super orders.
+        ##
+        # Retrieves all super orders placed during the current trading day.
+        #
+        # Fetches a special order book that only consists of Super Orders, where the target
+        # and stop loss orders are nested under the main entry order leg. Individual legs of
+        # each super order can also be found in the main order book with their Order ID.
+        #
+        # @return [Array<SuperOrder>] Array of SuperOrder objects. Returns empty array if no orders exist.
+        #   Each SuperOrder object contains (keys normalized to snake_case):
+        #   - **:dhan_client_id** [String] User-specific identification generated by Dhan
+        #   - **:order_id** [String] Order-specific identification generated by Dhan
+        #   - **:correlation_id** [String] User/partner generated ID for tracking
+        #   - **:order_status** [String] Last updated status of the order.
+        #     Valid values: "TRANSIT", "PENDING", "CLOSED", "REJECTED", "CANCELLED",
+        #     "PART_TRADED", "TRADED"
+        #   - **:transaction_type** [String] The trading side of transaction. "BUY" or "SELL"
+        #   - **:exchange_segment** [String] Exchange segment of instrument
+        #   - **:product_type** [String] Product type. Valid values: "CNC", "INTRADAY", "MARGIN", "MTF"
+        #   - **:order_type** [String] Order type. "LIMIT" or "MARKET"
+        #   - **:validity** [String] Validity of order. "DAY"
+        #   - **:trading_symbol** [String] Trading symbol of the instrument
+        #   - **:security_id** [String] Exchange standard ID for each scrip
+        #   - **:quantity** [Integer] Number of shares for the order
+        #   - **:remaining_quantity** [Integer] Quantity pending execution
+        #   - **:ltp** [Float] Last Traded Price of the instrument
+        #   - **:price** [Float] Price at which order is placed
+        #   - **:after_market_order** [Boolean] Whether the order is placed after market
+        #   - **:leg_name** [String] Leg identification. "ENTRY_LEG", "TARGET_LEG", "STOP_LOSS_LEG"
+        #   - **:trailing_jump** [Float] Price jump by which Stop Loss should be trailed
+        #   - **:exchange_order_id** [String] Exchange generated ID for the order
+        #   - **:create_time** [String] Time at which the order is created
+        #   - **:update_time** [String] Last updated time of the order
+        #   - **:exchange_time** [String] Time at which order was sent to the exchange
+        #   - **:oms_error_description** [String] Description of error if the order is rejected or failed
+        #   - **:average_traded_price** [Float] Average price at which order is traded
+        #   - **:filled_qty** [Integer] Quantity of order traded on Exchange
+        #   - **:leg_details** [Array<Hash>] Array of leg details for TARGET_LEG and STOP_LOSS_LEG.
+        #     Each leg detail contains:
+        #     - **:order_id** [String] Order ID of the leg
+        #     - **:leg_name** [String] Leg name ("TARGET_LEG" or "STOP_LOSS_LEG")
+        #     - **:transaction_type** [String] Transaction type of the leg
+        #     - **:total_quatity** [Integer] Total quantity (note: typo in API response)
+        #     - **:remaining_quantity** [Integer] Quantity pending execution
+        #     - **:triggered_quantity** [Integer] Quantity of Stop Loss or Target leg placed on Exchange
+        #     - **:price** [Float] Price of the leg
+        #     - **:order_status** [String] Order status of the leg.
+        #       "TRIGGERED" indicates the leg has been triggered and placed
+        #     - **:trailing_jump** [Float] Trailing jump for the leg
+        #
+        # @note **Order Status**: "CLOSED" is used when the ENTRY_LEG and one of either
+        #   TARGET_LEG or STOP_LOSS_LEG is triggered for entire quantity. "TRIGGERED" status
+        #   is present for TARGET_LEG and STOP_LOSS_LEG indicating which leg is actually triggered.
+        #
+        # @example Fetch and analyze super orders
+        #   orders = DhanHQ::Models::SuperOrder.all
+        #   pending_orders = orders.select { |o| o.order_status == "PENDING" }
+        #   pending_orders.each do |order|
+        #     puts "Order: #{order.order_id}"
+        #     puts "Target: ₹#{order.target_price}, Stop Loss: ₹#{order.stop_loss_price}"
+        #     order.leg_details.each do |leg|
+        #       puts "  #{leg[:leg_name]}: ₹#{leg[:price]} (#{leg[:order_status]})"
+        #     end
+        #   end
         #
-        # @return [Array<SuperOrder>]
         def all
           response = resource.all
           return [] unless response.is_a?(Array)
@@ -31,22 +137,150 @@ module DhanHQ
           response.map { |o| new(o, skip_validation: true) }
         end
 
-        # Creates a new super order with the provided legs.
+        ##
+        # Creates a new super order with entry, target, and stop loss legs.
+        #
+        # Places a super order that combines entry, target, and stop-loss legs into one
+        # atomic instruction. Supports an optional trailing jump for server-side risk
+        # management immediately after entry. Available across all exchanges and segments,
+        # supporting intraday, carry-forward, or MTF orders.
+        #
+        # @param params [Hash{Symbol => String, Integer, Float}] Super order creation parameters
+        #   @option params [String] :dhan_client_id (required) User-specific identification generated by Dhan.
+        #     Must be explicitly provided in the params hash
+        #   @option params [String] :correlation_id (optional) User/partner generated ID for tracking.
+        #     Max length: 25 characters
+        #   @option params [String] :transaction_type (required) The trading side of transaction.
+        #     Valid values: "BUY", "SELL"
+        #   @option params [String] :exchange_segment (required) Exchange segment of instrument.
+        #     Valid values: See {DhanHQ::Constants::EXCHANGE_SEGMENTS}
+        #   @option params [String] :product_type (required) Product type.
+        #     Valid values: "CNC", "INTRADAY", "MARGIN", "MTF"
+        #   @option params [String] :order_type (required) Order type.
+        #     Valid values: "LIMIT", "MARKET"
+        #   @option params [String] :security_id (required) Exchange standard ID for each scrip
+        #   @option params [Integer] :quantity (required) Number of shares for the order. Must be greater than 0
+        #   @option params [Float] :price (required) Price at which order is placed. Must be > 0
+        #   @option params [Float] :target_price (required) Target price for the Super Order. Must be > 0
+        #   @option params [Float] :stop_loss_price (required) Stop loss price for the Super Order. Must be > 0
+        #   @option params [Float] :trailing_jump (required) Price jump by which Stop Loss should be trailed.
+        #     Must be > 0. If set to 0 or omitted, trailing stop loss will be cancelled
+        #
+        # @return [SuperOrder, nil] SuperOrder object with order_id and order_status if creation succeeds,
+        #   nil otherwise.
+        #   Response structure:
+        #   - **:order_id** [String] Order-specific identification generated by Dhan
+        #   - **:order_status** [String] Last updated status of the order.
+        #     Valid values: "TRANSIT", "PENDING", "REJECTED"
+        #
+        # @example Create a super order with all legs
+        #   order = DhanHQ::Models::SuperOrder.create(
+        #     dhan_client_id: "1000000003",
+        #     transaction_type: "BUY",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "CNC",
+        #     order_type: "LIMIT",
+        #     security_id: "11536",
+        #     quantity: 5,
+        #     price: 1500,
+        #     target_price: 1600,
+        #     stop_loss_price: 1400,
+        #     trailing_jump: 10
+        #   )
+        #   puts "Super Order ID: #{order.order_id}"
+        #
+        # @example Create intraday super order
+        #   order = DhanHQ::Models::SuperOrder.create(
+        #     dhan_client_id: "1000000003",
+        #     transaction_type: "SELL",
+        #     exchange_segment: "NSE_EQ",
+        #     product_type: "INTRADAY",
+        #     order_type: "MARKET",
+        #     security_id: "1333",
+        #     quantity: 10,
+        #     price: 2000,
+        #     target_price: 1950,
+        #     stop_loss_price: 2050,
+        #     trailing_jump: 20
+        #   )
         #
-        # @param params [Hash]
-        # @return [SuperOrder, nil]
         def create(params)
-          response = resource.create(params)
+          # Normalize params and auto-inject dhan_client_id from configuration if not provided
+          normalized_params = snake_case(params)
+          normalized_params[:dhan_client_id] ||= DhanHQ.configuration.client_id if DhanHQ.configuration.client_id
+          response = resource.create(normalized_params)
           return nil unless response.is_a?(Hash) && response["orderId"]
 
           new(order_id: response["orderId"], order_status: response["orderStatus"], skip_validation: true)
         end
       end
 
-      # Updates the order legs for an existing super order.
+      ##
+      # Modifies any leg of a Super Order while it is in PENDING or PART_TRADED state.
+      #
+      # The ENTRY_LEG can modify the entire super order and can only be modified when
+      # the order status is PENDING or PART_TRADED. Once the entry order status is TRADED,
+      # only TARGET_LEG and STOP_LOSS_LEG price and trail jump can be modified.
+      #
+      # @param new_params [Hash{Symbol => String, Integer, Float}] Fields to modify
+      #   @option new_params [String] :dhan_client_id (required) User-specific identification generated by Dhan.
+      #     Must be explicitly provided in the params hash
+      #   @option new_params [String] :order_id (required) Order-specific identification generated by Dhan
+      #   @option new_params [String] :leg_name (required) Leg to modify.
+      #     Valid values:
+      #     - "ENTRY_LEG" - Entire Super Order can be modified, only when main order status
+      #       is "PENDING" or "PART_TRADED"
+      #     - "TARGET_LEG" - Target leg can be modified
+      #     - "STOP_LOSS_LEG" - Stop loss leg can be modified
+      #   @option new_params [String] :order_type (conditionally required) Order type.
+      #     Required for ENTRY_LEG. Valid values: "LIMIT", "MARKET"
+      #   @option new_params [Integer] :quantity (conditionally required) Quantity to be modified.
+      #     Required for ENTRY_LEG
+      #   @option new_params [Float] :price (conditionally required) Price to be modified.
+      #     Required for ENTRY_LEG
+      #   @option new_params [Float] :target_price (conditionally required) Target price to be modified.
+      #     Required for ENTRY_LEG or TARGET_LEG
+      #   @option new_params [Float] :stop_loss_price (conditionally required) Stop loss price to be modified.
+      #     Required for ENTRY_LEG or STOP_LOSS_LEG
+      #   @option new_params [Float] :trailing_jump (conditionally required) Stop loss price jump to be modified.
+      #     Required for ENTRY_LEG or STOP_LOSS_LEG. If set to 0 or not provided, trailing stop loss will be cancelled
       #
-      # @param new_params [Hash]
-      # @return [Boolean]
+      # @return [Boolean] true if modification succeeds (orderId matches), false otherwise
+      #
+      # @example Modify entry leg
+      #   order = DhanHQ::Models::SuperOrder.all.first
+      #   order.modify(
+      #     dhan_client_id: "1000000009",
+      #     order_id: order.order_id,
+      #     leg_name: "ENTRY_LEG",
+      #     order_type: "LIMIT",
+      #     quantity: 40,
+      #     price: 1300,
+      #     target_price: 1450,
+      #     stop_loss_price: 1350,
+      #     trailing_jump: 20
+      #   )
+      #
+      # @example Modify only target leg (after entry is traded)
+      #   order = DhanHQ::Models::SuperOrder.all.first
+      #   order.modify(
+      #     dhan_client_id: "1000000009",
+      #     order_id: order.order_id,
+      #     leg_name: "TARGET_LEG",
+      #     target_price: 1550
+      #   )
+      #
+      # @example Modify stop loss with trailing jump
+      #   order = DhanHQ::Models::SuperOrder.all.first
+      #   order.modify(
+      #     dhan_client_id: "1000000009",
+      #     order_id: order.order_id,
+      #     leg_name: "STOP_LOSS_LEG",
+      #     stop_loss_price: 1250,
+      #     trailing_jump: 15
+      #   )
+      #
+      # @raise [RuntimeError] If order ID is missing
       def modify(new_params)
         raise "Order ID is required to modify a super order" unless id
 
@@ -54,10 +288,36 @@ module DhanHQ
         response["orderId"] == id
       end
 
-      # Cancels a specific leg (or the entry leg by default).
+      ##
+      # Cancels a specific leg of a super order, or the entry leg by default.
+      #
+      # Cancels a pending/active super order leg using the order ID and leg name.
+      # Cancelling the main entry order ID (ENTRY_LEG) cancels all legs. If a particular
+      # target or stop loss leg is cancelled, it cannot be added again.
+      #
+      # @param leg_name [String] (default: "ENTRY_LEG") Order leg to be cancelled.
+      #   Valid values: "ENTRY_LEG", "TARGET_LEG", "STOP_LOSS_LEG"
+      #
+      # @return [Boolean] true if cancellation succeeds (order status becomes "CANCELLED"),
+      #   false otherwise
+      #
+      # @note The API returns HTTP 202 Accepted on successful cancellation.
+      #
+      # @example Cancel entry leg (cancels entire super order)
+      #   order = DhanHQ::Models::SuperOrder.all.first
+      #   if order.cancel("ENTRY_LEG")
+      #     puts "Super order cancelled successfully"
+      #   end
+      #
+      # @example Cancel only stop loss leg
+      #   order = DhanHQ::Models::SuperOrder.all.first
+      #   order.cancel("STOP_LOSS_LEG")
+      #
+      # @example Cancel only target leg
+      #   order = DhanHQ::Models::SuperOrder.all.first
+      #   order.cancel("TARGET_LEG")
       #
-      # @param leg_name [String]
-      # @return [Boolean]
+      # @raise [RuntimeError] If order ID is missing
       def cancel(leg_name = "ENTRY_LEG")
         raise "Order ID is required to cancel a super order" unless id