Agent Zero

The simplest possible Hyperliquid trading agent — one Python file, one strategy file, four dependencies, ~200 lines total. Built by the Algo Traders Club community.

This repository is a GitHub template + specification, not a finished bot. Clone it, then build v0.1 from the docs (with an AI assistant or by hand). When you're done, you'll have a working agent you can read in a single sitting.

---

What this repo is

• A product requirements document (docs/PRD.md) that defines exactly what Agent Zero is and is not
• A build prompt (docs/PROMPT.md) that walks an AI coding assistant through a disciplined, phase-by-phase implementation
• An AI engineer guide (docs/AGENT.md) that wires the PRD and prompt together for Cursor, Claude Code, and similar tools

The goal: you understand every line of code in your agent because you (or your assistant) built it from a clear spec — not because you inherited a black box.

---

What Agent Zero is not

Each absence is deliberate. If you need any of these during your first 10 hours, graduate to the Hyperliquid Operator (see Graduation below) — do not bolt features onto Agent Zero.

• Not a framework — it's a working agent you fork and modify
• Not a production trading system — laptop, dry-run, testnet by default
• Not async — synchronous CCXT; reads top-to-bottom like a recipe
• No web server — no FastAPI, no HTTP endpoints
• No CLI framework — no Typer, Click, or argparse subcommands; just python agent_zero.py
• No multiple strategies — one function in strategy.py; want more? Fork or graduate
• No emergency tooling — no kill switch; stop with Ctrl+C
• No drawdown tracking or daily loss limits — position-size cap + dry-run only
• No deployment story, backtesting, or CI in v0.1

---

Quick start

Path A — AI-assisted (recommended)

1. Use this template on GitHub (or clone below).
2. Open docs/AGENT.md and follow the one-shot instruction for your tool (Cursor, Claude Code, etc.).
3. Verify each build phase with your assistant before continuing.
4. Provide Hyperliquid testnet API keys when prompted (testnet API page).

Path B — Implement yourself

1. Read docs/PRD.md in full.
2. Implement the flat layout: agent_zero.py, strategy.py, and supporting files per PRD §4 and Appendix A.
3. Stay under 200 lines of Python and four dependencies — see PRD §3.

Clone URL

git clone https://github.com/algo-traders-club/agent-zero.git
cd agent-zero

On GitHub, you can also click Use this template to create your own copy (enable Template repository in repo settings after publishing).

---

Safety switches

Agent Zero uses two independent flags. Defaults are conservative: testnet + dry-run.

TESTNET	DRY_RUN	Behavior
true	true	Default. Loop runs, signals logged, nothing submitted on chain.
true	false	Real orders on testnet (fake money). Use to validate end-to-end.
false	true	Mainnet data, no orders (shadow mode).
false	false	Real money on mainnet. Only after you earn both flips.

These are set in .env after you build (from .env.example). Until then, treat this table as the contract your agent must implement.

---

After you build

Once your assistant (or you) finish the PROMPT phases, you should have:

uv sync
cp .env.example .env
# Edit .env: WALLET_ADDRESS and PRIVATE_KEY from Hyperliquid testnet API
uv run python agent_zero.py

Within about a minute you should see signals logged. Open agent_zero.py and read it top to bottom — that is the quality bar.

Note: PROMPT Phase 4 generates a runtime README (quick-start for operators). It replaces this template README. That's expected.

---

Graduation

Agent Zero teaches the verbs: fetch, compute, gate, log, repeat. When you need production-scale layers, move to the Hyperliquid Operator:

You want to…	Operator provides…
Multiple strategies with hot-swap	Strategy registry
Daily loss limits, drawdown breaker	Full risk manager
Cloud deployment, Docker	Deployment guides
AI-operated CLI, status API	CLAUDE.md, FastAPI /health, structured CLI
Emergency kill switch	close-all and related tooling

See the Algo Traders Club for the Hyperliquid Operator when you're ready.

---

Documentation

Document	Purpose
docs/PRD.md	Canonical spec — architecture, code reference, config, gotchas
docs/PROMPT.md	Phase-by-phase build instructions and discipline rules
docs/AGENT.md	Entry point for AI engineers using Cursor / Claude Code

---

License

MIT — see LICENSE.

"The whole point of Agent Zero is what it doesn't have."