hood-oracle

An autonomous launch trader for Robinhood Chain (chain id 4663, an Arbitrum
Orbit L2). It holds the chain's sequencer feed open, watches every token that
launches on NOXA and The Odyssey, scores each one in its first ninety
seconds with a conviction oracle that re-fits itself from realized outcomes, and
executes through hard guardrails on behalf of the strategies ("arms") an
operator has armed. One Node 24 process: the trading loop, the HTTP control
plane and the live dashboard run in the same container, so an arm change is
visible to the engine on the next tick.

The oracle and the guardrails were extracted from the three.ws Solana sniper
(the engine behind three.ws/oracle) and re-fitted
for an EVM chain where gas is ETH, liquidity lives in Uniswap v3 pools or on an
Odyssey bonding curve, and launches arrive a few dozen a week rather than a few
thousand a day. Every number the model publishes is one it earned on launches
it never saw, and the same purely functional scorer runs in the engine, the API
and the CLI, so they can never disagree about what "the model" means.

Risk disclaimer

This software can autonomously sign and broadcast real transactions with
real funds when an arm is in live mode. Trading is risky. Most new token
launches go to zero. Thin pools move against you, a bonding curve can be
bought but not sold, and software has bugs. There are no guarantees, no
warranty, and no recovery for funds lost to a bug, a bad market, or a
misconfigured guardrail. Simulate mode is the default for every arm and
touches no funds. Live mode requires TRADER_PRIVATE_KEY on the server
and an explicit per-arm mode: "live" write, and the API refuses to arm
anything without a stop loss. Start in simulate mode. Use a wallet you can
afford to lose. You are responsible for every transaction this software signs
on your behalf.

Quickstart

Local Postgres in Docker, the engine on your machine. Node 24 or newer.

git clone https://github.com/nirholas/hood-oracle.git
cd hood-oracle
cp .env.example .env            # DATABASE_URL already matches the compose db
docker compose up -d db         # Postgres 17 on localhost:5432
npm install
npm run db:migrate              # applies src/db/migrations
npm run oracle:backfill -- --days 30   # rebuild features + labels from chain history
npm run dev                     # tsx watch src/index.ts

Open http://localhost:8080. The dashboard is live: the oracle board fills as
launches are scored, the arm page is where you create and arm strategies, and
the positions tape shows every open and closed position with its exit reason.

The whole stack in Docker instead:

docker compose up --build

Writes (creating, arming, killing) need OPERATOR_TOKEN in .env; generate
one with openssl rand -hex 32. Reads and the dashboard are public.

Architecture

sequencer feed ─┐                                          ┌─ Hono API + SSE
log watchers ───┼─▶ launch intake ─▶ 90s observation ─▶ features ─▶ oracle score
                │                                          │
                │        arms (DB) ─▶ entry gate ─▶ guards ─▶ firewall ─▶ executor
                │                                                          │
                └───────────── positions sweep ◀── exit ladder ◀── positions (DB)
                                     │
                    realized labels ─▶ refit (promotion gate) ─▶ active model

