DhanHQ 2.1.5 → 2.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cff831c4d2dc881c38a4ecc6274ad9ba8601fd6c6910815ab9ec40fde31af564
-  data.tar.gz: 00b892609e077902e1137b789dcd3a6d0e51fa3e042d38b05c39fc92971da157
+  metadata.gz: 1ffcb72b2997f7841ef6c872ad71748c36f4305f9e746a5d4d8f2a3b9429c8da
+  data.tar.gz: 5a72519746d9ca58f6cb295855f9065ccc3b9059c2684347b58c3e998ad8668b
 SHA512:
-  metadata.gz: f476df43f8f9500515101c85d423b91f713f384e89a01f316ed66265d69502a45b4adf7c2cd06aa6c8d466e65d5548e0337361844305e6f9103df0dd6a7564f3
-  data.tar.gz: aa14913dfa8590e8ba52e2f49a97b4cf475ad6d0058deac7114c1c56cb3817c70a38655afa4b30ef9741ab3da82f53c9d719dec70bef70bb9e242f7081a7392e
+  metadata.gz: 397d51627f7049470332e23926ca7d00d78aad94d88eb0939d25164dc74330d68014a5ad6593453dfedb2da51c4f2a810ecc7e971d5f1735b3b21e96d3d068df
+  data.tar.gz: 2092c00ab1903f18d7718bd27125236251d2129cd536a071b506c3a53d2826a66eb5c9ba737ab89eff52b125e864138b507e577616ffc9e0a034da0a4eb8e37a

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [2.1.7] - 2025-01-28
+
+### Added
+- **Instrument instance methods**: Added convenience methods to Instrument model for accessing market feed, historical data, and option chain data
+  - `instrument.ltp` - Fetches last traded price using `DhanHQ::Models::MarketFeed.ltp`
+  - `instrument.ohlc` - Fetches OHLC data using `DhanHQ::Models::MarketFeed.ohlc`
+  - `instrument.quote` - Fetches full quote depth using `DhanHQ::Models::MarketFeed.quote`
+  - `instrument.daily(from_date:, to_date:, **options)` - Fetches daily historical data using `DhanHQ::Models::HistoricalData.daily`
+  - `instrument.intraday(from_date:, to_date:, interval:, **options)` - Fetches intraday historical data using `DhanHQ::Models::HistoricalData.intraday`
+  - `instrument.expiry_list` - Fetches expiry list using `DhanHQ::Models::OptionChain.fetch_expiry_list`
+  - `instrument.option_chain(expiry:)` - Fetches option chain using `DhanHQ::Models::OptionChain.fetch`
+  - All methods automatically use the instrument's `security_id`, `exchange_segment`, and `instrument` attributes
+- **InstrumentHelpers module**: Created reusable module to provide these convenience methods
+
+### Changed
+- Align Super Order documentation across README, README1, and GUIDE with the latest API contract (place, modify, cancel, list).
+- Normalise remaining documentation examples to snake_case, including order update WebSocket callbacks and kill switch response guidance.
+
 ## [2.1.5] - 2025-01-27
 
 ### ⚠️ BREAKING CHANGES
@@ -18,6 +36,9 @@
 ### Fixed
 - **RuboCop compliance**: Fixed all RuboCop offenses (179 → 0 offenses)
 - **Documentation**: Updated all documentation examples to use `require 'dhan_hq'`
+- **Documentation**: Correct Super Order examples to use snake_case parameters for `DhanHQ::Models` helpers
+- **Documentation**: Normalise Super Order path placeholders and response fields to snake_case for consistency
+- **Documentation**: Clarified that model helpers auto-inject `dhan_client_id`, removing the need to add it manually in Ruby payloads
 - **Code quality**: Added comprehensive validation tests for OptionChain methods
 
 ### Changed

data/GUIDE.md

@@ -156,9 +156,9 @@ puts order.order_status  # => "TRADED" / "PENDING" / ...
 
 `Order#modify` merges the existing attributes with the supplied overrides and validates against `ModifyOrderContract`.
 
-- Required: the instance must have an `order_id` and `dhan_client_id`.
+- Required: the instance must have an `order_id`; the model reuses the saved `dhan_client_id` when building the payload.
 - At least one of `order_type`, `quantity`, `price`, `trigger_price`, `disclosed_quantity`, `validity` must change.
