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.
Hold-to-Access — the $THREE demand lever
three.ws monetizes premium capability by holding $THREE, not by spending it. A wallet's live USD value of $THREE resolves to a membership tier; tiers unlock fee discounts, higher free quotas, and gated features. Holding removes float and rewards bag size without depleting it — a deflation-free status lever that creates standing demand rather than one-time spend.
This is the canonical reference for the system: the tier ladder, the enforcement primitive, the perk registry, and the roadmap for activating the perks that are registered but not yet enforced.
The only coin this platform references is $THREE (
FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump). Every threshold below is denominated in the USD value of $THREE held.
The tier ladder
Resolved from the USD value a wallet currently holds of $THREE, priced live. Source of
truth: api/_lib/three-tier.js.
| Level | Tier | Hold (USD) | Compute discount | Free-quota multiplier |
|---|---|---|---|---|
| 0 | Member | $0 | — | 1× |
| 1 | Bronze | $25 | 5% | 2× |
| 2 | Silver | $100 | 10% | 3× |
| 3 | Gold | $500 | 20% | 5× |
| 4 | Genesis | $2,500 | 30% | 10× |
A wallet that can't be priced (RPC/price hiccup) resolves to the Member floor, never an error — a balance read must never block a charge.
How resolution works
Three resolvers, picked by what the caller already knows:
| Resolver | I/O | Use |
|---|---|---|
tierForUsd(usd) |
none (pure) | a level from a known USD value |
resolveUserTier(user) |
RPC + price | a session user's on-chain tier (degrades to Member) |
verifyTierPass(token) |
none (pure HMAC) | a presented signed pass — no RPC, zero latency |
Signed tier passes (signTierPass / verifyTierPass)
seal a resolved { wallet, level, usd } into a 10-minute HMAC token (HOLDER_PASS_SECRET).
A service that can't run a Solana RPC — the multiplayer/Colyseus server, an edge worker —
gates on the pass alone. Because the pass is pure-HMAC, a holder presenting one is never
wrongly blocked during an RPC or price outage.
Enforcing a gate
One helper turns the registry into an actual gate:
requireFeatureAccess. It mirrors cors()/method()
semantics — on a blocked request it writes the response itself; on an allowed request it
writes nothing:
import { requireFeatureAccess } from './_lib/require-three.js';
const gate = await requireFeatureAccess(req, res, 'forge.high', { body });
if (!gate.ok) return; // 402 three_hold_required already sent
// ...gate.access, gate.level, gate.wallet are available here
Resolution is comp-first, then pass-first: a comped account (below), then a signed
tier pass (header x-three-tier-pass or body.tier_pass), then the session user's
on-chain tier, then anonymous Member. Every failure degrades to Member: a clean 402,
never a 500.
Comped accounts
Some accounts are exempt from the ladder entirely: the owner's own accounts, and creators/partners granted lifetime access. They clear every gated feature with no wallet, no holding, and no payment.
The allowlist is api/_lib/comp-access.js, and it is the
only place the exemption lives, because requireFeatureAccess is the single keystone
every enforced gate resolves through, one entry covers forge.high, forge.gameready,
and any gate added later. GET /api/three/access applies it too, so the UI renders those
features unlocked rather than showing a lock the API would let straight through; that
response carries tier.comped: true to explain why a $0 holder reads as entitled.
import { isCompedUser, resolveCompAccess } from './_lib/comp-access.js';
const { comped } = await resolveCompAccess(req); // from a request (session-aware)
if (isCompedUser(user)) { /* from an already-resolved user */ }
Grant access by adding a handle to COMPED_ACCOUNTS in that module, or by setting
THREE_COMP_ACCOUNTS to a comma-separated list of handles / emails / user ids. Env
entries are merged with the built-ins, never replace them, so an env typo cannot
silently revoke a comp granted in code.
Three properties keep it safe and cheap:
- Only unique identifiers count.
username,email, andidare uniquely indexed onusers, as is the handle in a platform-issued<handle>@users.three.ws.localaddress (minted byhandleRegisterfor username registrations, which leave theusernamecolumn null).display_nameis deliberately not matched, because it is user-settable and not unique, so honoring it would let anyone comp themselves by renaming. - Anonymous requests pay nothing. The lookup is guarded by
hasSessionCookie(), so a request with no session never issues a query and the zero-latency anonymous free lane is untouched. - It fails closed on the perk. An auth or DB hiccup resolves to "not comped", which simply means the normal hold-or-pay gate applies. It never fails the request.
A comp also lifts the free-lane rate multiplier to the top tier (api/forge.js,
api/gpt-forge.js). It does not bypass BYOK (a caller's own vendor key is still
their own key), nor the platform-wide spend ceilings that protect real vendor budget.
The hold-or-pay 402
A blocked request returns a structured 402 three_hold_required carrying everything the
UI needs to recover — no second round-trip:
{
"error": "three_hold_required",
"message": "High-quality generation requires holding $THREE (Bronze+) — or pay per use.",
"feature": "forge.high",
"reason": "insufficient_tier", // or sign_in | link_wallet
"held": { "level": 0, "id": "member", "usd": 12.50 },
"required": { "level": 1, "id": "bronze", "min_usd": 25 },
"usd_to_go": 12.50,
"acquire": { "mint": "Fe…pump", "symbol": "THREE", "swap_url": "…", "pump_url": "…" },
"pay_per_use": { "action": "forge.high", "usd": 0.50 } // null when hold-only
}
A feature with a payPerUse action lets a non-holder pay once in $THREE instead of
holding. A hold-only feature omits pay_per_use.
A handler that owns its own 402 (a pay-per-use action whose price depends on the request,
like pay-to-keep below) uses checkFeatureAccess(req, res, featureId, { body }) from the
same module instead. It resolves the caller the same way (comp, pass, on-chain tier) but
only reports { eligible, level, wallet } and writes no gate response.
The perk registry
Source of truth: api/_lib/three-access.js. Each feature
maps to a minimum tier, a pay-per-use fallback (or null), and an enforced flag.
enforced is the integrity contract: it is true only when the gate is wired and live
in the product — a request for it is actually checked. false means the perk is
registered/planned but not enforced anywhere. The /three page reads this flag to mark a
feature Live vs Planned, so the platform never promises an unwired perk.
The same honesty applies to the prose perk lines on each tier card. TIERS carries two
lists: perks is what the hold buys today, and planned is what is registered
but not enforced yet. Every surface that renders the ladder (/three,
GET /api/pricing, GET /api/three/tier) serves both, and /three draws the planned
lines with the same Planned flag as the gated-feature rows. Keeping them in one list is
how an unbuilt feature ends up reading as a benefit, so when a gate ships, flip its
enforced here and move its line from planned to perks in the same change.
tests/three-tier-honesty.test.js fails if an unenforced feature's label reappears in a
perks list, and npm run verify:three-gate checks the same thing against the live
/api/pricing payload.
| Feature | Min tier | Status | Pay-per-use | Backend |
|---|---|---|---|---|
forge.high — High-quality generation (200k poly + PBR) |
Bronze | Live | yes | api/forge.js |
forge.gameready — Game-ready export (Unity/Unreal) |
Bronze | Live | yes | api/forge-gameready.js |
forge.keep: Keep a Forge generation (original file) |
Bronze | Off by default (enforced: false) |
per-tier forge.keep.<tier> |
api/forge-keep.js |
worlds.private — Private, invite-only worlds |
Silver | Planned | — | partial (no visibility dim yet) |
mcp.priority — Priority MCP routing |
Silver | Planned | — | not built (no shared queue) |
worlds.branded — Branded worlds + custom environments |
Gold | Planned | — | not built |
drops.early — Early access to drops |
Gold | Planned | — | drop endpoints exist |
names.first_dibs — First dibs on rare *.threews.sol |
Genesis | Planned | name.auction |
SNS exists |
Pay-to-keep (forge.keep)
api/forge-keep.js is an optional gate on the original file of a
Forge generation. It is off unless FORGE_PAY_TO_KEEP=on (flip it with
npm run forge:pay-to-keep -- on|off|status, which uses --update-env-vars). While off,
every generation is keepable and the endpoint answers enabled: false, kept: true. While
on, generating and previewing on a free lane stays free, and the original file is released
once per creation to a Bronze+ holder, or against one settled $THREE payment for
forge.keep.draft ($0.05) or forge.keep.standard ($0.15). High needs no keep payment
because it is already held or paid for at generation time. Because the registry flag
describes a gate that is off by default, forge.keep stays enforced: false and /three
shows it as Planned. GET /api/forge-quote prices a generation (and the keep step) per
path, tier and options from the same tier and catalog code.
Adjacent levers (live, not feature-gated)
- Compute discount — every fixed-price action is re-priced by the holder's
discountBpsinapi/pricing.js(personalizedActions). - Free-quota multiplier — a verified tier pass lifts the anonymous free-generation
ceiling by
rateMultiplierinapi/forge.js(freeLaneMultiplier), zero added latency. - Charged-at tier on
/credits: every credit debit already applies the discount, andGET /api/creditsreports the caller's resolved tier asholder(the same shape/api/pricingreturns, degrading tonullon an RPC hiccup rather than failing the balance read), so the/creditspage shows the tier you are actually being charged at and the next one up.
Proving a holding from the browser
The server only ever sees what the page sends it, so a gated surface that mints its proof
from the wrong identity charges holders. src/three-access.js
is the one client module a gated surface may use. It resolves both identities a holder
can arrive with:
| Identity | How the pass is minted | Prompt? |
|---|---|---|
| Signed in, wallet linked to the account | POST /api/three/tier-pass with the session cookie |
silent |
| Wallet connected, no account (Phantom, Seeker) | signs a domain-bound message, POST { wallet, message, signature } |
one free signature |
Wire a gated request in three steps:
import { getAccess, getTierPass, attachTierPass } from './three-access.js';
const { access } = (await getAccess('forge.gameready', { fresh: true })) || {};
// Interactive only when the read says this identity is eligible, so a non-holder is
// never asked to sign for something that could not unlock anything.
await getTierPass({ interactive: Boolean(access?.eligible) });
const res = await fetch('/api/forge-gameready', {
method: 'POST',
headers: attachTierPass({ 'content-type': 'application/json' }),
body: JSON.stringify(payload),
});
Rules that keep the two identities from drifting apart:
- Mint before the request, not on page load. A pass lives 10 minutes; minting at the moment of the gated call is what guarantees the header is fresh.
- Read access with
{ fresh: true }, and re-read onwallet:changed. Connecting or switching a wallet changes who is asking; the cached matrix is then the wrong identity's. - Never gate the UI on the client's answer. The server is the only authority; the client read exists so the surface can state the viewer's real price up front instead of a generic pitch.
src/three-tier-pass.js is the earlier, session-only helper. It backs <three-gate>'s
access read and mints nothing for a connected wallet, so a surface that uses it to build
headers silently bills every account-less holder. Do not use it for a new gated request.
Activation roadmap
Goal: drive $THREE demand by activating registered-but-dormant perks. A perk is only
worth gating when its backend genuinely exists — wiring a gate onto a missing feature
would be a fake perk, exactly what enforced guards against.
Priority order by demand value × backend readiness:
worlds.private(Silver) — strongest standing-hold lever: a persistent private space you keep only while you hold Silver. Backend closest to ready. Spec below.names.first_dibs(Genesis) — window-gate the*.threews.solauction so Genesis holders get a head start. SNS backend exists (api/sns.js).drops.early(Gold) — time-gate the existing drop endpoints (api/irl/drops.js,api/vanity/drops.js) so Gold holders enter the window early.mcp.priority,worlds.branded— deferred: no backend (shared MCP queue / custom environments) exists to gate. Build the feature first, then the gate.
Each activation is the same shape: add the gate call, flip enforced: true, add a gate
test mirroring tests/forge-high-gate.test.js, add a changelog entry. Nothing else
changes — the access endpoint and /three pick it up automatically.
Spec: worlds.private (first activation)
Today worlds are owner-based with no visibility concept
(api/_lib/world-store.js,
api/world/[action].js). A world's doc is readable by anyone
with its id. Making "private" a real perk means adding a visibility dimension and
enforcing it on read.
1. Schema: a new migration in api/_lib/migrations/ (timestamp-prefixed, like
20261015000000_world_gems.sql) against the world_docs table from
2026-06-01-world-docs.sql:
ALTER TABLE world_docs ADD COLUMN IF NOT EXISTS visibility text NOT NULL DEFAULT 'public';
Thread visibility through world-store.js saveWorld / loadWorld and the returned
shape. Default 'public' so every existing world is untouched.
2. Create gate — in api/world/[action].js handleSave, when a write sets
visibility: 'private':
const gate = await requireFeatureAccess(req, res, 'worlds.private', { body });
if (!gate.ok) return; // 402 three_hold_required (hold-only, Silver+)
Hold-only (no pay-per-use) — a private world is a held perk, not a per-call cost.
3. Load enforcement — in handleLoad, a private world's doc is returned only to its
owner (or a service-token writer); any other caller gets 403 forbidden. This is the step
that makes the perk real rather than a label.
4. Activate — flip enforced: true on worlds.private in
three-access.js. /three auto-flips it to Live.
5. Test — tests/world-private-gate.test.js: non-holder blocked with a 402 on
private create; Silver holder allowed; private-world load forbidden to a stranger; public
worlds unaffected.
6. UI — a visibility toggle in the world builder, defaulting to public.
7. Changelog — a feature entry in data/changelog.json.
Verifying the claims without buying anything
Every public statement about this system is checkable from outside, and none of the checks require holding a token. Run them after any deploy that touches the gate:
npm run verify:three-gate # against https://three.ws
npm run verify:three-gate -- --no-forge # skip the two free-lane generations
scripts/verify-three-gate.mjs asserts five things
against the live site:
- The ladder matches what we publish. The thresholds, discounts, and quota
multipliers in
TIERSare compared to the numbers used in public copy. A silent threshold change fails here before a holder discovers it. - The deny path. An anonymous
POST /api/forge {"tier":"high"}and an anonymous Game-Ready export must return402 three_hold_requiredcarrying the required tier, themin_usd, the acquire block, and the pay-per-use alternative. - The allow path, read-only. The script reads the mint's largest token accounts,
resolves their owner wallets, and asks
GET /api/three/access?wallet=...what each one is entitled to. Real wallets holding real $THREE must come back eligible. A balance read moves nothing and costs nothing, so the unlock side is provable without a purchase. - The free floor. Draft and standard generation must still be accepted with no account, no wallet, and no hold.
- Planned stays planned. Every feature that is not wired must report
enforced: false, which is exactly what draws the "Planned" flag on/three. A perk promoted to "Live" without a gate behind it fails this check.
What the script deliberately does not cover is a holder completing a High generation
end to end, because that needs an authenticated session. Use a
comped account, which clears every gate with no hold, to
exercise that path; the gate treats a comp and a holder through the same
requireFeatureAccess branch.
Unit coverage for the same behavior lives in tests/forge-high-gate.test.js,
tests/forge-gameready-gate.test.js, tests/three-require.test.js, and
tests/comp-access.test.js.
Configuration
| Env var | Required | Purpose |
|---|---|---|
HOLDER_PASS_SECRET |
prod | HMAC key for signing/verifying tier passes |
FORGE_PAY_TO_KEEP |
no | on enables the pay-to-keep gate in api/forge-keep.js (default off) |
THREE_COMP_ACCOUNTS |
no | extra comped handles / emails / user ids, comma-separated (merged with the built-in allowlist) |
THREE_TOKEN_MINT |
— | $THREE mint (defaults to the canonical CA) |
THREE_TOKEN_DECIMALS |
— | token decimals (default 6) |
THREE_CREDIT_BONUS_BPS |
no | bonus credits for paying credits in $THREE, in basis points of the deposit's USD value (default 0: no bonus). Read live by creditBonusBps() in api/_lib/token/config.js; surfaced as credit_bonus_bps and in /api/credits deposit.assets[].bonus_bps |
SOLANA_RPC_URL (+ provider keys) |
— | RPC for on-chain balance reads (see solana/connection.js) |
UPSTASH_REDIS_REST_URL / _TOKEN |
— | caches balance/tier lookups (optional, fail-safe) |
Related
- Validation — the quality gate every model passes before publish.
- Pricing catalog — fixed-price actions the discount applies to.
/three— the holder-facing tier page that surfaces this ladder.