DhanHQ 2.5.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77553eb49e2a23ec764bc3baeebd5426f60054fbdbc4eb4c7c49d7f2c7e87515
-  data.tar.gz: 9fc44cb543abbc725cdee1489c66a08bd5d2615772640b454e46d54fb7b139f3
+  metadata.gz: 30825da308f5f85870f4efe9b702f7e2f653840b396b3265d36383d4a8c56f5e
+  data.tar.gz: b2874edeb45b60b6e68b4d8c69b9e9e3c6a0b6d2734ca645168626afd27cde76
 SHA512:
-  metadata.gz: 47344dfbf5aba9b0c48e05937e3d9ff28d7a43db87442d1e695b84477568d5df02e83c918e884000751f094996e43984000b8f4c32bec235313f64673756b176
-  data.tar.gz: f68c7be56db1807c284e01007cf0003f8519f92d57209d4073686f84e35d36db06e36f151c8b3b3df5dbae59bc272010c7e3ce4898e5a23eeddb5d6162f10b2c
+  metadata.gz: fe803337db74aa9689001b458627a532101fd0d298142b74ed0fefd87e7938ef4fd2b5e75bb53d871d8c535df35347065a43428986d930e6a0fa1ebae0c19aaf
+  data.tar.gz: aae78dbbbea337312262239f083c8fbb96f65b51b2d70cb9dce2683204f5e506d5a0835c85af6766ce0233262e79aaaf5dde45561eb410d51c52c74a185d5184

data/.rubocop.yml

@@ -6,6 +6,7 @@ plugins:
 
 require:
   - rubocop-rake
+  - ./lib/rubocop/cop/dhanhq/use_constants.rb
 
 AllCops:
   TargetRubyVersion: 3.2
@@ -25,4 +26,11 @@ RSpec/ExampleLength:
   Max: 15
 
 RSpec/MultipleMemoizedHelpers:
-  Max: 10
+  Max: 10
+
+DhanHQ/UseConstants:
+  Enabled: true
+  Exclude:
+    - 'lib/DhanHQ/constants.rb'
+    - 'lib/DhanHQ/ws/segments.rb'
+    - 'spec/**/*'

data/CHANGELOG.md

