DhanHQ 2.6.3 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef2616285615327c5e0ad08a85440d91617ea66818add0a55e4cd6c5e65512aa
-  data.tar.gz: 4232cfcd4c9626683e3bf993f75aa0a8add2f8c83702435c66edb2c58a3e252e
+  metadata.gz: 6d2ca9bd3c9c4f61504d06e8b2736baf9ded579d04bb21523a9e0c5fe9a74298
+  data.tar.gz: a981472b44efa9c86c1daa83461c27985664a0682022d3aa4b3e925a950788aa
 SHA512:
-  metadata.gz: c0ba9cd2119899ed6c9eaefe27601b142e75abbc541538f241058712b82bccdc5fab6af888489c5ac01423c1bfb387e42cdfcee22487bbafce6d32c7ce6f54b2
-  data.tar.gz: 4107fc9f9a5ced70692469c21a88f2ed6979739af7e3ef5444d1506e5ba574ba4124f2f7f264747a147157164610606ff22408dcd3612649cb19b9f1e558ca8a
+  metadata.gz: 03b2f01541f005e6d9ebd4d706023cf553b17bb80327f480f350e5d465a582006b0fc199cc541a804631a71a034b8cd454c8c715e962b95794df665e75eb0a63
+  data.tar.gz: e7320d2ae5e332238cf0e11bcd0f29ecd368772242019567f5dcb525e4b8baa9e71c5191b51b25724cd090ac82fb113524bb0578480f1bf71b82834bc74cda6d

data/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+This is a pure-Ruby gem (no Rails, no running servers). Development commands are documented in `CLAUDE.md`.
+
+### Quick reference
+
+| Task | Command |
+|------|---------|
+| Install deps | `bundle install` |
+| Tests | `bundle exec rspec` |
+| Lint | `bundle exec rubocop` |
+| Both | `bundle exec rake` |
+| Single spec | `bundle exec rspec spec/path/to_spec.rb` |
+
+### Non-obvious caveats
+
+- **Bundler 4.x required**: The lockfile was bundled with Bundler 4.0.6. Install with `sudo gem install bundler -v 4.0.6` if missing.
+- **`libyaml-dev` must be installed**: The `psych` gem (transitive dep) needs `yaml.h`. Without `libyaml-dev`, `bundle install` fails on native extension build.
+- **`vendor/bundle` path**: Gems are installed to `./vendor/bundle` via `.bundle/config` to avoid needing root write access to `/var/lib/gems`.
+- **No real API calls in tests**: All HTTP interactions are stubbed with WebMock/VCR. No `DHAN_CLIENT_ID` or `DHAN_ACCESS_TOKEN` secrets are needed to run the test suite.
+- **No services to start**: This is a library gem. There is no web server, database, or background worker. Testing is purely `bundle exec rspec` / `bundle exec rubocop`.

data/ARCHITECTURE.md

@@ -48,6 +48,8 @@ This document describes the architecture of the DhanHQ v2 API client gem: layers
 | `resources/` | REST wrappers | One class per API surface (Orders, Positions, MarketFeed, OptionChain, …). Set `HTTP_PATH`, `API_TYPE`; implement get/post/put/delete via BaseAPI. |
 | `contracts/` | Request/response validation | Dry::Validation contracts (PlaceOrderContract, ModifyOrderContract, OptionChainContract, etc.). BaseContract provides shared macros (e.g. lot_size, tick_size). |
 | `auth/` | Token lifecycle | Token generator/renewal/manager for dynamic tokens. |
+| `concerns/` | Shared behavior | Modules included across layers (e.g. `OrderAudit` for live trading guard + audit logging, included in all order resources). |
+| `utils/` | Utilities | Cross-cutting utilities not tied to a single layer (e.g. `NetworkInspector` for IP/hostname/env lookup used by order audit logging). |
 | `ws/` | WebSocket | Connection, packets, decoder, market depth, orders client — isolated from REST. |
 
 ---

data/CHANGELOG.md

