dhan-rs 0.1.7

# dhan-rs

[![Crates.io](https://img.shields.io/crates/v/dhan-rs.svg)](https://crates.io/crates/dhan-rs)
[![Documentation](https://docs.rs/dhan-rs/badge.svg)](https://docs.rs/dhan-rs)
[![CI](https://github.com/SPRAGE/dhan-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/SPRAGE/dhan-rs/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

An **unofficial** Rust client library for the [DhanHQ Broker API v2](https://dhanhq.co/docs/v2/).

> [!CAUTION]
> **⚠️ AI-GENERATED CODE — USE AT YOUR OWN RISK**
>
> This entire crate was generated by AI (GitHub Copilot / Claude). It includes
> local contract and recovery hardening, but **has not been extensively tested
> against the live API**. Before using this in production or with real money:
>
> - Review the source code thoroughly
> - Write your own integration tests against DhanHQ's sandbox/live API
> - Validate all order placement, modification, and cancellation flows
> - Verify WebSocket market feed parsing against real data
> - This is **not** an official DhanHQ product and is not endorsed by DhanHQ
>
> **The authors accept no responsibility for financial losses incurred through
> the use of this library.**

## Audit and design documentation

- [Current implementation status and operating boundaries](docs/implementation-status.md)
- [Sandbox testing and safety boundary](docs/sandbox-testing.md)
- [Current WebSocket stability guide](docs/websocket-stability.md)
- [Historical DhanHQ API v2 compliance audit](docs/dhan-v2-compliance-audit.md)
- [Historical WebSocket stability design](docs/websocket-stability-design.md)

The audit and design document the pre-remediation baseline and remain useful
evidence of Dhan documentation conflicts. The implementation-status and
stability pages describe the current code, deterministic local tests, and the
boundaries that still require authenticated validation.

---

## Features

- **Broad API coverage** — Typed REST modules including Data APIs, Global
  Stocks, multi-order/eDIS additions, and instrument-master downloads; see
  the [implementation status](docs/implementation-status.md) for conflicts
  and live-validation limits
- **WebSocket streaming** — Low-level market/order streams, a supervised
  standard-feed manager, a managed order-update supervisor, and separate
  20-level/200-level Full Market Depth streams
- **Typed models** — Serde-backed request and response types across implemented modules
- **Async/await** — Built on `tokio` and `reqwest` for async-first design
- **Native binary parsing** — Little-endian standard-feed packets parsed without an external binary parsing crate
- **Ergonomic error handling** — Rich `DhanError` enum with API error codes, HTTP errors, JSON errors, and WebSocket errors

## Supported API Modules

| Module | Description |
|---|---|
| **Authentication** | Access token generation, renewal, consent flows (individual & partner) |
| **Orders** | Place, modify, cancel, slice orders; order book & trade book |
| **Super Orders** | Multi-leg bracket/cover orders with stop-loss and target |
| **Forever Orders** | GTT (Good Till Triggered) and OCO (One Cancels Other) orders |
| **Conditional Triggers** | Alert-based conditional order placement |
| **Portfolio** | Holdings, positions, position conversion, exit all |
| **eDIS** | T-PIN generation, eDIS form, delivery inquiry |
| **Trader's Control** | Kill switch, P&L-based auto-exit |
| **Funds** | Margin calculator (single & multi), fund limits |
| **Statements** | Ledger reports, trade history |
| **Market Quotes** | LTP, OHLC, full market depth snapshots (REST) |
| **Historical Data** | Daily and intraday OHLCV candles |
| **Option Chain** | Option chain data with Greeks, expiry lists |
| **Postback** | Webhook payload deserialization types |
| **WebSocket: Market Feed** | Real-time ticker, quote, and Full packets on the standard binary protocol |
| **WebSocket: Managed Market Feed** | Lazy multi-socket ownership, retry, health, gap acknowledgement, and graceful shutdown |
| **WebSocket: Order Updates** | Real-time order status changes (JSON protocol), plus an optional managed/reconciling supervisor |
| **Full Market Depth** | Separate caller-polled 20-level and 200-level protocols; no depth reconnect manager yet |
| **Data APIs** | Rolling expired options, technical metrics, market movers, and company information |
| **Global Stocks** | Orders, estimates, margin, trades, market status, holdings, and fund limits |
| **Instruments** | Compact/detailed public CSV and authenticated segment CSV downloads |

For the managed market feed, create parsed receivers before subscribing.
Otherwise a live packet with no receiver is intentionally reported as a
durable data-quality gap rather than discarded silently.

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
dhan-rs = "0.1"
tokio = { version = "1", features = ["full"] }
```

## Quick Start

### REST API — Place an Order

```rust,no_run
use dhan_rs::DhanClient;
use dhan_rs::types::orders::PlaceOrderRequest;
use dhan_rs::types::enums::*;

#[tokio::main]
async fn main() -> dhan_rs::Result<()> {
    let client = DhanClient::new("your-client-id", "your-access-token");

    let req = PlaceOrderRequest {
        dhan_client_id: "your-client-id".into(),
        correlation_id: Some("example-order-1".into()),
        transaction_type: TransactionType::BUY,
        exchange_segment: ExchangeSegment::NSE_EQ,
        product_type: ProductType::INTRADAY,
        order_type: OrderType::LIMIT,
        validity: Validity::DAY,
        security_id: "1333".into(),    // HDFC Bank
        quantity: 1,
        disclosed_quantity: None,
        price: Some(1500.0),
        trigger_price: None,
        after_market_order: Some(false),
        amo_time: None,
        bo_profit_value: None,
        bo_stop_loss_value: None,
    };

    let response = client.place_order(&req).await?;
    println!("Order placed: {:?}", response);
    Ok(())
}
```

### REST API — Get Holdings

```rust,no_run
use dhan_rs::DhanClient;

#[tokio::main]
async fn main() -> dhan_rs::Result<()> {
    let client = DhanClient::new("your-client-id", "your-access-token");

    let holdings = client.get_holdings().await?;
    for h in &holdings {
        println!("{}: {} shares @ ₹{:.2}",
            h.trading_symbol.as_deref().unwrap_or("?"),
            h.total_qty.unwrap_or(0),
            h.avg_cost_price.unwrap_or(0.0),
        );
    }
    Ok(())
}
```

### REST API — Market Quotes

```rust,no_run
use dhan_rs::DhanClient;
use dhan_rs::types::market_quote::MarketQuoteRequest;

#[tokio::main]
async fn main() -> dhan_rs::Result<()> {
    let client = DhanClient::new("your-client-id", "your-access-token");

    let mut req = MarketQuoteRequest::new();
    req.insert("NSE_EQ".into(), vec![1333, 11536]);

    let ltp = client.get_ltp(&req).await?;
    println!("LTP data: {:?}", ltp);
    Ok(())
}
```

### WebSocket — Live Market Feed

```rust,no_run
use dhan_rs::ws::market_feed::{MarketFeedStream, Instrument};
use dhan_rs::types::enums::FeedRequestCode;
use futures_util::StreamExt;

#[tokio::main]
async fn main() -> dhan_rs::Result<()> {
    let mut stream = MarketFeedStream::connect("your-client-id", "your-access-token").await?;

    let instruments = vec![
        Instrument::new("NSE_EQ", "1333"),   // HDFC Bank
        Instrument::new("NSE_EQ", "11536"),  // TCS
    ];
    stream.subscribe(FeedRequestCode::SubscribeTicker, &instruments).await?;

    while let Some(event) = stream.next().await {
        match event {
            Ok(e) => println!("{e:?}"),
            Err(e) => eprintln!("Error: {e}"),
        }
    }
    Ok(())
}
```

### WebSocket — Live Order Updates

```rust,no_run
use dhan_rs::ws::order_update::OrderUpdateStream;
use futures_util::StreamExt;

#[tokio::main]
async fn main() -> dhan_rs::Result<()> {
    let mut stream = OrderUpdateStream::connect(
        "your-client-id",
        "your-access-token",
    ).await?;

    while let Some(msg) = stream.next().await {
        match msg {
            Ok(update) => println!(
                "Order {} → {}",
                update.Data.OrderNo.as_deref().unwrap_or("?"),
                update.Data.Status.as_deref().unwrap_or("?"),
            ),
            Err(e) => eprintln!("Error: {e}"),
        }
    }
    Ok(())
}
```

### Option Chain with Greeks

```rust,no_run
use dhan_rs::DhanClient;
use dhan_rs::types::option_chain::OptionChainRequest;

#[tokio::main]
async fn main() -> dhan_rs::Result<()> {
    let client = DhanClient::new("your-client-id", "your-access-token");

    let req = OptionChainRequest {
        UnderlyingScrip: 13,
        UnderlyingSeg: "IDX_I".into(),
        Expiry: "2026-02-26".into(),
    };

    let chain = client.get_option_chain(&req).await?;
    println!("NIFTY spot: {:?}", chain.data.last_price);

    for (strike, data) in &chain.data.oc {
        if let Some(ce) = &data.ce {
            println!("Strike {strike} CE — LTP: {:?}, IV: {:?}, Delta: {:?}",
                ce.last_price, ce.implied_volatility,
                ce.greeks.as_ref().map(|g| g.delta));
        }
    }
    Ok(())
}
```

## Architecture

```
dhan-rs/
├── src/
│   ├── lib.rs              # Crate root, re-exports
│   ├── client.rs           # DhanClient — HTTP client with auth
│   ├── error.rs            # DhanError enum, Result alias
│   ├── constants.rs        # Base URLs, WebSocket URLs, rate limits
│   ├── types/              # Request/response structs
│   │   ├── enums.rs        # 22+ shared enums (ExchangeSegment, OrderType, etc.)
│   │   ├── orders.rs       # Order types
│   │   ├── super_order.rs  # Super Order types
│   │   ├── forever_order.rs # Forever/GTT Order types
│   │   ├── conditional.rs  # Conditional trigger types
│   │   ├── portfolio.rs    # Holdings, Positions
│   │   ├── funds.rs        # Margin calculator, fund limits
│   │   ├── historical.rs   # OHLCV candle types
│   │   ├── option_chain.rs # Option chain + Greeks
│   │   ├── market_quote.rs # LTP, OHLC, depth quotes
│   │   ├── postback.rs     # Webhook payload type
│   │   └── ...             # auth, data, global_stocks, instruments, etc.
│   ├── api/                # Endpoint implementations (impl DhanClient)
│   │   ├── orders.rs       # 9 order endpoints
│   │   ├── portfolio.rs    # Holdings, positions, convert, exit
│   │   ├── auth.rs         # Token generation, consent flows
│   │   └── ...             # 18 endpoint modules total
│   └── ws/                 # WebSocket streaming
│       ├── market_feed.rs  # Standard binary feed parser + Stream impl
│       ├── manager.rs      # Supervised standard-feed owner
│       ├── order_update.rs # JSON stream and managed order supervisor
│       └── depth.rs        # Separate 20-level and 200-level depth streams
```

`DhanClient` methods are grouped into inherent `impl DhanClient` blocks across
the `api/` modules. The current implementation status page is the authoritative
coverage guide; the surface is deliberately not presented as complete Dhan API
parity.
WebSocket streams implement `futures_util::Stream` for integration with async
combinators.

## API Reference

Full documentation is available on [docs.rs](https://docs.rs/dhan-rs).

### DhanClient Methods

<details>
<summary><strong>Orders</strong> (9 methods)</summary>

| Method | Description |
|---|---|
| `place_order(req)` | Place a new order |
| `modify_order(order_id, req)` | Modify a pending order |
| `cancel_order(order_id)` | Cancel an open order |
| `slice_order(req)` | Slice a large order into smaller ones |
| `get_orders()` | Get all orders for the day |
| `get_order(order_id)` | Get a specific order by ID |
| `get_order_by_correlation_id(id)` | Get order by external correlation ID |
| `get_trades()` | Get all trades for the day |
| `get_trades_for_order(order_id)` | Get trades for a specific order |

</details>

<details>
<summary><strong>Super Orders</strong> (5 methods)</summary>

| Method | Description |
|---|---|
| `place_super_order(req)` | Place a bracket/cover order |
| `modify_super_order(order_id, req)` | Modify a super order |
| `cancel_super_order(order_id, leg)` | Cancel a super order leg |
| `cancel_super_order_no_content(order_id, leg)` | Cancel when the HTML empty-response contract applies |
| `get_super_orders()` | Get all super orders |

</details>

<details>
<summary><strong>Forever Orders</strong> (5 methods)</summary>

| Method | Description |
|---|---|
| `create_forever_order(req)` | Create a GTT/OCO order |
| `modify_forever_order(order_id, req)` | Modify a forever order |
| `delete_forever_order(order_id)` | Delete a forever order |
| `get_all_forever_orders()` | Get all forever orders |
| `get_all_forever_orders_openapi()` | List through the linked OpenAPI route |

</details>

<details>
<summary><strong>Conditional Triggers</strong> (6 methods)</summary>

| Method | Description |
|---|---|
| `place_conditional_trigger(req)` | Create a conditional trigger |
| `modify_conditional_trigger(id, req)` | Modify a trigger |
| `delete_conditional_trigger(id)` | Delete a trigger |
| `get_conditional_trigger(id)` | Get a specific trigger |
| `get_all_conditional_triggers()` | Get all triggers |
| `place_multi_order(req)` | Place the OpenAPI multi-order batch |

</details>

<details>
<summary><strong>Portfolio</strong> (4 methods)</summary>

| Method | Description |
|---|---|
| `get_holdings()` | Get demat holdings |
| `get_positions()` | Get open positions |
| `convert_position(req)` | Convert position product type |
| `exit_all_positions()` | Exit all open positions |

</details>

<details>
<summary><strong>Funds & Margin</strong> (3 methods)</summary>

| Method | Description |
|---|---|
| `calculate_margin(req)` | Calculate margin for a single order |
| `calculate_multi_margin(req)` | Calculate margin for multiple orders |
| `get_fund_limit()` | Get available fund limits |

</details>

<details>
<summary><strong>Market Data</strong> (7 methods)</summary>

| Method | Description |
|---|---|
| `get_ltp(req)` | Get last traded price |
| `get_ohlc(req)` | Get OHLC data |
| `get_quote(req)` | Get full market depth quote |
| `get_daily_historical(req)` | Get daily OHLCV candles |
| `get_intraday_historical(req)` | Get intraday candles |
| `get_option_chain(req)` | Get option chain with Greeks |
| `get_expiry_list(req)` | Get expiry dates |

</details>

<details>
<summary><strong>Selected additional methods</strong></summary>

| Method | Description |
|---|---|
| `generate_access_token(...)` | Generate JWT access token |
| `renew_token()` | Renew expiring token |
| `generate_consent(...)` / `consume_consent(...)` | API key consent flow |
| `partner_generate_consent(...)` / `partner_consume_consent(...)` | Partner consent flow |
| `get_profile()` | Get user profile |
| `set_ip(req)` / `modify_ip(req)` / `get_ip()` | Static IP management |
| `generate_tpin()` / `generate_edis_form(req)` / `generate_bulk_edis_form(req)` / `inquire_edis(isin)` | eDIS |
| `manage_kill_switch(status)` / `get_kill_switch_status()` | Kill switch |
| `set_pnl_exit(req)` / `stop_pnl_exit()` / `get_pnl_exit()` | P&L-based exit |
| `get_ledger_response(from, to)` / `get_ledger(from, to)` / `get_trade_history(from, to, page)` | Statements |

</details>

## Rate Limits

DhanHQ enforces the following rate limits:

| Category | Per Second | Per Minute | Per Hour | Per Day |
|---|---|---|---|---|
| Orders | 10 | 250 | 1,000 | 7,000 |
| Data (REST) | 5 | — | — | 100,000 |
| Historical | 1 | — | — | — |
| Instruments | 20 | — | — | — |

- Max 25 modifications per order
- Option Chain: 1 request per 3 seconds
- Market Quote: up to 1,000 instruments per request
- WebSocket: 5 connections per user, 5,000 instruments each

> **Note:** This library does **not** enforce rate limits automatically. You are
> responsible for staying within the limits.

## Dependencies

| Crate | Purpose |
|---|---|
| `reqwest` | Async HTTP client (rustls-tls) |
| `serde` / `serde_json` | JSON serialization |
| `tokio` | Async runtime |
| `tokio-tungstenite` | WebSocket client (rustls-tls) |
| `thiserror` | Error type derivation |
| `chrono` | Declared date/time serde support; currently unused by `src/` |
| `tracing` | Structured logging |
| `url` | URL parse errors represented by `DhanError` |
| `futures-util` | Stream/Sink traits for WebSocket |
| `bytes` | Raw market-frame buffers |

## Requirements

- Rust 2024 edition (1.85+)
- A DhanHQ trading account with API access
- Access token from [DhanHQ Developer Portal](https://dhanhq.co/docs/v2/)

## License

This project is licensed under the [MIT License](LICENSE).

## Disclaimer

This is an **unofficial**, **AI-generated** client library. It is **not**
affiliated with, endorsed by, or supported by DhanHQ or Dhan. Use at your own
risk. See [DISCLAIMER.md](DISCLAIMER.md) for full details.

Trading in financial markets involves substantial risk of loss. This software
is provided "as is" without warranty of any kind. The authors are not
responsible for any financial losses incurred through the use of this library.