DhanHQ 2.1.0

data/README1.md

@@ -0,0 +1,521 @@
+# DhanHQ - Ruby Client for DhanHQ API
+
+DhanHQ is a **Ruby client** for interacting with **Dhan API v2.0**. It provides **ActiveRecord-like** behavior, **RESTful resource management**, and **ActiveModel validation** for seamless integration into **algorithmic trading applications**.
+
+## ⚡ Features
+
+✅ **ORM-like Interface** (`find`, `all`, `where`, `save`, `update`, `destroy`)
+✅ **ActiveModel Integration** (`validations`, `errors`, `serialization`)
+✅ **Resource Objects for Trading** (`Orders`, `Positions`, `Holdings`, etc.)
+✅ **Supports WebSockets for Market Feeds**
+✅ **Error Handling & Validations** (`ActiveModel::Errors`)
+✅ **DRY & Modular Code** (`Helpers`, `Contracts`, `Request Handling`)
+
+---
+
+## 📌 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'DhanHQ', git: 'https://github.com/shubhamtaywade82/dhanhq-client.git', branch: 'main'
+```
+
+Then execute:
+
+```
+bundle install
+```
+
+Or install it manually:
+
+```
+gem install dhanhq
+```
+
+🔹 Configuration
+Set your DhanHQ API credentials:
+
+```ruby
+require 'DhanHQ'
+
+DhanHQ.configure_with_env
+DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
+```
+
+**Minimum environment variables**
+
+* `CLIENT_ID` – trading account client id issued by Dhan.
+* `ACCESS_TOKEN` – API access token generated from the Dhan console.
+
+If either key is missing `configure_with_env` raises an error. Ensure your
+application loads them into `ENV` before requiring the gem.
+
+**Optional overrides**
+
+* `DHAN_LOG_LEVEL` – change logger verbosity (`INFO` default).
+* `DHAN_BASE_URL` – point REST calls to an alternate host.
+* `DHAN_WS_VERSION` – lock WebSocket connections to a specific version.
+* `DHAN_WS_ORDER_URL` – override the order update WebSocket endpoint.
+* `DHAN_WS_USER_TYPE` – choose between `SELF` and `PARTNER` streaming modes.
+* `DHAN_PARTNER_ID` / `DHAN_PARTNER_SECRET` – required when streaming as a partner.
+
+Create a `.env` file in your project root to supply the minimum values (and any
+optional overrides you need):
+
+```dotenv
+CLIENT_ID=your_client_id
+ACCESS_TOKEN=your_access_token
+```
+
+The gem requires `dotenv/load`, so these variables are loaded automatically when you require `DhanHQ`.
+
+To override defaults (base URL, WebSocket settings, partner credentials), set
+`DHAN_BASE_URL`, `DHAN_WS_VERSION`, `DHAN_WS_ORDER_URL`, `DHAN_WS_USER_TYPE`,
+`DHAN_PARTNER_ID`, and `DHAN_PARTNER_SECRET` before calling
+`configure_with_env`.
+
+## 🚀 Usage
+
+✅ Placing an Order
+
+```ruby
+order = DhanHQ::Models::Order.new(
+  transaction_type: "BUY",
+  exchange_segment: "NSE_FNO",
+  product_type: "MARGIN",
+  order_type: "LIMIT",
+  validity: "DAY",
+  security_id: "43492",
+  quantity: 125,
+  price: 100.0
+)
+
+order.save
+puts order.persisted? # true
+```
+
+✅ Fetching an Order
+
+```ruby
+order = DhanHQ::Models::Order.find("452501297117")
+puts order.price # Current price of the order
+```
+
+✅ Updating an Order
+
+```ruby
+order.update(price: 105.0)
+puts order.price # 105.0
+```
+
+✅ Canceling an Order
+
+```ruby
+order.cancel
+```
+
+✅ Fetching All Orders
+
+```ruby
+orders = DhanHQ::Models::Order.all
+puts orders.count
+```
+
+✅ Querying Orders
+
+```ruby
+pending_orders = DhanHQ::Models::Order.where(status: "PENDING")
+puts pending_orders.first.order_id
+```
+
+✅ Exiting Positions
+
+```ruby
+positions = DhanHQ::Models::Position.all
+position = positions.first
+position.exit!
+```
+
+### Orders
+
+#### Place
+
+```ruby
+order = DhanHQ::Models::Order.new(transaction_type: "BUY", security_id: "123", quantity: 1)
+order.save
+```
+
+#### Modify
+
+```ruby
+order.modify(price: 102.5)
+```
+
+#### Cancel
+
+```ruby
+order.cancel
+```
+
+### Trades
+
+```ruby
+DhanHQ::Models::Trade.today
+DhanHQ::Models::Trade.find_by_order_id("452501297117")
+```
+
+### Positions
+
+```ruby
+positions = DhanHQ::Models::Position.all
+active = DhanHQ::Models::Position.active
+DhanHQ::Models::Position.convert(position_id: "1", product_type: "CNC")
+```
+
+### Holdings
+
+```ruby
+DhanHQ::Models::Holding.all
+```
+
+### Funds
+
+```ruby
+DhanHQ::Models::Funds.fetch
+balance = DhanHQ::Models::Funds.balance
+```
+
+### Option Chain
+
+```ruby
+DhanHQ::Models::OptionChain.fetch(security_id: "1333", expiry_date: "2024-06-30")
+DhanHQ::Models::OptionChain.fetch_expiry_list(security_id: "1333")
+```
+
+### Historical Data
+
+```ruby
+DhanHQ::Models::HistoricalData.daily(security_id: "1333", from_date: "2024-01-01", to_date: "2024-01-31")
+DhanHQ::Models::HistoricalData.intraday(security_id: "1333", interval: "15")
+```
+
+## 🔹 Available Resources
+
+| Resource                 | Model                            | Actions                                             |
+| ------------------------ | -------------------------------- | --------------------------------------------------- |
+| Orders                   | `DhanHQ::Models::Models::Order`          | `find`, `all`, `where`, `place`, `update`, `cancel` |
+| Trades                   | `DhanHQ::Models::Models::Trade`          | `all`, `find_by_order_id`                           |
+| Forever Orders           | `DhanHQ::Models::Models::ForeverOrder`   | `create`, `find`, `modify`, `cancel`, `all`         |
+| Holdings                 | `DhanHQ::Models::Models::Holding`        | `all`                                               |
+| Positions                | `DhanHQ::Models::Models::Position`       | `all`, `find`, `exit!`                              |
+| Funds & Margin           | `DhanHQ::Models::Models::Funds`          | `fund_limit`, `margin_calculator`                   |
+| Ledger                   | `DhanHQ::Models::Models::Ledger`         | `all`                                               |
+| Market Feeds             | `DhanHQ::Models::Models::MarketFeed`     | `ltp, ohlc`, `quote`                                |
+| Historical Data (Charts) | `DhanHQ::Models::Models::HistoricalData` | `daily`, `intraday`                                 |
+| Option Chain             | `DhanHQ::Models::Models::OptionChain`    | `fetch`, `fetch_expiry_list`                        |
+
+## 📌 Development
+
+Set `DHAN_DEBUG=true` to log HTTP requests during development:
+
+```bash
+export DHAN_DEBUG=true
+```
+
+Running Tests
+
+```bash
+bundle exec rspec
+```
+
+Installing Locally
+
+```bash
+bundle exec rake install
+```
+
+Releasing a New Version
+
+```bash
+bundle exec rake release
+```
+---
+
+## WebSocket Market Feed (NEW)
+
+### What you get
+
+* **Modes**
+
+  * `:ticker` → LTP + LTT
+  * `:quote`  → OHLCV + totals (recommended default)
+  * `:full`   → quote + **OI** + **best-5 depth**
+* **Normalized ticks** (Hash):
+
+  ```ruby
+  {
+    kind: :quote,                 # :ticker | :quote | :full | :oi | :prev_close | :misc
+    segment: "NSE_FNO",           # string enum
+    security_id: "12345",
+    ltp: 101.5,
+    ts:  1723791300,              # LTT epoch (sec) if present
+    vol: 123456,                  # quote/full
+    atp: 100.9,                   # quote/full
+    day_open: 100.1, day_high: 102.4, day_low: 99.5, day_close: nil,
+    oi: 987654,                   # full or OI packet
+    bid: 101.45, ask: 101.55      # from depth (mode :full)
+  }
+  ```
+
+### Start, subscribe, stop
+
+```ruby
+DhanHQ.configure_with_env
+DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
+
+ws = DhanHQ::WS::Client.new(mode: :quote).start
+
+ws.on(:tick) do |t|
+  puts "[#{t[:segment]}:#{t[:security_id]}] LTP=#{t[:ltp]} kind=#{t[:kind]}"
+end
+
+# Subscribe instruments (≤100 per frame; send multiple frames if needed)
+ws.subscribe_one(segment: "IDX_I",   security_id: "13")     # NIFTY index value
+ws.subscribe_one(segment: "NSE_FNO", security_id: "12345")  # an option
+
+# Unsubscribe
+ws.unsubscribe_one(segment: "NSE_FNO", security_id: "12345")
+
+# Graceful disconnect (sends broker disconnect code 12, no reconnect)
+ws.disconnect!
+
+# Or hard stop (no broker message, just closes and halts loop)
+ws.stop
+
+# Safety: kill all local sockets (useful in IRB)
+DhanHQ::WS.disconnect_all_local!
+```
+
+### Under the hood
+
+* **Request codes** (per Dhan docs)
+
+  * Subscribe: **15** (ticker), **17** (quote), **21** (full)
+  * Unsubscribe: **16**, **18**, **22**
+  * Disconnect: **12**
+* **Limits**
+
+  * Up to **100 instruments per SUB/UNSUB** message (client auto-chunks)
+  * Up to 5 WS connections per user (per Dhan)
+* **Backoff & 429 cool-off**
+
+  * Exponential backoff with jitter
+  * Handshake **429** triggers a **60s cool-off** before retry
+* **Reconnect & resubscribe**
+
+  * On reconnect the client resends the **current subscription snapshot** (idempotent)
+* **Graceful shutdown**
+
+  * `ws.disconnect!` or `ws.stop` prevents reconnects
+  * An `at_exit` hook stops all registered WS clients to avoid leaked sockets
+
+---
+
+## Exchange Segment Enums
+
+Use the string enums below in WS `subscribe_*` and REST params:
+
+| Enum           | Exchange | Segment           |
+| -------------- | -------- | ----------------- |
+| `IDX_I`        | Index    | Index Value       |
+| `NSE_EQ`       | NSE      | Equity Cash       |
+| `NSE_FNO`      | NSE      | Futures & Options |
+| `NSE_CURRENCY` | NSE      | Currency          |
+| `BSE_EQ`       | BSE      | Equity Cash       |
+| `MCX_COMM`     | MCX      | Commodity         |
+| `BSE_CURRENCY` | BSE      | Currency          |
+| `BSE_FNO`      | BSE      | Futures & Options |
+
+---
+
+## Accessing ticks elsewhere in your app
+
+### Direct handler
+
+```ruby
+ws.on(:tick) { |t| do_something_fast(t) } # avoid heavy work here
+```
+
+### Shared TickCache (recommended)
+
+```ruby
+# app/services/live/tick_cache.rb
+class TickCache
+  MAP = Concurrent::Map.new
+  def self.put(t)  = MAP["#{t[:segment]}:#{t[:security_id]}"] = t
+  def self.get(seg, sid) = MAP["#{seg}:#{sid}"]
+  def self.ltp(seg, sid) = get(seg, sid)&.dig(:ltp)
+end
+
+ws.on(:tick) { |t| TickCache.put(t) }
+ltp = TickCache.ltp("NSE_FNO", "12345")
+```
+
+### Filtered callback
+
+```ruby
+def on_tick_for(ws, segment:, security_id:, &blk)
+  key = "#{segment}:#{security_id}"
+  ws.on(:tick){ |t| blk.call(t) if "#{t[:segment]}:#{t[:security_id]}" == key }
+end
+```
+
+---
+
+## Rails integration (example)
+
+**Goal:** Generate signals from clean **Historical Intraday OHLC** (5-min bars), and use **WebSocket** only for **exits/trailing** on open option legs.
+
+1. **Initializer**
+   `config/initializers/dhanhq.rb`
+
+   ```ruby
+   DhanHQ.configure_with_env
+   DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
+   ```
+
+2. **Start WS supervisor**
+   `config/initializers/stream.rb`
+
+   ```ruby
+   INDICES = [
+     { segment: "IDX_I", security_id: "13" },  # NIFTY index value
+     { segment: "IDX_I", security_id: "25" }   # BANKNIFTY index value
+   ]
+
+   Rails.application.config.to_prepare do
+     $WS = DhanHQ::WS::Client.new(mode: :quote).start
+     $WS.on(:tick) do |t|
+       TickCache.put(t)
+       Execution::PositionGuard.instance.on_tick(t)  # trailing & fast exits
+     end
+     INDICES.each { |i| $WS.subscribe_one(segment: i[:segment], security_id: i[:security_id]) }
+   end
+   ```
+
+3. **Bar fetch (every 5 min) via Historical API**
+
+   * Fetch intraday OHLC at 5-minute boundaries.
+   * Update your `CandleSeries`; on each closed bar, run strategy to emit signals.
+     *(Use your existing `Bars::FetchLoop` + `CandleSeries` code.)*
+
+4. **Routing & orders**
+
+   * On signal: place **Super Order** (SL/TP/TSL) or fallback to Market + local trailing.
+   * After a successful place, **register** the leg in `PositionGuard` and **subscribe** its option on WS.
+
+5. **Shutdown**
+
+   ```ruby
+   at_exit { DhanHQ::WS.disconnect_all_local! }
+   ```
+
+---
+
+## Super Orders (example)
+
+```ruby
+intent = {
+  exchange_segment: "NSE_FNO",
+  security_id:      "12345",   # option
+  transaction_type: "BUY",
+  quantity:         50,
+  # derived risk params from ATR/ADX
+  take_profit:      0.35,      # 35% target
+  stop_loss:        0.18,      # 18% SL
+  trailing_sl:      0.12       # 12% trail
+}
+
+# If your SuperOrder model exposes create/modify:
+o = DhanHQ::Models::SuperOrder.create(intent)
+# or fallback:
+mkt = DhanHQ::Models::Order.new(
+  transaction_type: "BUY", exchange_segment: "NSE_FNO",
+  order_type: "MARKET", validity: "DAY",
+  security_id: "12345", quantity: 50
+).save
+```
+
+If you placed a Super Order and want to trail SL upward using WS ticks:
+
+```ruby
+DhanHQ::Models::SuperOrder.modify(
+  order_id: o.order_id,
+  stop_loss: new_abs_price,    # broker API permitting
+  trailing_sl: nil
+)
+```
+
+---
+
+## Packet parsing (for reference)
+
+* **Response Header (8 bytes)**:
+  `feed_response_code (u8, BE)`, `message_length (u16, BE)`, `exchange_segment (u8, BE)`, `security_id (i32, LE)`
+* **Packets supported**:
+
+  * **1** Index (surface as raw/misc unless documented)
+  * **2** Ticker: `ltp`, `ltt`
+  * **4** Quote: `ltp`, `ltt`, `atp`, `volume`, totals, `day_*`
+  * **5** OI: `open_interest`
+  * **6** Prev Close: `prev_close`, `oi_prev`
+  * **7** Market Status (raw/misc unless documented)
+  * **8** Full: quote + `open_interest` + 5× depth (bid/ask)
+  * **50** Disconnect: reason code
+
+---
+
+## Best practices
+
+* Keep the `on(:tick)` handler **non-blocking**; push work to a queue/thread.
+* Use `mode: :quote` for most strategies; switch to `:full` only if you need depth/OI in real-time.
+* Call **`ws.disconnect!`** (or `ws.stop`) when leaving IRB / tests.
+  Use **`DhanHQ::WS.disconnect_all_local!`** to be extra safe.
+* Don’t exceed **100 instruments per SUB frame** (the client auto-chunks).
+* Avoid rapid connect/disconnect loops; the client already **backs off & cools off** when server replies 429.
+
+---
+
+## Troubleshooting
+
+* **429: Unexpected response code**
+  You connected too frequently or have too many sockets. The client auto-cools off for **60s** and backs off. Prefer `ws.disconnect!` before reconnecting; and call `DhanHQ::WS.disconnect_all_local!` to kill stragglers.
+* **No ticks after reconnect**
+  Ensure you re-subscribed after a clean start (the client resends the snapshot automatically on reconnect).
+* **Binary parse errors**
+  Run with `DHAN_LOG_LEVEL=DEBUG` to inspect; we safely drop malformed frames and keep the loop alive.
+
+---
+
+
+## 📌 Contributing
+
+Bug reports and pull requests are welcome on GitHub at:
+🔗 <https://github.com/shubhamtaywade82/dhanhq>
+
+This project follows a code of conduct to maintain a safe and welcoming community.
+
+## 📌 License
+
+This gem is available under the MIT License.
+🔗 <https://opensource.org/licenses/MIT>
+
+## 📌 Code of Conduct
+
+Everyone interacting in the DhanHQ project is expected to follow the
+🔗 Code of Conduct.
+
+```markdown
+This **README.md** file is structured and formatted for **GitHub** or any **Markdown-compatible** documentation system. 🚀
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/TAGS

