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.
Notifications: the bell, the /notifications center, and the inbox API
Everything that happens to your work on three.ws (a payment lands, a skill sells, someone remixes your model, follows you, a quest finishes, a royalty arrives) becomes a row in one per-user inbox. Two surfaces read that inbox: the bell in the site header, and the full notification center at /notifications. This page documents both surfaces as coded, the category system behind the filter tabs, and the complete API contract. Where those notifications come from (which features fire which events) is covered in The social layer; this page picks up where that one leaves off.
| Piece | Where | Source |
|---|---|---|
| Bell dropdown | The bell button in the header, on every page | src/notifications.js |
| Notification center | /notifications | pages/notifications.html, src/notifications-page.js |
| Preference editor | /dashboard/settings |
src/dashboard-next/pages/settings.js |
| Avatar announcements | The corner companion, on any page | src/notification-herald.js |
| Inbox API | GET/POST/DELETE /api/notifications/* |
api/notifications/ |
One inbox, two views. The dropdown holds the latest page for a quick glance;
the /notifications page adds category tabs, per-row delete, and cursor
pagination for the full history. Both import the same icon, label, link, and
escaping helpers from src/notifications.js, so a
notification always reads identically in both places.
The notification record
Every row the API returns is
{ id, type, payload, read_at, created_at }
typeis a machine string likeskill_purchased,remix,follow,quest_complete, orroyalty_paid. The full producing vocabulary isUSER_EVENT_TYPESin api/_lib/feed.js plus the types written directly by the purchase, forge, withdrawal, and security flows.payloadcarries the type-specific details (actor name, skill name, amounts, alinkfor click-through). The human-readable sentence is built client-side bynotifLabel(); the click target is resolved bynotifLink()frompayload.link, then a Solana transaction signature (payload.tx_signature, linked to its Solscan page), thenpayload.agent_id.read_atis null until the notification is read;created_atorders the inbox and doubles as the pagination cursor.
Payload values are other users' text, so both surfaces HTML-escape every
interpolated string, and notifLink() only permits same-origin relative paths
or absolute http(s) URLs. A hostile payload cannot inject markup or drive
navigation into a javascript: URL. Payment amounts denominated in $THREE
render with the $THREE label; other recognized mints render with their
standard symbol, and an unrecognized mint degrades to a bare number rather
than naming a coin.
Categories: how the filter tabs group types
The /notifications page has nine tabs: All, Sales & earnings,
Purchases, Social, In person, Market alerts, Creations,
Companion, and Account. Each notification type maps to exactly one
category; the mapping (TYPE_CATEGORY) lives in
api/_lib/notify-prefs.js and is mirrored in
src/notifications-page.js for tab filtering.
| Category (tab) | Key | Notification types |
|---|---|---|
| Sales & earnings | sales |
skill_purchased, asset_purchased, sale, payment-earned, payment_received, referral_earned, referral_signup, referral_reward, pump_launch_filled, royalty_paid |
| Purchases | purchases |
skill_purchase_confirmed, asset_purchase_confirmed, skill_gift_received, skill_gift_sent, print_update |
| Social | social |
remix, reply, comment, embed, mention, fork, follow, dm_received, agent_review, quest_complete, duel_challenge (another owner challenged your agent to a duel, or answered your challenge) |
| In person | irl |
irl_interaction, irl_reply |
| Market alerts | alerts |
pump_alert |
| Creations | creations |
forge_complete, forge_failed |
| Companion | companion |
companion_delivery |
| Approvals | approvals |
approval_requested (see Approvals) |
| (no tab yet) | knock |
knock_received |
| (no tab yet) | mail |
mail_received |
| Account | account |
withdrawal_completed, withdrawal_failed, payment_mismatch, asset_payment_mismatch, skill_payment_mismatch, security_alert, wallet_anomaly_frozen, plus any type not in the map (the agent-inference inference_topup and inference_budget_exhausted land here this way), token_budget_paused and spend_cap_alert (the spend page caps) |
print_update is the single type Materialize uses for a physical order's whole
lifecycle, quoted through delivered, and it sits with purchases because the
order is the buyer's own.
Three details worth knowing:
- Unmapped types fall back to
account, so a newly added notification type is never silently undeliverable or unfilterable. - Tab filtering is client-side over the pages already fetched. The API's
own
?type=parameter filters server-side by a single exact type (e.g.?type=pump_alert), not by category. knockandmailare preference categories without a tab. The preference center lists them ("Knocks at your door", "Agent mail") and the server gates delivery on them, but the page's own copy of the map has no entry forknock_receivedormail_received, so on/notificationsboth are filtered under Account rather than a tab of their own. Mail the spam filter holds back never notifies at all.
The avatar channel: delivered in person
A badge waits to be noticed. Some notifications should not have to. When one of those lands while you are on the site, the corner companion (the avatar that already walks your pages) turns to you, plays a gesture, and says it out loud, with a link straight to the thing that happened.
avatar is a real delivery channel next to in_app, push, email,
telegram, and discord. It is gated by the same per-category matrix, edited in the same
place (/dashboard/settings), and measured in the same funnel.
What gets announced. By default: Sales & earnings, Creations,
Companion deliveries, Knocks at your door, and Account. Money
landing, a generation finishing while you waited, a message your companion
triaged as worth hearing, someone who paid your price to reach you, and
anything touching your account are worth an interruption. Purchases, social,
in person, market alerts, and agent mail are off by default because they are
frequent.
Every one of them is a toggle, so an inbox that should speak up more (or not
at all) is two clicks away. The defaults live in DEFAULTS in
api/_lib/notify-prefs.js.
When it stays quiet. The rules live in src/notification-herald.js:
- Only unread notifications under 15 minutes old. Older rows are history, and history belongs in the bell.
- Each notification exactly once per browser. Delivered ids are remembered
in
localStorage, so navigating, re-polling, or opening a second tab never replays a line. - Two lines per batch, maximum. Anything past that becomes a single
"N more waiting" line pointing at
/notifications, so a backlog never turns into a monologue. - Never into a background tab. The point is telling someone who is here.
- Nothing is spoken aloud unless you asked for audio. Announcements use
the companion's own narration setting (
walk:companion:narrate, the toggle on the companion itself). On the default caption-only setting the message is text in the bubble, which is also anaria-liveregion, so screen readers get it either way.
Controls. The bubble carries "Turn off", which silences announcements in
that browser instantly without touching the account-wide setting. Per-category
control lives in the Notifications panel of /dashboard/settings.
No companion running? It is summoned for that one message and walks off
again afterwards, without turning itself on permanently. When an avatar cannot
be rendered at all (no WebGL, inside an iframe, or a route that already owns
the corner, such as /play or /avatar-studio) the line degrades to a normal
toast, so the notification is never lost to a missing GPU.
The delivery itself is one call into the walk SDK, which any surface can reuse:
// walk-sdk/src/companion.js: mounts if needed, gestures, speaks, retreats.
await window.__walkCompanion.announce('Your agent made a sale', {
tone: 'alert',
emote: 'dance',
actions: [{ label: 'Open', href: '/dashboard' }],
});
How the bell and unread state work
The bell (src/notifications.js) is mounted by the shared nav on every page and is deliberately cheap:
- Auth-aware. It reads a local sign-in hint (
3dagent:auth-hintin localStorage). Signed out: no polling at all, the badge stays hidden, and opening the panel shows a sign-in prompt instead of an empty inbox. - Polling. Signed in, it fetches
GET /api/notifications?limit=20every 30 seconds, re-polls when the tab regains focus, and pauses while the tab is hidden. - One fetch per user, not per tab. All open tabs share the result through a localStorage cache plus a BroadcastChannel: whichever tab wins a best-effort fetch lock spends the request and broadcasts the payload; every other tab reuses it for the poll interval. A new tab seeds its badge from the cache instantly without its own request.
- Backoff. A 429 from the per-user rate budget starts an exponential backoff (doubling from 30 seconds, capped at 5 minutes), so the badge self-heals without hammering a drained budget.
- The badge shows the server's
unread_count(rendered as99+past 99), updates itsaria-label, and announces changes politely to screen readers. - Opening the panel marks everything read. The dropdown is a glance
surface: if anything is unread when it opens, it fires
POST /api/notifications/read-alland zeroes the badge. Clicking a single row also marks that row read, sends anopenedfunnel beacon toPOST /api/notifications/track, and navigates to the resolved link. - Push upsell at the value moment. While the panel is open (never on page
load), a one-time banner offers Web Push if it is supported, configured,
not yet subscribed, and not previously declined. Push plumbing lives in
src/push-notifications.js and
public/push-sw.js. Inside the three.ws iOS app the
same calls register with Apple Push Notification service instead (the
WebView runs no service worker), and the bell also fires a
threews:unreadwindow event with the count so the app can keep its icon badge in step.
The notification center: /notifications
pages/notifications.html (served at
/notifications, noindex) is the overflow surface the dropdown never has
to be: full history, filterable, deletable.
- Auth wall. Without the local sign-in hint (or on a 401 from the API)
the page shows a sign-in wall linking to
/login?next=/notifications. - Category tabs filter the fetched list client-side per the table above.
The active tab is reflected with
aria-selected; each empty category has its own designed empty state. - Pagination. Pages of 30 load via the
beforecursor: the Load more button passes the last row'screated_atback to the API and appends the result. The button renders only while the API reportshas_more. - Per-row actions. Clicking a row marks it read, tracks the open, and
navigates. The delete button on each row removes it permanently
(
DELETE /api/notifications/:id), optimistically in the UI and fire-and-forget on the wire. Mark all read clears everything at once. - Unlike the dropdown, the page never auto-marks the whole inbox read on open; unread rows stay highlighted until clicked or bulk-cleared.
API contract
All endpoints require authentication: a session cookie or a bearer credential
(API key / OAuth). Unauthenticated calls answer
401 { "error": "unauthorized" }. State-changing routes additionally require
a CSRF token for cookie sessions (fetch one from GET /api/csrf-token, echo
it in the X-CSRF-Token header); bearer callers are CSRF-exempt, which is
what the examples below use. Every query is scoped to the caller's user_id,
so one user can never read, mark, or delete another's notifications. The
same endpoints are exposed as MCP tools by
packages/notifications-mcp.
List the inbox
GET /api/notifications?limit=20&type=<type>&before=<iso>
limit is 1..50 (default 20). type filters one exact notification type.
before pages past a created_at cursor.
curl -s 'https://three.ws/api/notifications?limit=5' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"notifications": [
{
"id": "5f3c9c2a-1111-4222-8333-444455556666",
"type": "remix",
"payload": { "actor": "mira", "royaltyPaid": true, "royaltyUsd": 0.012, "link": "/viewer?src=..." },
"read_at": null,
"created_at": "2026-07-30T09:14:02.511Z"
}
],
"unread_count": 3,
"has_more": false
}
Source: api/notifications/index.js.
Mark one read
curl -s -X POST \
'https://three.ws/api/notifications/5f3c9c2a-1111-4222-8333-444455556666/read' \
-H 'Authorization: Bearer YOUR_API_KEY'
Returns { id, read_at }. Idempotent: an already-read row keeps its original
read_at. 404 if the row is not the caller's.
Source: api/notifications/[id]/read.js.
Mark everything read
curl -s -X POST 'https://three.ws/api/notifications/read-all' \
-H 'Authorization: Bearer YOUR_API_KEY'
Returns { marked_read: <count> }.
Source: api/notifications/read-all.js.
Delete one
curl -s -X DELETE \
'https://three.ws/api/notifications/5f3c9c2a-1111-4222-8333-444455556666' \
-H 'Authorization: Bearer YOUR_API_KEY'
Returns { ok: true, id, deleted: true }; 400 for a non-UUID id, 404 if the
row is not the caller's. Removal is permanent.
Source: api/notifications/[id]/index.js.
Track a funnel event
POST /api/notifications/track
{ "notification_id": "<uuid>", "channel": "push" | "in_app" | "avatar", "event": "opened" | "returned" }
An idempotent analytics beacon closing the sent-to-opened-to-returned loop:
the service worker fires opened on a push click, the corner companion fires
opened when you click through from a line it announced, and the app fires
returned when it boots from a push-sourced open. Session-cookie auth only (no bearer),
CSRF-exempt, deduplicated server-side.
Source: api/notifications/track.js.
Preferences
# Read the resolved category x channel matrix
curl -s 'https://three.ws/api/notifications/preferences' \
-H 'Authorization: Bearer YOUR_API_KEY'
# Turn push off for the social category
curl -s -X PUT 'https://three.ws/api/notifications/preferences' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'content-type: application/json' \
-d '{ "categories": { "social": { "push": false } } }'
GET returns
{ categories, channels, type_categories, prefs, push: { subscribed_devices, ios_devices }, gateways: { telegram, discord } }:
the categories from the table above, the channels (in_app, push, email,
telegram, discord, avatar), the type-to-category map (so a browser client
can resolve a category without a round trip per notification), the caller's
resolved matrix, the push device count (browsers plus iPhones enrolled through
the iOS app, with the iPhones also counted alone), and how many chats paired
through the Telegram and Discord chat gateways have notifications on. The
telegram and discord channels deliver to those paired chats. PUT returns
{ ok: true, prefs }: it stores a sparse override, unknown categories,
channels, and keys are dropped, and prefs is the re-resolved matrix. The
body also accepts telegram_chat_id (digits, settable and clearable) for the
Telegram channel.
Delivery gating notes, all enforced in api/_lib/notify-prefs.js:
- Muting
in_appfor a category writes no inbox row at all for it: nothing inunread_count, nothing inGET /api/notifications, and turning it back on is not retroactive. The channels are independent, so a muted bell with push left on still delivers the OS notification. - The
accountcategory'sin_appchannel is locked on. It is the durable record of withdrawals and security events, and the fallback bucket for unmapped types; every other channel stays fully mutable. - A user who never saved gets the defaults, and new categories light up automatically without a backfill.
The visual editor for all of this is the Notifications panel in
/dashboard/settings (source),
one click from the gear icon in both notification surfaces.
Source: api/notifications/preferences.js. The endpoint-level README at api/notifications/README.md covers the same routes from the operator's side (rate limits, table names, routing).
Related pages
- The social layer: where notification events come from and how they connect to the feed, follows, and portfolios.
- api/notifications/README.md: the endpoint directory's own reference.
- packages/notifications-mcp: the same inbox as MCP tools for machine clients.