DhanHQ 3.2.0 → 3.3.0

data/skills/dhanhq-ruby/examples/order_management.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "dhan_hq"
+require_relative "../scripts/dhan_helpers"
+
+# Initialize credentials
+get_client
+
+security_id = "2885"
+price = 2000.0
+quantity = 1
+
+puts preview_order(
+  security_id: security_id,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  quantity: quantity,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  price: price,
+  trading_symbol: "RELIANCE"
+)
+
+if ENV["RUN_LIVE_EXAMPLE"] != "1"
+  puts "Set RUN_LIVE_EXAMPLE=1 to place, modify, and cancel a live demo order."
+  exit 0
+end
+
+# The gem has its own independent safety gate: Order.place/modify/cancel raise
+# DhanHQ::LiveTradingDisabledError unless ENV["LIVE_TRADING"]="true" is also set.
+if ENV["LIVE_TRADING"] != "true"
+  puts "Also set ENV['LIVE_TRADING']='true' — the SDK blocks order placement without it."
+  exit 0
+end
+
+# Step 1: Place a limit order (well below market for demo — won't fill)
+puts "Step 1: Placing limit buy order for RELIANCE..."
+order = DhanHQ::Models::Order.place(
+  security_id: security_id,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  quantity: quantity,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  price: price, # Below market — will stay pending
+  validity: DhanHQ::Constants::Validity::DAY
+)
+
+if order.nil? || order.order_id.to_s.empty?
+  puts "Order failed to place."
+  exit 1
+end
+
+order_id = order.order_id
+puts "Order placed: #{order_id}"
+
+# Step 2: Check order status
+puts "\nStep 2: Checking order status..."
+sleep(1)
+order = DhanHQ::Models::Order.find(order_id)
+status = order.order_status
+puts "Status: #{status}"
+puts "  Security:  #{order.trading_symbol}"
+puts "  Qty:       #{order.quantity}"
+puts "  Price:     ₹#{order.price}"
+puts "  Filled:    #{order.filled_qty || 0}"
+
+# Step 3: Modify the order (change price)
+if status == DhanHQ::Constants::OrderStatus::PENDING
+  puts "\nStep 3: Modifying order price to ₹2050..."
+  modified_order = order.modify(
+    order_type: DhanHQ::Constants::OrderType::LIMIT,
+    quantity: quantity,
+    price: 2050.00,
+    validity: DhanHQ::Constants::Validity::DAY
+  )
+  puts "Modify result: #{modified_order ? "Success" : "Failure"}"
+end
+
+# Step 4: Cancel the order
+puts "\nStep 4: Cancelling order..."
+cancel_success = order.cancel
+puts "Cancel result: #{cancel_success ? "Success" : "Failure"}"
+
+# Step 5: View order book
+puts "\nStep 5: Today's order book:"
+orders = begin
+  DhanHQ::Models::Order.all
+rescue StandardError
+  []
+end
+if orders.any?
+  orders.last(5).each do |o| # Last 5 orders
+    printf("  %-12s | %-12s | %-4s | %-12s | ₹%-8.2f\n", o.order_id.to_s[0...12], o.trading_symbol, o.transaction_type, o.order_status, o.price.to_f)
+  end
+end
+
+# Step 6: View trade book
+puts "\nStep 6: Today's trade book:"
+trades = begin
+  DhanHQ::Models::Trade.today
+rescue StandardError
+  []
+end
+if trades.any?
+  trades.last(5).each do |t|
+    printf("  %-12s | %-4s | Qty: %-5d | ₹%-8.2f\n", t.trading_symbol, t.transaction_type, t.traded_quantity, t.traded_price.to_f)
+  end
+else
+  puts "  No trades today"
+end

data/skills/dhanhq-ruby/examples/place_equity_order.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "dhan_hq"
+require_relative "../scripts/dhan_helpers"
+
+# Initialize credentials
+get_client
+
+security_id = "2885" # RELIANCE
+price = 2450.0
+quantity = 1
+
+puts preview_order(
+  security_id: security_id,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_EQ,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  quantity: quantity,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  product_type: DhanHQ::Constants::ProductType::CNC,
+  price: price,
+  trading_symbol: "RELIANCE"
+)
+
+# Uncomment after confirmation:
+# order = DhanHQ::Models::Order.place(
+#   security_id: security_id,
+#   exchange_segment: "NSE_EQ",
+#   transaction_type: "BUY",
+#   quantity: quantity,
+#   order_type: "LIMIT",
+#   product_type: "CNC",
+#   price: price,
+#   validity: "DAY"
+# )
+# puts "Placed order ID: #{order.order_id}"

