DhanHQ — The Ruby SDK for Dhan API v2

Build trading systems in Ruby without fighting raw HTTP, fragile auth flows, or unreliable market streams.

DhanHQ is a production-grade Ruby SDK for the Dhan trading API, 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.

# Gemfile
gem 'DhanHQ'

require 'dhan_hq'

DhanHQ.configure do |c|
  c.client_id    = ENV["DHAN_CLIENT_ID"]
  c.access_token = ENV["DHAN_ACCESS_TOKEN"]
end

# You're live — no manual HTTP, no JSON parsing
positions = DhanHQ::Models::Position.all

• 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

• One-off scripts where raw HTTP is enough
• Non-Ruby stacks

Pick the path that matches what you want to build:

• Get live prices fast → Market Feed WebSocket
• Place orders safely → Order Safety
• Build a trading strategy → WebSockets
• Build a trading bot → examples/basic_trading_bot.rb
• Use with Rails → docs/RAILS_INTEGRATION.md

• 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

Most API clients give you HTTP access. DhanHQ gives you a working Ruby system.

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.

• ActiveRecord-style models — find, all, where, save, cancel across Orders, Positions, Holdings, Funds, and more
• Auto token refresh — 401 retry with fresh token via provider callback
• Thread-safe WebSocket client — Orders, Market Feed, Market Depth with auto-reconnect
• Exponential backoff + 429 cool-off — no manual rate-limit management
• 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
• EDIS model — ORM-style T-PIN, form, and status inquiry for delivery instruction slips

• 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, docs/TESTING_GUIDE.md, and docs/TROUBLESHOOTING.md for the deeper implementation details.

# Gemfile (recommended)
gem 'DhanHQ'

bundle install
# or
gem install DhanHQ

Bleeding edge? Use gem 'DhanHQ', git: 'https://github.com/shubhamtaywade82/dhanhq-client.git', branch: 'main' only if you need unreleased features.

bundle update / bundle install warnings — If you see "Local specification for rexml-3.2.8 has different dependencies" or "Unresolved or ambiguous specs during Gem::Specification.reset: psych", the bundle still completes successfully. To clear the rexml warning once, run: gem cleanup rexml. The psych message is a known Bundler quirk and can be ignored.

The require statement changed:

# Before         # Now
require 'DhanHQ'  →  require 'dhan_hq'

The gem name in your Gemfile stays DhanHQ — only the require changes.

require 'dhan_hq'
DhanHQ.configure_with_env   # reads DHAN_CLIENT_ID + DHAN_ACCESS_TOKEN from ENV

DhanHQ.configure do |config|
  config.client_id = ENV["DHAN_CLIENT_ID"]
  config.access_token_provider = -> { YourTokenStore.active_token }
  config.on_token_expired = ->(error) { YourTokenStore.refresh! }  # optional
end

When the API returns 401, the client retries once with a fresh token from your provider.

Full details: TOTP flows, partner mode, token endpoint bootstrap, auto-management — see docs/AUTHENTICATION.md.

Order placement (create, slicing) is blocked unless you explicitly enable it:

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

Every order attempt (place, modify, slice) automatically logs a structured JSON line at WARN level:

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

Use per-app prefixes for instant source identification in the Dhan orderbook:

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

order = DhanHQ::Models::Order.new(
  transaction_type: DhanHQ::Constants::TransactionType::BUY,
  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO,
  product_type: DhanHQ::Constants::ProductType::MARGIN,
  order_type: DhanHQ::Constants::OrderType::LIMIT,
  validity: DhanHQ::Constants::Validity::DAY,
  security_id:      "43492",
  quantity:         50,
  price:            100.0
)
order.save          # places the order
order.modify(price: 101.5)
order.cancel

DhanHQ::Models::Position.all
DhanHQ::Models::Holding.all
DhanHQ::Models::Fund.balance

bars = DhanHQ::Models::HistoricalData.intraday(
  security_id:      "13",
  exchange_segment: DhanHQ::Constants::ExchangeSegment::IDX_I,
  instrument: DhanHQ::Constants::InstrumentType::INDEX,
  interval:         "5",
  from_date:        "2025-08-14",
  to_date:          "2025-08-18"
)