@@ -1,3 +1,61 @@
+## [2.8.0] - 2026-03-21
+
+### Added
+
+- **Complete SDK Documentation Overhaul**: Added high-level guides and structured learning paths for Ruby developers:
+  - `BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md`: Strategic advice for Ruby-centric integration.
+  - `BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md`: Step-by-step tutorial for algo trading.
+  - `HOW_TO_USE_DHAN_API_WITH_RUBY.md`: Foundational guide for REST and WebSocket.
+  - `DHAN_API_RUBY_EXAMPLES.md`: Curated collection of common API patterns.
+  - `DHAN_WEBSOCKET_RUBY_GUIDE.md`: Deep dive into real-time market data and order updates.
+  - `DHAN_RUBY_QA.md`: Troubleshooting and frequently asked questions.
+- **Production-Ready Examples**:
+  - `examples/basic_trading_bot.rb`: Skeleton for a strategy-based bot.
+  - `examples/options_watchlist.rb`: Script for monitoring specific option strikes.
+  - `examples/portfolio_monitor.rb`: Live tracker for PnL and position status.
+- **Architectural Visualization**: New `docs/architecture-overview.svg` illustrating the SDK's layered design (Models, Resources, Contracts, WebSocket).
+
+### Changed
+
+- **SDK Positioning**: Updated `README.md` and `DhanHQ.gemspec` to reflect the SDK's status as a "production-grade Ruby SDK for Dhan API v2" with an emphasis on algo trading, portfolio monitoring, and resilient streaming.
+- **Documentation Refinement**: Improved clarity and navigation in `CONFIGURATION.md`, `LIVE_ORDER_UPDATES.md`, `RAILS_INTEGRATION.md`, `TESTING_GUIDE.md`, `TROUBLESHOOTING.md`, and `WEBSOCKET_INTEGRATION.md`.
+
+---
+
+## [2.7.0] - 2026-03-17
+
+### Added
+
+- **Order audit logging across all order types**: Every order submission (regular, super, forever/GTT, and alert orders) now emits a WARN-level structured JSON log line capturing: event type, public IPv4/IPv6, hostname, runtime environment, `security_id`, `correlation_id`, and UTC timestamp. Log output example:
+  ```json
+  {"event":"DHAN_ORDER_ATTEMPT","hostname":"DESKTOP-SHUBHAM","env":"production","ipv4":"122.171.22.40","ipv6":"2401:4900:...","security_id":"11536","correlation_id":"SCALPER_7af1","timestamp":"2026-03-17T06:45:22Z"}
+  ```
+  Events logged: `DHAN_ORDER_ATTEMPT`, `DHAN_ORDER_MODIFY_ATTEMPT`, `DHAN_ORDER_SLICING_ATTEMPT`, `DHAN_SUPER_ORDER_ATTEMPT`, `DHAN_SUPER_ORDER_MODIFY_ATTEMPT`, `DHAN_SUPER_ORDER_CANCEL_ATTEMPT`, `DHAN_FOREVER_ORDER_ATTEMPT`, `DHAN_FOREVER_ORDER_MODIFY_ATTEMPT`, `DHAN_FOREVER_ORDER_CANCEL_ATTEMPT`, `DHAN_ALERT_ORDER_ATTEMPT`, `DHAN_ALERT_ORDER_MODIFY_ATTEMPT`, `DHAN_ALERT_ORDER_DELETE_ATTEMPT`, `DHAN_PNL_EXIT_CONFIGURE_ATTEMPT`, `DHAN_PNL_EXIT_STOP_ATTEMPT`.
+- **`DhanHQ::Concerns::OrderAudit`**: Shared concern providing `log_order_context` and `ensure_live_trading!` — included in `Resources::Orders`, `Resources::SuperOrders`, `Resources::ForeverOrders`, `Resources::AlertOrders`, and `Resources::PnlExit`.
+- **`DhanHQ::Utils::NetworkInspector`**: New utility class that resolves the machine's public IPv4 (via api.ipify.org), IPv6 (via api64.ipify.org), hostname (`Socket.gethostname`), and runtime environment (`RAILS_ENV` / `RACK_ENV` / `APP_ENV`). IP lookups are memoized for the process lifetime; call `NetworkInspector.reset_cache!` to refresh.
+- **Live trading guard**: All mutating order/trader-control calls require `ENV["LIVE_TRADING"]="true"`. Guarded methods:
+  - `Resources::Orders#create`, `#update`, `#slicing`, `#cancel`
+  - `Resources::SuperOrders#create`, `#update`, `#cancel`
+  - `Resources::ForeverOrders#create`, `#update`, `#cancel`
+  - `Resources::AlertOrders#create`, `#update`, `#delete`
+  - `Resources::PnlExit#configure`, `#stop`
+- **`DhanHQ::LiveTradingDisabledError`**: New error class raised when the live trading guard fires.
+- **Correlation ID prefix convention**: Recommended per-app correlation ID prefixes for instant source identification in the Dhan orderbook (e.g. `SCALPER_7af1`, `TRADER_3bc9`). See README.
+
+### Changed
+
+- **`Resources::Orders`**: `#create`, `#update`, `#slicing`, `#cancel` log order context and enforce the live trading guard.
+- **`Resources::SuperOrders`**: `#create`, `#update`, `#cancel` log order context and enforce the live trading guard.
+- **`Resources::ForeverOrders`**: `#create`, `#update`, `#cancel` log order context and enforce the live trading guard.
+- **`Resources::AlertOrders`**: `#create`, `#update`, `#delete` log order context and enforce the live trading guard; `#delete` added.
+- **`Resources::PnlExit`**: `#configure` and `#stop` use `OrderAudit` (guard + audit log).
+
+### Breaking
+
+- **`ENV["LIVE_TRADING"]` required for all order/trader-control mutations**: Any call that creates, updates, cancels, or deletes orders (or configures/stops PnL exit) now raises `LiveTradingDisabledError` unless `ENV["LIVE_TRADING"]="true"`. Affects `Resources::Orders`, `Resources::SuperOrders`, `Resources::ForeverOrders`, `Resources::AlertOrders`, `Resources::PnlExit`, and the corresponding model wrappers. Set `LIVE_TRADING=true` in production and `LIVE_TRADING=false` (or omit) in development/test.
+
+---
+
 ## [2.6.3] - 2026-03-14
 
 ### Added

