# ojuawo/hyperliquidaibot architecture

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

- Interactive diagram: https://gitdiagram.com/ojuawo/hyperliquidaibot
- Repository: https://github.com/ojuawo/hyperliquidaibot

## Overview

HyperliquidAiBot is a continuously running .NET trading bot that turns exchange and account data into AI trade proposals, checks them against deterministic safety rules, then submits approved orders. Its main workflow is orchestrated by the background TradingWorker: gather market/account inputs, compute technical indicators, request a research decision, evaluate risk, and execute orders with protective triggers. A web dashboard exposes status and cycle-trigger controls, backed by in-memory state. The README documents REST/WebSocket exchange access, EIP-712 signing, dry-run operation, and Gemini/OpenAI support; some worker and client wiring is inferred only where excerpts omit method bodies.

Main entry points: [`src/HyperliquidAiBot.Worker/TradingWorker.cs`](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/TradingWorker.cs) (Trading worker), [`src/HyperliquidAiBot.Core/Services/HyperliquidClient.cs`](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/HyperliquidClient.cs) (Exchange client), [`src/HyperliquidAiBot.Worker/Program.cs`](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/Program.cs) (Web host and API), [`src/HyperliquidAiBot.Core/Services/ResearchEngine.cs`](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/ResearchEngine.cs) (AI research engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Trading runtime"]
  node_worker["Trading worker<br/>[TradingWorker.cs]"]
  node_settings["Bot settings<br/>[BotSettings.cs]"]
end

subgraph group_analysis["Market analysis"]
  node_market["Market context<br/>[MarketContext.cs]"]
  node_technical["Technical analysis"]
  node_research["AI research engine<br/>[ResearchEngine.cs]"]
  node_decision["Trade decision<br/>[TradeDecision.cs]"]
end

subgraph group_execution["Risk and execution"]
  node_client["Exchange client"]
  node_payloads["Exchange payloads"]
  node_signer["EIP-712 signer"]
  node_risk["Risk manager<br/>[RiskManager.cs]"]
  node_rules["Risk rules<br/>[RiskRules.cs]"]
end

subgraph group_operations["Dashboard and state"]
  node_state[("In-memory bot state<br/>[BotStateService.cs]")]
  node_program["Web host and API<br/>[Program.cs]"]
  node_dashboard["Visual dashboard<br/>[index.html]"]
end

node_operator(("Bot operator"))
node_exchange{{"Hyperliquid DEX"}}
node_llm{{"Gemini / OpenAI"}}

node_settings -->|"configures"| node_worker
node_worker -->|"fetches market data"| node_client
node_client -->|"requests data"| node_exchange
node_exchange -->|"returns data"| node_client
node_worker -->|"builds context"| node_market
node_worker -->|"computes indicators"| node_technical
node_technical -->|"returns indicators"| node_market
node_worker -->|"requests analysis"| node_research
node_research -->|"requests proposal"| node_llm
node_llm -->|"returns proposal"| node_research
node_research -->|"creates"| node_decision
node_worker -->|"evaluates trade"| node_risk
node_risk -->|"applies limits"| node_rules
node_worker -->|"submits approved orders"| node_client
node_client -->|"signs action"| node_signer
node_client -->|"formats exchange payloads"| node_payloads
node_client -->|"posts signed orders"| node_exchange
node_worker -->|"records cycle"| node_state
node_operator -->|"views status"| node_dashboard
node_dashboard -->|"requests dashboard"| node_program
node_program -->|"reads snapshot"| node_state
node_program -->|"queues cycle trigger"| node_state
node_state -->|"signals immediate cycle"| node_worker
node_program -->|"binds configuration"| node_settings

click node_worker "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/TradingWorker.cs"
click node_settings "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Config/BotSettings.cs"
click node_client "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/HyperliquidClient.cs"
click node_payloads "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Models/HyperliquidPayloads.cs"
click node_signer "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/HyperliquidSigner.cs"
click node_market "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Models/MarketContext.cs"
click node_technical "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/TechnicalAnalysisService.cs"
click node_research "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/ResearchEngine.cs"
click node_decision "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Models/TradeDecision.cs"
click node_risk "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/RiskManager.cs"
click node_rules "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Config/RiskRules.cs"
click node_state "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/BotStateService.cs"
click node_program "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/Program.cs"
click node_dashboard "https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/wwwroot/index.html"

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_worker,node_settings toneBlue
class node_market,node_technical,node_research,node_decision toneAmber
class node_client,node_payloads,node_signer,node_risk,node_rules toneMint
class node_state,node_program,node_dashboard toneRose
class node_operator,node_exchange,node_llm toneIndigo
```

## Components

### Trading runtime

- [Trading worker](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/TradingWorker.cs): `src/HyperliquidAiBot.Worker/TradingWorker.cs`
- [Bot settings](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Config/BotSettings.cs): `src/HyperliquidAiBot.Core/Config/BotSettings.cs`

### Market analysis

- [Market context](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Models/MarketContext.cs): `src/HyperliquidAiBot.Core/Models/MarketContext.cs`
- [Technical analysis](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/TechnicalAnalysisService.cs): `src/HyperliquidAiBot.Core/Services/TechnicalAnalysisService.cs`
- [AI research engine](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/ResearchEngine.cs): `src/HyperliquidAiBot.Core/Services/ResearchEngine.cs`
- [Trade decision](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Models/TradeDecision.cs): `src/HyperliquidAiBot.Core/Models/TradeDecision.cs`

### Risk and execution

- [Exchange client](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/HyperliquidClient.cs): `src/HyperliquidAiBot.Core/Services/HyperliquidClient.cs`
- [Exchange payloads](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Models/HyperliquidPayloads.cs): `src/HyperliquidAiBot.Core/Models/HyperliquidPayloads.cs`
- [EIP-712 signer](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/HyperliquidSigner.cs): `src/HyperliquidAiBot.Core/Services/HyperliquidSigner.cs`
- [Risk manager](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/RiskManager.cs): `src/HyperliquidAiBot.Core/Services/RiskManager.cs`
- [Risk rules](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Config/RiskRules.cs): `src/HyperliquidAiBot.Core/Config/RiskRules.cs`

### Dashboard and state

- [In-memory bot state](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Core/Services/BotStateService.cs): `src/HyperliquidAiBot.Core/Services/BotStateService.cs`
- [Web host and API](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/Program.cs): `src/HyperliquidAiBot.Worker/Program.cs`
- [Visual dashboard](https://github.com/ojuawo/hyperliquidaibot/blob/main/src/HyperliquidAiBot.Worker/wwwroot/index.html): `src/HyperliquidAiBot.Worker/wwwroot/index.html`

### Other components

- **Bot operator**
- **Hyperliquid DEX**
- **Gemini / OpenAI**

## Connections

- Bot settings → Trading worker: configures
- Trading worker → Exchange client: fetches market data
- Exchange client → Hyperliquid DEX: requests data
- Hyperliquid DEX → Exchange client: returns data
- Trading worker → Market context: builds context
- Trading worker → Technical analysis: computes indicators
- Technical analysis → Market context: returns indicators
- Trading worker → AI research engine: requests analysis
- AI research engine → Gemini / OpenAI: requests proposal
- Gemini / OpenAI → AI research engine: returns proposal
- AI research engine → Trade decision: creates
- Trading worker → Risk manager: evaluates trade
- Risk manager → Risk rules: applies limits
- Trading worker → Exchange client: submits approved orders
- Exchange client → EIP-712 signer: signs action
- Exchange client → Exchange payloads: formats exchange payloads
- Exchange client → Hyperliquid DEX: posts signed orders
- Trading worker → In-memory bot state: records cycle
- Bot operator → Visual dashboard: views status
- Visual dashboard → Web host and API: requests dashboard
- Web host and API → In-memory bot state: reads snapshot
- Web host and API → In-memory bot state: queues cycle trigger
- In-memory bot state → Trading worker: signals immediate cycle
- Web host and API → Bot settings: binds configuration