-- Payload is camelised automatically before hitting `/v2/orders/{orderId}`.
+- Payload is camelised automatically before hitting `/v2/orders/{order_id}`.
 
 ```ruby
 order.modify(price: 154.2, trigger_price: 149.5)
@@ -208,42 +208,174 @@ DhanHQ::Models::Order.resource.slicing(payload)
 
 ### Super Orders
 
-`DhanHQ::Models::SuperOrder` wraps `/v2/super/orders`.
+`DhanHQ::Models::SuperOrder` wraps the `/v2/super/orders` family. A super order combines entry, target, and stop-loss legs into one atomic instruction and supports an optional trailing jump so risk is managed server-side immediately after entry.
 
-```ruby
-legs = {
-  transactionType: "BUY",
-  exchangeSegment: "NSE_FNO",
-  productType: "CO",
-  orderType: "LIMIT",
-  validity: "DAY",
-  securityId: "43492",
-  quantity: 50,
-  price: 100.0,
-  stopLossPrice: 95.0,
-  targetPrice: 110.0
+#### Endpoints
+
+| Method   | Path                                   | Description                           |
+| -------- | -------------------------------------- | ------------------------------------- |
+| `POST`   | `/super/orders`                        | Create a new super order              |
+| `PUT`    | `/super/orders/{order_id}`             | Modify a pending super order          |
+| `DELETE` | `/super/orders/{order_id}/{order_leg}` | Cancel a pending super order leg      |
+| `GET`    | `/super/orders`                        | Retrieve the list of all super orders |
+
+#### Place Super Order
+
+> ℹ️ Static IP whitelisting with Dhan support is required before invoking these APIs.
+
+```bash
+curl --request POST \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
+```
+
+Request body:
+
+```json
+{
+  "dhan_client_id": "1000000003",
+  "correlation_id": "123abc678",
+  "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
+}
+```
+
+Key parameters:
+
+| Field              | Type                     | Notes                                                                                                          |
+| ------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `dhan_client_id`   | string *(required)*      | User specific identifier generated by Dhan. Automatically merged when you call through the Ruby model helpers. |
+| `correlation_id`   | string                   | Optional caller supplied correlation id.                                                                       |
+| `transaction_type` | enum string *(required)* | `BUY` or `SELL`.                                                                                               |
+| `exchange_segment` | enum string *(required)* | Exchange segment.                                                                                              |
+| `product_type`     | enum string *(required)* | `CNC`, `INTRADAY`, `MARGIN`, or `MTF`.                                                                         |
+| `order_type`       | enum string *(required)* | `LIMIT` or `MARKET`.                                                                                           |
+| `security_id`      | string *(required)*      | Exchange security identifier.                                                                                  |
+| `quantity`         | integer *(required)*     | Entry quantity.                                                                                                |
+| `price`            | float *(required)*       | Entry price.                                                                                                   |
+| `target_price`     | float *(required)*       | Target price for the super order.                                                                              |
+| `stop_loss_price`  | float *(required)*       | Stop-loss price for the super order.                                                                           |
+| `trailing_jump`    | float *(required)*       | Trailing jump size.                                                                                            |
+
+> 🐍 Pass snake_case keys when invoking `DhanHQ::Models::SuperOrder.create`—the client camelizes internally before calling the REST API and injects your configured `dhan_client_id`, so the key is optional in Ruby payloads.
+
+Response:
+
+```json
+{
+  "order_id": "112111182198",
+  "order_status": "PENDING"
 }
+```
+
+#### Modify Super Order
 
-super_order = DhanHQ::Models::SuperOrder.create(legs)
-super_order.modify(trailingJump: 2.5)
-super_order.cancel("ENTRY_LEG")
+Modify while the order is `PENDING` or `PART_TRADED`. Entry leg updates adjust the entire super order until the entry trades; afterwards only target and stop-loss legs (price, trailing) remain editable.
+
+```bash
+curl --request PUT \
+  --url https://api.dhan.co/v2/super/orders/{order_id} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT' \
+  --data '{Request JSON}'
 ```
 
+Example payload:
+
+```json
+{
+  "dhan_client_id": "1000000009",
+  "order_id": "112111182045",
+  "order_type": "LIMIT",
+  "leg_name": "ENTRY_LEG",
+  "quantity": 40,
+  "price": 1300,
+  "target_price": 1450,
+  "stop_loss_price": 1350,
+  "trailing_jump": 20
+}
+```
+
+Conditional fields:
+
+| Field             | Required when                           | Notes                                |
+| ----------------- | --------------------------------------- | ------------------------------------ |
+| `order_type`      | Updating `ENTRY_LEG`                    | `LIMIT` or `MARKET`.                 |
+| `quantity`        | Updating `ENTRY_LEG`                    | Adjusts entry quantity.              |
+| `price`           | Updating `ENTRY_LEG`                    | Adjusts entry price.                 |
+| `target_price`    | Updating `ENTRY_LEG` or `TARGET_LEG`    | Adjusts target price.                |
+| `stop_loss_price` | Updating `ENTRY_LEG` or `STOP_LOSS_LEG` | Adjusts stop-loss price.             |
+| `trailing_jump`   | Updating `ENTRY_LEG` or `STOP_LOSS_LEG` | Pass `0` or omit to cancel trailing. |
+
+Response:
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "TRANSIT"
+}
+```
+
+#### Cancel Super Order
+
+```bash
+curl --request DELETE \
+  --url https://api.dhan.co/v2/super/orders/{order_id}/{order_leg} \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+Path parameters:
+
+| Field       | Description                                                    | Example       |
+| ----------- | -------------------------------------------------------------- | ------------- |
+| `order_id`  | Super order identifier.                                        | `11211182198` |
+| `order_leg` | Leg to cancel (`ENTRY_LEG`, `TARGET_LEG`, or `STOP_LOSS_LEG`). | `ENTRY_LEG`   |
+
+Response:
+
+```json
+{
+  "order_id": "112111182045",
+  "order_status": "CANCELLED"
+}
+```
+
+#### Super Order List
+
+```bash
+curl --request GET \
+  --url https://api.dhan.co/v2/super/orders \
+  --header 'Content-Type: application/json' \
+  --header 'access-token: JWT'
+```
+
+The response returns one object per super order with nested `leg_details`. Key attributes include `order_status`, `filled_qty`, `remaining_quantity`, `average_traded_price`, and leg-level trailing configuration. `CLOSED` indicates the entry plus either target or stop-loss filled the entire quantity; `TRIGGERED` surfaces on the target or stop-loss leg that fired.
+
 ### Forever Orders (GTT)
 
 `DhanHQ::Models::ForeverOrder` maps to `/v2/forever/orders`.
 
 ```ruby
 params = {
-  dhanClientId: "123456",
-  transactionType: "SELL",
-  exchangeSegment: "NSE_EQ",
-  productType: "CNC",
-  orderType: "LIMIT",
+  transaction_type: "SELL",
+  exchange_segment: "NSE_EQ",
+  product_type: "CNC",
+  order_type: "LIMIT",
   validity: "DAY",
-  securityId: "1333",
+  security_id: "1333",
   price: 200.0,
-  triggerPrice: 198.0
+  trigger_price: 198.0
 }
 
 forever_order = DhanHQ::Models::ForeverOrder.create(params)
@@ -251,6 +383,8 @@ forever_order.modify(price: 205.0)
 forever_order.cancel
 ```
 
