DhanHQ 2.4.0 → 2.6.0

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.
 
 ---
 

data/{README1.md → docs/ARCHIVE_README.md}

@@ -81,11 +81,11 @@ To override defaults (base URL, WebSocket settings, partner credentials), set
 
 ```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: 125,
   price: 100.0
@@ -125,7 +125,7 @@ puts orders.count
 ✅ Querying Orders
 
 ```ruby
-pending_orders = DhanHQ::Models::Order.where(status: "PENDING")
+pending_orders = DhanHQ::Models::Order.where(status: DhanHQ::Constants::OrderStatus::PENDING)
 puts pending_orders.first.order_id
 ```
 
@@ -142,7 +142,7 @@ position.exit!
 #### Place
 
 ```ruby
-order = DhanHQ::Models::Order.new(transaction_type: "BUY", security_id: "123", quantity: 1)
+order = DhanHQ::Models::Order.new(transaction_type: DhanHQ::Constants::TransactionType::BUY, security_id: "123", quantity: 1)
 order.save
 ```
 
@@ -170,7 +170,7 @@ DhanHQ::Models::Trade.find_by_order_id("452501297117")
 ```ruby
 positions = DhanHQ::Models::Position.all
 active = DhanHQ::Models::Position.active
-DhanHQ::Models::Position.convert(position_id: "1", product_type: "CNC")
+DhanHQ::Models::Position.convert(position_id: "1", product_type: DhanHQ::Constants::ProductType::CNC)
 ```
 
 ### Holdings
@@ -196,8 +196,8 @@ DhanHQ::Models::OptionChain.fetch_expiry_list(security_id: "1333")
 ### Historical Data
 
 ```ruby
-DhanHQ::Models::HistoricalData.daily(security_id: "1333", exchange_segment: "NSE_EQ", instrument: "EQUITY", from_date: "2024-01-01", to_date: "2024-01-31")
-DhanHQ::Models::HistoricalData.intraday(security_id: "1333", exchange_segment: "NSE_EQ", instrument: "EQUITY", interval: "15", from_date: "2024-09-11", to_date: "2024-09-15")
+DhanHQ::Models::HistoricalData.daily(security_id: "1333", exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ, instrument: DhanHQ::Constants::InstrumentType::EQUITY, from_date: "2024-01-01", to_date: "2024-01-31")
+DhanHQ::Models::HistoricalData.intraday(security_id: "1333", exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ, instrument: DhanHQ::Constants::InstrumentType::EQUITY, interval: "15", from_date: "2024-09-11", to_date: "2024-09-15")
 ```
 
 ### Instrument Model with Convenience Methods
@@ -278,7 +278,7 @@ bundle exec rake release
   ```ruby
   {
     kind: :quote,                 # :ticker | :quote | :full | :oi | :prev_close | :misc
-    segment: "NSE_FNO",           # string enum
+    segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO,           # string enum
     security_id: "12345",
     ltp: 101.5,
     ts:  1723791300,              # LTT epoch (sec) if present
@@ -303,11 +303,11 @@ ws.on(:tick) do |t|
 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
+ws.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I,   security_id: "13")     # NIFTY index value
+ws.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO, security_id: "12345")  # an option
 
 # Unsubscribe
-ws.unsubscribe_one(segment: "NSE_FNO", security_id: "12345")
+ws.unsubscribe_one(segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO, security_id: "12345")
 
 # Graceful disconnect (sends broker disconnect code 12, no reconnect)
 ws.disconnect!