data/skills/dhanhq-ruby/examples/place_fno_order.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "dhan_hq"
+require_relative "../scripts/dhan_helpers"
+
+# Initialize credentials
+get_client
+
+expiries = DhanHQ::Models::OptionChain.fetch_expiry_list(underlying_scrip: 13, underlying_seg: DhanHQ::Constants::ExchangeSegment::IDX_I)
+nearest_expiry = expiries.first
+
+if nearest_expiry.nil?
+  puts "Failed to fetch expiries."
+  exit 1
+end
+
+puts "Nearest expiry: #{nearest_expiry}"
+
+chain_df, spot = fetch_chain_df(under_security_id: 13, expiry: nearest_expiry)
+atm = find_atm_row(chain_df, spot)
+
+if atm.nil?
+  puts "Failed to find ATM row."
+  exit 1
+end
+
+ce_security_id = atm["ce_security_id"]
+ce_ltp = atm["ce_ltp"].to_f
+lot_size = get_lot_size(underlying: "NIFTY") || 75
+quantity = lot_size
+
+puts "Nifty spot: #{spot}"
+puts "ATM strike: #{atm["strike"]}"
+puts "CE security ID: #{ce_security_id}, LTP: Rs. #{"%.2f" % ce_ltp}"
+puts
+
+puts preview_order(
+  security_id: ce_security_id,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  quantity: quantity,
+  order_type: DhanHQ::Constants::OrderType::LIMIT,
+  product_type: DhanHQ::Constants::ProductType::INTRADAY,
+  price: ce_ltp,
+  trading_symbol: "NIFTY #{atm["strike"].to_i} CE"
+)
+
+margin = check_margin(
+  security_id: ce_security_id,
+  exchange_segment: DhanHQ::Constants::ExchangeSegment::NSE_FNO,
+  transaction_type: DhanHQ::Constants::TransactionType::BUY,
+  quantity: quantity,
+  product_type: DhanHQ::Constants::ProductType::INTRADAY,
+  price: ce_ltp
+)
+
+printf(
+  "Margin check: sufficient=%s required=Rs. %s available=Rs. %s\n",
+  margin["sufficient"].to_s,
+  "%.2f" % margin["total_margin"],
+  "%.2f" % margin["available_balance"]
+)
+
+# Uncomment only after confirmation:
+# order = DhanHQ::Models::Order.place(
+#   security_id: ce_security_id,
+#   exchange_segment: "NSE_FNO",
+#   transaction_type: "BUY",
+#   quantity: quantity,
+#   order_type: "LIMIT",
+#   product_type: "INTRADAY",
+#   price: ce_ltp,
+#   validity: "DAY"
+# )
+# puts "Placed order ID: #{order.order_id}"

data/skills/dhanhq-ruby/examples/portfolio_summary.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "dhan_hq"
+require_relative "../scripts/dhan_helpers"
+
+# Initialize credentials
+get_client
+
+holdings = begin
+  DhanHQ::Models::Holding.all
+rescue StandardError
+  []
+end
+positions = begin
+  DhanHQ::Models::Position.all
+rescue StandardError
+  []
+end
+funds = begin
+  DhanHQ::Models::Funds.fetch
+rescue StandardError
+  nil
+end
+trades = begin
+  DhanHQ::Models::Trade.today
+rescue StandardError
+  []
+end
+
+summary = format_pnl_report(holdings, positions)
+
+puts "=" * 50
+puts "             PORTFOLIO SUMMARY"
+puts "=" * 50
+puts "\nHoldings count:   #{summary["holdings_count"]}"
+puts "Positions count:  #{summary["positions_count"]}"
+printf("Current value:    Rs. %12.2f\n", summary["current_value"])
+printf("Total P&L:        Rs. %12.2f\n", summary["total_pnl"])
+printf("Day P&L:          Rs. %12.2f\n", summary["day_pnl"])
+
+if funds
+  available = funds.availabel_balance || funds.available_balance || 0.0
+  utilized = funds.utilized_amount || 0.0
+  collateral = funds.collateral_amount || 0.0
+  withdrawable = funds.withdrawable_balance || 0.0
+
+  puts "\nFUNDS"
+  printf("  Available:      Rs. %12.2f\n", available)
+  printf("  Utilized:       Rs. %12.2f\n", utilized)
+  printf("  Collateral:     Rs. %12.2f\n", collateral)
+  printf("  Withdrawable:   Rs. %12.2f\n", withdrawable)
+end
+
+if holdings.any?
+  puts "\nTOP HOLDINGS"
+  # Sort holdings by quantity
+  sorted_holdings = holdings.sort_by { |h| -(h.total_qty || 0) }
+  sorted_holdings.first(5).each do |holding|
+    printf("  %-15s qty=%5d available=%5d\n", holding.trading_symbol, holding.total_qty.to_i, holding.available_qty.to_i)
+  end
+end
+
+open_positions = positions.reject { |p| p.net_qty.to_i.zero? }
+if open_positions.any?
+  puts "\nOPEN POSITIONS"
+  open_positions.first(5).each do |position|
+    pnl = position.realized_profit.to_f + position.unrealized_profit.to_f
+    printf("  %-20s netQty=%5d pnl=Rs. %8.0f\n", position.trading_symbol, position.net_qty.to_i, pnl)
+  end
+end
+
+puts "\nTrades today:     #{trades.size}"
+puts "=" * 50

