Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Architecture — hood-traders</title>
<meta name="description" content="The observe → decide → simulate → risk-check → execute → journal loop behind every hood-traders agent." />
<link rel="icon" href="data:image/svg+xml,%3Csvg%20xmlns%3D%27http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%27%20viewBox%3D%270%200%2032%2032%27%3E%3Cdefs%3E%3ClinearGradient%20id%3D%27g%27%20x1%3D%270%27%20y1%3D%270%27%20x2%3D%271%27%20y2%3D%271%27%3E%3Cstop%20offset%3D%270%27%20stop-color%3D%27%236d5ef8%27%2F%3E%3Cstop%20offset%3D%271%27%20stop-color%3D%27%232fd0e0%27%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Ccircle%20cx%3D%2716%27%20cy%3D%2716%27%20r%3D%2713%27%20fill%3D%27url(%23g)%27%2F%3E%3C%2Fsvg%3E" />
<link rel="stylesheet" href="style.css" />
</head>
<body>
<nav class="topnav">
<div class="brand"><span class="dot"></span>hood-traders</div>
<div class="links">
<a href="index.html">Overview</a>
<a href="architecture.html" class="active">Architecture</a>
<a href="strategies.html">Strategies</a>
<a href="quickstart.html">Quickstart</a>
<a href="https://github.com/nirholas/hood-traders" target="_blank" rel="noopener">GitHub ↗</a>
</div>
</nav>
<div class="wrap">
<h1>Architecture</h1>
<p class="lede">
An agent is a strategy plugged into a fixed pipeline. The strategy only ever proposes —
every risk cap is enforced by the agent, after simulation, before anything executes. A
strategy cannot skip the gate, in paper mode or live.
</p>
<h2>The pipeline</h2>
<div class="flow-diagram">
<div class="flow-step">
<div class="flow-num">1</div>
<div class="flow-body">
<h3>Observe — <code>Market</code> (<code>src/framework/market.ts</code>)</h3>
<p>
Every number a strategy sees comes from a live RPC call through the <code>hoodchain</code>
SDK: Chainlink <code>latestRoundData()</code> for Stock Token quotes, Uniswap v3
<code>QuoterV2</code> simulated calls for spot prices, and the live sequencer/log
watchers for new launches. Nothing here is cached beyond a few seconds (ETH/USD, 30s)
and nothing is fabricated — nulls propagate instead of invented numbers.
</p>
</div>
</div>
<div class="flow-step">
<div class="flow-num">2</div>
<div class="flow-body">
<h3>Decide — <code>Strategy.tick()</code></h3>
<p>
Pure function of the current market view and open positions to a <code>Decision</code>:
a list of <code>Intent</code>s (buy/sell proposals) and <code>Alert</code>s. Strategies
never touch the wallet, the risk engine, or the journal directly — they cannot.
</p>
</div>
</div>
<div class="flow-step">
<div class="flow-num">3</div>
<div class="flow-body">
<h3>Simulate — a real <code>eth_call</code></h3>
<p>
Every intent is re-quoted against live liquidity via <code>QuoterV2</code> before
anything else happens — this is a real simulation against the current pool state, the
same call type Uniswap's own frontend uses, not a cached or stale price.
</p>
</div>
</div>
<div class="flow-step">
<div class="flow-num">4</div>
<div class="flow-body">
<h3>Risk-check — <code>RiskEngine.check()</code> (fails CLOSED)</h3>
<p>
Kill switch → zero/negative amount → cooldown → slippage bound → position cap → agent
daily cap → fleet daily cap, in that order, so the journaled refusal reason is always
the most specific true one. Any check the engine cannot satisfy refuses the trade —
there is no default-allow path. See the full table below.
</p>
</div>
</div>
<div class="flow-step">
<div class="flow-num">5</div>
<div class="flow-body">
<h3>Execute</h3>
<p>
<strong>Paper:</strong> the simulated fill is recorded as the trade — same code path,
same accounting, no signature. <strong>Live:</strong> <code>buildSwapTx</code> →
<code>ensureApproval</code> → <code>sendTransaction</code> → wait for receipt, using
<code>hoodchain</code>'s router-flavor-aware swap builder (mainnet SwapRouter02 vs.
testnet's classic SwapRouter).
</p>
</div>
</div>
<div class="flow-step">
<div class="flow-num">6</div>
<div class="flow-body">
<h3>Journal — SQLite (<code>src/framework/journal.ts</code>)</h3>
<p>
Every trade AND every refusal is written, with the strategy's reason string, the risk
verdict, and an equity mark. bigints are stored as decimal TEXT (SQLite's native
integer is 64-bit signed; token amounts routinely exceed that). The dashboard reads
straight from this table — nothing is held only in memory.
</p>
</div>
</div>
</div>
<h2>Risk rails</h2>
<p>Every rail applies identically in paper and live mode. Sells are exempt from the position/spend caps — they reduce risk, and refusing a de-risking sell because of a spend cap would trap an agent in a losing position.</p>
<table class="risk-table">
<thead><tr><th>Rail</th><th>Env var</th><th>Enforced where</th></tr></thead>
<tbody>
<tr><td>Per-position cap</td><td><code>AGENT_MAX_POSITION_USDG</code></td><td>Before any buy — projected position value must stay under the cap</td></tr>
<tr><td>Per-agent daily spend cap</td><td><code>AGENT_MAX_DAILY_SPEND_USDG</code></td><td>Before any buy — UTC-day rolling spend</td></tr>
<tr><td>Fleet-wide daily spend cap</td><td><code>FLEET_MAX_DAILY_SPEND_USDG</code></td><td>Before any buy, across every agent</td></tr>
<tr><td>Slippage bound</td><td><code>AGENT_MAX_SLIPPAGE_BPS</code></td><td>Every order, buy or sell</td></tr>
<tr><td>Cooldown</td><td><code>AGENT_COOLDOWN_SECONDS</code></td><td>Every order, buy or sell</td></tr>
<tr><td>Kill switch</td><td><code>KILL_FILE</code> / SIGINT / <code>POST /api/kill</code></td><td>Every order — halts new risk immediately, never force-sells</td></tr>
</tbody>
</table>
<h2>Paper vs. live</h2>
<p>
Paper mode runs the <em>identical</em> pipeline against <em>identical</em> live data — the
only difference is step 5: paper records the QuoterV2-simulated fill as the trade, live
signs and broadcasts it. This means a strategy validated in paper mode behaves the same way
in live mode, modulo real-world slippage/MEV the simulation can't see. Live mode requires
<strong>both</strong> <code>HOOD_TRADERS_LIVE=1</code> <strong>and</strong> a valid
<code>ROBINHOOD_CHAIN_PRIVATE_KEY</code> — missing either falls back to paper, so there is no
accidental-live path.
</p>
<h2>Why a fresh framework and not hoodkit</h2>
<p>
This package's prompt called for building on <code>hoodkit</code> (the wave-2 advanced
SDK wrapper) if it existed. At build time it had not shipped, so <code>hood-traders</code>
talks to <code>hoodchain</code> (the core SDK) directly through <code>src/framework/market.ts</code>
— a thin adapter that is the only place a future <code>hoodkit</code> swap-in would touch.
</p>
<footer class="footer">
<span>hood-traders · Robinhood Chain autonomous trading fleet</span>
<span>Built by <a href="https://x.com/nichxbt" target="_blank" rel="noopener">nirholas</a> · <a href="https://three.ws" target="_blank" rel="noopener">three.ws</a></span>
</footer>
</div>
</body>
</html>