@@ -412,8 +412,8 @@ end
 
    ```ruby
    INDICES = [
-     { segment: "IDX_I", security_id: "13" },  # NIFTY index value
-     { segment: "IDX_I", security_id: "25" }   # BANKNIFTY index value
+     { segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13" },  # NIFTY index value
+     { segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "25" }   # BANKNIFTY index value
    ]
 
    Rails.application.config.to_prepare do

data/docs/AUTHENTICATION.md

@@ -105,7 +105,7 @@ Rescue `AuthenticationError` for local config/token resolution failures; rescue
 
 - [README.md](../README.md) — Configuration and “Dynamic access token”
 - [GUIDE.md](../GUIDE.md) — Dynamic access token and RenewToken
-- [rails_integration.md](rails_integration.md) — Rails initializer with optional `access_token_provider` and RenewToken
+- [RAILS_INTEGRATION.md](RAILS_INTEGRATION.md) — Rails initializer with optional `access_token_provider` and RenewToken
 - [TESTING_GUIDE.md](TESTING_GUIDE.md) — Config examples and RenewToken
 - [CHANGELOG.md](../CHANGELOG.md) — 2.2.0 and 2.2.1 auth and token changes
 
@@ -113,50 +113,112 @@ Rescue `AuthenticationError` for local config/token resolution failures; rescue
 # SUPPORTED AUTHENTICATION AND TOKEN GENERATION APPROACHES:
 
 We now support five distinct authentication approaches in this gem.
+
 1️⃣ Static token (manual, simplest)
 What: You paste a token you got from Dhan (web, OAuth, partner, whatever) into config.
 How:
-DhanHQ.configure do |config|  config.client_id    = ENV["DHAN_CLIENT_ID"]  config.access_token = ENV["DHAN_ACCESS_TOKEN"]end
+```ruby
+DhanHQ.configure do |config|
+  config.client_id    = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
+end
+```
 When: You’re OK rotating tokens manually (e.g. cron job, ops runbook).
+
 2️⃣ Dynamic token via access_token_provider
 What: Gem asks you for a token on every request (proc/lambda).
 How:
-DhanHQ.configure do |config|  config.client_id = ENV["DHAN_CLIENT_ID"]  config.access_token_provider = -> { MyTokenStore.fetch_current_token }  config.on_token_expired = ->(error) { MyTokenStore.refresh!(error) }end
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = ENV["DHAN_CLIENT_ID"]
+  config.access_token_provider = -> { MyTokenStore.fetch_current_token }
+  config.on_token_expired = ->(error) { MyTokenStore.refresh!(error) }
+end
+```
 Behavior:
 On 401 (auth failure), client calls on_token_expired, then retries once using a fresh token from access_token_provider.
+
 3️⃣ Fetch-from-token-endpoint (configure_from_token_endpoint)
 What: Gem calls your HTTP endpoint once to get access_token + client_id.
 How:
-DhanHQ.configure_from_token_endpoint(  base_url:    "https://myapp.com",  bearer_token: ENV["DHAN_TOKEN_ENDPOINT_BEARER"])# expects JSON: { access_token: "...", client_id: "...", base_url: "..." (optional) }
+```ruby
+DhanHQ.configure_from_token_endpoint(
+  base_url:    "https://myapp.com",
+  bearer_token: ENV["DHAN_TOKEN_ENDPOINT_BEARER"]
+)
+# expects JSON: { access_token: "...", client_id: "...", base_url: "..." (optional) }
+```
 When: Multi-tenant or central credential service, you don’t want tokens in ENV directly.
+
 4️⃣ TOTP-based token generation (new DhanHQ::Auth flow)
 Module API (low-level)
 What: Direct call to Dhan’s generateAccessToken endpoint using TOTP.
-totp = DhanHQ::Auth.generate_totp(ENV["DHAN_TOTP_SECRET"])response = DhanHQ::Auth.generate_access_token(  dhan_client_id: ENV["DHAN_CLIENT_ID"],  pin:           ENV["DHAN_PIN"],  totp:          totp)token  = response["accessToken"]expiry = response["expiryTime"]
+```ruby
+totp = DhanHQ::Auth.generate_totp(ENV["DHAN_TOTP_SECRET"])
+response = DhanHQ::Auth.generate_access_token(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp:          totp
+)
+token  = response["accessToken"]
+expiry = response["expiryTime"]
+```
+
 Client API (high-level, returns TokenResponse)