nifty = DhanHQ::Models::Instrument.find("IDX_I", "NIFTY")
nifty.ltp           # last traded price
nifty.ohlc          # OHLC data
nifty.option_chain(expiry: "2025-02-28")
nifty.intraday(from_date: "2025-08-14", to_date: "2025-08-18", interval: "15")

Three real-time feeds, all with auto-reconnect, backoff, 429 cool-off, and thread-safe operation.

DhanHQ::WS::Orders.connect do |order_update|
  puts "#{order_update.order_no} → #{order_update.status} (#{order_update.traded_qty}/#{order_update.quantity})"
end

client = DhanHQ::WS.connect(mode: :ticker) do |tick|
  puts "#{tick[:security_id]} = ₹#{tick[:ltp]}"
end

client.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")   # NIFTY
client.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "25")   # BANKNIFTY

reliance = DhanHQ::Models::Instrument.find("NSE_EQ", "RELIANCE")

DhanHQ::WS::MarketDepth.connect(symbols: [
  { symbol: "RELIANCE", exchange_segment: reliance.exchange_segment, security_id: reliance.security_id }
]) do |depth|
  puts "Best Bid: #{depth[:best_bid]} | Best Ask: #{depth[:best_ask]} | Spread: #{depth[:spread]}"
end

DhanHQ::WS.disconnect_all_local!   # kills all local WS connections

Entry + target + stop-loss + trailing jump in a single request:

DhanHQ::Models::SuperOrder.create(
  transaction_type: DhanHQ::Constants::TransactionType::BUY,
  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
  product_type: DhanHQ::Constants::ProductType::CNC,
  order_type: DhanHQ::Constants::OrderType::LIMIT,
  security_id:      "11536",
  quantity:         5,
  price:            1500,
  target_price:     1600,
  stop_loss_price:  1400,
  trailing_jump:    10
)

Full API reference (modify, cancel, list, response schemas): docs/SUPER_ORDERS.md

require 'dhan_hq'

DhanHQ.configure_with_env

# 1. Check the trend using historical 5-min bars
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
)

closes = bars.map { |b| b[:close] }
sma_20 = closes.last(20).sum / 20.0
trend  = closes.last > sma_20 ? :bullish : :bearish
puts "NIFTY trend: #{trend} (LTP: #{closes.last}, SMA20: #{sma_20.round(2)})"

# 2. Stream live ticks for real-time monitoring
client = DhanHQ::WS.connect(mode: :quote) do |tick|
  puts "NIFTY ₹#{tick[:ltp]} | Vol: #{tick[:vol]} | #{Time.now.strftime('%H:%M:%S')}"
end
client.subscribe_one(segment: DhanHQ::Constants::ExchangeSegment::IDX_I, security_id: "13")

# 3. On signal, place a super order with built-in risk management
# DhanHQ::Models::SuperOrder.create(
#   transaction_type: DhanHQ::Constants::TransactionType::BUY, exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO, ...
#   target_price: entry + 50, stop_loss_price: entry - 30, trailing_jump: 5
# )

# 4. Clean shutdown
at_exit { DhanHQ::WS.disconnect_all_local! }
sleep   # keep the script alive

Need initializers, service objects, ActionCable wiring, and background workers? See the Rails Integration Guide.

These scripts are designed around user goals rather than API surfaces:

For search-driven discovery and onboarding content, see:

• docs/HOW_TO_USE_DHAN_API_WITH_RUBY.md
• docs/BUILD_A_TRADING_BOT_WITH_RUBY_AND_DHAN.md

• docs/DHAN_API_RUBY_EXAMPLES.md
• docs/DHAN_WEBSOCKET_RUBY_GUIDE.md
• docs/BEST_WAY_TO_USE_DHAN_API_IN_RUBY.md
• docs/DHAN_RUBY_QA.md

• Keep on(:tick) handlers non-blocking — push heavy work to a queue/thread
• Use mode: :quote for most strategies; :full only if you need depth/OI
• 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

PRs welcome! Please include tests for new features. See CHANGELOG.md for recent changes.

bundle exec rake          # run tests
bundle exec rubocop       # lint
bin/console               # interactive console

MIT