data/skills/dhanhq-ruby/examples/super_order_with_sl.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "dhan_hq"
+require_relative "../scripts/dhan_helpers"
+
+# Initialize credentials
+get_client
+
+# Fetch LTP for Reliance
+ltp_response = DhanHQ::Models::MarketFeed.ltp("NSE_EQ" => [2885])
+if ltp_response[:status] != "success"
+  puts "Failed to fetch LTP: #{ltp_response[:remarks]}"
+  exit 1
+end
+
+reliance_ltp = ltp_response[:data][DhanHQ::Constants::ExchangeSegment::NSE_EQ]["2885"]["last_price"].to_f
+puts "Reliance LTP: Rs. #{"%.2f" % reliance_ltp}"
+
+entry_price = reliance_ltp
+target_price = (entry_price * 1.02).round(2)
+sl_price = (entry_price * 0.99).round(2)
+trailing_jump = 5.0
+
+puts "\n--- Super Order Preview ---"
+puts "Action:        BUY 1 share of RELIANCE"
+puts "Entry Price:   Rs. #{"%.2f" % entry_price}"
+puts "Target:        Rs. #{"%.2f" % target_price}"
+puts "Stop Loss:     Rs. #{"%.2f" % sl_price}"
+puts "Trailing Jump: Rs. #{"%.2f" % trailing_jump}"
+puts "Product:       INTRADAY"
+
+# Uncomment after confirmation:
+# order = DhanHQ::Models::SuperOrder.create(
+#   security_id: "2885",
+#   exchange_segment: "NSE_EQ",
+#   transaction_type: "BUY",
+#   quantity: 1,
+#   order_type: "LIMIT",
+#   product_type: "INTRADAY",
+#   price: entry_price,
+#   target_price: target_price,
+#   stop_loss_price: sl_price,
+#   trailing_jump: trailing_jump
+# )
+#
+# if order
+#   puts "Super order placed: #{order.order_id} - #{order.order_status}"
+#
+#   # Connect to Order Update websocket to listen for updates
+#   orders_client = DhanHQ::WS::Orders.connect do |update|
+#     puts "Order Update -> OrderNo: #{update.order_no}, Status: #{update.status}"
+#   end
+#
+#   sleep(10)
+#   orders_client.stop rescue nil
+# end

data/skills/dhanhq-ruby/references/backtesting-with-dhan.md

@@ -0,0 +1,65 @@
+# Backtesting With Dhan Data (Ruby SDK)
+
+## Daily Equity Backtest Skeleton
+
+```ruby
+# Fetch daily charts via HistoricalData model
+candles = DhanHQ::Models::HistoricalData.daily(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  instrument: "EQUITY",
+  from_date: "2023-01-01",
+  to_date: "2024-12-31"
+)
+
+# candles is a normalized array of hashes:
+# [{ timestamp: Time, open: Float, high: Float, low: Float, close: Float, volume: Integer }]
+```
+
+Typical next steps:
+- Create signals based on technical calculations.
+- Shift positions to avoid look-ahead bias.
+- Apply transaction costs.
+- Compute CAGR, maximum drawdown, Sharpe ratio, and win rate.
+
+## Minute-Level Backtest Skeleton
+
+```ruby
+candles = DhanHQ::Models::HistoricalData.intraday(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  instrument: "EQUITY",
+  from_date: "2024-09-11 09:30:00",
+  to_date: "2024-09-15 13:00:00",
+  interval: "5", # 5-minute interval
+  oi: false
+)
+```
+
+## Expired Options Backtest Skeleton
+
+```ruby
+response = DhanHQ::Models::ExpiredOptionsData.fetch(
+  underlying_scrip: 13,
+  exchange_segment: "NSE_FNO",
+  expiry_flag: "MONTH",
+  expiry_code: 1,
+  strike: "ATM",
+  option_type: "CALL",
+  required_data: ["open", "high", "low", "close", "volume", "oi", "spot"],
+  from_date: "2021-08-01",
+  to_date: "2021-08-31",
+  interval: "1"
+)
+```
+
+## Cost Model Reminders
+
+At minimum consider:
+- Brokerage charges
+- Securities Transaction Tax (STT)
+- Exchange transaction charges
+- GST (Service Tax)
+- Stamp duty
+- SEBI turnover charges
+- Slippage