+> 🪄 Model helpers merge the configured `dhan_client_id` automatically, so you can omit it when constructing Ruby hashes like the example above.
+
 The forever order helpers accept snake_case parameters and camelize them internally; only the low-level resource requires raw API casing.
 
 ---
@@ -268,7 +402,6 @@ Convert an intraday position to delivery (or vice versa):
 
 ```ruby
 convert_payload = {
-  dhan_client_id: "123456",
   security_id: "1333",
   from_product_type: "INTRADAY",
   to_product_type: "CNC",
@@ -281,6 +414,8 @@ response = DhanHQ::Models::Position.convert(convert_payload)
 raise response.errors.to_s if response.is_a?(DhanHQ::ErrorObject)
 ```
 
+> 🪄 No need to merge `dhan_client_id`; the helper adds it from your configuration before calling `/v2/positions/convert`.
+
 The conversion helper validates the payload with `PositionConversionContract`; missing or invalid fields raise `DhanHQ::Error` before the request is sent.
 
 ### Holdings
@@ -379,7 +514,6 @@ The model filters strikes where both CE and PE have zero `last_price`, keeping t
 
 ```ruby
 params = {
-  dhan_client_id: "123456",
   exchange_segment: "NSE_EQ",
   transaction_type: "BUY",
   quantity: 10,
@@ -392,6 +526,8 @@ margin = DhanHQ::Models::Margin.calculate(params)
 puts margin.total_margin
 ```
 
