# dhan-oss/dhanhq-py architecture

> Architecture diagram of the GitHub repository dhan-oss/dhanhq-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhan-oss/dhanhq-py
- Repository: https://github.com/dhan-oss/dhanhq-py

## Overview

DhanHQ-py is the official Python client for Dhan’s trading and market-data APIs. The main workflow is: a user obtains credentials through authentication, creates a connection context and client, then invokes trading, account, or data operations; the client sends REST requests through a shared HTTP layer and returns API responses. Separate WebSocket clients provide live market, full-depth, and US-stock feeds. The README documents the broader feature set; several service modules are represented from their names and documented capabilities because their source was not sampled.

Main entry points: [`src/dhanhq/dhanhq.py`](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhanhq.py) (DhanHQ client), [`src/dhanhq/dhan_http.py`](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhan_http.py) (REST transport), [`src/dhanhq/dhan_context.py`](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhan_context.py) (DhanContext), [`src/dhanhq/auth.py`](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/auth.py) (DhanLogin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connection["Connection and Auth"]
  node_login["DhanLogin<br/>[auth.py]"]
  node_context["DhanContext<br/>[dhan_context.py]"]
  node_http["REST transport<br/>[dhan_http.py]"]
  node_facade["DhanHQ client<br/>[dhanhq.py]"]
end

subgraph group_trading["Trading Operations"]
  node_orders["Orders<br/>[_order.py]"]
  node_conditional["Conditional orders"]
  node_forever["Forever orders<br/>[_forever_order.py]"]
  node_super["Super orders<br/>[_super_order.py]"]
  node_controls["Trader controls<br/>[_trader_control.py]"]
end

subgraph group_account["Account and Instruments"]
  node_portfolio["Portfolio<br/>[_portfolio.py]"]
  node_funds["Funds and margin<br/>[_funds.py]"]
  node_statements["Statements and reports<br/>[_statement.py]"]
  node_security["eDIS and securities<br/>[_security.py]"]
end

subgraph group_marketdata["Market Data"]
  node_history["Historical data"]
  node_quotes["Quotes and option chain<br/>[_market_feed.py]"]
  node_options["Option chain<br/>[_option_chain.py]"]
  node_live["Live market feed<br/>[marketfeed.py]"]
  node_depth["Full market depth<br/>[fulldepth.py]"]
end

subgraph group_global["Global Stocks"]
  node_globalops["Global stock operations<br/>[_global_stocks.py]"]
  node_globalfeed["Global stocks feed"]
end

node_user(("Client application"))
node_dhanapi{{"Dhan API"}}
node_ws{{"Dhan WebSocket services"}}

node_user -->|"authenticates"| node_login
node_login -->|"requests tokens"| node_dhanapi
node_user -->|"provides credentials"| node_context
node_context -->|"creates transport"| node_http
node_context -->|"creates login"| node_login
node_user -->|"invokes client"| node_facade
node_facade -->|"uses context"| node_context
node_facade -->|"delegates orders"| node_orders
node_facade -->|"delegates conditions"| node_conditional
node_facade -->|"delegates orders"| node_forever
node_facade -->|"delegates orders"| node_super
node_facade -->|"delegates controls"| node_controls
node_facade -->|"delegates portfolio"| node_portfolio
node_facade -->|"delegates funds"| node_funds
node_facade -->|"delegates reports"| node_statements
node_facade -->|"delegates securities"| node_security
node_facade -->|"delegates history"| node_history
node_facade -->|"delegates quotes"| node_quotes
node_facade -->|"delegates options"| node_options
node_facade -->|"delegates global trades"| node_globalops
node_orders -->|"sends requests"| node_http
node_conditional -->|"sends requests"| node_http
node_forever -->|"sends requests"| node_http
node_super -->|"sends requests"| node_http
node_controls -->|"sends requests"| node_http
node_portfolio -->|"sends requests"| node_http
node_funds -->|"sends requests"| node_http
node_statements -->|"sends requests"| node_http
node_security -->|"sends requests"| node_http
node_history -->|"sends requests"| node_http
node_quotes -->|"sends requests"| node_http
node_options -->|"sends requests"| node_http
node_globalops -->|"sends requests"| node_http
node_http -->|"sends REST"| node_dhanapi
node_user -->|"subscribes"| node_live
node_user -->|"subscribes"| node_depth
node_user -->|"subscribes"| node_globalfeed
node_live -->|"opens feed"| node_ws
node_depth -->|"opens feed"| node_ws
node_globalfeed -->|"opens feed"| node_ws

click node_login "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/auth.py"
click node_context "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhan_context.py"
click node_http "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhan_http.py"
click node_facade "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhanhq.py"
click node_orders "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_order.py"
click node_conditional "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_conditional_order.py"
click node_forever "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_forever_order.py"
click node_super "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_super_order.py"
click node_controls "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_trader_control.py"
click node_portfolio "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_portfolio.py"
click node_funds "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_funds.py"
click node_statements "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_statement.py"
click node_security "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_security.py"
click node_history "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_historical_data.py"
click node_quotes "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_market_feed.py"
click node_options "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_option_chain.py"
click node_live "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/marketfeed.py"
click node_depth "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/fulldepth.py"
click node_globalops "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_global_stocks.py"
click node_globalfeed "https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/global_stocks_feed.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_login,node_context,node_http,node_facade,node_user toneBlue
class node_orders,node_conditional,node_forever,node_super,node_controls toneAmber
class node_portfolio,node_funds,node_statements,node_security,node_dhanapi toneMint
class node_history,node_quotes,node_options,node_live,node_depth toneRose
class node_globalops,node_globalfeed,node_ws toneIndigo
```

## Components

### Connection and Auth

- [DhanLogin](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/auth.py): `src/dhanhq/auth.py`
- [DhanContext](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhan_context.py): `src/dhanhq/dhan_context.py`
- [REST transport](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhan_http.py): `src/dhanhq/dhan_http.py`
- [DhanHQ client](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/dhanhq.py): `src/dhanhq/dhanhq.py`

### Trading Operations

- [Orders](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_order.py): `src/dhanhq/_order.py`
- [Conditional orders](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_conditional_order.py): `src/dhanhq/_conditional_order.py`
- [Forever orders](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_forever_order.py): `src/dhanhq/_forever_order.py`
- [Super orders](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_super_order.py): `src/dhanhq/_super_order.py`
- [Trader controls](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_trader_control.py): `src/dhanhq/_trader_control.py`

### Account and Instruments

- [Portfolio](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_portfolio.py): `src/dhanhq/_portfolio.py`
- [Funds and margin](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_funds.py): `src/dhanhq/_funds.py`
- [Statements and reports](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_statement.py): `src/dhanhq/_statement.py`
- [eDIS and securities](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_security.py): `src/dhanhq/_security.py`

### Market Data

- [Historical data](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_historical_data.py): `src/dhanhq/_historical_data.py`
- [Quotes and option chain](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_market_feed.py): `src/dhanhq/_market_feed.py`
- [Option chain](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_option_chain.py): `src/dhanhq/_option_chain.py`
- [Live market feed](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/marketfeed.py): `src/dhanhq/marketfeed.py`
- [Full market depth](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/fulldepth.py): `src/dhanhq/fulldepth.py`

### Global Stocks

- [Global stock operations](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/_global_stocks.py): `src/dhanhq/_global_stocks.py`
- [Global stocks feed](https://github.com/dhan-oss/dhanhq-py/blob/main/src/dhanhq/global_stocks_feed.py): `src/dhanhq/global_stocks_feed.py`

### Other components

- **Client application**
- **Dhan API**
- **Dhan WebSocket services**

## Connections

- Client application → DhanLogin: authenticates
- DhanLogin → Dhan API: requests tokens
- Client application → DhanContext: provides credentials
- DhanContext → REST transport: creates transport
- DhanContext → DhanLogin: creates login
- Client application → DhanHQ client: invokes client
- DhanHQ client → DhanContext: uses context
- DhanHQ client → Orders: delegates orders
- DhanHQ client → Conditional orders: delegates conditions
- DhanHQ client → Forever orders: delegates orders
- DhanHQ client → Super orders: delegates orders
- DhanHQ client → Trader controls: delegates controls
- DhanHQ client → Portfolio: delegates portfolio
- DhanHQ client → Funds and margin: delegates funds
- DhanHQ client → Statements and reports: delegates reports
- DhanHQ client → eDIS and securities: delegates securities
- DhanHQ client → Historical data: delegates history
- DhanHQ client → Quotes and option chain: delegates quotes
- DhanHQ client → Option chain: delegates options
- DhanHQ client → Global stock operations: delegates global trades
- Orders → REST transport: sends requests
- Conditional orders → REST transport: sends requests
- Forever orders → REST transport: sends requests
- Super orders → REST transport: sends requests
- Trader controls → REST transport: sends requests
- Portfolio → REST transport: sends requests
- Funds and margin → REST transport: sends requests
- Statements and reports → REST transport: sends requests
- eDIS and securities → REST transport: sends requests
- Historical data → REST transport: sends requests
- Quotes and option chain → REST transport: sends requests
- Option chain → REST transport: sends requests
- Global stock operations → REST transport: sends requests
- REST transport → Dhan API: sends REST
- Client application → Live market feed: subscribes
- Client application → Full market depth: subscribes
- Client application → Global stocks feed: subscribes
- Live market feed → Dhan WebSocket services: opens feed
- Full market depth → Dhan WebSocket services: opens feed
- Global stocks feed → Dhan WebSocket services: opens feed