A fill is: sequencer frame decoded (100 to 300ms before the block is
queryable), factory calldata matched, launch confirmed by log, 0 to 90s of
observation (the arm's buyDelayMs), score, guards, firewall simulation,
pre-built swap, raw transaction broadcast to every RPC in parallel. Nothing on
that path touches HTTP routing. The full map of directories, the boot order
and the money rules are in docs/architecture.md.

Arms: the knobs

An arm is one strategy: a row of knobs deciding what to buy, how much, and when
to exit. Arming flips it enabled. Wei fields are sent as decimal wei strings
or through the perTradeEth / dailyBudgetEth spellings.

The walkthrough from a first simulated arm to a live one is
docs/arming.md.

Guardrails

Every buy passes these in this order before the executor sees it. A refusal is
journaled with its reason and shown on the dashboard in plain language. Sells
are exempt from the exposure caps (a cap must never trap a losing position)
but still honor the kill switch, cooldown and slippage bound.

The full write-up, including what the kill switch will and will not clear, is
docs/guardrails.md.

How the oracle learns

1. Every launch gets a 90-second feature snapshot (26 EVM-native features
   across structure, momentum, pedigree and narrative) and a score under the
   active model.
2. Labels resolve 24h later from chain history and are price-independent:
   moon means it ran at all, rug means a first-sight holder is down more
   than half, win means it ran and a first-sight holder is still up. A
   position we actually closed overrides the chart label for that token.
3. The refit job (every 6h) fits three logistic heads on bucketed
   features with a time-split holdout and runs a promotion gate: an
   absolute AUC floor, every tier band still earning at least 70% of the
   probability it claims, no collapse of the feature set, and a gain over the
   incumbent bigger than fit noise. A losing candidate is archived with the
   reason and the live model is untouched.
4. The bootstrap prior shipped in src/oracle/bootstrap-model.json was
   fitted on the three.ws pump.fun corpus (296k launches). It is a prior, not
   a claim about Robinhood Chain: its SOL-denominated bucket edges are
   re-denominated to ETH at a recorded exchange rate, and the dashboard shows
   its provenance as bootstrap until the first promoted refit replaces it.
   npm run oracle:backfill reconstructs features and labels from chain
   history so that first refit can happen on day one.

Feature definitions, the heads, tiers, fit and calibration are in
docs/oracle.md.

API

Reads are public. Writes need Authorization: Bearer <OPERATOR_TOKEN>. Wei
serializes as decimal strings, dates as ISO 8601, and every error is
{ "error": code, "message": text }. Examples for every route are in
docs/api.md.

Every response carries security headers and an X-Request-Id; reads are
rate-limited at 600 per minute per client and writes at 30, bodies are
capped at 64KB, and CORS is same-origin unless CORS_ORIGINS opens it. The
details are in docs/api.md.

Non-custodial accounts

Anyone with a wallet can trade this engine without handing it a key. Sign in
at /app/connect with one EIP-4361 signature, deploy a HoodArmAccount from
your own wallet, fund it, and point an arm at it. The engine is only the
account's operator: the contract lets it call buy and sell inside the
per-trade cap, daily budget, cooldown, concurrency, slippage bound and oracle
gate you wrote on chain, and lets it do nothing else. Withdrawal, policy
changes, operator rotation and the kill switch stay with the owner. Loosening
a bound queues for an hour; tightening one lands immediately; rotating the
operator away disarms every arm bound to the account within a minute.

Every buy is pre-flighted with an eth_call of the exact account call, so a
policy refusal is journaled as per_trade_cap or cooldown instead of
costing gas to learn. docs/multi-tenant.md.

Agents: MCP, SDK, x402

MCP. npx hood-oracle-mcp (or npm run mcp) is an MCP server over
stdio for Claude Code, Claude Desktop and any MCP client; the engine also
serves the same tools over Streamable HTTP at /mcp. Tools: engine_status,
oracle_feed, oracle_score, oracle_model, arms_list, arm_get,
arm_create, arm_update, arm_enable, arm_disable, arm_kill,
kill_switch, positions_list, position_close, trades_list,
decisions_list; resources hood-oracle://status, hood-oracle://oracle/feed
and hood-oracle://docs/{slug}. Writes need the operator token. Setup and
every tool's arguments: docs/mcp.md.

SDK. @hood-oracle/sdk is a typed client for every
route with an async iterator over the SSE stream, waitForScore, and an
x402 helper. docs/sdk.md.

x402. GET /api/x402/score/:token sells one verdict for USDG on
Robinhood Chain over the hood402 rail; set X402_PAY_TO to enable it.
docs/x402.md.

Deploying

Production runs on Google Cloud Run as one always-on instance (the engine
holds a websocket open and must never be scaled to zero or CPU-throttled).
cloudbuild.yaml builds the image, pushes it to Artifact Registry and deploys
with every credential read from Secret Manager:

gcloud builds submit --config cloudbuild.yaml --region us-central1 \
  --project aerial-vehicle-466722-p5 \
  --substitutions=SHORT_SHA=manual$(date +%s)

The runbook with the secret creation commands, the Alchemy accelerator RPC
setup (the single biggest fill-latency win) and rollback is
docs/deploy.md.

Relationship to three.ws

hood-oracle is a sibling of three.ws.
The conviction oracle (three heads, bucketed logistic fit, the promotion gate,
the price-independent labels) and the guardrail layer (the ordered risk
engine, the kill switch semantics, earned autonomy, the bounded optimizer) were
extracted from the three.ws Solana sniper and re-fitted for Robinhood Chain.
The live Solana engine is at three.ws/oracle. What
changed in the port: wei instead of lamports, ETH gas headroom instead of
rent, Uniswap v3 and Odyssey curves instead of pump.fun, a sequencer feed
instead of a Geyser stream, and fit thresholds sized for a young chain.

Repository map

Scripts

License

Apache-2.0. Copyright 2026 nirholas.

Star History

Support the project

If hood-oracle saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/hood-oracle and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors