Walter

Walter is an automated trading assistant that pulls real-time market context from Hyperliquid, aggregates crypto news from multiple sources, and asks a LLM to decide whether to buy, sell, or hold. It persists every decision, market snapshot, and news summary to a local SQLite database for analysis. Designed for fast strategy prototyping, not unattended production trading.

Features

• Aggregates Hyperliquid mid prices, candles, volume, funding, open interest, and trade pressure into a concise market snapshot.
• Fetches crypto news from CryptoPanic and CryptoCompare, then clusters articles into market narratives using TF-IDF vectors and DBSCAN.
• Feeds market data, account state, news summaries, and recent decision history to a LLM that returns a structured JSON decision (action, size, leverage, TIF).
• Places market or limit orders through the official Hyperliquid SDK with automatic tick-size snapping and leverage updates.
• Persists market snapshots, account snapshots, news summaries, and order attempts to a local SQLite database for auditability and review.
• Serves a live localhost web dashboard with price/action charts, account metrics, news context, and decision traceability.
• Runs as a simple scheduler loop (configurable interval) so you can monitor output and interrupt with Ctrl+C.

Requirements

• Python 3.10+
• Hyperliquid API access (public key plus a funded wallet private key for execution).
• OpenRouter API key.
• (Optional) CryptoPanic API key and/or CryptoCompare API key for news aggregation. CryptoCompare works without an API key.

Installation

git clone <your fork or repo url>
cd walter
python -m venv .venv && source .venv/bin/activate
pip install -e .

If you prefer the requirements file:

pip install -r requirements.txt

Configuration

Walter reads configuration from two places:

1. Hardcoded defaults in src/walter/config.py — scheduler interval, coin, Hyperliquid URL, LLM model, news API settings, etc.
2. Environment variables loaded from .env / .env.local files — secrets and connection strings.

Secrets (.env / .env.local)

Variable	Purpose
API_WALLET_PRIVATE_KEY	Private key that signs Hyperliquid orders.
API_WALLET_PUBLIC_KEY	Public key for the API wallet.
GENERAL_PUBLIC_KEY	Public key used when fetching existing positions.
SQLITE_DB_PATH	Path to the SQLite database file (defaults to walter.db).
OPENROUTER_API_KEY	OpenRouter API key for unified LLM access.
CP_CRYPTOPANIC_KEY	(Optional) CryptoPanic API key.
CC_CRYPTOCOMPARE_KEY	(Optional) CryptoCompare API key.

Defaults in config.py

Constant	Default	Purpose
SCHEDULER_INTERVAL_SECONDS	4	Seconds between decision cycles.
COIN	ETH	Hyperliquid asset ticker.
HYPERLIQUID_URL	https://api.hyperliquid-testnet.xyz/info	Base URL for the Hyperliquid info endpoint.
LLM_MODEL	openai/gpt-oss-20b:free	OpenRouter model (short name or full ID).
LLM_HISTORY_LENGTH	5	Number of recent decisions fed back to the LLM.
EPS	0.3	DBSCAN epsilon for narrative clustering.

Order size, leverage, and time-in-force are no longer configured statically — they are determined by the LLM on each decision cycle.

Walter uses OpenRouter to access a wide range of free and paid models. See src/walter/LLM_API.py for a list of popular free models you can reference by short name.

Usage

python main.py

The script prints each market snapshot, open position payload, news summaries, the LLM decision (including its reasoning), and order status. Stop the loop with Ctrl+C.

Walter also serves a browser dashboard on localhost by default:

• URL: http://127.0.0.1:8765
• API: http://127.0.0.1:8765/api/state

To configure/disable the web dashboard:

WALTER_ENABLE_WEB_DASHBOARD=0 python main.py
WALTER_WEB_HOST=127.0.0.1 WALTER_WEB_PORT=9000 python main.py

Development

• Core modules in src/walter/:
  • config.py — centralised configuration and secret loading.
  • dashboard.py — runtime state model + terminal/web dashboard publishing.
  • market_data.py — Hyperliquid market snapshot builder.
  • LLM_API.py — OpenRouter prompt construction, API call, and response parsing.
  • hyperliquid_API.py — position queries and order placement.
  • news_API_aggregator.py — CryptoPanic and CryptoCompare news fetching.
  • news_summerizer.py — TF-IDF vectorization + DBSCAN narrative clustering.
  • db_utils.py — SQLite schema initialisation and data persistence.