data/README.md

@@ -1,13 +1,31 @@
-# DhanHQ — Ruby Client for Dhan API v2
+# DhanHQ — The Ruby SDK for Dhan API v2
 
 [![Gem Version](https://badge.fury.io/rb/DhanHQ.svg)](https://rubygems.org/gems/DhanHQ)
 [![CI](https://github.com/shubhamtaywade82/dhanhq-client/actions/workflows/main.yml/badge.svg)](https://github.com/shubhamtaywade82/dhanhq-client/actions/workflows/main.yml)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg)](https://www.ruby-lang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.txt)
 
-A production-grade Ruby SDK for the [Dhan trading API](https://dhanhq.co/docs/v2/) — ORM-like models, WebSocket market feeds, and battle-tested reliability for real trading.
+Build trading systems in Ruby without fighting raw HTTP, fragile auth flows, or unreliable market streams.
 
-## 🚀 60-Second Quick Start
+DhanHQ is a production-grade Ruby SDK for the [Dhan trading API](https://dhanhq.co/docs/v2/), designed for:
+
+- trading bots
+- real-time market data streaming
+- portfolio and order management
+- Rails or standalone trading systems
+
+If you're looking for a Ruby SDK for Dhan API, this is built to be the default choice.
+
+Unlike thin wrappers, DhanHQ gives you:
+
+- typed models for orders, positions, holdings, and more
+- WebSocket clients with auto-reconnect and backoff
+- token lifecycle management with retry-on-401
+- safety rails for live trading
+
+This is closer to trading infrastructure than a simple API client.
+
+## Install and Run in 60 Seconds
 
 ```ruby
 # Gemfile
@@ -22,25 +40,69 @@ DhanHQ.configure do |c|
   c.access_token = ENV["DHAN_ACCESS_TOKEN"]
 end
 
-# You're live
+# You're live — no manual HTTP, no JSON parsing
 positions = DhanHQ::Models::Position.all
-holdings  = DhanHQ::Models::Holding.all
 ```
 
 ---
 
-## Why DhanHQ?
+## Who This Is For
+
+- Ruby developers building trading bots
+- Rails apps integrating the Dhan API
+- Algo trading systems that need clean abstractions over raw HTTP
+- Long-running processes that rely on WebSocket market data
+
+## Who This Is Not For
+
+- One-off scripts where raw HTTP is enough
+- Non-Ruby stacks
+
+---
+
+## Start Here (Pick Your Use Case)
+
+Pick the path that matches what you want to build:
+
+- **Get live prices fast** → [Market Feed WebSocket](#market-feed-ticker--quote--full)
+- **Place orders safely** → [Order Safety](#order-safety)
+- **Build a trading strategy** → [WebSockets](#websockets)
+- **Build a trading bot** → [examples/basic_trading_bot.rb](examples/basic_trading_bot.rb)
+- **Use with Rails** → [docs/RAILS_INTEGRATION.md](docs/RAILS_INTEGRATION.md)
+
+---
+
+## Trust Signals
+
+- **CI on supported Rubies** — GitHub Actions runs RSpec on Ruby 3.2.0 and 3.3.4, plus RuboCop on every push and pull request
+- **Typed domain models** — Orders, Positions, Holdings, Funds, MarketFeed, OptionChain, Super Orders, and more expose a Ruby-first API instead of raw hashes
+- **No real API calls in the default test suite** — WebMock blocks outbound HTTP and VCR covers cassette-backed integration paths
+- **Auth lifecycle support** — static tokens, dynamic token providers, 401 retry with refresh hooks, and token sanitization in logs
+- **WebSocket resilience** — reconnect, backoff, 429 cool-off, local connection cleanup, and dedicated market/order stream clients
+- **Live trading guardrails** — order placement is blocked unless `LIVE_TRADING=true`, and order attempts emit structured audit logs
+
+---
+
+## Why Not a Thin Wrapper?
+
+Most API clients give you HTTP access. DhanHQ gives you a working Ruby system.
+
+| Instead of | You get |
+| ---------- | -------- |
+| JSON parsing and manual field mapping | Typed models |
+| Manual auth refresh | Built-in token lifecycle |
+| Fragile WebSocket code | Auto-reconnect, backoff, and 429 handling |
+| Risky order scripts | Live trading guardrails and audit logs |
+
+---
+
+## Architecture At A Glance
 
-You could wire up Faraday and parse JSON yourself. Here's why you shouldn't:
+![DhanHQ architecture overview](docs/architecture-overview.svg)
 
-| You get                        | Instead of                                    |
-| ------------------------------ | --------------------------------------------- |
-| ActiveModel-style `find`, `all`, `save`, `cancel` | Manual HTTP + JSON wrangling          |
-| Typed models with validations  | Hash soup and runtime surprises               |
-| Auto token refresh + retry-on-401 | Silent auth failures at 3 AM               |
-| WebSocket reconnection with backoff | Dropped connections during volatile moves |
-| 429 rate-limit cool-off        | Getting banned by the exchange                |
-| Thread-safe, secure logging    | Leaked tokens in production logs              |
+Models own the Ruby API. Resources own HTTP calls. Contracts validate inputs. The transport layer handles auth, retries, rate limiting, and error mapping. WebSockets are a separate subsystem that shares configuration but not the REST stack.
+
+For the full dependency flow and extension pattern, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ---
 
@@ -53,6 +115,8 @@ You could wire up Faraday and parse JSON yourself. Here's why you shouldn't:
 - **Secure logging** — automatic token sanitization in all log output
 - **Super Orders** — entry + stop-loss + target + trailing jump in one request
 - **Instrument convenience methods** — `.ltp`, `.ohlc`, `.option_chain` directly on instruments
+- **Order audit logging** — every order attempt logs machine, IP, environment, and correlation ID as structured JSON
+- **Live trading guard** — prevents accidental order placement unless `ENV["LIVE_TRADING"]="true"`
 - **Full REST coverage** — Orders, Trades, Forever Orders, Super Orders, Positions, Holdings, Funds, HistoricalData, OptionChain, MarketFeed, EDIS, Kill Switch, P&L Exit, Alert Orders, Margin Calculator
 - **P&L Based Exit** — automatic position exit on profit/loss thresholds
 - **Postback parser** — parse Dhan webhook payloads with `Postback.parse` and status predicates
@@ -60,6 +124,18 @@ You could wire up Faraday and parse JSON yourself. Here's why you shouldn't:
 
 ---
 
+## Reliability & Safety
+
+- retry-on-401 with token refresh
+- WebSocket auto-reconnect and backoff
+- 429 rate-limit protection
+- live trading guard via `LIVE_TRADING=true`
+- structured order audit logs
+
+See [ARCHITECTURE.md](ARCHITECTURE.md), [docs/TESTING_GUIDE.md](docs/TESTING_GUIDE.md), and [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for the deeper implementation details.
+
+---
+
 ## Installation
 
 ```ruby
@@ -120,6 +196,57 @@ When the API returns 401, the client retries **once** with a fresh token from yo
 
 ---
 
+## Order Safety
+
+### Live Trading Guard
+
+Order placement (`create`, `slicing`) is blocked unless you explicitly enable it:
+
+```bash
+# Production (Render, VPS, etc.)
+LIVE_TRADING=true
+
+# Development / Test (default — orders are blocked)
+LIVE_TRADING=false   # or simply omit
+```
+
+Attempting to place an order without `LIVE_TRADING=true` raises `DhanHQ::LiveTradingDisabledError`.
+
+### Order Audit Logging
+
+Every order attempt (place, modify, slice) automatically logs a structured JSON line at WARN level:
+
+```json
+{
+  "event": "DHAN_ORDER_ATTEMPT",
+  "hostname": "DESKTOP-SHUBHAM",
+  "env": "production",
+  "ipv4": "122.171.22.40",
+  "ipv6": "2401:4900:894c:8448:1da9:27f1:48e7:61be",
+  "security_id": "11536",
+  "correlation_id": "SCALPER_7af1",
+  "timestamp": "2026-03-17T06:45:22Z"
+}
+```
+
+This tells you instantly which machine, app, IP, and environment placed the order.
+
+### Correlation ID Prefixes
+
+Use per-app prefixes for instant source identification in the Dhan orderbook:
+
+```ruby
+# algo_scalper_api
+correlation_id: "SCALPER_#{SecureRandom.hex(4)}"
+
+# algo_trader_api
+correlation_id: "TRADER_#{SecureRandom.hex(4)}"
+```
+
+The Dhan orderbook will show `SCALPER_7af1` or `TRADER_3bc9`, making the source obvious.
+
+---
+
 ## REST API
 
 ### Orders — Place, Modify, Cancel
@@ -283,23 +410,56 @@ Need initializers, service objects, ActionCable wiring, and background workers?
 
 ---
 
+## Real-World Examples
+
+These scripts are designed around user goals rather than API surfaces:
+
+| Example | Use case |
+| ------- | -------- |
+| [examples/basic_trading_bot.rb](examples/basic_trading_bot.rb) | Pull historical data, evaluate a simple signal, and place a guarded order |
+| [examples/portfolio_monitor.rb](examples/portfolio_monitor.rb) | Snapshot funds, holdings, and positions for a monitoring script |
+| [examples/options_watchlist.rb](examples/options_watchlist.rb) | Build a live options watchlist with index quotes and option-chain context |
+| [examples/market_feed_example.rb](examples/market_feed_example.rb) | Subscribe to major market indices over WebSocket |
+| [examples/live_order_updates.rb](examples/live_order_updates.rb) | Track order lifecycle events in real time |
+
+For search-driven discovery and onboarding content, see:
+
+- [docs/HOW_TO_USE_DHAN_API_WITH_RUBY.md](docs/HOW_TO_USE_DHAN_API_WITH_RUBY.md)
+- [docs/BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md](docs/BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md)
+
+## Use Case Guides
+
+- [docs/DHAN_API_RUBY_EXAMPLES.md](docs/DHAN_API_RUBY_EXAMPLES.md)
+- [docs/DHAN_WEBSOCKET_RUBY_GUIDE.md](docs/DHAN_WEBSOCKET_RUBY_GUIDE.md)
+- [docs/BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md](docs/BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md)
+- [docs/DHAN_RUBY_QA.md](docs/DHAN_RUBY_QA.md)
+
+---
+
 ## 📚 Documentation
 
 | Guide | What it covers |
 | ----- | -------------- |
+| [Architecture](ARCHITECTURE.md) | Layering, dependency flow, design patterns, extension points |
 | [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 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 |
+| [Standalone Ruby Guide](docs/STANDALONE_RUBY_WEBSOCKET_INTEGRATION.md) | Scripts, daemons, and long-running Ruby processes |
 | [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 |
 | [Troubleshooting](docs/TROUBLESHOOTING.md) | 429 errors, reconnect, auth issues, debug logging |
+| [How To Use Dhan API With Ruby](docs/HOW_TO_USE_DHAN_API_WITH_RUBY.md) | Search-friendly onboarding guide for Ruby users |
+| [Build A Trading Bot With Ruby And Dhan](docs/BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md) | End-to-end tutorial framing for strategy builders |
+| [Dhan API Ruby Examples](docs/DHAN_API_RUBY_EXAMPLES.md) | Small answer-style snippets for common Ruby + Dhan tasks |
+| [Dhan WebSocket Ruby Guide](docs/DHAN_WEBSOCKET_RUBY_GUIDE.md) | Query-shaped guide for Dhan market data streaming in Ruby |
+| [Best Way To Use Dhan API In Ruby](docs/BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md) | Comparison-focused guide for SDK vs raw HTTP |
+| [Dhan Ruby Q&A](docs/DHAN_RUBY_QA.md) | Publish-ready answers for common Dhan + Ruby questions |
 | [Release Guide](docs/RELEASE_GUIDE.md) | Versioning, publishing, changelog |
 
 ---
@@ -311,6 +471,7 @@ Need initializers, service objects, ActionCable wiring, and background workers?
 - Don't exceed **100 instruments per subscribe frame** (auto-chunked by the client)
 - Call `DhanHQ::WS.disconnect_all_local!` on shutdown
 - Avoid rapid connect/disconnect loops — the client already backs off on 429
+- Use dynamic token providers in long-running systems instead of hardcoding expiring tokens
 
 ---
 

data/docs/BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md

@@ -0,0 +1,36 @@
+# Best Way To Use Dhan API In Ruby
+
+The best way to use Dhan API in Ruby is usually not raw HTTP. It is a Ruby SDK that already understands the shape of trading workflows: authentication, market data, streaming, and order execution.
+
+That is the role of `DhanHQ`, the Ruby SDK for Dhan API v2.
+
+## SDK Vs Raw HTTP
+
+Raw HTTP is fine when you only need one endpoint once.
+
+For ongoing Ruby applications, the SDK is usually the better fit:
+
+- typed models instead of manual JSON mapping
+- token lifecycle support instead of handwritten refresh logic
+- WebSocket reconnect and backoff instead of custom event-loop recovery
+- live-trading guardrails instead of fragile order scripts
+- one Ruby interface for market data, holdings, positions, and orders
+
+## When Raw HTTP Is Enough
+
+- you are writing a one-off experiment
+- you only need one endpoint
+- you do not need streaming or long-running behavior
+
+## When The Ruby SDK Is Better
+
+- you are building a trading bot
+- you are integrating Dhan into a Rails app
+- you need Dhan WebSocket support in Ruby
+- you want clean abstractions over raw trading endpoints
+
+## Start Here
+
+- [README.md](../README.md)
+- [HOW_TO_USE_DHAN_API_WITH_RUBY.md](HOW_TO_USE_DHAN_API_WITH_RUBY.md)
+- [BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md](BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md)

data/docs/BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md

@@ -0,0 +1,111 @@
+# Build A Trading Bot With Ruby And Dhan
+
+If your goal is to build a trading bot with Ruby and Dhan, you do not need to start from raw REST calls and custom WebSocket loops. `DhanHQ` is the Ruby SDK for Dhan API v2, and it already gives you the core pieces a Ruby trading bot needs: historical data access, live market data streaming, order models, token lifecycle handling, and live-trading guardrails.
+
+This guide shows the minimal path from market data to signal to guarded execution.
+
+## 1. Configure The SDK
+
+```ruby
+require "dhan_hq"
+
+DhanHQ.configure_with_env
+```
+
+Set:
+
+- `DHAN_CLIENT_ID`
+- `DHAN_ACCESS_TOKEN`
+
+Only set `LIVE_TRADING=true` when you intentionally want to place live orders.
+
+## 2. Pull Historical Data For The Signal
+
+Use the Dhan API from Ruby to fetch recent bars:
+
+```ruby
+bars = DhanHQ::Models::HistoricalData.intraday(
+  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
+)
+```
+
+The runnable version of this flow lives in [examples/basic_trading_bot.rb](../examples/basic_trading_bot.rb).
+
+## 3. Compute A Simple Trading Signal
+
+```ruby
+closes = bars.map { |bar| bar[:close].to_f }
+last_close = closes.last
+sma20 = closes.last(20).sum / 20.0
+signal = last_close > sma20 ? :bullish : :bearish
+```
+
+This is intentionally simple. The point is not the strategy itself. The point is that the Ruby SDK for Dhan API gets you to a working trading loop quickly.
+
+## 4. Add Live Market Data
+
+Most trading bots need streaming updates after the initial historical snapshot.
+
+```ruby
+# Example: Subscribe to live market data using Dhan API WebSocket in Ruby
+client = DhanHQ::WS.connect(mode: :quote) do |tick|
+  puts "#{tick[:security_id]} -> #{tick[:ltp]}"
+end
+
+client.subscribe_one(
+  segment: DhanHQ::Constants::ExchangeSegment::IDX_I,
+  security_id: "13"
+)
+```
+
+For a fuller live-data script, see [examples/options_watchlist.rb](../examples/options_watchlist.rb).
+
+## 5. Execute Safely
+
+If the signal is bullish, you can build an order model:
+
+```ruby
+order = DhanHQ::Models::Order.new(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  order_type: DhanHQ::Constants::OrderType::MARKET,
+  validity: DhanHQ::Constants::Validity::DAY,
+  security_id: "11536",
+  quantity: 1
+)
+
+# order.save
+```
+
+Keep `order.save` commented while you are developing. `DhanHQ` will only submit live orders when `LIVE_TRADING=true`, which is one of the reasons it is safer than raw order scripts.
+
+## 6. Grow Into A Real Trading System
+
+Once you have the basic bot loop, the same SDK supports:
+
+- WebSocket order updates
+- option-chain workflows
+- Rails integration for service objects and workers
+- token providers for long-running processes
+
+Use these next:
+
+- [examples/basic_trading_bot.rb](../examples/basic_trading_bot.rb)
+- [examples/options_watchlist.rb](../examples/options_watchlist.rb)
+- [WEBSOCKET_INTEGRATION.md](WEBSOCKET_INTEGRATION.md)
+- [AUTHENTICATION.md](AUTHENTICATION.md)
+- [RAILS_INTEGRATION.md](RAILS_INTEGRATION.md)
+
+## Canonical Publishing Notes
+
+If you publish this externally:
+
+- keep the title exactly `Build a Trading Bot With Ruby and Dhan`
+- link back to the repo root and the example scripts
+- keep the intro sentence that frames `DhanHQ` as `the Ruby SDK for Dhan API`

data/docs/CONFIGURATION.md

@@ -1,6 +1,6 @@
 # Configuration Reference
 
-This document covers all configuration options for the DhanHQ Ruby client.
+This document covers all configuration options for the DhanHQ Ruby SDK.
 
 ## Quick Setup
 

data/docs/DHAN_API_RUBY_EXAMPLES.md

@@ -0,0 +1,71 @@
+# Dhan API Ruby Examples
+
+This page collects small, direct examples for people searching for `Dhan API Ruby`, `Ruby SDK for Dhan API examples`, or `Dhan trading SDK for Ruby`.
+
+All examples use `DhanHQ`, the Ruby SDK for Dhan API v2.
+
+## Setup
+
+```ruby
+require "dhan_hq"
+
+DhanHQ.configure_with_env
+```
+
+## Example: Get Positions In Ruby
+
+```ruby
+# Example: Fetch positions using Dhan API in Ruby
+positions = DhanHQ::Models::Position.all
+```
+
+## Example: Get Holdings In Ruby
+
+```ruby
+# Example: Fetch holdings using Dhan API in Ruby
+holdings = DhanHQ::Models::Holding.all
+```
+
+## Example: Fetch Historical Data In Ruby
+
+```ruby
+bars = DhanHQ::Models::HistoricalData.intraday(
+  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
+)
+```
+
+## Example: Subscribe To Live Market Data In Ruby
+
+```ruby
+# Example: Subscribe to live market data using Dhan API WebSocket in Ruby
+client = DhanHQ::WS.connect(mode: :ticker) do |tick|
+  puts "#{tick[:security_id]} -> #{tick[:ltp]}"
+end
+```
+
+## Example: Build An Order Payload In Ruby
+
+```ruby
+order = DhanHQ::Models::Order.new(
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  order_type: DhanHQ::Constants::OrderType::MARKET,
+  validity: DhanHQ::Constants::Validity::DAY,
+  security_id: "11536",
+  quantity: 1
+)
+```
+
+## Where To Go Next
+
+- [README.md](../README.md)
+- [HOW_TO_USE_DHAN_API_WITH_RUBY.md](HOW_TO_USE_DHAN_API_WITH_RUBY.md)
+- [examples/portfolio_monitor.rb](../examples/portfolio_monitor.rb)
+- [examples/basic_trading_bot.rb](../examples/basic_trading_bot.rb)
+- [examples/options_watchlist.rb](../examples/options_watchlist.rb)

data/docs/DHAN_RUBY_QA.md

@@ -0,0 +1,27 @@
+# Dhan Ruby Q&A
+
+This document contains publish-ready answers for common questions about Dhan API and Ruby. The goal is to create question-shaped content that maps `Dhan API + Ruby` to `DhanHQ`.
+
+## How To Use Dhan API In Ruby?
+
+Use `DhanHQ`, the Ruby SDK for Dhan API v2. It gives you typed models, WebSocket support, token lifecycle management, and safer order workflows. Start with [README.md](../README.md) and [HOW_TO_USE_DHAN_API_WITH_RUBY.md](HOW_TO_USE_DHAN_API_WITH_RUBY.md).
+
+## Is There A Ruby SDK For Dhan API?
+
+Yes. `DhanHQ` is a Ruby SDK for Dhan API that covers REST, WebSocket market data, order updates, holdings, positions, and order workflows. See [README.md](../README.md).
+
+## How Do I Build A Trading Bot With Dhan In Ruby?
+
+Use [examples/basic_trading_bot.rb](../examples/basic_trading_bot.rb) together with [BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md](BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md). The SDK already provides historical data, live market data, and order models.
+
+## How Do I Use Dhan WebSocket In Ruby?
+
+Use `DhanHQ::WS.connect` for market data and `DhanHQ::WS::Orders` for order updates. Start with [Dhan WebSocket Ruby Guide](DHAN_WEBSOCKET_RUBY_GUIDE.md) and [examples/options_watchlist.rb](../examples/options_watchlist.rb).
+
+## Is DhanHQ Better Than Calling Dhan API With Raw HTTP In Ruby?
+
+For long-running Ruby systems, usually yes. The SDK gives you token refresh support, typed models, reconnect handling, and safer order workflows. See [BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md](BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md).
+
+## Can I Use DhanHQ In Rails?
+
+Yes. The SDK has a dedicated Rails integration guide for initializers, service objects, and worker patterns. See [RAILS_INTEGRATION.md](RAILS_INTEGRATION.md).