@@ -0,0 +1,10 @@
+
+lib/DhanHQ/version.rb,97
+module DhanHQDhanHQ
3,0
+  VERSION = "0.1.0"VERSION
4,0
+  VERSION = "0.1.0"DhanHQ::VERSION
4,0
+
+lib/DhanHQ.rb,123
+module DhanHQDhanHQ
5,0
+  class Error < StandardError; endError
6,0
+  class Error < StandardError; endDhanHQ::Error
6,0

data/TODO-1.md

@@ -0,0 +1,14 @@
+# TODO List
+
+- [x] Wire `DhanHQ::Models::Order.place` to the resource’s `create` endpoint so order placement stops raising `NoMethodError` (`lib/DhanHQ/models/order.rb:73`, `lib/DhanHQ/resources/orders.rb:14`).
+- [x] Align `Order#cancel` with `DhanHQ::Resources::Orders#cancel` to restore cancellation support (`lib/DhanHQ/models/order.rb:120`, `lib/DhanHQ/resources/orders.rb:26`).
+- [x] Rework `Order#modify` to send a proper payload and capture the response instead of delegating to the broken generic update flow (`lib/DhanHQ/models/order.rb:99`, `lib/DhanHQ/core/base_model.rb:155`).
+- [x] Repair or replace the shared CRUD helpers in `BaseModel` so URL construction and response handling behave (`lib/DhanHQ/core/base_model.rb:120`, `lib/DhanHQ/core/base_model.rb:129`, `lib/DhanHQ/core/base_model.rb:155`).
+- [x] Make `BaseModel#save!` raise a real exception type (e.g. `DhanHQ::Error`) to avoid the current `TypeError` (`lib/DhanHQ/core/base_model.rb:165`).
+- [x] Strip read-only attributes before posting modify requests to pass API validation (`lib/DhanHQ/models/order.rb:166`, `lib/DhanHQ/core/base_model.rb:197`).
+- [x] Require `fileutils` in the WebSocket singleton lock so acquiring the lock no longer raises (`lib/DhanHQ/ws/singleton_lock.rb:11`).
+- [x] Implement EDIS and kill-switch endpoints surfaced in the OpenAPI spec so the client can call `/edis/bulkform`, `/edis/form`, `/edis/inquire/{isin}`, `/edis/tpin`, and `/killswitch` (`/home/nemesis/dhanhq-bundled.json:827`, `/home/nemesis/dhanhq-bundled.json:873`, `/home/nemesis/dhanhq-bundled.json:949`).
+- [x] Correct `ForeverOrders#all` to hit `/v2/forever/orders` instead of the undocumented `/v2/forever/all` path (`lib/DhanHQ/resources/forever_orders.rb:9`, `/home/nemesis/dhanhq-bundled.json:578`).
+- [x] Run the existing `MarginCalculatorContract` before posting to `/margincalculator` so required fields like `transactionType` and `productType` are enforced client-side (`lib/DhanHQ/models/margin.rb:23`, `lib/DhanHQ/contracts/margin_calculator_contract.rb:5`).
+- [ ] Validate slice-order payloads with `SliceOrderContract` to uphold STOP_LOSS requirements before calling `/orders/slicing` (`lib/DhanHQ/models/order.rb:217`, `lib/DhanHQ/contracts/slice_order_contract.rb:30`, `/home/nemesis/dhanhq-bundled.json:234`).
+- [x] Add a contract-backed validation for `Position.convert` so `PositionConversionRequest` fields like `fromProductType` and `convertQty` are checked prior to hitting `/positions/convert` (`lib/DhanHQ/models/position.rb:39`, `/home/nemesis/dhanhq-bundled.json:1391`).

