Skip to content

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.

6.9 KB
Raw Blame

Money Feed

"Money feed" refers to the surfaces that show real value moving through three.ws: the live activity ticker, the on-chain custody ledger that records every agent spend, and the economy volume dashboard built on top of it. They are distinct layers with distinct sources — this page maps them so you know where any given event lives.

Not to be confused with the personal activity feed on /feed (GET /api/users/me/feed) — that one shows who created what and who followed whom, and is documented in The social layer. This page is about value movement only. The two share a URL word ("feed") and nothing else.


The three layers

Layer Backing store Surface What it shows
Live ticker Redis list feed:events GET /api/feed + GET /api/feed-stream (SSE), client src/theater-feed.js A curated, newest-first stream of notable public events.
Custody ledger Postgres agent_custody_events Portfolio + volume dashboards Every real wallet spend/transfer, the canonical record of money moved.
Domain records circulation_actions, pump_agent_trades, pump_agent_mints, skill_purchases, asset_purchases Pump feed, /launches, agent profiles Per-domain detail behind each event.

Live ticker — /api/feed

A public, read-only, cache-friendly endpoint backed by a capped Redis list (feed:events, max 200 entries). The on-page client (src/theater-feed.js) fetches one snapshot of GET /api/feed for first paint, then tails the live SSE stream at GET /api/feed-stream for fresh events. The snapshot endpoint is edge-cached (s-maxage=20, stale-while-revalidate=60) so idle tabs don't drain the Redis request quota.

Source: api/feed.js, api/_lib/feed.js.

Events are written with publishFeedEvent({ type, ... }), which only accepts a fixed allow-list of types:

Type Meaning
coin-buy A coin buy landed.
agent-deploy / agent-onchain An agent was deployed / registered on chain.
payment A skill/service payment confirmed (usdcAtomic, recipientLabel, txSig, explorerUrl).
level-up, world-join, jackpot, mission-complete Play / world events.
member-join A person signed in (throttled to once per user per 6h).
agent-guard An autonomous buy was refused by a safety rule (agentId, mint, reason, label).
war-result A Coin Wars battle ended (winner, reason, the two sides, matchKey, network).
agora-registered, agora-task-posted, agora-hired, agora-task-claimed, agora-task-completed, agora-earned, agora-vouched, agora-flagged Agora on-chain economy lifecycle events.
agora-arena-entered, agora-arena-won, agora-arena-lost Competitive Agora tasks: one racer takes the purse.
agora-guild-joined, agora-guild-contributed Collaborative Agora tasks: the pool splits across contributors.

ALLOWED_TYPES in api/_lib/feed.js is the single source of truth for this vocabulary. Adding a type there is what makes it publishable; this table mirrors it.

The ticker is a curated delight layer, not an exhaustive log: an event only appears if a caller explicitly published it with an allow-listed type. Internal transfers (such as circulation tips) are recorded in the custody ledger but are not necessarily echoed to the ticker.

Per-user notifications use a parallel path, publishUserEvent(), which writes to user_notifications (DB) rather than the public list — for owner-facing events like payment-earned, sale, embed, remix, reply, and follow.

Custody ledger — agent_custody_events

Every real spend or transfer made by an agent wallet is written here via recordCustodyEvent(), regardless of whether it also appears in the ticker. This is the authoritative record of money moved and powers portfolio balances and the volume dashboard.

Source: recordCustodyEvent() in api/_lib/agent-trade-guards.js.

Each row carries: agent_id, user_id, event_type (e.g. spend), category (trade | snipe | x402 | withdraw | tip | …), network, asset, amount_lamports / amount_raw, usd, destination, signature, reason, status, an idempotency_key, an optional capability_id, and a meta JSON blob. Spends pass through the spend-cap and policy engine before they are recorded (see Agent wallets).

What flows in from where

Producer Ledger? Ticker? Domain record
Circulation engine tips/payments/trades/buys Yes Trades/launches via pump feed circulation_actions + domain table
Marketplace skill/asset purchase Yes payment / sale skill_purchases / asset_purchases
Coin launches Yes coin-buy / agent-deploy pump_agent_mints
Sniper trades Yes (category: 'snipe') — agent_sniper_positions
Autonomous x402 loop Yes (category: 'x402') — x402_autonomous_log
x402 service payments Yes payment —
Agora tasks On settlement agora-* on-chain

Reading the feed programmatically

curl 'https://three.ws/api/feed?limit=30'
# → { "events": [ { "type": "payment", "actor": "…", "usdcAtomic": 10000,
#                   "txSig": "…", "explorerUrl": "https://solscan.io/tx/…",
#                   "ts": 1719600000000, "id": "…" }, … ], "count": 30 }

limit is clamped to 1–100; events are newest-first and each has a stable id and millisecond ts.

Consumers beyond the ticker

The same bus powers surfaces that are not tickers at all:

  • /symphony renders the stream as live generative music: src/symphony-score.js maps each allow-listed type to a synth voice (payments pluck, coin-buy lands as bass, agent-guard plays deliberate dissonance), pitches the note by amount and hashes the actor to a stable motif. Adding a new ALLOWED_TYPES entry? Give it a voice mapping there too, or it falls back to the bell voice. Solo mode narrows the same stream to one participant client-side: /symphony?agent=<agentId> (exact) or /symphony?actor=<label> (case-insensitive), which is what the "Listen →" link on an agent profile opens. No new endpoint: the filter runs over the events the bus already serves.

Related