# sanketagarwal/hyperliquid-trading-agent architecture

> Architecture diagram of the GitHub repository sanketagarwal/hyperliquid-trading-agent, 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/sanketagarwal/hyperliquid-trading-agent
- Repository: https://github.com/sanketagarwal/hyperliquid-trading-agent

## Overview

This is a Hyperliquid perpetual-futures trading agent: a configured trading loop gathers account and candle context, computes local indicators, asks Claude for per-asset decisions, applies code-enforced risk checks, and submits approved orders. The loop also exposes diary and log endpoints. The README documents the overall sequence; sampled source confirms the main orchestration, exchange wrapper, indicator calculations, Claude integration, and risk checks. Some implementation details in the unsampled portions of the loop are not independently verified here.

Main entry points: [`src/main.py`](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/main.py) (Trading loop and API), [`src/trading/hyperliquid_api.py`](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/trading/hyperliquid_api.py) (Hyperliquid client), [`src/agent/decision_maker.py`](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/agent/decision_maker.py) (Claude decisions), [`src/config_loader.py`](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/config_loader.py) (Environment config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Trading loop"]
  node_main["Trading loop and API<br/>[main.py]"]
  node_config["Environment config<br/>[config_loader.py]"]
end

subgraph group_analysis["Market analysis"]
  node_indicators["Local indicators"]
  node_agent["Claude decisions<br/>[decision_maker.py]"]
end

subgraph group_execution["Risk and execution"]
  node_exchange["Hyperliquid client<br/>[hyperliquid_api.py]"]
  node_risk["Risk guards<br/>[risk_manager.py]"]
end

subgraph group_interfaces["External interfaces"]
  node_claude["Anthropic Claude"]
  node_hyperliquid["Hyperliquid exchange"]
end

node_operator(("Operator"))

node_operator -->|"starts loop"| node_main
node_main -->|"reads settings"| node_config
node_main -->|"fetches account and market data"| node_exchange
node_exchange -->|"queries candles and account"| node_hyperliquid
node_exchange -->|"submits and manages orders"| node_hyperliquid
node_main -->|"computes indicators"| node_indicators
node_main -->|"requests decisions"| node_agent
node_agent -->|"sends context"| node_claude
node_claude -->|"returns decisions"| node_agent
node_main -->|"validates trades"| node_risk
node_main -->|"executes approved trades"| node_exchange
node_main -->|"closes loss-limit positions"| node_exchange
node_operator -->|"requests diary or logs"| node_main
node_main -->|"serves API response"| node_operator
node_main -->|"records trade activity"| node_agent
node_agent -->|"reads settings"| node_config
node_risk -->|"reads limits"| node_config
node_exchange -->|"reads credentials"| node_config

click node_main "https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/main.py"
click node_config "https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/config_loader.py"
click node_exchange "https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/trading/hyperliquid_api.py"
click node_indicators "https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/indicators/local_indicators.py"
click node_agent "https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/agent/decision_maker.py"
click node_risk "https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/risk_manager.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_main,node_config toneBlue
class node_indicators,node_agent toneAmber
class node_exchange,node_risk toneMint
class node_claude,node_hyperliquid toneRose
class node_operator toneIndigo
```

## Components

### Trading loop

- [Trading loop and API](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/main.py): `src/main.py`
- [Environment config](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/config_loader.py): `src/config_loader.py`

### Market analysis

- [Local indicators](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/indicators/local_indicators.py): `src/indicators/local_indicators.py`
- [Claude decisions](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/agent/decision_maker.py): `src/agent/decision_maker.py`

### Risk and execution

- [Hyperliquid client](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/trading/hyperliquid_api.py): `src/trading/hyperliquid_api.py`
- [Risk guards](https://github.com/sanketagarwal/hyperliquid-trading-agent/blob/master/src/risk_manager.py): `src/risk_manager.py`

### External interfaces

- **Anthropic Claude**
- **Hyperliquid exchange**

### Other components

- **Operator**

## Connections

- Operator → Trading loop and API: starts loop
- Trading loop and API → Environment config: reads settings
- Trading loop and API → Hyperliquid client: fetches account and market data
- Hyperliquid client → Hyperliquid exchange: queries candles and account
- Hyperliquid client → Hyperliquid exchange: submits and manages orders
- Trading loop and API → Local indicators: computes indicators
- Trading loop and API → Claude decisions: requests decisions
- Claude decisions → Anthropic Claude: sends context
- Anthropic Claude → Claude decisions: returns decisions
- Trading loop and API → Risk guards: validates trades
- Trading loop and API → Hyperliquid client: executes approved trades
- Trading loop and API → Hyperliquid client: closes loss-limit positions
- Operator → Trading loop and API: requests diary or logs
- Trading loop and API → Operator: serves API response
- Trading loop and API → Claude decisions: records trade activity
- Claude decisions → Environment config: reads settings
- Risk guards → Environment config: reads limits
- Hyperliquid client → Environment config: reads credentials