+> 🪄 The margin helper appends `dhan_client_id` from your credentials before calling `/v2/margincalculator`.
+
 If a required field is missing (for example `transaction_type`), the contract raises `DhanHQ::Error` before any API call is issued.
 
 ### REST Market Feed (Batch LTP/OHLC/Quote)
@@ -407,7 +543,55 @@ ohlc  = DhanHQ::Models::MarketFeed.ohlc(payload)
 quote = DhanHQ::Models::MarketFeed.quote(payload)
 ```
 
-These endpoints are rate-limited by Dhan. The client’s internal `RateLimiter` throttles calls—consider batching symbols sensibly.
+These endpoints are rate-limited by Dhan. The client's internal `RateLimiter` throttles calls—consider batching symbols sensibly.
+
+### Instrument Convenience Methods
+
+The Instrument model provides convenient instance methods that automatically use the instrument's attributes (`security_id`, `exchange_segment`, `instrument`) to fetch market data. This eliminates the need to manually construct parameters for each API call.
+
+```ruby
+# Find an instrument first
+instrument = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
+# or
+reliance = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")
+
+# Market Feed Methods - automatically uses instrument's attributes
+ltp_data = instrument.ltp        # Last traded price
+ohlc_data = instrument.ohlc     # OHLC data
+quote_data = instrument.quote    # Full quote depth
+
+# Historical Data Methods
+daily_data = instrument.daily(
+  from_date: "2024-01-01",
+  to_date: "2024-01-31",
+  expiry_code: 0  # Optional, only for derivatives
+)
+
+intraday_data = instrument.intraday(
+  from_date: "2024-09-11",
+  to_date: "2024-09-15",
+  interval: "15"  # 1, 5, 15, 25, or 60 minutes
+)
+
+# Option Chain Methods (for F&O instruments)
+fn_instrument = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
+expiries = fn_instrument.expiry_list  # Get all available expiries
+chain = fn_instrument.option_chain(expiry: "2024-02-29")  # Get option chain for specific expiry
+```
+
+**Available Instance Methods:**
+
+| Method                                                            | Description                      | Underlying API                                  |
+| ----------------------------------------------------------------- | -------------------------------- | ----------------------------------------------- |
+| `instrument.ltp`                                                  | Fetches last traded price        | `DhanHQ::Models::MarketFeed.ltp`                |
+| `instrument.ohlc`                                                 | Fetches OHLC data                | `DhanHQ::Models::MarketFeed.ohlc`               |
+| `instrument.quote`                                                | Fetches full quote depth         | `DhanHQ::Models::MarketFeed.quote`              |
+| `instrument.daily(from_date:, to_date:, **options)`               | Fetches daily historical data    | `DhanHQ::Models::HistoricalData.daily`          |
+| `instrument.intraday(from_date:, to_date:, interval:, **options)` | Fetches intraday historical data | `DhanHQ::Models::HistoricalData.intraday`       |
+| `instrument.expiry_list`                                          | Fetches expiry list              | `DhanHQ::Models::OptionChain.fetch_expiry_list` |
+| `instrument.option_chain(expiry:)`                                | Fetches option chain             | `DhanHQ::Models::OptionChain.fetch`             |
+
+All methods automatically extract `security_id`, `exchange_segment`, and `instrument` from the instrument instance, making it easier to work with market data without manually managing these parameters.
 
 ### WebSocket Market Feed
 
@@ -473,14 +657,20 @@ All helpers accept snake_case keys; the client camelizes them before calling `/v
 ### Kill Switch
 
 ```ruby
-DhanHQ::Models::KillSwitch.activate    # => {"killSwitchStatus"=>"ACTIVATE"}
-DhanHQ::Models::KillSwitch.deactivate  # => {"killSwitchStatus"=>"DEACTIVATE"}
+activate_payload   = DhanHQ::Models::KillSwitch.activate
+deactivate_payload = DhanHQ::Models::KillSwitch.deactivate
+
+DhanHQ::Models::KillSwitch.snake_case(activate_payload)
+# => { kill_switch_status: "ACTIVATE" }
+
+DhanHQ::Models::KillSwitch.snake_case(deactivate_payload)
+# => { kill_switch_status: "DEACTIVATE" }
 
 # Explicit status update
 DhanHQ::Models::KillSwitch.update("ACTIVATE")
 ```
 
-Only `"ACTIVATE"` and `"DEACTIVATE"` are accepted—any other value raises `DhanHQ::Error`.
+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.
 
 ---