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.
API
Vercel serverless functions that power the three.ws backend. Every .js file under api/ (outside the _-prefixed helper folders) is deployed as its own HTTP endpoint, and the file path maps directly to the route:
api/agents.js->/api/agentsapi/avatars/index.js->/api/avatarsapi/agents/[id].js->/api/agents/:idapi/erc8004/[action].js->/api/erc8004/:actionapi/studio-assets/[...path].js->/api/studio-assets/*
Most handlers run on the Node.js runtime; api/chat.js runs on the Edge runtime to stream SSE. vercel.json sets maxDuration / includeFiles per function and declares the cron schedule (see below).
Shared internals (not endpoints)
The _-prefixed folders are imported by the endpoints; they are not routes:
_lib/— shared helpers. HTTP utilities in_lib/http.js(json,text,redirect,error,readJson,readForm,cors,wrap,method); Postgres in_lib/db.js(thesqltagged-template proxy +query); auth in_lib/auth.js(getSessionUser,authenticateBearer,extractBearer,hasScope, sessions, access/refresh tokens, CSRF). Also covers x402 (x402*.js), Solana/EVM transfers, pump.fun pricing, R2 storage, rate limiting, and validation._mcp/— Model Context Protocol internals: toolcatalog,dispatch,auth,payments,render,embed-policy._providers/— third-party provider adapters (gcp.js,huggingface.js,replicate.js).
Endpoint groups
Agents and identity
agents.js,agents/— agent identity registry: list/create,agents/me,agents/[id](get/update), plusby-wallet,check-name,pricing,talk,sns,solana-wallet,pumpfun,nfts,suggest, and more.agent-3d/,agent-actions.js,agent-delegate.js,agent-memory.js,agent-skills.js,agent-skill-price.js,agent-strategy.js— agent versions, actions, ERC-7710 delegation, memory, and skills.erc8004/— ERC-8004 identity + reputation via an[action].jsdispatcher, plusregister-confirm.js.sns.js,sns-subdomain.js,threews/— Solana Name Service (.solresolve + reverse-lookup, cached) and three.ws subdomains.
Avatars and 3D
avatars/,avatar/— avatar CRUD plusavatar/optimize,avatar/render,avatar/video-generate,avatar/video-status.actions/— avatar action renders;animations/,mocap/,render/,scene/,nft/— animation presigns, motion-capture clips, GLB/clip rendering, scene gating, and scene-NFT minting.
AI, chat, and inference
chat.js(Edge SSE, multi-provider routing across Groq / OpenRouter / OpenAI / Anthropic),chat/,brain/chat.js,llm/anthropic.js,chat-skills.js.inference/livepeer.js: side-by-side LLM comparison, the three.ws provider chain against a Livepeer AI gateway, each leg reporting its own latency, tokens, and error.tts/— text-to-speech (speak,edge,eleven,eleven-clone).persona/,seed/— persona extraction/preview and seed synthesis from X / GitHub / Farcaster.mcp.js— MCP server over Streamable HTTP (MCP 2025-06-18, JSON-RPC 2.0):POSTtool calls,GETSSE,DELETEterminate.pump-fun-mcp.js— the pump.fun MCP surface.
Payments and x402
x402/— x402 paid endpoints (e.g.agent-reputation,asset-download,fact-check,pay-by-name,mint-to-mesh,skill-marketplace,my-receipts,model-check).x402-pay.js(server-side payer streaming the challenge -> build -> verify -> settle lifecycle as SSE),x402-pay/,x402-checkout.js,x402-checkout-record.js,x402-skus.js,x402-status.js.payments/,billing/,monetization/,subscriptions.js,subscriptions/,purchase/,wallet/— payment intents, billing/receipts, monetization revenue/withdrawals, subscriptions, wallet balances.
Marketplace and discovery
marketplace.js(301-redirects to/api/marketplace/agents),marketplace/— skill/asset marketplace: list, buy, reviews, trials, theme, skill pricing.bazaar/— x402 bazaar service discovery (search,list,providers,arbitrage,context).skills/,skills-manifest.js,chat-skills.js,assets/,widgets/,creators/,explore.js,discover-detail.js,showcase.js,characters.js— catalogs and discovery surfaces.
Pump.fun / Solana
pump/— pump.fun token data and actions:dashboard,curve,balances,by-agent,channel-feed,helius-stats,helius-webhook,launch-prep,quote-sdk,trades-stream, withdraw / accept-payment prep + confirm.solana-rpc.js,three-token/,kol/— Solana RPC proxy, the three.ws token, and KOL trade data.
Auth and accounts
auth/,oauth/,csrf-token.js,zauth-status.js,onboarding/,permissions/,api-keys.js,api-keys/,keys/,user/,users/,dashboard/,notifications/,developer/— sessions, OAuth, CSRF, onboarding, capability permissions, API keys, user profiles, developer usage/webhooks.
Social and syndication
x/— X (Twitter) posting, drafts, scheduling, analytics, triggers, reviews.social/,rss/,sentiment.js,club/— sentiment, RSS announcements, and the club leaderboard / presence / tips.
Embedding and pages
embed/,widgets/(oembed, og, page, view),agent-oembed.js,agent-og.js,agent-page.js, and the*-og.jsfiles (a-og,app-og,avatar-og,u-og,walk-og) — embed resolution, oEmbed, Open Graph image/page generation.artifact.js— Claude-Artifact bundle endpoint (seespecs/CLAUDE_ARTIFACT.md).sitemap.js,sitemap/,openapi-json.js,config.js,features.js,home-stats.js,platform/,healthz.js— sitemaps, OpenAPI doc, runtime config / feature flags, stats, health checks.
Integrations and ops
aws-marketplace/,lobehub/,plugins/,pinning/,forever/,launchpad/,rider/,webhooks/,tx/,audit-log.js,usage/,insights/,admin/— external marketplace/registry integrations, IPFS pinning, on-chain inscription, launchpad, paywall (rider), inbound webhooks, transaction explanation, audit logging, usage/insights, and admin tooling.
Scheduled jobs (Vercel Cron)
cron/[name].js— a single dynamic dispatcher for every cron job. Vercel hits/api/cron/<name>;req.query.nameselects the job. Schedules are declared invercel.jsonundercrons, including:audit-log-cleanup(daily 04:00);expire-pending-purchases,solana-attestations-crawl,index-delegations,run-coin-cycle,unstoppable-tick(every 5 min);cleanup-csrf-tokens(hourly :17);process-withdrawals,run-dca,run-subscriptions(hourly);erc8004-crawl,pumpfun-signals(every 15 min);run-x-scheduled-posts(every min);run-x-triggers(every 5 min);fetch-x-metrics,process-subscriptions(every 6 h);pump-agent-stats,solana-attest-event-cleanup(every 10 min);pumpfun-monitor(every 3 min);settle-royalties,siwx-gc(daily 03:00); and the staggeredrun-coin-payouts/club-payouts.
Quick examples
Every endpoint speaks plain HTTP. These run as-is against production (all verified):
# Liveness plus the exact commit and Cloud Run revision serving production
curl -s https://three.ws/api/version
# Public agent directory (no auth)
curl -s "https://three.ws/api/agents/public?limit=3"
# Paginated manifest of the free rigged-character library
curl -s "https://three.ws/api/avatars/library?limit=5"
# Free x402 market index: every paid market-data endpoint and its price
curl -s https://three.ws/api/x402/market
# The full MCP tool catalog as plain JSON (no auth, no payment)
curl -s https://three.ws/api/tool_schema
# Probing a paid surface bare returns its x402 payment challenge, not an error page
curl -s -X POST https://three.ws/api/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Three auth models coexist, and each handler states its own:
- Public: no credentials (everything above).
- Session + CSRF: browser surfaces send the session cookie plus a token from
/api/csrf-token; see_lib/auth.js(getSessionUser). - Bearer: developer API keys and scoped agent tokens via the
Authorization: Bearerheader; see_lib/auth.js(authenticateBearer,hasScope) and docs/developer-platform.md.
Paid endpoints layer x402 on top: pay the challenge with any x402 client and retry with the X-PAYMENT header. Buyer-side walkthrough: docs/x402-buyer.md; free debugging bench: docs/x402-dev-tools.md.
Local development
These run under vercel dev, or behind the Vite dev-server proxy. CORS is applied per-endpoint via the cors helper in _lib/http.js.