# hammad-tayyab/trading-agent-harold-of-hackathon- architecture

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

## Overview

Harold’s principal workflow is an autonomous trading cycle: gather ETH market and Prism news data, derive signals, obtain a structured Groq decision, apply position and risk controls, then request a signed on-chain trade intent and record the outcome. The main source excerpt is incomplete, so some integrations are supported by README documentation rather than inspected call sites; the README’s example launch path is absent from the supplied tree, and this graph uses the actual root-level files. Local persistence and validation attestations are included as distinct audit paths.

Main entry points: [`Main-Trading_Agent.py`](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py) (Agent orchestrator), [`validation_client.py`](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/validation_client.py) (Checkpoint attestation), [`trade_intent.py`](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/trade_intent.py) (Intent signer), [`prism_news.py`](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/prism_news.py) (News sentiment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cycle["Trading cycle"]
  node_main["Agent orchestrator"]
  node_signals["Signal engine"]
  node_decision["LLM decision"]
  node_position["Position monitor"]
end

subgraph group_inputs["Market intelligence"]
  node_kraken(("Kraken market API"))
  node_prism["News sentiment<br/>[prism_news.py]"]
  node_groq(("Groq LLM"))
end

subgraph group_trust["Trust and execution"]
  node_intent["Intent signer<br/>[trade_intent.py]"]
  node_contractconfig["Contract definitions<br/>[contracts.py]"]
  node_router{{"Risk Router"}}
  node_sepolia(("Sepolia network"))
  node_directexec["Trade execution"]
  node_validation["Checkpoint attestation"]
  node_registry{{"Validation registry"}}
end

subgraph group_records["State and audit"]
  node_state["Agent state<br/>[harold_state.json]"]
  node_trades["Trade log<br/>[trades_log.csv]"]
  node_metrics["Agent metrics<br/>[agent_metrics.json]"]
  node_checkpoints["Checkpoint log<br/>[checkpoints.jsonl]"]
end

node_operator(("Autonomous cycle"))

node_operator -->|"starts cycle"| node_main
node_main -->|"fetches market data"| node_kraken
node_kraken -->|"returns prices"| node_main
node_main -->|"requests news context"| node_prism
node_prism -->|"returns sentiment"| node_main
node_main -->|"builds signals"| node_signals
node_main -->|"requests decision"| node_decision
node_decision -->|"queries model"| node_groq
node_groq -->|"returns JSON"| node_decision
node_main -->|"checks position risk"| node_position
node_main -->|"submits trade intent"| node_intent
node_intent -->|"uses ABI and domain"| node_contractconfig
node_intent -->|"simulates and submits"| node_router
node_router -->|"executes contract call"| node_sepolia
node_main -->|"executes approved trade"| node_directexec
node_directexec -->|"sends signed transaction"| node_sepolia
node_main -->|"posts checkpoint"| node_validation
node_validation -->|"uses registry ABI"| node_contractconfig
node_validation -->|"posts attestation"| node_registry
node_registry -->|"records on-chain"| node_sepolia
node_main -->|"loads and saves"| node_state
node_main -->|"appends trades"| node_trades
node_main -->|"updates metrics"| node_metrics
node_validation -->|"appends checkpoint"| node_checkpoints

click node_main "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py"
click node_signals "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py"
click node_decision "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py"
click node_position "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py"
click node_prism "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/prism_news.py"
click node_intent "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/trade_intent.py"
click node_contractconfig "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/contracts.py"
click node_directexec "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py"
click node_validation "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/validation_client.py"
click node_state "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/harold_state.json"
click node_trades "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/trades_log.csv"
click node_metrics "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/agent_metrics.json"
click node_checkpoints "https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/checkpoints.jsonl"

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_signals,node_decision,node_position toneBlue
class node_kraken,node_prism,node_groq toneAmber
class node_intent,node_contractconfig,node_router,node_sepolia,node_directexec,node_validation,node_registry toneMint
class node_state,node_trades,node_metrics,node_checkpoints toneRose
class node_operator toneIndigo
```

## Components

### Trading cycle

- [Agent orchestrator](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py): `Main-Trading_Agent.py`
- [Signal engine](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py): `Main-Trading_Agent.py`
- [LLM decision](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py): `Main-Trading_Agent.py`
- [Position monitor](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py): `Main-Trading_Agent.py`

### Market intelligence

- **Kraken market API**
- [News sentiment](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/prism_news.py): `prism_news.py`
- **Groq LLM**

### Trust and execution

- [Intent signer](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/trade_intent.py): `trade_intent.py`
- [Contract definitions](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/contracts.py): `contracts.py`
- **Risk Router**
- **Sepolia network**
- [Trade execution](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/Main-Trading_Agent.py): `Main-Trading_Agent.py`
- [Checkpoint attestation](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/validation_client.py): `validation_client.py`
- **Validation registry**

### State and audit

- [Agent state](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/harold_state.json): `harold_state.json`
- [Trade log](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/trades_log.csv): `trades_log.csv`
- [Agent metrics](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/agent_metrics.json): `agent_metrics.json`
- [Checkpoint log](https://github.com/hammad-tayyab/trading-agent-harold-of-hackathon-/blob/main/checkpoints.jsonl): `checkpoints.jsonl`

### Other components

- **Autonomous cycle**

## Connections

- Autonomous cycle → Agent orchestrator: starts cycle
- Agent orchestrator → Kraken market API: fetches market data
- Kraken market API → Agent orchestrator: returns prices
- Agent orchestrator → News sentiment: requests news context
- News sentiment → Agent orchestrator: returns sentiment
- Agent orchestrator → Signal engine: builds signals
- Agent orchestrator → LLM decision: requests decision
- LLM decision → Groq LLM: queries model
- Groq LLM → LLM decision: returns JSON
- Agent orchestrator → Position monitor: checks position risk
- Agent orchestrator → Intent signer: submits trade intent
- Intent signer → Contract definitions: uses ABI and domain
- Intent signer → Risk Router: simulates and submits
- Risk Router → Sepolia network: executes contract call
- Agent orchestrator → Trade execution: executes approved trade
- Trade execution → Sepolia network: sends signed transaction
- Agent orchestrator → Checkpoint attestation: posts checkpoint
- Checkpoint attestation → Contract definitions: uses registry ABI
- Checkpoint attestation → Validation registry: posts attestation
- Validation registry → Sepolia network: records on-chain
- Agent orchestrator → Agent state: loads and saves
- Agent orchestrator → Trade log: appends trades
- Agent orchestrator → Agent metrics: updates metrics
- Checkpoint attestation → Checkpoint log: appends checkpoint
