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.
robinhood-feed
The PumpPortal-equivalent for Robinhood Chain (mainnet chain ID 4663): a long-lived Node worker that watches The Odyssey plus every other launch venue observed on chain (Pons, Virtuals and more, discovered from ERC-20 mint logs) and their Uniswap pools, grades each deployer, normalizes every launch/trade/graduation into the same shape three.ws's pump.fun consumers already understand, and serves it over SSE + WebSocket + a REST snapshot. No mocks — every field comes from a real on-chain read (RPC logs + the Arbitrum sequencer feed).
It is also useful standalone: any Robinhood Chain trading bot, alert bot or dashboard needs exactly this firehose, and nothing here is three.ws-specific apart from the pump-compatible field names.
Why it exists
three.ws's /play feature turns every pump.fun coin into a deterministic 3D
world you walk into as your avatar, with live trades animating the space. This
worker is the data plane that lets /play do the same for Robinhood Chain
coins — see api/robinhood/coin-trades.js and api/robinhood/play-worlds.js,
which proxy it into the exact contract src/game/chart-screen.js (the in-world
trading terminal) already polls.
What the two API bridges guarantee their callers
The terminal re-polls /api/robinhood/coin-trades every 5 seconds and the
/worlds lobby swallows any non-2xx from /api/robinhood/play-worlds, so a
single bad event in /recent must never become a 5xx. Both bridges therefore
treat this worker as untrusted input:
- An event with a missing or non-object
datapayload is skipped, and the rest of the snapshot still renders. - A
timestampthat is not a positive number is served asnull, whichchart-screen.jsalready reads as "now", instead of an invalid date. - A missing
price_usd/usd_amountstaysnullrather than becoming a real0print on the chart. - A launch whose
mintis not a0x-prefixed 40-hex address is dropped, since its lobby card would seed a world from nothing. - An unreachable or non-2xx worker yields an empty list with
configured: false, never invented trades or worlds.
Caller input is validated separately: coin-trades answers 400 {"error":"invalid_mint"} for an address that is not an EVM contract address,
so a client bug cannot read as "this coin has never traded".
tests/api/robinhood-play-endpoints.test.js pins all of the above.
Architecture
| File | Role |
|---|---|
index.js |
Entrypoint: starts the firehose, wires it into the server, probes every configured RPC once so a dead one is visible in the logs, graceful SIGINT/SIGTERM shutdown. |
src/config.js |
Env-driven config (network, RPC URLs, sequencer feed URL, poll intervals, buffer sizes). Every default works with zero config against the public endpoints. |
src/chain.js |
Shared hoodchain (the robinhood-chain-sdk npm package) read client over a viem fallback transport; cached ERC-20 name/symbol resolution; cached block timestamps; one-time Uniswap v3 pool inspection (which side is the coin, ETH vs USDG quote). |
src/rpc.js |
withRpcRetry: the transient-failure classifier the bulk log reads run through. See "Public RPC behaviour" below. |
src/eth-price.js |
ETH/USD spot, 4-source failover (Coinbase → Kraken → CoinGecko → DefiLlama), cached ~60s — the ETH-gas-chain analogue of three.ws's sol-price.js. |
src/normalize.js |
Pure functions mapping decoded on-chain events to the pump-compatible shape. No chain reads — unit-tests directly against captured real logs (tests/fixtures/). |
src/feed.js |
The orchestrator: composes the SDK's watchLaunches/watchCurveTrades/watchGraduations (Odyssey via RPC logs), the mint-log venue watcher, a dynamic Uniswap v3 Swap watcher over tracked pools, the dev-sold sweep, and the sequencer feed as a liveness/gap watchdog. Backfills on cold start, gap-fills on a stalled watcher, dedupes cross-source. |
src/venue-catalog.json, src/venues.js |
The launch venues observed on chain (51 contract and selector pairs), generated from the upstream launch-relay catalog by scripts/build-venue-catalog.mjs and verified read-only on chain. venueForCall maps a mint transaction's target and selector to a venue. |
src/mints.js |
Venue discovery. An ERC-20 mints its supply with Transfer(0x0, to, n); the contract the mint transaction called identifies the launchpad. Chunked eth_getLogs that bisects on the RPC's matched-log cap, ERC-721 and AMM-pair filtering. |
src/reputation.js |
Deployer reputation and the dev-sold read: launch allocation from the receipt, current balance by multicall, an in-memory index of observed launches per creator, and the risk flags. |
src/server.js |
HTTP + WS server: /healthz, /recent, SSE /events, WebSocket /ws. Keeps a small replay buffer so a fresh subscriber sees recent history instead of a blank feed. |
Built entirely on hoodchain (robinhood/robinhood-chain-sdk/, published npm
name hoodchain) — this worker adds composition, pump-shape normalization, and
serving on top; it does not reimplement chain reads the SDK already provides.
Divergences from the pump.fun (PumpPortal) feed
Documented per the mission brief — fields map 1:1 where semantics align:
- Chain: Robinhood Chain is EVM (Arbitrum Orbit L2), not Solana. Addresses
are
0x…(40 hex chars), not base58.mintin every event is the coin's ERC-20 contract address. - Native asset: ETH, not SOL. The
sol_amount/sol_value_usdfield names are kept verbatim for compatibility with the existing consumer field reads (ingest()insrc/game/chart-screen.jsmapssol_amount/usd_amountinto thesol/usdthe in-world ticker andMarketReactoranimate from): the value carried is the trade's native-ETH magnitude, not SOL. Aquote_symbolfield ('ETH'or'USDG') always tells you which. - Launchpads: many. NOXA shut down on 2026-07-13 and is no longer watched.
The Odyssey (pump.fun-style ETH bonding curve; graduates via
PoolMigratedto a locked Uniswap v3 pool) is watched through the SDK. Every other venue is discovered from mint logs (src/mints.js) and named fromsrc/venue-catalog.json.launchpadis the venue id andvenuecarries{id, label, kind, address}. - Deployer reputation and dev-sold: every launch carries
deployer(prior_launches,prior_dev_exits,inspected,window_blocks),dev_sold,dev_sold_pctandflags(dev_sold,prior_dev_exit,serial_exit,serial_deployer). The dev allocation is the tokens the launch transaction sent to its sender;dev_soldis a current balance of zero. Aprior_dev_exitis a heuristic (a creator who sold out of an earlier launch we saw), not a proven rug, and the history covers only the backfill window (RH_BACKFILL_BLOCKS). A launch with no creator allocation reportsnull, not false. A launch re-emits when dev-sold changes, replacing the earlier record in/recent. - No off-chain metadata service: pump.fun ships
image_uri/description/ socials from its own API; Robinhood Chain launchpads don't expose an equivalent yet, soimage_uri/description/twitter/etc. are alwaysnull.name/symbolARE real — resolved on-chain via the ERC-20name()/symbol()calls. initial_buy_native/initial_buy_usdon a launch event are best-effort: venue launches are found from the mint log and do not carry the buy amount, so these resolve tonullrather than a fabricated figure.- Sequencer feed vs RPC logs: the Arbitrum Nitro sequencer feed
(
wss://feed.mainnet.chain.robinhood.com) delivers every L2 transaction ~100–300ms before it's queryable over RPC, but decoding trade semantics (which pool, buy vs sell, amounts) out of its raw RLP payload is far less reliable than reading decoded event logs. This worker uses RPC logs (viahoodchain'swatchContractEvent, polled atRH_POLL_MS, default 2s) for every decoded event, and the sequencer feed only as a sub-second block-tip / gap-detection signal (GET /healthz→firehose.feed.seconds_since_frame). market_cap_usdis alwaysnull— computing a live circulating market cap needs a total-supply read this worker doesn't do per-trade (would be one more RPC call per event); leftnullrather than approximated.
Running it
cd workers/robinhood-feed
npm install # installs hoodchain from npm (published from robinhood-chain-sdk)
npm start # listens on :8788 (mainnet, public RPC + sequencer feed)
hoodchain is a normal npm dependency pinned to the version published from the
standalone robinhood-chain-sdk repo, the SDK's source of truth (see
robinhood/README.md). No local build step is needed.
Zero-config defaults hit the public Robinhood Chain endpoints. Every knob is an env var:
| Var | Default | Meaning |
|---|---|---|
RH_NETWORK |
mainnet |
mainnet (4663) or testnet (46630). |
RH_RPC_URL |
public RPC | Preferred HTTP RPC. The public RPC always stays in the list behind it as a fallback rung. |
ALCHEMY_API_KEY |
(unset) | If set, mainnet calls try Alchemy first and fall back to the public RPC. See Known limitations. |
RH_FEED_URL |
public sequencer feed | Override the sequencer WS URL. |
RH_USE_FEED |
1 |
Set 0 to disable the sequencer-feed watchdog entirely (RPC-only mode). |
RH_POLL_MS |
2000 |
RPC log poll interval for the SDK watchers. |
PORT |
8788 |
HTTP/WS server port. |
RH_BACKFILL_BLOCKS |
200000 |
How many blocks of launch history to backfill on cold start. |
RH_GAP_BLOCKS |
2000 |
Chain-head lead that triggers a gap-fill rescan (≈3.3 min of blocks at Robinhood Chain's ~100ms cadence — must clear one poll tick's normal advance or every tick misreads itself as stalled). |
RH_MAX_POOLS |
400 |
LRU cap on concurrently-watched Uniswap v3 pools. |
RH_BUFFER_LIMIT |
40 |
Replay-buffer depth per event kind (what a fresh subscriber and /recent see). |
RH_SEEN_LIMIT |
4000 |
Cross-source dedupe memory, in event keys. |
Public RPC behaviour (measured, not assumed)
Two things about rpc.mainnet.chain.robinhood.com shape the worker's design.
Both were measured live against mainnet, not inferred:
- It sheds load with a wrong error code. Under load it answers a perfectly
valid
eth_getLogswith JSON-RPC-32602 "Missing or invalid parameters."The identical request succeeds on the very next attempt (measured: 4/4 on a range that had just failed). viem never retries-32602, because that code means "the caller sent nonsense" everywhere else, so one shed request used to abort an entire cold-start backfill. Every bulk read now goes throughwithRpcRetry(src/rpc.js), which treats-32602as transient and backs off. Retries are reported asstatusevents (src: 'backfill' | 'gap-fill') so they show up on/eventsinstead of disappearing. - Ranges are generous. A 4 000 000-block
eth_getLogswindow is accepted; the SDK's own 10 000-block chunking ingetRecentLaunchesis well inside the limit. The failures above are load, not range.
The chain produces about 9.6 blocks a second, so the default
RH_BACKFILL_BLOCKS (200 000 blocks) covers about 5.8 h; use 830 000 for 24 h.
The backfill scans the whole window before it serves launches, because
deployer history is built from it. /healthz shows last_scanned_block,
mint_cursor_block and indexed_deployers while it runs.
npm run smoke:live proves the decode path end to end regardless, by finding
the newest launch that actually exists.
API
GET /healthz→{ ok, network, uptime_s, subscribers, buffer, firehose: { chain_id, rpc, last_scanned_block, tracked_pools, feed: { last_sequence, seconds_since_frame } } }(rpclists the configured endpoints with any provider key masked.)GET /recent?kind=launch|trade|graduation|all&limit=20→{ events: [{ kind, data }] }, newest first.GET /events?kinds=launch,trade,graduation(SSE) → replays the buffer (replay: true), then streams live.text/event-stream, each linedata: {"kind":"trade","data":{...}}.WS /ws?kinds=launch,trade,graduation→ identical events over a WebSocket.
Event shapes are documented inline in src/normalize.js. Every trade carries
both the legacy pump-compatible fields (sol_amount, usd_amount, user,
tx, is_buy) and chain-explicit fields (chain, chain_id, quote_symbol,
explorer_tx_url).
Tests
npm test # offline: normalizer + retry classifier + HTTP/WS/SSE plumbing
npm run smoke:live # online: the real chain end to end (read-only, ~20s)
npm test never touches the network, so it runs anywhere and never fails
because a launchpad is quiet:
tests/normalize.test.jsruns the pure normalizer against real captured logs (below).tests/rpc.test.jspins the transient-error classifier, including the public RPC's-32602load-shed response.tests/server.test.jsis the core-path smoke test: real fixture logs go through the real normalizers into the real server, and are asserted back out over real sockets (/healthz,/recentordering + kind filtering + dedupe, SSE replay-then-live with?kinds=, WebSocket replay + fan-out, shutdown with a subscriber still attached).
npm run smoke:live covers what only the live chain can: that the configured
RPCs answer, that the SDK's decoding still matches the deployed launchpad
contracts, that ERC-20 metadata / block times / the ETH price resolve, that a
real Uniswap swap classifies buy-vs-sell correctly, that the sequencer feed
delivers frames, and that all of it survives /recent and SSE. It reads only:
no keys, no writes, no spend. Because the launchpads idle for long stretches, it
scans backward from the head until it finds the newest launch that exists rather
than assuming recent activity.
Unit tests (tests/normalize.test.js) run the pure normalizer against real
on-chain logs, captured live from Robinhood Chain mainnet during development
and committed as fixtures (tests/fixtures/*.json) — an Odyssey Traded log,
a historical NOXA TokenLaunched log, an Odyssey TokenCreated log, a Uniswap v3
Swap log on the resulting pool, and one real launch per discovered venue
(tests/fixtures/venue-launches.json, captured by
node scripts/capture-venue-fixtures.mjs). No mocks: every asserted value traces back to
a real transaction hash. Captured with:
import { createHoodClient, ODYSSEY_ADDRESSES, NOXA_ADDRESSES,
odysseyTradedEvent, odysseyTokenCreatedEvent, noxaTokenLaunchedEvent } from 'hoodchain';
const hood = createHoodClient();
const logs = await hood.public.getLogs({
address: ODYSSEY_ADDRESSES.bondingCurveFactory,
event: odysseyTradedEvent,
fromBlock: /* recent range */, toBlock: 'latest',
});
Deploying
Not deployed today. No robinhood-feed service exists on Cloud Run and
ROBINHOOD_FEED_URL is unset on three-ws-api, so
api/robinhood/coin-trades.js and api/robinhood/play-worlds.js serve their
designed empty state. Everything needed to change that is in this directory; the
deploy itself is owner-gated per CLAUDE.md.
Same shape as the other long-lived Node workers in workers/ (e.g.
agent-sniper): a Cloud Run service (not a job, it is a persistent WS/SSE
server), min instances 1 so the SDK watchers and replay buffer stay warm.
Build from the repo root. gcloud run deploy --source workers/robinhood-feed
cannot work here: the worker depends on the local SDK through
file:../../robinhood/robinhood-chain-sdk, which sits outside that build
context. Dockerfile builds the SDK in a first stage and the worker in a
second, so the whole thing comes from a clean checkout with no manual step:
# local
docker build -f workers/robinhood-feed/Dockerfile -t robinhood-feed .
docker run --rm -p 8788:8788 robinhood-feed
# Cloud Build (from the repo root)
gcloud builds submit --config workers/robinhood-feed/cloudbuild.yaml \
--region us-central1 --project aerial-vehicle-466722-p5
# first deploy
gcloud run deploy robinhood-feed --region us-central1 \
--project aerial-vehicle-466722-p5 \
--image us-central1-docker.pkg.dev/aerial-vehicle-466722-p5/workers/robinhood-feed:latest \
--service-account [email protected] \
--min-instances 1 --max-instances 1 --no-cpu-throttling \
--port 8788 --allow-unauthenticated \
--set-env-vars RH_NETWORK=mainnet
--max-instances 1: the firehose is a single logical stream (RPC watchers +
sequencer feed + replay buffer); running two instances would double the RPC
load and split subscribers across two independent buffers. Scale reads by
fronting it with a CDN/cache on /recent, not by adding instances.
Do not put ALCHEMY_API_KEY on the service until the Alchemy app has the
Robinhood network enabled (see Known limitations). The client falls back to the
public RPC on its own, so a disabled key costs latency rather than uptime, but
there is no reason to pay for the failed first hop.
Once deployed, set ROBINHOOD_FEED_URL on the three.ws API service (Cloud Run
three-ws-api) to this worker's URL so api/robinhood/coin-trades.js and
api/robinhood/play-worlds.js stop falling back to their empty-but-honest
configured: false state.
Known limitations (owner action)
- Alchemy accelerator not enabled:
ALCHEMY_API_KEYis set in.env, but the Alchemy app does not have the Robinhood Chain network enabled. Re-verified live on 2026-08-11: every call torobinhood-mainnet.g.alchemy.comreturns-32600 ROBINHOOD_MAINNET is not enabled for this app. The worker runs correctly against the public RPC without it (the client lists Alchemy first and falls through), and the boot probe logs the rung as unusable so it is not mistaken for a quiet chain. Enabling it would cut RPC latency, not add capability. Enable athttps://dashboard.alchemy.com/apps/<app>/networks. - Public RPC has no SLA:
rpc.mainnet.chain.robinhood.comsheds load with a misleading-32602(see "Public RPC behaviour").withRpcRetryabsorbs that, but under sustained load a paid provider is still the right answer: pointRH_RPC_URLat it and the public RPC stays behind it as a fallback. - Backfill is bounded by the public RPC: a wide
RH_BACKFILL_BLOCKSissues manyeth_getLogscalls and the public RPC answers 429 under sustained load. PointRH_RPC_URLat a paid provider for a 24 h window.