@@ -1,3 +1,67 @@
+## [2.6.0] - 2026-03-06
+
+### Fixed (API docs alignment)
+
+- **Kill Switch**: Manage API now uses query parameter per [dhanhq.co/docs/v2/traders-control](https://dhanhq.co/docs/v2/traders-control/). `Resources::KillSwitch#update(status)` sends `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or `DEACTIVATE`) with no body. `Models::KillSwitch.update("ACTIVATE")` / `.activate` / `.deactivate` unchanged.
+- **IP Setup**: Set/Modify now send required API fields. `Resources::IPSetup#set` and `#update` accept `ip:`, `ip_flag: "PRIMARY"` (or `"SECONDARY"`), and optional `dhan_client_id:` (defaults from `DhanHQ.configuration.client_id`). See [dhanhq.co/docs/v2/authentication/#setup-static-ip](https://dhanhq.co/docs/v2/authentication/#setup-static-ip).
+- **Alert Orders (Conditional Trigger)**: Condition now requires `exchange_segment`, `exp_date`, and `frequency` per [dhanhq.co/docs/v2/conditional-trigger](https://dhanhq.co/docs/v2/conditional-trigger/). `time_frame` is required when `comparison_type` starts with `TECHNICAL`. `AlertOrderContract` and all examples updated.
+
+### Breaking changes
+
+- **AlertOrder.create / AlertOrderContract**: Contract expects nested structure (see 2.5.0). Condition hash must include `exchange_segment`, `exp_date`, and `frequency`; for `comparison_type` starting with `TECHNICAL`, `time_frame` is required. See GUIDE.md and [conditional-trigger](https://dhanhq.co/docs/v2/conditional-trigger/).
+- **Resources::KillSwitch#update**: Signature is now `update(status)` (string). Use `update("ACTIVATE")` or `Models::KillSwitch.activate` / `.deactivate`, unchanged.
+- **AlertOrderContract** — expected payload shape:
+
+```ruby
+AlertOrderContract.new.call(
+  condition: {
+    exchange_segment:  "NSE_EQ",
+    security_id:       "11536",
+    comparison_type:   "PRICE_WITH_VALUE",
+    operator:          "GREATER_THAN",
+    exp_date:          "2026-12-31",
+    frequency:         "ONCE"
+  },
+  orders: [
+    { transaction_type: "BUY", exchange_segment: "NSE_EQ", product_type: "INTRADAY", order_type: "MARKET", security_id: "11536", quantity: 5, validity: "DAY" }
+  ]
+)
+```
+
+### Added
+
+#### Order Model — New Public Methods
+- **`Order#destroy` / `#delete`**: Cancels an order via `DELETE /v2/orders/{id}`. Returns `true` if the API confirms `CANCELLED` status, `false` otherwise. `#delete` is an alias.
+- **`Order#slice_order(params)`**: Splits a large order into multiple legs to exceed freeze-limit quantities on F&O instruments via `POST /v2/slicing`. Delegates to `Resources::Orders#slicing`.
+- **`Order#save`**: ActiveRecord-style save — places a new order for new records, modifies existing records. Returns `true`/`false`.
+- **`Order.place` — `dhan_client_id` auto-injection**: If `dhan_client_id` is not passed in params, it is automatically read from `DhanHQ.configuration.client_id`. Existing code that passes `dhan_client_id` explicitly continues to work unchanged.
+
+#### Contract Hardening
+- **`OrderContract`** (base for `PlaceOrderContract` and `ModifyOrderContract`) now enforces:
+  - `LIMIT` orders require `price`; `MARKET` orders reject `price`
+  - `STOP_LOSS` / `STOP_LOSS_MARKET` require `trigger_price`
+  - Stop-loss price relationships: BUY requires `trigger_price >= price`; SELL requires `trigger_price <= price`
+  - Bracket Order (BO): both `bo_profit_value` and `bo_stop_loss_value` required; directional profit/loss relationship validated
+  - `disclosed_quantity` cannot exceed 30% of `quantity`
+  - `amo_time` required when `after_market_order: true`
+  - Lot-size and tick-size enforcement when `instrument_meta` is provided
+  - Segment-based product restrictions (CNC equity-only, BO/CO currency restrictions)
+- **`ModifyOrderContract`**: Requires at least one modifiable field; inherits all `OrderContract` business rules.
+- **New contracts**: `EdisContract`, `UserIpContract`, `PnlBasedExitContract`, `MultiScripMarginCalcContract`, `SliceOrderContract`.
+
+#### Infrastructure
+- **`ApiResponseHandler` concern** (`lib/DhanHQ/models/concerns/api_response_handler.rb`): Shared module for uniform API response handling, attribute merging, and structured logging. Included in `Order` and `ForeverOrder`.
+- **Global Constants Enforcement**: Replaced all hardcoded API strings with `DhanHQ::Constants` across the repository. Built a custom RuboCop cop (`RuboCop::Cop::DhanHQ::UseConstants`) that strictly enforces typed constants instead of loose strings for robust API payloads.
+- **Constants Documentation**: Added `docs/CONSTANTS_REFERENCE.md` detailing all SDK constants (e.g., `ExchangeSegment`, `ProductType`, `OrderType`, etc.).
+
+### Changed
+- Replaced 160+ hardcoded usages of strings like `"NSE_EQ"` and `"BUY"` with `DhanHQ::Constants::ExchangeSegment::NSE_EQ` and `DhanHQ::Constants::TransactionType::BUY`.
+- Added `NO_HOLDINGS` (value `"DH-1111"`) to `TradingErrorCode`.
+- `PlaceOrderContract` refactored to inherit from `OrderContract`, eliminating duplicated validation logic. Derivative-specific fields (`drv_expiry_date`, `drv_option_type`, `drv_strike_price`) remain on `PlaceOrderContract`.
+- `Resources::Orders` now fetches optional instrument metadata (lot size, tick size) to pass into contract validation.
+
+---
+
 ## [2.5.0] - 2026-02-21
 
 ### Added
@@ -55,7 +119,7 @@
 
 ### Added
 - **Alert Orders**: `DhanHQ::Resources::AlertOrders` (BaseResource) and `DhanHQ::Models::AlertOrder` with full CRUD. Endpoints: GET/POST `/alerts/orders`, GET/PUT/DELETE `/alerts/orders/{id}` (per API docs). Validation via `DhanHQ::Contracts::AlertOrderContract`.
-- **IP Setup**: `DhanHQ::Resources::IPSetup` (resource-only). Methods: `current` (GET `/ip/getIP`), `set(ip:)` (POST `/ip/setIP`), `update(ip:)` (PUT `/ip/modifyIP`) per API docs.
+- **IP Setup**: `DhanHQ::Resources::IPSetup` (resource-only). Methods: `current` (GET `/ip/getIP`), `set(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` (POST `/ip/setIP`), `update(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` (PUT `/ip/modifyIP`). Body includes `dhanClientId` (default from config) and `ipFlag` per API docs.
 - **Trader Control (Kill Switch)**: `DhanHQ::Resources::TraderControl` (resource-only). Methods: `status` (GET `/trader-control`), `enable` (POST action ENABLE), `disable` (POST action DISABLE). `DhanHQ::Resources::KillSwitch` and `DhanHQ::Models::KillSwitch` remain for backward compatibility.
 - **docs/API_VERIFICATION.md**: Documents alignment with [dhanhq.co/docs/v2](https://dhanhq.co/docs/v2/) and [api.dhan.co/v2](https://api.dhan.co/v2/#/) for EDIS, Alert Orders, IP Setup.
 
@@ -92,9 +156,9 @@
 - **README.md**: Note under Dynamic access token for RenewToken via `DhanHQ::Auth.renew_token` and that API key/Partner flows are implemented in the app.
 - **GUIDE.md**: “Dynamic access token” section extended with RenewToken (`DhanHQ::Auth.renew_token`) and note that API key/Partner flows are in the app.
 - **docs/TESTING_GUIDE.md**: Optional config comment for RenewToken and pointer to AUTHENTICATION.md (API key/Partner in app).
-- **docs/rails_integration.md**: “Dynamic access token” section extended with RenewToken (web-generated tokens) and link to AUTHENTICATION.md.
-- **docs/websocket_integration.md**, **docs/live_order_updates.md**: Notes updated for dynamic token, RenewToken, and API key/Partner in app.
-- **docs/standalone_ruby_websocket_integration.md**, **docs/rails_websocket_integration.md**: Configuration section updated with RenewToken and AUTHENTICATION.md link.
+- **docs/RAILS_INTEGRATION.md**: “Dynamic access token” section extended with RenewToken (web-generated tokens) and link to AUTHENTICATION.md.
+- **docs/WEBSOCKET_INTEGRATION.md**, **docs/LIVE_ORDER_UPDATES.md**: Notes updated for dynamic token, RenewToken, and API key/Partner in app.
+- **docs/STANDALONE_RUBY_WEBSOCKET_INTEGRATION.md**, **docs/RAILS_WEBSOCKET_INTEGRATION.md**: Configuration section updated with RenewToken and AUTHENTICATION.md link.
 
 ### CI / Release
 
@@ -144,8 +208,8 @@
 - **GUIDE.md**: Short “Dynamic access token” note and link to docs/AUTHENTICATION.md.
 - **docs/AUTHENTICATION.md**: New doc for static vs dynamic token, retry-on-401, and auth-related errors.
 - **docs/TESTING_GUIDE.md**: Optional access_token_provider / on_token_expired in config examples.
-- **docs/rails_integration.md**: “Dynamic access token (optional)” with Rails initializer example.
-- **docs/websocket_integration.md**, **docs/live_order_updates.md**: Pointer to docs/AUTHENTICATION.md for dynamic token.
+- **docs/RAILS_INTEGRATION.md**: “Dynamic access token (optional)” with Rails initializer example.
+- **docs/WEBSOCKET_INTEGRATION.md**, **docs/LIVE_ORDER_UPDATES.md**: Pointer to docs/AUTHENTICATION.md for dynamic token.
 
 ### Backward compatibility
 

data/GUIDE.md

@@ -150,11 +150,11 @@ Example:
 
 ```ruby
 payload = {
-  transaction_type: "BUY",
-  exchange_segment: "NSE_EQ",
-  product_type: "CNC",
-  order_type: "LIMIT",
-  validity: "DAY",
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  validity: DhanHQ::Constants::Validity::DAY,
   security_id: "1333",
   quantity: 10,
   price: 150.0,
@@ -162,7 +162,7 @@ payload = {
 }
 
 order = DhanHQ::Models::Order.place(payload)
-puts order.order_status  # => "TRADED" / "PENDING" / ...
+puts order.order_status  # => DhanHQ::Constants::OrderStatus::TRADED / "PENDING" / ...
 ```
 
 ### Modification & Cancellation
@@ -193,10 +193,10 @@ Use the same fields as placement, but the contract allows additional validity op
 ```ruby
 slice_payload = {
   order_id: order.order_id,
-  transaction_type: "BUY",
-  exchange_segment: "NSE_EQ",
-  product_type: "STOP_LOSS",
-  order_type: "STOP_LOSS",
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::OrderType::STOP_LOSS,
+  order_type: DhanHQ::Constants::OrderType::STOP_LOSS,
   validity: "GTC",
   security_id: "1333",
   quantity: 100,
@@ -381,11 +381,11 @@ The response returns one object per super order with nested `leg_details`. Key a
 
 ```ruby
 params = {
-  transaction_type: "SELL",
-  exchange_segment: "NSE_EQ",
-  product_type: "CNC",
-  order_type: "LIMIT",
-  validity: "DAY",
+  transaction_type: DhanHQ::Constants::TransactionType::SELL,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  validity: DhanHQ::Constants::Validity::DAY,
   security_id: "1333",
   price: 200.0,
   trigger_price: 198.0
@@ -416,10 +416,10 @@ Convert an intraday position to delivery (or vice versa):
 ```ruby
 convert_payload = {
   security_id: "1333",
-  from_product_type: "INTRADAY",
-  to_product_type: "CNC",
+  from_product_type: DhanHQ::Constants::ProductType::INTRADAY,
+  to_product_type: DhanHQ::Constants::ProductType::CNC,
   convert_qty: 10,
-  exchange_segment: "NSE_EQ",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
   position_type: "LONG"
 }
 
@@ -496,8 +496,8 @@ Both endpoints return arrays and skip validation because they represent historic
 ```ruby
 bars = DhanHQ::Models::HistoricalData.intraday(
   security_id: "13",
-  exchange_segment: "IDX_I",
-  instrument: "INDEX",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::IDX_I,
+  instrument: DhanHQ::Constants::InstrumentType::INDEX,
   interval: "5",
   from_date: "2024-08-14",
   to_date: "2024-08-14"
@@ -509,13 +509,13 @@ bars = DhanHQ::Models::HistoricalData.intraday(
 ```ruby
 chain = DhanHQ::Models::OptionChain.fetch(
   underlying_scrip: 1333,
-  underlying_seg: "NSE_FNO",
+  underlying_seg: DhanHQ::Constants::ExchangeSegment::NSE_FNO,
   expiry: "2024-12-26"
 )
 
 expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(
   underlying_scrip: 1333,
-  underlying_seg: "NSE_FNO"
+  underlying_seg: DhanHQ::Constants::ExchangeSegment::NSE_FNO
 )
 ```
 
@@ -527,10 +527,10 @@ The model filters strikes where both CE and PE have zero `last_price`, keeping t
 
 ```ruby
 params = {
-  exchange_segment: "NSE_EQ",
-  transaction_type: "BUY",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
   quantity: 10,
-  product_type: "INTRADAY",
+  product_type: DhanHQ::Constants::ProductType::INTRADAY,
   security_id: "1333",
   price: 150.0
 }
@@ -618,8 +618,8 @@ ws.on(:tick) do |tick|
   puts "[#{tick[:segment]} #{tick[:security_id]}] LTP=#{tick[:ltp]} kind=#{tick[:kind]}"
 end
 
-ws.subscribe_one(segment: "IDX_I", security_id: "13")
-ws.unsubscribe_one(segment: "IDX_I", security_id: "13")
+ws.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")
+ws.unsubscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")
 
 ws.disconnect!
 ```
@@ -643,17 +643,34 @@ If the credentials are invalid the helper raises `DhanHQ::InvalidAuthenticationE
 
 ### Alert Orders
 
+Condition must include `exchange_segment`, `exp_date`, and `frequency` per [conditional-trigger API](https://dhanhq.co/docs/v2/conditional-trigger/). For technical indicators, `time_frame` is also required.
+
 ```ruby
 # Model (CRUD)
 DhanHQ::Models::AlertOrder.all
 alert = DhanHQ::Models::AlertOrder.find("alert-id")
 alert = DhanHQ::Models::AlertOrder.create(
-  exchange_segment: "NSE_EQ",
-  security_id: "11536",
-  condition: "GTE",
-  trigger_price: 100.0,
-  transaction_type: "BUY",
-  quantity: 10
+  condition: {
+    security_id: "11536",
+    exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+    comparison_type: DhanHQ::Constants::ComparisonType::PRICE_WITH_VALUE,
+    operator: DhanHQ::Constants::Operator::GREATER_THAN,
+    comparing_value: 100.0,
+    exp_date: (Date.today + 365).strftime("%Y-%m-%d"),
+    frequency: "ONCE"
+  },
+  orders: [
+    {
+      transaction_type: DhanHQ::Constants::TransactionType::BUY,
+      exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+      product_type: DhanHQ::Constants::ProductType::CNC,
+      order_type: DhanHQ::Constants::OrderType::LIMIT,
+      security_id: "11536",
+      quantity: 10,
+      validity: DhanHQ::Constants::Validity::DAY,
+      price: 150.0
+    }
+  ]
 )
 alert.save
 alert.destroy
@@ -687,13 +704,14 @@ Params use snake_case; the client camelizes them before calling `/edis/...`.
 
 ### IP Setup
 
-Resource-only (account configuration) per API docs: GET /ip/getIP, POST /ip/setIP, PUT /ip/modifyIP.
+Resource-only (account configuration) per [API docs](https://dhanhq.co/docs/v2/authentication/#setup-static-ip): GET /ip/getIP, POST /ip/setIP, PUT /ip/modifyIP. Set/Modify require `dhanClientId`, `ip`, and `ipFlag` (PRIMARY or SECONDARY).
 
 ```ruby
 ip = DhanHQ::Resources::IPSetup.new
-ip.current              # GET /ip/getIP
-ip.set(ip: "103.21.58.121")
-ip.update(ip: "103.21.58.121")
+ip.current                                    # GET /ip/getIP
+ip.set(ip: "103.21.58.121")                   # ip_flag defaults to "PRIMARY", dhan_client_id from config
+ip.set(ip: "103.21.58.121", ip_flag: "SECONDARY")
+ip.update(ip: "103.21.58.121", ip_flag: "PRIMARY")
 ```
 
 ### Trader Control (Kill Switch)
@@ -709,7 +727,7 @@ tc.enable              # Trading resumed
 
 ### Kill Switch (model)
 
-Existing model API for backward compatibility:
+Uses query parameter per API doc: `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or DEACTIVATE), no body.
 
 ```ruby
 activate_payload   = DhanHQ::Models::KillSwitch.activate
@@ -725,7 +743,7 @@ DhanHQ::Models::KillSwitch.snake_case(deactivate_payload)
 DhanHQ::Models::KillSwitch.update("ACTIVATE")
 ```
 
-Only `"ACTIVATE"` and `"DEACTIVATE"` are accepted—any other value raises `DhanHQ::Error`. Use the `snake_case` helper to normalise API responses when you prefer underscore keys.
+Only `"ACTIVATE"` and `"DEACTIVATE"` are accepted. Use the `snake_case` helper to normalise API responses when you prefer underscore keys.
 
 ---
 

data/README.md

@@ -124,11 +124,11 @@ When the API returns 401, the client retries **once** with a fresh token from yo
 
 ```ruby
 order = DhanHQ::Models::Order.new(
-  transaction_type: "BUY",
-  exchange_segment: "NSE_FNO",
-  product_type:     "MARGIN",
-  order_type:       "LIMIT",
-  validity:         "DAY",
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO,
+  product_type: DhanHQ::Constants::ProductType::MARGIN,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  validity: DhanHQ::Constants::Validity::DAY,
   security_id:      "43492",
   quantity:         50,
   price:            100.0
@@ -151,8 +151,8 @@ DhanHQ::Models::Fund.balance
 ```ruby
 bars = DhanHQ::Models::HistoricalData.intraday(
   security_id:      "13",
-  exchange_segment: "IDX_I",
-  instrument:       "INDEX",
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::IDX_I,
+  instrument: DhanHQ::Constants::InstrumentType::INDEX,
   interval:         "5",
   from_date:        "2025-08-14",
   to_date:          "2025-08-18"
@@ -190,8 +190,8 @@ client = DhanHQ::WS.connect(mode: :ticker) do |tick|
   puts "#{tick[:security_id]} = ₹#{tick[:ltp]}"
 end
 
-client.subscribe_one(segment: "IDX_I", security_id: "13")   # NIFTY
-client.subscribe_one(segment: "IDX_I", security_id: "25")   # BANKNIFTY
+client.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")   # NIFTY
+client.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "25")   # BANKNIFTY
 ```
 
 ### Market Depth
@@ -220,10 +220,10 @@ Entry + target + stop-loss + trailing jump in a single request:
 
 ```ruby
 DhanHQ::Models::SuperOrder.create(
-  transaction_type: "BUY",
-  exchange_segment: "NSE_EQ",
-  product_type:     "CNC",
-  order_type:       "LIMIT",
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
   security_id:      "11536",
   quantity:         5,
   price:            1500,
@@ -246,8 +246,8 @@ DhanHQ.configure_with_env
 
 # 1. Check the trend using historical 5-min bars
 bars = DhanHQ::Models::HistoricalData.intraday(
-  security_id: "13", exchange_segment: "IDX_I",
-  instrument: "INDEX", interval: "5",
+  security_id: "13", exchange_segment: DhanHQ::Constants::ExchangeSegment::IDX_I,
+  instrument: DhanHQ::Constants::InstrumentType::INDEX, interval: "5",
   from_date: Date.today.to_s, to_date: Date.today.to_s
 )
 
@@ -260,11 +260,11 @@ puts "NIFTY trend: #{trend} (LTP: #{closes.last}, SMA20: #{sma_20.round(2)})"
 client = DhanHQ::WS.connect(mode: :quote) do |tick|
   puts "NIFTY ₹#{tick[:ltp]} | Vol: #{tick[:vol]} | #{Time.now.strftime('%H:%M:%S')}"
 end
-client.subscribe_one(segment: "IDX_I", security_id: "13")
+client.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")
 
 # 3. On signal, place a super order with built-in risk management
 # DhanHQ::Models::SuperOrder.create(
-#   transaction_type: "BUY", exchange_segment: "NSE_FNO", ...
+#   transaction_type: DhanHQ::Constants::TransactionType::BUY, exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO, ...
 #   target_price: entry + 50, stop_loss_price: entry - 30, trailing_jump: 5
 # )
 
@@ -277,7 +277,7 @@ sleep   # keep the script alive
 
 ## Rails Integration
 
-Need initializers, service objects, ActionCable wiring, and background workers? See the [Rails Integration Guide](docs/rails_integration.md).
+Need initializers, service objects, ActionCable wiring, and background workers? See the [Rails Integration Guide](docs/RAILS_INTEGRATION.md).
 
 ---
 
@@ -287,15 +287,16 @@ Need initializers, service objects, ActionCable wiring, and background workers?
 | ----- | -------------- |
 | [Authentication](docs/AUTHENTICATION.md) | Token flows, TOTP, OAuth, auto-management |
 | [Configuration Reference](docs/CONFIGURATION.md) | Full ENV matrix, logging, timeouts, available resources |
-| [WebSocket Integration](docs/websocket_integration.md) | All WS types, architecture, best practices |
+| [WebSocket Integration](docs/WEBSOCKET_INTEGRATION.md) | All WS types, architecture, best practices |
 | [WebSocket Protocol](docs/WEBSOCKET_PROTOCOL.md) | Packet parsing, request codes, tick schema, exchange enums |
-| [Rails WebSocket Guide](docs/rails_websocket_integration.md) | Rails-specific patterns, ActionCable |
-| [Rails Integration](docs/rails_integration.md) | Initializers, service objects, workers |
-| [Standalone Ruby Guide](docs/standalone_ruby_websocket_integration.md) | Scripts, daemons, CLI tools |
+| [Rails WebSocket Guide](docs/RAILS_WEBSOCKET_INTEGRATION.md) | Rails-specific patterns, ActionCable |
+| [Rails Integration](docs/RAILS_INTEGRATION.md) | Initializers, service objects, workers |
+| [Standalone Ruby Guide](docs/STANDALONE_RUBY_WEBSOCKET_INTEGRATION.md) | Scripts, daemons, CLI tools |
 | [Super Orders API](docs/SUPER_ORDERS.md) | Full REST reference for super orders |
+| [API Constants Reference](docs/CONSTANTS_REFERENCE.md) | All valid enums, exchange segments, and order parameters |
 | [Data API Parameters](docs/DATA_API_PARAMETERS.md) | Historical data, option chain parameters |
 | [Testing Guide](docs/TESTING_GUIDE.md) | WebSocket testing, model testing, console helpers |
-| [Technical Analysis](docs/technical_analysis.md) | Indicators, multi-timeframe aggregation |
+| [Technical Analysis](docs/TECHNICAL_ANALYSIS.md) | Indicators, multi-timeframe aggregation |
 | [Troubleshooting](docs/TROUBLESHOOTING.md) | 429 errors, reconnect, auth issues, debug logging |
 | [Release Guide](docs/RELEASE_GUIDE.md) | Versioning, publishing, changelog |
 

data/docs/API_DOCS_GAPS.md

@@ -0,0 +1,128 @@
+# DhanHQ v2 API docs vs dhanhq-client — gaps and fixes
+
+Reference: [dhanhq.co/docs/v2](https://dhanhq.co/docs/v2/)
+
+This document lists mismatches between the official DhanHQ v2 API documentation and the dhanhq-client gem, and suggested fixes.
+
+---
+
+## 1. Kill Switch — request format
+
+**Doc:** [Trader's Control](https://dhanhq.co/docs/v2/traders-control/)
+
+- **Manage Kill Switch:** *"You can pass header parameter as ACTIVATE or DEACTIVATE"* and the curl example uses a **query parameter**:  
+  `POST https://api.dhan.co/v2/killswitch?killSwitchStatus=ACTIVATE`  
+  **Request structure: No Body**
+
+**Gem:** `Resources::KillSwitch#update(params)` sends a **POST body** with `kill_switch_status: "ACTIVATE"` or `"DEACTIVATE"`.
+
+**Gap:** The API may expect `killSwitchStatus` as a **query parameter** (or header), not in the JSON body. That can explain `DH-905: Missing required fields` when calling activate/deactivate.
+
+**Suggested fix:** In `Resources::KillSwitch#update(status)`, call the API with a query string, e.g. `post("?killSwitchStatus=#{status}")` (or equivalent), and do not send a body. If the live API accepts body and your integration works, this may be a doc inaccuracy; otherwise prefer matching the doc (query param).
+
+**Fixed:** Resource now sends `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or DEACTIVATE) with no body. Model passes status string to resource.
+
+---
+
+## 2. IP Setup — missing required parameters
+
+**Doc:** [Authentication → Setup Static IP](https://dhanhq.co/docs/v2/authentication/#setup-static-ip)
+
+- **Set IP:** Body must include:
+  - `dhanClientId` (required)
+  - `ip` (required)
+  - `ipFlag` (required): `"PRIMARY"` or `"SECONDARY"`
+- **Modify IP:** Same body as Set IP.
+
+**Gem:** `Resources::IPSetup#set(ip:)` and `#update(ip:)` send only `{ ip: ip }`.
+
+**Gap:** `dhanClientId` and `ipFlag` are not sent. Set/Modify IP may fail or behave incorrectly for accounts that require them.
+
+**Suggested fix:** Add `dhan_client_id` and `ip_flag` to the resource (e.g. `set(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)`), defaulting `dhan_client_id` from `DhanHQ.configuration.client_id` when not provided.
+
+**Fixed:** `IPSetup#set` and `#update` now accept `ip:, ip_flag: "PRIMARY"` (or `"SECONDARY"`), and `dhan_client_id:` (defaults from config when nil).
+
+---
+
+## 3. Alert Orders (Conditional Trigger) — condition fields
+
+**Doc:** [Conditional Trigger](https://dhanhq.co/docs/v2/conditional-trigger/)
+
+For **Place** and **Modify**:
+
+- `condition.exchangeSegment` — **required**
+- `condition.expDate` — **required** (date, default 1 year)
+- `condition.frequency` — **required** (e.g. `"ONCE"`)
+- `condition.timeFrame` — required for technical conditions (e.g. `"DAY"`, `"ONE_MIN"`)
+
+**Gem:** `Contracts::AlertOrderContract` and `Models::AlertOrder`:
+
+- Condition has: `security_id`, `comparison_type`, `operator`, and optional `indicator_name`, `time_frame`, `comparing_value`, `comparing_indicator_name`.
+- **Missing from contract/model:** `exchange_segment`, `exp_date`, `frequency` in the condition hash.
+
+**Gap:** Creating or modifying alert orders that satisfy the API may require these fields; the gem does not expose or validate them.
+
+**Suggested fix:** Add `exchange_segment`, `exp_date`, and `frequency` to the alert order condition in the contract and model (and ensure they are sent in the API payload in the expected format, e.g. camelCase).
+
+**Fixed:** `AlertOrderContract` condition now requires `exchange_segment`, `exp_date`, `frequency`; rule added so `time_frame` is required when `comparison_type` starts with `TECHNICAL`. Test script and specs updated.
+
+---
+
+## 4. EDIS — doc typo only
+
+**Doc:** [EDIS](https://dhanhq.co/docs/v2/edis/) table lists `POST /edis/from` for the form endpoint.
+
+**Gem:** Uses `POST /edis/form`.
+
+**Conclusion:** The doc table has a typo ("from" vs "form"). The doc’s curl and request structure use `/edis/form`. No change needed in the gem.
+
+---
+
+## 5. Forever Order list — doc inconsistency
+
+**Doc:** [Forever Order](https://dhanhq.co/docs/v2/forever/)
+
+- Table: `GET /forever/orders` — retrieve all forever orders.
+- Section "All Forever Order Detail": curl shows `GET /forever/all`.
+
+**Gem:** Uses `GET /forever/orders` (e.g. `ForeverOrders#all` → `get("/orders")` with `HTTP_PATH = "/v2/forever"`).
+
+**Conclusion:** Doc is inconsistent. The gem matches the table. If the API actually uses `/forever/all`, the resource path would need to change; otherwise no change.
+
+---
+
+## 6. P&L Exit — dhanClientId
+
+**Doc:** [Trader's Control → P&L Based Exit](https://dhanhq.co/docs/v2/traders-control/) does not list `dhanClientId` in the request body for Configure.
+
+**Gem:** Was updated to send `dhanClientId` from config when present, to fix `DH-905: dhanClientId is required`.
+
+**Conclusion:** Either the doc omits this field or the API was updated to require it. The gem’s behaviour is aligned with the API response you saw; no further change unless the doc is updated.
+
+---
+
+## Summary table
+
+| Area            | Doc reference        | Gap / note                                                                 | Status   |
+|-----------------|----------------------|----------------------------------------------------------------------------|----------|
+| Kill Switch     | traders-control      | Manage API expects query param `killSwitchStatus`, not body                | **Fixed** |
+| IP Setup        | authentication       | Set/Modify IP required `dhanClientId`, `ipFlag`                            | **Fixed** |
+| Alert Orders    | conditional-trigger  | Condition required `exchangeSegment`, `expDate`, `frequency`               | **Fixed** |
+| EDIS            | edis                 | Doc typo `/edis/from`; gem correctly uses `/edis/form`                     | None     |
+| Forever list    | forever              | Doc inconsistency `/forever/orders` vs `/forever/all`; gem uses `/orders`  | Low      |
+| P&L Exit    | traders-control      | Gem sends `dhanClientId`; doc does not mention it                          | None     |
+
+---
+
+## Endpoints covered by the gem (no gaps found)
+
+- **Orders:** Place, modify, cancel, slicing, order book, get by id, get by correlation id — paths and behaviour match the [Orders](https://dhanhq.co/docs/v2/orders/) doc.
+- **Trades:** Trade book, trades by order id — match doc.
+- **Super Order:** Create, modify, cancel, list — match [Super Order](https://dhanhq.co/docs/v2/super-order/) doc.
+- **Forever Order:** Create, modify, cancel, list — paths match [Forever Order](https://dhanhq.co/docs/v2/forever/) table (list path as above).
+- **Profile:** GET /v2/profile — match [Authentication → User Profile](https://dhanhq.co/docs/v2/authentication/#user-profile).
+- **Trader’s Control:** Kill Switch status (GET), manage via query param (see above). P&L Exit configure/stop/status — match doc.
+- **EDIS:** tpin, form, bulkform, inquire — paths and params match [EDIS](https://dhanhq.co/docs/v2/edis/) (form URL as above).
+- **Postback:** Incoming webhook payload; gem’s `Postback.parse` is for parsing, not an outgoing API — no endpoint gap.
+
+The Kill Switch query-param change, IP Setup parameter additions, and Alert Order condition fields have been implemented in the gem. See CHANGELOG (Unreleased), GUIDE.md, docs/API_VERIFICATION.md, and docs/TESTING_GUIDE.md for updated documentation.

data/docs/API_VERIFICATION.md

@@ -28,7 +28,7 @@ This document records how the gem’s implementation aligns with the official Dh
 
 ## Alert Orders
 
-**Doc ref:** `CODE_REVIEW_ISSUES.md` (§31) – Alert Orders endpoints.
+**Doc ref:** [dhanhq.co/docs/v2/conditional-trigger](https://dhanhq.co/docs/v2/conditional-trigger/).
 
 | Doc path                  | Gem resource              | Path used        |
 |---------------------------|---------------------------|------------------|
@@ -36,27 +36,26 @@ This document records how the gem’s implementation aligns with the official Dh
 | GET/POST `/alerts/orders` | `#all`, `#create`         | BaseResource     |
 | GET/PUT/DELETE `/alerts/orders/{trigger-id}` | `#find`, `#update`, `#delete` | `/{id}` |
 
-Model: `Models::AlertOrder`; ID attribute `alert_id` (response field name may be `alertId` or `triggerId` depending on API; adjust if production returns `triggerId`).
+Model: `Models::AlertOrder`. Condition must include `exchange_segment`, `exp_date`, `frequency`; `time_frame` required when `comparison_type` starts with `TECHNICAL`. Validated by `AlertOrderContract`.
 
 ---
 
 ## IP Setup
 
-**Doc ref:** `CODE_REVIEW_ISSUES.md` (§32) – IP Setup endpoints.
+**Doc ref:** [dhanhq.co/docs/v2/authentication/#setup-static-ip](https://dhanhq.co/docs/v2/authentication/#setup-static-ip).
 
-| Doc path        | Gem method     | Path used     |
-|-----------------|----------------|---------------|
-| GET /ip/getIP   | `#current`     | `get("/getIP")`   |
-| POST /ip/setIP  | `#set(ip:)`    | `post("/setIP", params: { ip: ip })` |
-| PUT /ip/modifyIP| `#update(ip:)` | `put("/modifyIP", params: { ip: ip })` |
+| Doc path        | Gem method     | Path / body |
+|-----------------|----------------|-------------|
+| GET /ip/getIP   | `#current`     | `get("/getIP")` |
+| POST /ip/setIP  | `#set(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` | `post("/setIP", params: { ip:, ip_flag:, dhan_client_id: })`; `dhan_client_id` defaults from config |
+| PUT /ip/modifyIP| `#update(ip:, ip_flag: "PRIMARY", dhan_client_id: nil)` | `put("/modifyIP", params: { ip:, ip_flag:, dhan_client_id: })` |
 
 ---
 
 ## Trader Control / Kill Switch
 
-- **Existing:** `Resources::KillSwitch`, `Models::KillSwitch` – path `/v2/killswitch`.
-- **Added:** `Resources::TraderControl` – path `/trader-control`; `#status`, `#enable`, `#disable`.  
-  Not found on the public docs pages checked; kept for compatibility with design that referenced trader-control.
+- **Kill Switch:** `Resources::KillSwitch`, `Models::KillSwitch` – path `/v2/killswitch`. Manage (activate/deactivate) uses **query parameter** per [traders-control](https://dhanhq.co/docs/v2/traders-control/): `POST /v2/killswitch?killSwitchStatus=ACTIVATE` (or `DEACTIVATE`) with no body. `#status` is GET.
+- **Trader Control:** `Resources::TraderControl` – path `/trader-control`; `#status`, `#enable`, `#disable`. Not found on the public docs; kept for compatibility.
 
 ---