data/TODO.md

@@ -0,0 +1,127 @@
+Below are several suggestions and improvements you can consider to further enhance your gem’s structure, error handling, validations, and overall design:
+
+---
+
+### **1. Decouple HTTP/Resource Handling from Models**
+
+- **Inject the API instance:**
+  Instead of having your BaseModel inherit from or tightly couple to BaseAPI, you already moved to instantiating a shared API object via the `api` method. This is good for testing and future flexibility. Consider allowing dependency injection so that in tests you can supply a mock client.
+
+- **Separate Resource Objects:**
+  Create separate “Resource” classes for each endpoint (e.g. Orders, Funds, MarketFeed, etc.) that are solely responsible for forming the correct URL and HTTP call. Then, your models (Order, Funds, etc.) become thin wrappers on top of these resources.
+
+---
+
+### **2. Improved Error Handling**
+
+- **Consistent Error Hierarchy:**
+  You already have a structured set of custom errors. Ensure that all API responses are wrapped in a uniform error response. For instance, for network errors, consider implementing a retry mechanism for transient errors (such as timeouts or 429 responses).
+
+- **Retry Mechanism:**
+  Enhance your Client by adding an optional retry strategy (with exponential backoff) for cases when a request fails due to rate limiting or temporary network issues.
+
+- **Detailed Logging:**
+  Enable more granular logging (perhaps controlled via configuration) to help troubleshoot errors without exposing sensitive information.
+
+---
+
+### **3. Enhanced Validations**
+
+- **Centralize Contracts:**
+  Use your `BaseContract` as a foundation for all contracts so that common rules and messages are shared. Consider adding custom predicates if you need more complex business rules.
+  For example, you can write a custom predicate for “valid_order_quantity” that could check against exchange limits.
+
+- **Error Messages & Localization:**
+  Consider standardizing error messages across contracts so that errors returned by your gem are predictable. If needed, use a localization mechanism to map raw error keys to user-friendly messages.
+
+- **Use Dry-Struct (Optional):**
+  If you want stronger typing and immutability for your models, you might consider using [dry-struct](https://dry-rb.org/gems/dry-struct/) in combination with dry-validation. This can help enforce attribute types and reduce runtime errors.
+
+---
+
+### **4. Model Improvements and Convenience Methods**
+
+- **Dynamic Attribute Getters/Setters:**
+  Your current approach to dynamically assign attribute getters is good. You might consider also generating setters if you want to allow updating the local object state before pushing an update to the API.
+
+- **CRUD Methods Consistency:**
+  Ensure that your instance methods like `update`, `delete`, `refresh`, etc., always return either a new instance of the model (with updated values) or a well-formed error object. This will make it easier for users to chain operations.
+
+- **Merge Updated Attributes Correctly:**
+  In your `modify` method (for orders, for instance), make sure you correctly merge the existing attributes with the new ones before issuing the PUT request. Currently, there’s a commented line and then an immediate call to `update(attributes)`—this should be updated to use the merged `updated_params`.
+
+- **Caching or Memoization:**
+  If your API endpoints don’t change frequently (e.g., for retrieving configuration or instruments), consider caching responses to minimize API calls.
+
+---
+
+### **5. Testing & VCR**
+
+- **VCR Cassette Management:**
+  Ensure that your VCR cassettes capture both successful and error responses. When you need to simulate scenarios (e.g., update order, cancellation), manually edit the cassette files to reflect those states if the real API cannot produce them reliably.
+
+- **Spec Coverage:**
+  Write comprehensive specs for each model that exercises both the “happy path” and error cases. For instance, ensure that Order.create returns an order with the proper attributes, and that Order.update merges new attributes as expected.
+
+---
+
+### **6. Configuration Improvements**
+
+- **Global Configuration Object:**
+  Continue iterating on the existing configuration helpers while keeping `DhanHQ.configure_with_env` as the primary entrypoint. Provide any additional toggles by reading from ENV so docs can focus on the single bootstrap path.
+
+---
+
+### **7. Overall Architecture and Documentation**
+
+- **Document Model Methods:**
+  Ensure that each model (Order, Funds, OptionChain, etc.) is well documented. Explain the expected inputs/outputs and any side effects.
+
+- **Separation of Concerns:**
+  Keep your gem’s responsibilities clear:
+
+  - **Client:** Low-level HTTP calls with error handling and rate limiting.
+  - **Resources:** Form URLs and endpoint-specific logic.
+  - **Models:** Map resource data to business objects and provide CRUD operations with validation.
+  - **Contracts:** Define dry-validation contracts for input validation.
+
+- **Extensibility:**
+  Consider ways to allow users to extend models or override default behavior. For instance, provide hooks (callbacks) before or after an update or create operation.
+
+---
+
+### **Example of a Revised Modify Method in Order Model**
+
+Here’s a small snippet that shows how you might update the `modify` method in the Order model to merge attributes properly:
+
+```ruby
+def modify(new_params)
+  raise "Order ID is required to modify an order" unless id
+
+  # Merge current attributes with new ones
+  updated_params = attributes.merge(new_params)
+  validate_params!(updated_params, DhanHQ::Contracts::ModifyOrderContract)
+
+  # Perform the PUT request with merged parameters
+  response = self.class.api.put("#{self.class.resource_path}/#{id}", params: updated_params)
+
+  # If the response indicates a transitional status (e.g., "TRANSIT"), re-fetch the order
+  if success_response?(response) && response[:orderStatus] == "TRANSIT"
+    return self.class.find(id)
+  end
+
+  DhanHQ::ErrorObject.new(response)
+end
+```
+
+---
+
+### **Conclusion**
+
+Implementing these improvements will result in a more robust, testable, and maintainable gem. Enhancing error handling, validations, and separation of concerns not only eases future modifications but also improves the overall developer experience when using the gem.
+
+Feel free to ask if you’d like more details or examples on any of these suggestions!
+
+PROGRESS:
+
+1. OptionChain working