data/skills/dhanhq-ruby/references/common-workflows.md

@@ -0,0 +1,76 @@
+# Common Workflows — Agent Playbooks (Ruby SDK)
+
+## Portfolio Rebalance
+
+Recommended sequence:
+1. Fetch holdings and funds.
+2. Compute target deltas.
+3. Resolve symbols and quantities.
+4. Preview proposed orders.
+5. Confirm with the user.
+6. Place live orders.
+
+```ruby
+holdings = DhanHQ::Models::Holding.all rescue []
+funds = DhanHQ::Models::Funds.fetch rescue nil
+
+if funds
+  available_cash = funds.availabel_balance || funds.available_balance || 0.0
+end
+```
+
+## Delivery Sell With eDIS
+
+Use this flow for selling demat holdings:
+1. Fetch holdings and identify ISIN.
+2. Generate TPIN: `DhanHQ::Models::Edis.generate_tpin`
+3. Generate the authorization form: `DhanHQ::Models::Edis.generate_form(isin: "...", qty: 5, exchange: "NSE", segment: "EQ")`
+4. Check status: `DhanHQ::Models::Edis.inquire(isin: "...")`
+5. Place the sell order.
+
+```ruby
+# Generate TPIN
+DhanHQ::Models::Edis.generate_tpin
+
+# Generate authorization form
+DhanHQ::Models::Edis.generate_form(isin: "INE002A01018", qty: 5, exchange: "NSE", segment: "EQ")
+
+# Check status
+status = DhanHQ::Models::Edis.inquire(isin: "INE002A01018")
+```
+
+## Single-Leg F&O Execution
+
+Recommended sequence:
+1. Resolve current contract from option chain or security master.
+2. Resolve lot size.
+3. Validate quantity.
+4. Check margin.
+5. Preview & Confirm.
+6. Place live order.
+
+```ruby
+require_relative "../scripts/dhan_helpers"
+
+chain_df, spot = fetch_chain_df(under_security_id: 13, expiry: "2025-03-27")
+atm = find_atm_row(chain_df, spot)
+
+margin = check_margin(
+  security_id: atm["ce_security_id"],
+  exchange_segment: "NSE_FNO",
+  transaction_type: "BUY",
+  quantity: 75,
+  product_type: "INTRADAY",
+  price: atm["ce_ltp"].to_f
+)
+```
+
+## Daily P&L Summary
+
+```ruby
+require_relative "../scripts/dhan_helpers"
+
+holdings = DhanHQ::Models::Holding.all
+positions = DhanHQ::Models::Position.all
+summary = format_pnl_report(holdings, positions)
+```

data/skills/dhanhq-ruby/references/error-codes.md

