larp-quant-agent/worker

Paper-trading worker

The always-on runtime that makes the swarm real — without real-money risk.

It reuses the exact browser brain (src/lib/hyperliquid.ts · ta.ts · signals.ts, pure functions, no DOM) on a server loop, paper-trades the verdict against live Hyperliquid prices, and broadcasts every fill to Telegram. This turns the site's biggest fiction — the performance track record — into an honest, verifiable record.

real candles → real TA → 4 agents vote → verdict → paper open/close → Telegram + JSON
   (L1)          (L2)        (L3)          (L4)        (L5 paper)        (L6)

Run

pnpm worker        # run forever, polling every QUANT_POLL_MS (default 60s)
pnpm worker:once   # single tick then exit (smoke test)

No setup required — with no Telegram configured it runs head-less and prints every signal/fill to stdout. Add a bot to broadcast (see below).

Telegram (optional)

1. Create a bot with @BotFather → copy the token.
2. Message the bot once, then get your chat id from @userinfobot.
3. Put both in .env.local:

   TELEGRAM_BOT_TOKEN=123456:ABC-...
   TELEGRAM_CHAT_ID=123456789
   

4. pnpm worker. The bot posts on open/close and answers commands: /status · /positions · /pnl (a.k.a. /learn) · /help.

What's real vs. paper

• Real: market data, candles, every indicator, the agent votes, the verdict, the entry/exit prices, and therefore the PnL.
• Paper: no order is ever signed or sent. mode is fixed to dry-run. Positions are marked to market against the live price; TP/SL are assumed filled at the level. This is the deliberate 80/20 line — all the credibility, none of the key-management / loss risk.

Config (env, all optional)

var	default	meaning
QUANT_COINS	BTC,ETH,SOL	universe
QUANT_INTERVAL	1h	candle timeframe
QUANT_POLL_MS	60000	tick cadence
QUANT_EQUITY_START	10000	starting paper bankroll (USD)
QUANT_LEVERAGE	5	applied to sizePct → notional
QUANT_CONF_FLOOR	0.55	min verdict confidence to open
QUANT_MAX_OPEN_PER_COIN	1	concurrent positions per coin
QUANT_DATA_FILE	worker/data/state.json	persisted state

State

A single JSON file (worker/data/, gitignored) written atomically each tick: equity, open positions, closed trades, signals log, and an equityCurve. It is exactly the shape a future /api/equity · /api/signals endpoint would serve so the site's Performance section and "recent fills" can read the real record instead of the seeded one.

Next 20% (deliberately skipped)

• Live execution: sign + send real Hyperliquid orders. Needs an account, key management, and accepts real loss — keep behind a flag, dry-run stays default.
• /api/* + frontend wiring: serve this state and point Performance / fills at it.
• Claude in the loop: LLM-written reasoning per verdict and a real LLM /learn retrospective (off the risk path).