-client = DhanHQ::Client.new(api_type: :order_api)token = client.generate_access_token(  dhan_client_id: ENV["DHAN_CLIENT_ID"],  pin:           ENV["DHAN_PIN"],  totp_secret:   ENV["DHAN_TOTP_SECRET"] # or `totp:` if you computed it)# auto-applies token + client_id to `DhanHQ.configuration`
+```
+client = DhanHQ::Client.new(api_type: :order_api)
+token = client.generate_access_token(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp_secret:   ENV["DHAN_TOTP_SECRET"] # or `totp:` if you computed it
+)
+# auto-applies token + client_id to `DhanHQ.configuration`
+```
+
 When: Fully automated individual setup (no manual web token generation).
+
 5️⃣ Auto token lifecycle management (TokenManager)
 What: Gem handles generate + renew + retry around every API call.
 How:
-client = DhanHQ::Client.new(api_type: :order_api)client.enable_auto_token_management!(  dhan_client_id: ENV["DHAN_CLIENT_ID"],  pin:           ENV["DHAN_PIN"],  totp_secret:   ENV["DHAN_TOTP_SECRET"])# From now on, `client.request` auto-ensures a valid token.
+```ruby
+client = DhanHQ::Client.new(api_type: :order_api)
+client.enable_auto_token_management!(
+  dhan_client_id: ENV["DHAN_CLIENT_ID"],
+  pin:           ENV["DHAN_PIN"],
+  totp_secret:   ENV["DHAN_TOTP_SECRET"]
+)
+# From now on, `client.request` auto-ensures a valid token.
+```
 Behavior:
 On first use: calls TOTP TokenGenerator → applies token.
 Before each request: ensure_valid_token!:
 If no token → generate.
 If needs_refresh? → TokenRenewal (POST /v2/RenewToken) with current token + dhanClientId.
 If renewal fails with auth error → falls back to full generate.
+
 6️⃣ Web-token renewal only (RenewToken)
 Module API:
-response = DhanHQ::Auth.renew_token(  access_token: current_token,  client_id:    ENV["DHAN_CLIENT_ID"])
+```ruby
+response = DhanHQ::Auth.renew_token(
+  access_token: current_token,
+  client_id:    ENV["DHAN_CLIENT_ID"]
+)
+```
 Client / manager (high-level):
-client.renew_access_token (returns TokenResponse, updates config).
-TokenManager#refresh! internally uses Auth::TokenRenewal.
+
+`client.renew_access_token` (returns TokenResponse, updates config).
+`TokenManager#refresh!` internally uses Auth::TokenRenewal.
 When: You’re using web-generated 24h tokens and want to extend them without switching to TOTP.
+
 TL;DR
 Manual: Static token (access_token)
+
 Dynamic: access_token_provider (+ optional on_token_expired)
+
 Central service: configure_from_token_endpoint
+
 Fully automated: TOTP generate (Auth / Client#generate_access_token)
+
 Production-grade automation: enable_auto_token_management! (generate + renew)
+
 If you tell me your exact deployment style (single user box, multi-user SaaS, on-prem, etc.), I can tell you which one you should actually use and what to delete as overkill.

data/docs/CONFIGURATION.md

@@ -0,0 +1,109 @@
+# Configuration Reference
+
+This document covers all configuration options for the DhanHQ Ruby client.
+
+## Quick Setup
+
+```ruby
+require 'dhan_hq'
+DhanHQ.configure_with_env
+```
+
+`configure_with_env` reads `DHAN_CLIENT_ID` and `DHAN_ACCESS_TOKEN` from `ENV` and raises if either is missing.
+
+## Required Environment Variables
+
+| Variable             | Purpose                                           |
+| -------------------- | ------------------------------------------------- |
+| `DHAN_CLIENT_ID`     | Trading account client ID issued by Dhan          |
+| `DHAN_ACCESS_TOKEN`  | API access token generated from the Dhan console  |
+
+## Optional Environment Variables
+
+Set these _before_ calling `configure_with_env` to override defaults:
+
+| Variable                         | Default    | Description                                             |
+| -------------------------------- | ---------- | ------------------------------------------------------- |
+| `DHAN_LOG_LEVEL`                 | `INFO`     | Logger verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`)     |
+| `DHAN_BASE_URL`                  | Dhan prod  | Point REST calls to a different API hostname            |
+| `DHAN_WS_VERSION`                | latest     | Pin WebSocket connections to a specific API version     |
+| `DHAN_WS_ORDER_URL`              | Dhan prod  | Override the order update WebSocket endpoint            |
+| `DHAN_WS_USER_TYPE`              | `SELF`     | Switch between `SELF` and `PARTNER` streaming modes     |
+| `DHAN_PARTNER_ID`                | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
+| `DHAN_PARTNER_SECRET`            | —          | Required when `DHAN_WS_USER_TYPE=PARTNER`               |
+| `DHAN_CONNECT_TIMEOUT`           | `10`       | Connection timeout in seconds                           |
+| `DHAN_READ_TIMEOUT`              | `30`       | Read timeout in seconds                                 |
+| `DHAN_WRITE_TIMEOUT`             | `30`       | Write timeout in seconds                                |
+| `DHAN_WS_MAX_TRACKED_ORDERS`     | `10000`    | Maximum orders to track in WebSocket                    |
+| `DHAN_WS_MAX_ORDER_AGE`          | `604800`   | Maximum order age in seconds before cleanup (7 days)    |
+
+## `.env` File Setup
+
+Create a `.env` file in your project root:
+
+```dotenv
+DHAN_CLIENT_ID=your_client_id
+DHAN_ACCESS_TOKEN=your_access_token
+
+# Optional overrides
+DHAN_LOG_LEVEL=DEBUG
+DHAN_CONNECT_TIMEOUT=15
+DHAN_READ_TIMEOUT=60
+```
+
+The gem requires `dotenv/load`, so these variables are loaded automatically when you require `dhan_hq`.
+
+## Block-Style Configuration
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id    = ENV["DHAN_CLIENT_ID"]
+  config.access_token = ENV["DHAN_ACCESS_TOKEN"]
+end
+```
+
+## Logging
+
+```ruby
+DhanHQ.logger.level = (ENV["DHAN_LOG_LEVEL"] || "INFO").upcase.then { |level| Logger.const_get(level) }
+```
+
+Set `DHAN_LOG_LEVEL=DEBUG` for full HTTP request/response and WebSocket frame logging during development.
+
+## Dynamic Access Token
+
+For production or OAuth-style flows, resolve the token at **request time**:
+
+```ruby
+DhanHQ.configure do |config|
+  config.client_id = ENV["DHAN_CLIENT_ID"]
+  config.access_token_provider = lambda do
+    token = YourTokenStore.active_token  # e.g. from DB or OAuth
+    raise "Token expired or missing" unless token
+    token
+  end
+  # Optional: called when the API returns 401/token-expired
+  config.on_token_expired = ->(error) { YourTokenStore.refresh! }
+end
+```
+
+- **`access_token_provider`**: Callable (Proc/lambda) returning the token string. Called on every request (no memoization). When set, the gem uses it instead of `access_token`.
+- **`on_token_expired`**: Optional callable invoked when a 401/token-expired triggers a **single retry** (only when `access_token_provider` is set).
+
+For detailed authentication flows, see [AUTHENTICATION.md](AUTHENTICATION.md).
+
+## Available Resources
+
+| Resource                 | Model                                  | Actions                                             |
+| ------------------------ | -------------------------------------- | --------------------------------------------------- |
+| Orders                   | `DhanHQ::Models::Order`                | `find`, `all`, `where`, `place`, `update`, `cancel` |
+| Trades                   | `DhanHQ::Models::Trade`                | `all`, `find_by_order_id`                           |
+| Forever Orders           | `DhanHQ::Models::ForeverOrder`         | `create`, `find`, `modify`, `cancel`, `all`         |
+| Holdings                 | `DhanHQ::Models::Holding`              | `all`                                               |
+| Positions                | `DhanHQ::Models::Position`             | `all`, `find`, `exit!`                              |
+| Funds & Margin           | `DhanHQ::Models::Fund`                 | `fund_limit`, `margin_calculator`                   |
+| Ledger                   | `DhanHQ::Models::Ledger`               | `all`                                               |
+| Market Feeds             | `DhanHQ::Models::MarketFeed`           | `ltp`, `ohlc`, `quote`                              |
+| Historical Data (Charts) | `DhanHQ::Models::HistoricalData`       | `daily`, `intraday`                                 |
+| Option Chain             | `DhanHQ::Models::OptionChain`          | `fetch`, `fetch_expiry_list`                        |
+| Super Orders             | `DhanHQ::Models::SuperOrder`           | `create`, `modify`, `cancel`, `all`                 |