@@ -0,0 +1,50 @@
+# Error Codes — Complete Reference (Ruby SDK)
+
+In the Ruby SDK, raw API error codes are automatically mapped in the client layer and raised as structured exceptions.
+
+## Exception Mapping
+
+The Ruby client maps Dhan error codes to specific error classes under the `DhanHQ` module:
+
+| Error Code | Error Class | Meaning |
+|------------|-------------|---------|
+| `DH-901` | `DhanHQ::InvalidAuthenticationError` | Client ID or access token is invalid or expired |
+| `DH-902` | `DhanHQ::InvalidAccessError` | User does not have required Data API or Trading API access |
+| `DH-903` | `DhanHQ::UserAccountError` | Account setup issue or segment activation requirement |
+| `DH-904` | `DhanHQ::RateLimitError` | Rate limit exceeded |
+| `DH-905` | `DhanHQ::InputExceptionError` | Missing or invalid request fields |
+| `DH-906` | `DhanHQ::OrderError` | Order request cannot be processed |
+| `DH-907` | `DhanHQ::DataError` | Data unavailable or parameters invalid |
+| `DH-908` | `DhanHQ::InternalServerError` | Server-side failure |
+| `DH-909` | `DhanHQ::NetworkError` | Backend communication failure |
+| `DH-1111` | `DhanHQ::NoHoldingsError` | No holdings present in the account |
+| `DH-910` / other | `DhanHQ::OtherError` / `DhanHQ::Error` | Other failure reasons |
+
+## Data API Errors
+
+| Code | Exception | Meaning |
+|------|-----------|---------|
+| `800` | `DhanHQ::InternalServerError` | Internal Server Error |
+| `804` | `DhanHQ::Error` | Requested number of instruments exceeds limit |
+| `805` | `DhanHQ::RateLimitError` | Too many requests or connections |
+| `806` | `DhanHQ::DataError` | Data APIs not subscribed |
+| `807` | `DhanHQ::TokenExpiredError` | Access token is expired |
+| `808` | `DhanHQ::AuthenticationFailedError` | Authentication failed - client ID or access token invalid |
+| `809` | `DhanHQ::InvalidTokenError` | Access token is invalid |
+| `810` | `DhanHQ::InvalidClientIDError` | Client ID is invalid |
+| `811` | `DhanHQ::InvalidRequestError` | Invalid expiry date |
+| `812` | `DhanHQ::InvalidRequestError` | Invalid date format |
+| `813` | `DhanHQ::InvalidRequestError` | Invalid security ID |
+| `814` | `DhanHQ::InvalidRequestError` | Invalid request |
+
+## User Action Checklist
+
+### Invalid Data Subscription (`806` or `DH-902`)
+If you receive access errors:
+1. Log in to `web.dhan.co`.
+2. Go to **My Profile** -> **Access DhanHQ APIs**.
+3. Verify that the **Data API** plan is active.
+4. If not active, activate it, generate a fresh access token, and retry.
+
+### Static IP Error (`DH-911` or IP issue)
+If placing or managing orders fails with IP errors, ensure that the server's public IP is whitelisted in your Dhan console.

data/skills/dhanhq-ruby/references/funds.md

@@ -0,0 +1,67 @@
+# Funds & Margin — Complete Reference (Ruby SDK)
+
+The Ruby SDK exposes first-class models `DhanHQ::Models::Funds` and `DhanHQ::Models::Margin` for funds retrieval and pre-flight margin checks (both single-order and multi-leg).
+
+## Fund Limits
+
+Use `DhanHQ::Models::Funds.fetch`:
+
+```ruby
+funds = DhanHQ::Models::Funds.fetch
+
+puts "Available Balance: Rs. #{funds.availabel_balance || funds.available_balance}"
+puts "Utilized:          Rs. #{funds.utilized_amount}"
+puts "Collateral:        Rs. #{funds.collateral_amount}"
+puts "Withdrawable:      Rs. #{funds.withdrawable_balance}"
+```
+
+Normalized model attributes:
+- `dhan_client_id`
+- `availabel_balance` (or alias `available_balance`)
+- `sod_limit`
+- `collateral_amount`
+- `receiveable_amount`
+- `utilized_amount`
+- `blocked_payout_amount`
+- `withdrawable_balance`
+
+---
+
+## Margin Calculator — Single Order
+
+Use `DhanHQ::Models::Margin.calculate(params)`:
+
+```ruby
+margin = DhanHQ::Models::Margin.calculate(
+  security_id: "2885",
+  exchange_segment: "NSE_EQ",
+  transaction_type: "BUY",
+  quantity: 10,
+  product_type: "CNC",
+  price: 2450.0
+)
+
+puts "Total Margin:       Rs. #{margin.total_margin}"
+puts "Available Balance:  Rs. #{margin.available_balance}"
+puts "Brokerage Charges:  Rs. #{margin.brokerage}"
+puts "Leverage Offered:   #{margin.leverage}x"
+```
+
+---
+
+## Multi-Order Margin
+
+Unlike the Python SDK, the Ruby SDK has first-class support for multi-leg portfolio margin calculation via `DhanHQ::Models::Margin.calculate_multi(params)`:
+
+```ruby
+margin = DhanHQ::Models::Margin.calculate_multi(
+  include_position: true,
+  include_orders: true,
+  scripts: [
+    { exchange_segment: "NSE_EQ", transaction_type: "BUY", quantity: 100, product_type: "CNC", security_id: "1333", price: 1428.0 },
+    { exchange_segment: "NSE_EQ", transaction_type: "SELL", quantity: 50, product_type: "INTRADAY", security_id: "11536", price: 3000.0 }
+  ]
+)
+
+puts "Portfolio Total Margin Required: Rs. #{margin.total_margin}"
+```