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.

14.8 KB
Raw Blame

The social layer: feed, follows, notifications, rankings, portfolios

Shipped in July 2026, the social layer connects every creation surface on three.ws (forge, dioramas, agents, coin launches, walking) into one graph: you follow creators, their work shows up in your feed, milestones ring your notification bell, and everyone's output rolls up into portfolios and a cross-surface leaderboard. This page maps the whole layer: the pages, the APIs, and how the pieces feed each other.

There is no separate "social events" database to drift out of sync. The feed, portfolios, rankings, and search all read from the same records the rest of the platform already writes (forge_creations, dioramas, material_restyles, pump_agent_mints, user_follows, walk_metrics).

Piece Page API
Activity feed /feed, /community GET /api/users/me/feed
Follow graph Follow buttons on /u/:username `GET
Notification bell Bell in the header, preferences in /dashboard/settings GET /api/notifications + /preferences
Leaderboard, streaks, badges /rankings, /leaderboard?tab=earned GET /api/leaderboard/unified, GET /api/leaderboard/earnings
Creator portfolio /u/:username GET /api/users/:username/creations
Cross-entity search /search GET /api/search
Onboarding tour /start GET /api/me (show_onboarding_tour)

How they interconnect:

  • Follow feeds everything. A new follow edge fires a bell notification for the followed user, unlocks the scope=following feed for the follower, boosts the followed creator in search ranking, and counts toward the followers leaderboard metric.
  • Every feed item links to a portfolio. Feed cards deep-link to /u/:username, where the same records render as that creator's portfolio.
  • Showing up advances your streak. Forging a model, saving a world, restyling, walking, or landing a confirmed on-chain trade while signed in calls the streak engine, which in turn awards the badges shown on /rankings and your profile.

Activity feed: /feed and /community

/feed is your personal feed (accounts you follow). /community leads with the same API in platform-wide mode, so it doubles as the feed for first-time visitors with no follows yet.

GET /api/users/me/feed?scope=following|all&limit=30&before=<iso>
  • scope=following (default) needs a session; anonymous callers get a 401 so the client can route to sign-in.
  • scope=all is public: platform-wide recent activity.
  • limit is 1..50 (default 30); before is an ISO-timestamp cursor (pass the last item's created_at back for infinite scroll).

Every item is { kind, id, created_at, actor, title, subtitle?, href, image?, external?, isRemix?, isVariant? } where actor is { username, display_name, avatar_url }. Items of kind: "follow" additionally carry a target shaped like actor; isRemix marks a model forged from another creation, isVariant a restyle that is a seeded colorway fan-out rather than an instructed restyle. actor.username is null for creations made while signed out; the client renders those without a profile link rather than inventing one.

Item kinds: avatar, agent, coin, model, world, and restyle creations, plus follow events. They are merged live from forge_creations, dioramas, material_restyles, and user_follows at read time (the restyle and follow queries are fail-soft, so a deployment without those migrations still serves a feed).

Source: api/users/me/feed.js. Not to be confused with GET /api/feed, the public Money Pulse ticker backed by Redis; see Money Feed for that one.

Follow graph

The social-graph edge behind everything above.

GET    /api/users/:username/follow    → { following, followed_by, followers_count, following_count }
POST   /api/users/:username/follow    → follow   (idempotent)
DELETE /api/users/:username/follow    → unfollow (idempotent)
  • following = does the signed-in viewer follow this user; followed_by = do they follow the viewer back. Both false for anonymous viewers; the GET is never cached (viewer-specific).
  • POST/DELETE require a session + CSRF token, return the same envelope as GET (one round-trip updates the button and the counts), block self-follows (400), and 401 for anonymous callers.
  • A genuinely new edge (insert with ON CONFLICT DO NOTHING) publishes a follow user event, so the followed user's bell rings exactly once no matter how many times the button is clicked.
GET /api/users/:username/follows?type=followers|following&limit=50&offset=0

Lists either side of the graph (limit 1..100); each row carries is_following so the client can render its own follow-back buttons.

Source: api/users/[username]/follow.js, api/users/[username]/follows.js, table user_follows. Tests: tests/api/users-follow.test.js.

Notification bell

The header bell is an inbox over user_notifications, fed by the per-user event vocabulary in api/_lib/feed.js (USER_EVENT_TYPES → publishUserEvent() → insertNotification). Recent additions to the vocabulary:

Event Fired from
remix (someone remixed your model) api/x402/remix-asset.js
dm_received api/friends/messages.js
pump_launch_filled (your coin graduated its bonding curve) the pump cron in api/cron/[name].js
follow the follow endpoint above

Endpoints:

GET   /api/notifications?limit=…        → the inbox, newest first
POST  /api/notifications/:id/read      → mark one read
POST  /api/notifications/read-all      → mark everything read
POST  /api/notifications/track         → delivery/click tracking
GET   /api/notifications/preferences   → the preference matrix
PUT   /api/notifications/preferences   → update it

Preferences are a category × channel matrix (api/_lib/notify-prefs.js): categories are sales, purchases, social, IRL, market alerts, event markets, creations, companion deliveries, knocks at your door, agent mail, orders, approvals, and account & security; channels are in_app, push, email, telegram, discord, and avatar. Every channel is a per-category toggle (in_app defaults on everywhere, and is locked on for account & security so the bell record of security events never goes silent), edited from the Notifications panel in /dashboard/settings (src/dashboard-next/pages/settings.js). Bell client: src/notifications.js.

telegram and discord deliver to chats paired with an agent through the chat gateways (/api/gateway/connections), so GET /preferences reports a gateways: { telegram, discord } count of paired chats with notifications on, and the panel keeps a column disabled until one exists (Telegram also accepts a legacy telegram_chat_id). Both default off except for market alerts. push.subscribed_devices counts Web Push browsers plus iPhones enrolled through the iOS app (APNs), with the iPhones also reported alone as push.ios_devices. The mail category (an email arriving in one of your agents' inboxes; spam never notifies) defaults to the bell and push only.

The avatar channel is the corner companion walking on screen and saying the notification out loud. It is delivered client-side: the bell hands its unread inbox to src/notification-herald.js, which owns every rule (the per-category preference, freshness, per-id dedupe, a batch cap), and GET /preferences ships the server's type_categories map so the browser gates on the same type-to-category table push and email use. It defaults on only for the categories worth interrupting for (sales, creations, companion, knock, account & security) and off for the rest. A click-through from a spoken notification is tracked as channel: "avatar" on POST /api/notifications/track. PUT /preferences is a merge, not a replacement: a body carries only the keys being changed, omitting a key keeps its stored value, and telegram_chat_id must be a numeric chat id (send null or "" to disconnect).

Leaderboard, streaks, and badges: /rankings

One leaderboard across every surface, plus daily streaks and badges.

GET /api/leaderboard/unified?metric=creations&limit=50&offset=0

metric is one of creations, remixes_received, launches, followers, walk_distance, ufo_score (best verified Flappin UFO run per user, from ufo_runs; see play-ufo.md; limit 1..100, default 50). launches counts distinct mainnet mints from the platform's own launch records (pump_agent_mints, including coins signed by an agent's custodial wallet, plus fixed_supply_launches), through api/_lib/launch-counts.js, the same count the daily top-10 badge sweep uses. Sending the request with a session or Bearer token pins your own row into the response even when you are outside the page window. remixes_received counts only finished derivatives made by someone else: both the parent and the child must be status = 'done', and a creator's own refines of their own model (which also write parent_creation_id) never count, so nobody climbs that board by re-refining their own work.

The streak engine (api/_lib/streaks.js, recordDailyActivity()) is called from sign-in, forge saves, diorama saves, restyle saves, CAD part saves, anatomy saves, walk metrics, and a confirmed on-chain trade (both legs of api/pump/[action].js, fire-and-forget so the streak can never delay or fail the trade that earned it), and writes user_streaks / user_badges. The upsert is idempotent per UTC day, so a busy session still counts once: the streak measures showing up, not volume. A daily rollup cron (api/cron/leaderboard-rollup.js) sweeps the top10_<metric> badge awards. The rest of the catalog (BADGE_META in the same file) is awarded where it is earned: first creation, first remix received, a 7-day streak, completing the copy-trade path, founding or joining a syndicate, daily trading quests (first quest, a daily clear, a 7-day quest streak), and trader duels (first call, a correct call, three correct in a row, and 70% or better over ten or more decided duels), plus the Event Market forecaster badges (first correct call, an upset call, five in a row, season top 10, season champion; see event-markets.md). Badges and streaks also render on profile pages.

An authenticated request gets streak and badges back in the same response as the board, keyed on the session's user id, so the /rankings streak card works for accounts that have never picked a username. Those three per-viewer blocks (me, streak, badges) make an authenticated response cache-control: private; anonymous responses stay edge-cacheable.

Agents also have an earnings board: GET /api/leaderboard/earnings?window=24h|7d|30d|all&limit=25&offset=0 ranks public agents by creator fees plus service income for the window, with each row's movement against the previous window of the same length. It is public, edge-cached for a minute, and computed the same way as each agent's Earned card; the full contract is in the API reference.

Page: pages/rankings.html. Source: api/leaderboard/unified.js, api/leaderboard/earnings.js.

Creator portfolio: /u/:username

Every forge model and saved world a creator makes while signed in is attributed to them at create time (user_id on forge_creations and dioramas) and aggregates onto their public profile.

GET /api/users/:username            → public profile
GET /api/users/:username/creations  → cursor-paginated portfolio items

Attribution links point back here from the diorama viewer and gallery and from the forge result bar, so any model you encounter on the platform is one click from the person who made it.

Page: pages/profile.html (also serves /profile for self-view; signed-out visitors get a claim-your-handle CTA, not a sign-in wall). Source: api/users/[username].js, api/users/[username]/creations.js.

Cross-entity search: /search

One query across everything creatable on the platform.

GET /api/search?q=<text>&type=all|avatar|agent|model|world|part|coin&limit=18

Six sources are queried in parallel (api/_lib/cross-search.js): avatars, on-chain and Solana agents, forged models, worlds, CAD parts (type=part, opening at /cad/:id, with no remix action), and coins (platform launches first, then external token search). Ranking is recency first, boosted by follower, remix, and view signals. limit is 4..48 (default 18); a scoped type search gives the full limit to that one source.

Model results carry a remix block wired to POST /api/x402/remix-asset; other types deliberately do not get a fake Remix button.

Page: pages/search.html, client src/search-page.js. Source: api/search.js.

Onboarding tour: /start

A self-referential guided tour that chains the platform's own surfaces: welcome at /start → selfie-to-avatar → build a world → markets → launch a coin (optional, at /create-agent) → your profile. It is the hand-authored 6-stop onboarding track of the site-wide Feature Tour: a 3D guide avatar walks the real pages and narrates each stop. The full curriculum in public/tour/curriculum.json (three tracks: full, quick, onboarding) is generated from data/pages.json by scripts/build-tour.mjs; the engine is src/feature-tour/.

First-visit targeting: GET /api/me returns show_onboarding_tour, backed by users.onboarding_tour_seen_at / onboarding_tour_completed_at. The tour can be replayed any time from the getting-started page.


Related pages