three.ws

Website · X / Twitter · GitHub · $THREE on pump.fun

https://github.com/user-attachments/assets/d52515d1-cb04-4dd6-98bd-fef233312dc4

Give your AI a body. three.ws is an open-source, browser-native 3D AI agent platform. Type a prompt and Forge generates a textured 3D model — or drop a GLB you already have. Add an LLM brain, register on-chain, and embed anywhere — no plugins, no server uploads, no installs required.

Try it in 60 seconds: open three.ws/forge, type "a brass steampunk owl, full body", and download the GLB. Text→3D, image→3D, and sketch→3D — free draft tier, no account. Jump to the Forge section ↓

$THREE

$THREE is the native token of the three.ws ecosystem — the one and only coin of the platform.

Always verify the contract address above before trading. $THREE is the only token associated with three.ws.

Table of Contents

• What is three.ws?
• Vision
• Roadmap
• Key Features
• Forge — Text & Image to 3D
• Platform Pages
• Install in Claude Code
• Cloud Marketplaces
• Ecosystem Directories
• IBM watsonx & Granite
• Screenshots
• Architecture
  • Design Docs & Specs
• Tech Stack
  • Browser Support
• Getting Started
• Examples
• Tutorials
• Project Structure
• The Agent System
  • Event Bus (Agent Protocol)
  • LLM Runtime
  • Empathy Layer
  • Skills
  • Memory
• Web Component & Embedding
• Widget System
• Embed Editor
• Pose Studio
• Launchpad
• The Club
• Walk & Multiplayer
• Coin Communities
• City
• Friends, Presence & Social
• In-Game Economy
• Voice Lab & Mocap Studio
• x402 Payments
• A2A — Agent-to-Agent Protocol
• Talk Mode & Lip-Sync
• Solana Mobile (Seeker)
• Selfie Reconstruction Pipeline (Phase 1)
• Livepeer Inference Network (Phase 4)
• Voice & Persona Hub (Phase 2)
• WASM Vanity Grinder
• News CMS & Syndication
• Security Hardening
• Developer SDKs
• Claude Code Integration
• Demos Hub
• Skill Library
• Animation System
• Avatar Accessories & Coin Launchpad
• Brain Proxy & LLM Routing
• API Reference
• Authentication & OAuth 2.1
• MCP Server
• On-Chain Identity (ERC-8004 + Metaplex Core)
• Pump.fun Integration
• Database Schema
• Build & Deployment
  • Versioning & Compatibility
• Environment Variables
• Testing
• FAQ & Troubleshooting
• Contributing
• Contributors
• License

What is three.ws?

three.ws is a full-stack system for creating, deploying, and embedding 3D AI agents. It combines a WebGL model viewer, an LLM-driven agent runtime, on-chain identity contracts, and a distributable web component into one cohesive platform.

At its core, it does five things:

1. Generate — turns a text prompt, 1–4 photos, or a sketch into a textured, downloadable GLB via Forge. Free draft tier, no account required; auto-rigging, restyling, and retexturing in the same flow.

2. Render — loads and validates glTF 2.0 / GLB models in WebGL 2.0 with zero server-side processing. Drag a file onto the browser and it renders instantly with full Draco, KTX2, and Meshopt decompression.

3. Embody — wraps any avatar with an LLM brain. The agent listens to the user, thinks with Claude, executes tools (animations, gestures, memory operations, skill calls), and expresses emotion through morph-target blending on the 3D model in real time.

4. Register — optionally mints the agent on-chain: as an ERC-8004 token on any EVM chain, or as a Metaplex Core NFT on Solana. Either path gives the agent a stable on-chain identity, a wallet address, signed action history, and a reputation score that cannot be forged.

5. Embed — distributes the agent as an <agent-3d> web component that anyone can drop into a page, or as one of five purpose-built widget types (turntable, animation gallery, talking agent, passport card, hotspot tour) with Open Graph and oEmbed support built in.

The backend is a set of Vercel serverless functions backed by Neon Postgres for metadata, Cloudflare R2 for model storage, and Upstash Redis for rate limiting. It exposes a full OAuth 2.1 authorization server and an MCP (Model Context Protocol) endpoint so external AI systems can drive avatars programmatically.

three.ws is production-ready and serves three.ws live. The entire stack — viewer, agent runtime, contracts, backend, and web component — is open source under Apache 2.0.

Vision

One day, creating your agent should be as simple as taking a selfie.

Point your camera at yourself — or anyone — and watch a fully realized 3D avatar emerge: your face, your voice, your personality, alive in the browser. That avatar becomes an agent with memory and skills, registered onchain — as an ERC-8004 token on EVM or a Metaplex Core asset on Solana — permanent and verifiable by anyone forever. No 3D software. No wallet setup. No uploads. Just a photo and a name.

This is the direction three.ws is heading: photo → avatar → agent → onchain identity, in a single flow. The infrastructure is already here — the viewer, the runtime, the contracts, the embedding layer. What comes next is closing the gap between a picture of a person and a living, ownable, embeddable piece of them that exists on the internet permanently.

Roadmap

three.ws ships in four phases. Each phase closes a specific gap between the current platform and the end-state vision: anyone can mint a 3D agent of themselves, own it onchain, and embed it anywhere on the internet.

Phase 0 — Foundations (Shipped)

The full stack is live at three.ws: WebGL viewer, LLM agent runtime, ERC-8004 identity contracts (EVM) and Metaplex Core mints (Solana), OAuth 2.1 server, MCP endpoint, and the <agent-3d> web component. Anyone can register an agent today — but the avatar still has to come from a 3D artist or a third-party tool.

What works: model upload, agent runtime, onchain registration, embedding, signed action history, reputation scores. What doesn't: there is no automated path from a real human face to a usable 3D avatar.

Phase 1 — Selfie → Avatar Engine

Goal: any user takes 3 selfies (left, center, right) and receives a rigged, animatable 3D avatar in under 60 seconds.

Deliverables

• Mobile-first capture UX with realtime quality gates (lighting, framing, blur)
• Multi-view face reconstruction pipeline (FLAME / 3DMM fitting on top of a base body mesh)
• Hosted inference workers (GPU-backed) for sub-minute generation
• Output written directly to R2 and minted as a draft agent token — ERC-8004 on EVM, Metaplex Core asset on Solana

Compute requirements

• A100/H100-class GPUs for inference, sized to ~10k avatars/day at launch
• Training budget for fine-tuning a stylized face-fitter on a curated dataset
• CDN egress scaling for high-res GLB delivery

Verification: 1,000 test users complete capture and mint an onchain agent of themselves end-to-end with ≥4/5 likeness score.

Phase 2 — Agent Personalization

Goal: the avatar isn't just you — the agent acts like you.

Deliverables

• Voice cloning (3–10 seconds of speech → ElevenLabs custom voice bound to the agent)
• Persona extraction from a short onboarding interview (tone, vocabulary, interests)
• Memory seeding from connected accounts (X, GitHub, Farcaster) with explicit user consent
• Per-agent fine-tuned system prompt stored in the manifest, signed and pinned to IPFS

Verification: users return to converse with their own agent; ≥30% week-2 retention on minted agents.

Phase 3 — Onchain Economy

Goal: agents are real economic objects on EVM and Solana, not just collectibles.

Deliverables

• Agent tokens — ERC-8004 mints with bonding-curve pricing or fair launch options
• Reputation markets — stake on agents, earn from their action history (extends ReputationRegistry.sol)
• Skill royalties — skill authors earn per-call fees through EIP-7710 delegated permissions
• Agent-to-agent payments — agents transact autonomously via their delegated signer wallets
• Subscriptions & DCA — recurring onchain payments to creators (cron infra already in place)

Funding requirements

• Smart contract audits (multi-firm) for the reputation, royalty, and delegation contracts
• Liquidity for agent token launches
• Indexer infrastructure across Base, Solana, and additional EVM chains

Verification: ≥1,000 agents minted with active onchain reputation; ≥$X in cumulative skill royalties paid out.

Phase 4 — Open Inference Network

Goal: decouple agent inference from any single provider. Anyone can run a node; agents pay nodes onchain for compute.

Deliverables

• Open protocol for agent inference (model weights, GPU runtime, signed responses)
• Node operator client (Docker + GPU drivers) with onchain registration
• Onchain settlement for inference jobs — pay-per-token with cryptographic receipts
• Federation with existing decentralized compute networks where appropriate

Compute requirements

• Bootstrap GPU credits for early node operators
• Cryptoeconomic security model (slashing, validator set) — research + audit budget

Verification: ≥50% of production agent traffic served by independent node operators; latency parity with centralized inference.

What we need

Phases 1 and 2 unblock the consumer story — anyone gets an agent of themselves. Phases 3 and 4 unblock the onchain story — those agents are real economic actors that don't depend on any one company to keep running. Both are required for the vision; neither is funded yet.

If you want to support the project — compute credits, grants, partnerships, or contributions — open an issue or reach out via three.ws.

Key Features

Text → 3D Generation (Forge)

• Prompt-to-3D at three.ws/forge — describe an object in a sentence and download a textured GLB
• Image→3D (one to four photos) and sketch→3D in the same composer
• Multiple generation engines with live health checks: self-hosted lanes plus bring-your-own-key Meshy and Tripo (keys stay in the browser)
• Prompt-to-avatar at three.ws/create/prompt — a description becomes a rigged, animatable 3D avatar
• Generated models carry straight into Scene Studio, embeds, worlds, and on-chain deployment

3D Viewer

• WebGL 2.0 rendering via three.js r184
• glTF 2.0 and GLB with Draco geometry compression, KTX2 texture compression, and Meshopt mesh optimization
• Khronos-spec glTF validation with line-level error reporting
• HDR environment maps, PBR materials, skinned mesh animations, morph targets, and embedded cameras
• OrbitControls (pan, zoom, rotate) with configurable auto-rotation
• Real-time parameter tweaking (lights, exposure, morph weights) via dat.GUI

Agent Runtime

• LLM brain powered by Claude (Anthropic API) with a structured tool-loop architecture
• Up to 8 tool iterations per turn before returning final output
• Built-in tools: wave, lookAt, play_clip, setExpression, speak, remember
• Composable skill system — install skills from IPFS, Arweave, or HTTP; each skill is a self-contained bundle with a description, tool definitions, and async handlers
• Weighted emotion blending (celebration, concern, curiosity, empathy, patience) driven by protocol events, not a finite-state machine
• Web Speech API for STT/TTS out of the box; ElevenLabs integration for production-quality voice
• Talk mode with audio-driven ARKit-52 lip-sync — TTS audio is analysed in real time and drives 52 standard blendshapes on the avatar
• Anonymous Groq-powered chat for unauthenticated visitors; owner-card gating when an agent has a paying author

x402 Payments & Bazaar

• Native x402 paid endpoints on Base, BSC, and Solana — agents pay other agents in USDC for API calls, asset downloads, and skill royalties
• Coinbase CDP facilitator on Base mainnet; direct-scheme payments on BSC
• Permit2 gas-sponsoring siblings on every CDP-settled endpoint (buyer signs, relayer pays gas)
• Pay-by-name — /api/x402/pay-by-name resolves @username, *.sol (incl. subdomains), or raw base58 to a recipient and builds an unsigned USDC transfer for the payer's wallet. Every 402 manifest emitted by a named agent advertises recipient_name next to the wallet, so payers verify a human-readable name before signing
• SKU catalog + Stripe-style checkout at /dashboard/x402; receipts ledger with admin tooling
• Subscriptions, idempotency tokens, offer receipts, paid asset download, and a bazaar listing/search API
• SIWX (Sign-In with X-chain) server for auth-gated paid endpoints
• Listed on x402scan and the MCP Registry

SNS / *.threews.sol subdomains

• /threews/claim lets any signed-in user mint [username].threews.sol in a single atomic Solana transaction — createSubdomain → URL record → transferSubdomain to the user's wallet, with three.ws absorbing gas
• Brave Browser resolves the subdomain directly to the user's /u/[username] showcase via the SNS URL record
• Agents can bind a .sol name (theirs or a fresh registration) via /api/agents/:id/sns; once bound, every public surface — agent page, x402 manifest, MCP listing, marketplace card — displays the name in place of the raw wallet
• See docs/internal/SNS_PARTNERSHIP_PROPOSAL.md for the partnership pitch to Bonfida

A2A — Agent-to-Agent Protocol

• A2A client + server, MCP bridge, DID resolution, spending ledger, receipts storage
• Agents transact autonomously via their delegated signer wallets and EIP-7710 permissions

Identity & On-Chain

• ERC-8004 smart contracts (IdentityRegistry, ReputationRegistry, ValidationRegistry) deployable on any EVM chain — plus a program-free Metaplex Core analog on Solana (asset pubkey = agent ID, SPL Memo–anchored reputation + validation attestations)
• Each agent is an ERC-721 token with a stable agentId, owner wallet, delegated signer (EIP-712), and IPFS-pinned manifest
• Signed action log — every speak, remember, skill-done, and validate event is recorded on-chain-optionally or in the database with a cryptographic signature
• EIP-7710 delegated permissions for composable agent-to-agent authorization
• Solana support (SIWS sign-in, Solana wallet linking, Metaplex NFT option)

Embedding & Distribution

• <agent-3d> custom element — drop it anywhere with no framework dependency
• Five widget variants: turntable, animation gallery, talking agent, ERC-8004 passport card, hotspot tour
• Widget Studio + WYSIWYG Embed Editor at /embed-editor — pick an avatar, animation, framing, and background, copy the snippet
• Launchpad at /launchpad — hosted public launch pages at /p/[slug] for tokens, agents, and drops
• Open Graph metadata and oEmbed support for rich social previews when links are shared
• Versioned CDN bundles at /agent-3d/x.y.z/agent-3d.js

Social & Multiplayer 3D

• Coin Communities at /communities + /play — every Solana token gets a live 3D world; pick the same coin and land together, with peer avatars, chat, emotes, voxel building, and a live market-cap screen
• City at /city — free-roam walkable 3D city scene
• Friends, presence & DMs — account-level social graph with live presence ("Online · Mainland"), direct messages, and a per-account realtime delivery hub
• The Club at /club — multiplayer venue with rigged dancers, audio tracks, tips, leaderboard, payouts cron, perf-aware renderer that auto-downgrades on slow frames
• Walk at /walk — authoritative multiplayer walk scene backed by a Colyseus server in multiplayer/ (deployable on Fly.io)
• Pose Studio at /pose-studio, Voice Lab at /voice, Mocap Studio at /mocap-studio — author poses, bind voices, and capture/retarget motion into reusable clips

Backend & Integrations

• OAuth 2.1 server (RFC 6749 + PKCE, RFC 7591 dynamic registration, RFC 7009 revocation, RFC 7662 introspection, RFC 8414 discovery)
• Developer API keys with scope and expiry
• MCP (Model Context Protocol) over HTTP with JSON-RPC 2.0 for tool-calling from external AI systems; A2A bridge exposes paid tools as x402 endpoints
• Avaturn (photo-to-avatar), Character Studio (in-browser builder), Avatar Studio (rebranded marketplace), and Privy (embedded wallet) integrations
• Replicate-backed avatar regeneration provider for photo-to-avatar workflows
• Native selfie reconstruction pipeline (Phase 1) + Livepeer inference network (Phase 4) wired into the agent runtime
• DCA strategy execution and on-chain subscription scheduling via cron jobs
• News CMS at /admin/news with multi-destination syndication (WebSub, Dev.to, Medium, HackerNoon, CMC handoff)
• Solana Mobile (Seeker) MWA wallet wired into the web app + Solana Mobile dApp Store release pipeline
• Hardened API surface: SSRF guard, CSRF gates, header-origin pinning, fail-closed crons
• OpenAPI 3.1 spec generated at /openapi.json

Forge — Text & Image to 3D

Type a sentence, get a 3D model. Forge turns a text prompt, one to four photos, or a rough sketch into a textured, downloadable GLB — in the browser, with a free draft tier and no account required.

Three quality tiers — draft (~12k polygons), standard (~30k, default), high (~200k + PBR textures) — and two generation paths: the platform-keyed image pipeline (FLUX → TRELLIS) that works with no key at all, and bring-your-own-key native geometry via Meshy or Tripo for the cleanest quad topology (your key stays in your browser).

Forge is not a dead end. Every generated model carries straight into the rest of the platform: open it in Scene Studio, auto-rig it into an animatable character, restyle it (voxel / brick / voronoi / low-poly), retexture it from a prompt, embed it with <agent-3d>, give it an LLM brain, or deploy it on-chain. Prompt-to-avatar lives at three.ws/create/prompt — a description becomes a rigged, animatable agent body.

REST API

The same engine is one HTTP call, free and auth-free:

# Submit a text→3D job
curl -X POST https://three.ws/api/forge \
  -H 'content-type: application/json' \
  -d '{"prompt": "a brass steampunk owl, full body", "tier": "standard"}'
# → { "job_id": "…", … }

# Poll until done
curl 'https://three.ws/api/forge?job=<job_id>'
# → { "status": "done", "glb_url": "https://…/model.glb", … }

Image→3D is the same endpoint with image_urls: ["https://…/front.png", …] (1–4 views) instead of a prompt. GET /api/forge?catalog returns the live tier/backend/cost matrix.

From Claude, Cursor, or any MCP client

The 3D Studio MCP server at https://three.ws/api/mcp-3d exposes the full pipeline as 15 tools — text_to_3d, image_to_3d, auto_rig_model, apply_animation, stylize_model, retexture_model, segment_model, and more — so an AI assistant can generate, rig, and animate a model mid-conversation and render it as an inline interactive artifact. See docs/mcp-3d-studio.md.

Pay-per-call for autonomous agents (x402)

POST /api/x402/forge is the monetized twin: agents pay per generation in USDC on Base or Solana — no API key, no account. Draft $0.05, standard $0.15, high $0.50; polling is free; retried payments are idempotent and never double-charge. See docs/api/forge-x402.md.

Learn more

• Tutorial: Turn a Text Prompt into a 3D Model — first model in about a minute
• Tutorial: Turn Photos into a 3D Model — reconstruct a real object from 1–4 photos
• 3D Studio MCP server — generate from inside Claude or Cursor
• Paid generation API (x402) — autonomous agent-to-agent generation

Platform Pages

A map of every user-facing route. Full detail (source files, feature descriptions, hash-routes) is in docs/internal/PAGES.md.

Install in Claude Code

three.ws ships an official Claude Code plugin marketplace — install wallet, payments, pump.fun trading, agent scaffolding, and the 3D Forge as namespaced skills and MCP tools, in one command. Add the marketplace once:

/plugin marketplace add nirholas/three.ws

Then install any of the four plugins:

/plugin install three-ws-core@three-ws       # wallet + x402 — authenticate, fund, send, trade, bazaar, pay, monetize, query onchain
/plugin install three-ws-developer@three-ws  # scaffold agents, configure MCP, runnable code examples
/plugin install three-ws-pump-fun@three-ws   # create coins, swap, creator fees, tokenize agents, live avatar reactions
/plugin install three-ws-3d@three-ws         # text→3D (free), text→avatar, mesh forge, auto-rig + scene/avatar MCP

Run /reload-plugins and the skills appear under each plugin's namespace (e.g. /three-ws-3d:forge-3d). Plugins that expose MCP tools (three-ws-developer, three-ws-3d) wire the published @three-ws/* MCP servers automatically — forge_free is free (no wallet); the paid lanes settle over x402 in USDC. The canonical manifest lives at .claude-plugin/marketplace.json.

Cloud Marketplaces

three.ws is available on major cloud marketplaces and open to infrastructure partnerships.

Ecosystem Directories

three.ws is indexed in chain-ecosystem dApp directories so the community can discover, vet, and rank it.

IBM watsonx & Granite

three.ws is an IBM Business Partner, and the agent runtime runs on IBM Granite foundation models served through IBM watsonx.ai. One IBM Cloud API key + project unlocks the whole suite; every call is real inference (no mock path — endpoints return 503 when unconfigured). Full docs: docs/ibm.md. Live showcase: three.ws/ibm/galaxy.

The public showcase is not the partnership. The demos under /ibm/* are independent tools three.ws built for developers to explore Granite on watsonx.ai and build their own integrations — they are not official IBM partnership deliverables, not IBM products, and not endorsed by IBM. Our formal partnership work with IBM is being built on the IBM platform and is not yet public.

Six showcase surfaces put it on screen, cross-linked by an in-page suite switcher: the Agent Galaxy (semantic 3D star-map), the Granite Oracle (narrated forecast), the Digital Twin (back-test + what-if), the Trust Layer (Guardian + hash-chained audit ledger), Granite Proof (a Guardian-governed forecast notarized on Solana), and Granite Vision. The standalone connector @three-ws/ibm-watsonx-mcp exposes watsonx.ai to any MCP host — it is community-built and not an IBM product; the hosted platform integration is what runs on IBM watsonx.ai.

Pay-per-call Granite over MCP (x402)

The world's first x402-enabled MCP server on IBM Cloud: @three-ws/ibm-x402-mcp turns IBM Granite into a metered utility any AI agent can call. The operator holds the IBM credentials and funds inference; the caller pays a few cents of USDC per call — no IBM Cloud account, no subscription, no API-key signup. Full guide: docs/ibm-x402-mcp.md.

The same five tools ship over two transports: stdio (npx @three-ws/ibm-x402-mcp, for Claude Desktop / Code / Cursor, paid on Solana) and Streamable HTTP (https://three.ws/api/ibm-mcp, for hosted clients and watsonx Orchestrate, paid on Base or Solana). An unpaid tools/call returns a 402 quoting the exact USDC price; x402-capable clients pay and retry automatically, settling on-chain only after the tool succeeds. Independent project integrating IBM Granite via watsonx.ai — not an IBM product.

Screenshots

Viewer	Widget Studio

Agent Discovery	Avatar Creation

Architecture

The platform is organized into four layers. All layers communicate through a single event bus (agent-protocol) rather than direct calls.

┌────────────────────────────────────────────────────────────┐
│  Layer 4: Embed & Distribution                             │
│  <agent-3d> web component · CDN library · 5 widget types   │
│  Widget Studio · oEmbed · Open Graph cards                 │
└────────────────────────────────────────────────────────────┘
                            ↓ protocol events
┌────────────────────────────────────────────────────────────┐
│  Layer 3: Identity & Persistence                           │
│  Agent passport · ERC-8004 (EVM) + Metaplex Core (Solana)  │
│  Signed action log · Memory store · Cross-chain SIWX       │
└────────────────────────────────────────────────────────────┘
                            ↓ protocol events
┌────────────────────────────────────────────────────────────┐
│  Layer 2: Agent Runtime                                    │
│  LLM tool-loop · Built-in tools · Skill registry           │
│  Empathy Layer (emotion blending) · TTS/STT                │
└────────────────────────────────────────────────────────────┘
                            ↓ protocol events
┌────────────────────────────────────────────────────────────┐
│  Layer 1: Viewer                                           │
│  three.js r184 · glTF / GLB · Draco / KTX2 / Meshopt       │
│  Animations · Morph targets · HDR · Validation             │
└────────────────────────────────────────────────────────────┘

The event bus decouples every component. The avatar emotion system reacts to speak events without knowing the runtime exists. The identity module records actions without knowing the UI exists. This makes the system testable, embeddable in isolation, and composable across pages.

The backend is stateless serverless functions. All persistent state lives in Postgres (Neon), object storage (Cloudflare R2), or on-chain. Cron jobs handle scheduled blockchain operations (ERC-8004 crawl, DCA execution, subscription execution).

Design Docs & Specs

The architecture above is the bird's-eye view; each load-bearing surface has a dedicated spec that defines its wire format, invariants, and extension points. New contributors should skim the spec for any subsystem they're about to change.

Longer-form architecture and how-to documentation lives under docs/: docs/architecture.md, docs/agent-system.md, docs/3d-asset-pipeline.md, docs/animations.md, docs/web-component.md, docs/api-reference.md, docs/mcp.md, docs/permissions.md, docs/security.md, docs/smart-contracts.md, and more.

3D asset pipeline — FBX, GLB, JSON

Every avatar the site renders is a GLB (binary glTF 2.0 — the body, rig, and textures in one file); every shared gesture and dance is a format-light clip JSON (a serialized THREE.AnimationClip — motion only, retargeted onto any rig at runtime); and both originate as FBX source from Mixamo or a DCC tool. Two conversions come off one FBX — npm run convert:fbx for a full character GLB, npm run build:animations for a reusable library clip — then npm run optimize:glb makes it web-ready (~90% smaller). The full explainer, format specs, runtime modules, and the generate→rig→animate→export capability chain are in docs/3d-asset-pipeline.md.

Tech Stack

Frontend

• Main UI: The core application, including the 3D viewer, agent creation, and marketplace, is built with vanilla JavaScript modules and Vite.
• Chat: The chat interface is a standalone Svelte application located in the chat/ directory.
• 3D Rendering: three.js (r184) is used for WebGL 2.0 rendering.

Backend (Vercel Serverless)

• Runtime: Node.js
• Database: Neon Postgres (serverless)
• Storage: Cloudflare R2 for model and avatar storage.
• Rate Limiting: Upstash Redis.
• LLM: The agent's brain is powered by the Anthropic (Claude) SDK.

Smart Contracts

• Language: Solidity 0.8+
• Framework: Foundry for compiling, testing, and deploying the ERC-8004 contracts.
• Standards: ERC-721, EIP-712, EIP-7710.

Browser Support

The viewer targets every browser that ships WebGL 2.0 on a desktop or modern mobile device. Concrete support matrix:

Capabilities and graceful degradation

• WebGL 2.0 is required; the viewer refuses to boot without it and shows a fallback message.
• WebAssembly is required for the Draco / KTX2 / Meshopt decoders that ship under public/three/draco/, public/three/basis/, and node_modules/three/examples/jsm/libs/.
• getUserMedia (microphone) requires HTTPS — see Common gotchas. Without it the agent falls back to text input.
• speechSynthesis is detected at runtime; agents fall back to silent text replies when TTS is unavailable.
• WebGPU is not required and is not used yet — Phase 4 reserves it for client-side inference experiments.

Getting Started

Prerequisites

• Node.js 24+ (the project pins "engines.node": "24.x" in package.json; earlier majors are not tested)
• npm 10+
• A Neon Postgres database
• A Cloudflare R2 bucket
• An Anthropic API key

Installation and Setup

1. Clone the repository:
   bash

   git clone https://github.com/nirholas/three.ws.git
   cd three.ws
   

2. Install dependencies:
   bash

   npm install
   

3. Set up environment variables: Copy the .env.example file to .env.local and fill in the required values. See the Environment Variables section for more details.
   bash

   cp .env.example .env.local
   

4. Initialize the database: The schema is idempotent. Run it against your Postgres instance to create all tables:
   bash

   psql $DATABASE_URL < api/_lib/schema.sql
   

5. Run the development server:
   bash

   npm run dev
   

   The application will be available at http://localhost:3000.

Examples

Copy-paste ready snippets for the most common use cases. Swap in your own GLB URL and go.

1. Minimal viewer (no AI)

The simplest possible setup — one script tag, one element, zero build step.

<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>3D Viewer</title>
		<style>
			body {
				margin: 0;
				background: #0a0a0a;
				display: flex;
				align-items: center;
				justify-content: center;
				height: 100vh;
			}
			agent-3d {
				width: 400px;
				height: 560px;
				display: block;
			}
		</style>
	</head>
	<body>
		<script type="module" src="https://three.ws/agent-3d/1.5.2/agent-3d.js"></script>
		<agent-3d body="https://cdn.three.ws/models/sample-avatar.glb"></agent-3d>
	</body>
</html>

Drag-to-rotate, scroll-to-zoom, full PBR rendering — no API key, no account required. Swap body= for any publicly accessible .glb URL.

2. Talking agent with inline instructions

Add brain= and instructions= to turn the viewer into a conversational agent.

<script type="module" src="https://three.ws/agent-3d/1.5.2/agent-3d.js"></script>

<agent-3d
	body="https://cdn.three.ws/models/sample-avatar.glb"
	brain="claude-sonnet-4-6"
	name="Aria"
	instructions="You are Aria, a friendly AI guide. Be warm, concise, and occasionally playful.
                When someone greets you, wave at them. Keep replies to 2–3 sentences."
	mode="inline"
	width="400px"
	height="560px"
></agent-3d>

The chat input and mic button appear automatically when brain is set. No UI to build.

3. Floating bubble (support widget style)

Pin the agent to a corner of the page so it persists as users scroll.

<script type="module" src="https://three.ws/agent-3d/1.5.2/agent-3d.js"></script>

<agent-3d
	body="https://cdn.three.ws/models/sample-avatar.glb"
	brain="claude-sonnet-4-6"
	instructions="You are a helpful product assistant. Answer questions about our features."
	mode="floating"
	position="bottom-right"
	width="320px"
	height="420px"
></agent-3d>

position accepts bottom-right, bottom-left, top-right, or top-left.

4. Load a registered agent by ID

If you've registered an agent on the platform, load it entirely from its manifest — no inline attributes needed.

<!-- By platform agent ID -->
<agent-3d agent-id="a_abc123def456"></agent-3d>

<!-- By on-chain ERC-8004 ID -->
<agent-3d agent-id="42" chain-id="8453"></agent-3d>

The element fetches the manifest (model URL, instructions, skills, memory config) automatically.

5. Custom chat UI with JavaScript API

Hide the built-in chrome and wire in your own input using the element's JS API.

<script type="module" src="https://three.ws/agent-3d/1.5.2/agent-3d.js"></script>

<agent-3d
	id="agent"
	body="./avatar.glb"
	brain="claude-sonnet-4-6"
	kiosk
	style="width:400px;height:560px;display:block"
></agent-3d>

<input id="msg" type="text" placeholder="Ask something…" />
<button onclick="send()">Send</button>

<script>
	const agent = document.getElementById('agent');
	const input = document.getElementById('msg');

	async function send() {
		const text = input.value.trim();
		if (!text) return;
		input.value = '';
		await agent.say(text);
	}

	input.addEventListener('keydown', (e) => {
		if (e.key === 'Enter') send();
	});

	// Auto-greet on load
	agent.addEventListener('agent:ready', () => {
		setTimeout(() => agent.say('Hello! How can I help you today?'), 1200);
	});

	// Listen to replies
	agent.addEventListener('brain:message', (e) => {
		if (e.detail.role === 'assistant') console.log('Agent:', e.detail.content);
	});
</script>

Full JS API:

Key events: agent:ready, brain:message, brain:thinking, skill:tool-called, voice:transcript

6. iframe widget (works in Notion, Substack, Webflow)

Use a widget URL directly — no script tag needed.

<iframe
	src="https://three.ws/a/8453/42/embed"
	width="400"
	height="560"
	frameborder="0"
	allow="microphone"
	style="border-radius:16px;"
></iframe>

Generate the src URL from Widget Studio — pick an avatar, choose a widget type, and copy the snippet.

7. Agent manifest JSON

For anything beyond a quick one-liner, define the agent in a manifest file and reference it with manifest=.

agent.json:

{
	"spec": "agent-manifest/0.2",
	"name": "Aria",
	"description": "A friendly AI guide",
	"body": {
		"uri": "./avatar.glb",
		"format": "gltf-binary"
	},
	"brain": {
		"provider": "anthropic",
		"model": "claude-sonnet-4-6",
		"instructions": "You are Aria, a warm and curious AI guide. Wave when greeted.",
		"temperature": 0.8,
		"maxTokens": 1024
	},
	"voice": {
		"tts": { "provider": "browser", "rate": 1.05 },
		"stt": { "provider": "browser", "language": "en-US" }
	},
	"memory": { "mode": "local" },
	"skills": [{ "uri": "https://cdn.three.ws/skills/wave/" }]
}

<agent-3d manifest="./agent.json" width="400px" height="560px"></agent-3d>

8. Dead-simple copy-paste widget

For the absolute simplest way to embed an agent, use this snippet. It requires no build tools or imports. Just copy and paste it into your HTML.

<div
	class="threews-widget"
	data-agent-id="YOUR_AGENT_ID"
	data-background="transparent"
	data-nameplate="true"
	style="width: 400px; height: 500px;"
></div>
<script src="https://three.ws/dist/widget.js" defer></script>

You can find your agent ID in the agent's settings page. This method is great for quick integrations on platforms like WordPress, Ghost, or any static HTML site. Customize the appearance with data-background and data-nameplate.

Tutorials

Step-by-step guides in docs/tutorials/:

Common gotchas

CORS — if your GLB is hosted on a different domain, the server must send Access-Control-Allow-Origin: *. Without it the fetch is blocked and the canvas stays blank. Uploading via the platform's storage sets this automatically.

File size — models over ~50 MB load slowly. Compress with Draco:

npx gltf-transform draco input.glb output.glb

Voice on HTTPS — getUserMedia (microphone) requires HTTPS. Localhost is exempt; any remote deployment needs TLS. Vercel and Netlify both provide it automatically.

CSP — if your page has a strict Content Security Policy, add:

script-src 'self' https://three.ws;

For sandboxed iframes use the widget embed path instead — it runs in its own browsing context.

Project Structure

• src/: The core frontend JavaScript for the main application, including the 3D viewer, agent protocol, custom element, and feature modules (club-*.js, walk*.js, pose-*.js, voice/, selfie-*.js). Social/gameplay surfaces live in game/ (Coin Communities: coincommunities*, spin-wheel-ui, cosmetics-visual, avatar-rig), city/ (the /city world), social/ (sentiment, X-post impact), community/ (coin lobby/town), plus friends.js, communities.js, marketplace*.js, and token-pay.js.
• api/: Vercel serverless functions that form the backend API. Subdirectories include x402/, a2a/, club/, pump/, persona/, news/, admin/, agents/, auth/, oauth/, cron/, plus the social/game surfaces play/, token/, three-token/, friends/, social/, community/, marketplace/, and mocap/.
• public/: Static assets and various sub-applications (club/, seeker/, news/, persona/, vanity-wallet.html, pumpfun.html).
• chat/: A standalone Svelte application for the chat interface.
• character-studio/: A sub-project for in-browser character creation; also serves the rebranded Avatar Studio marketplace.
• rider/: A-Frame WebVR music visualization experiment.
• contracts/: Solidity smart contracts for on-chain identity (ERC-8004) and the multichain payment factory.
• multiplayer/: Colyseus WebSocket server for /walk and /play (WalkRoom); deployable on Fly.io. Holds the authoritative world logic and single sources of truth — items.js, playerStore.js, game-token.js, play-pass.js, holder-pass.js, and the per-account social-hub.js.
• sdk/: @three-ws/sdk (the AgentKit SDK; the legacy avatar helpers live in sdk/agent-sdk/).
• agent-payments-sdk/: EVM agent payments SDK (Base / BSC / other EVM chains).
• solana-agent-sdk/: SDK for Solana blockchain interactions (Metaplex Core mints, SIWS, attestations).
• pump-fun-skills/: Skills related to the pump.fun integration.
• scripts/: Node.js scripts for development, build, deployment, and pump.fun launch automation.
• workers/: Code for background workers — includes the Cloudflare Worker mirror of the pump.fun MCP read API in workers/pump-fun-mcp/.
• docs/: Public-facing developer docs.
• docs/internal/: Working docs (PLAN, STATUS, TODO, NEXT, PROGRESS, RELEASE_CHECKLIST, club venue notes) — not part of the published docs surface.
• tests/: Vitest unit tests (tests/api/, tests/src/, tests/workers/) and Playwright end-to-end smokes (tests/e2e/).

The Agent System

Event Bus (Agent Protocol)

src/agent-protocol.js implements a lightweight EventTarget subclass that is the nervous system of the platform. Every component — avatar, runtime, identity, UI — communicates exclusively through this bus. There are no direct method calls between layers.

The bus maintains a 200-action ring buffer for debugging and replay. Embed variants expose a filtered subset of events through postMessage to the host page.

Core event types:

Identity-relevant events (speak, remember, sign, skill-done, validate, load-end) are fire-and-forwarded to POST /api/agent-actions for durable logging.

LLM Runtime

src/runtime/index.js implements the Runtime class, which drives the agent's LLM-powered brain.

Tool-loop flow:

1. User message (text or STT transcript) arrives
2. System prompt is assembled: manifest instructions + recalled memory + skill descriptions
3. Claude is called with the conversation history and all available tools
4. Tool calls are dispatched in order — each built-in tool or skill handler receives a rich context object:
   js

   {
   	viewer,
   		memory,
   		llm,
   		speak,
   		listen,
   		fetch,
   		loadGLB,
   		loadClip,
   		loadJSON,
   		call,
   		stage,
   		agentId;
   }
   

5. Tool results are appended to conversation history as tool_result messages
6. Steps 3–5 repeat until Claude returns with no tool calls, or the iteration limit (8) is hit
7. Final text response is optionally spoken via TTS

Providers (src/runtime/providers.js):

• AnthropicProvider — connects to the Anthropic API, supports streaming
• NullProvider — no-op for testing and offline mode

Built-in tools (src/runtime/tools.js):

Skills can define additional tools that override or augment the built-ins. The skill registry is loaded from the agent manifest before each conversation turn.

Empathy Layer

src/agent-avatar.js implements the Empathy Layer — a continuous weighted emotion blend that drives the avatar's facial morph targets and head orientation in real time.

Emotions are not a finite-state machine. Each emotion is a float (0..1) that decays linearly per frame at a different rate. Protocol events inject spikes:

Decay half-lives (approximate):

• Patience: ~20s — persists during long operations
• Empathy: ~13s — lingers after emotional events
• Concern: ~12s — sustained worry
• Curiosity: ~8s — alert, fades moderately
• Celebration: ~6s — brief, upbeat

The blended emotion mix drives morph target values each frame. For example:

• Celebration → mouthSmile 0.85, mouthOpen 0.2
• Concern → mouthFrown 0.55, browInnerUp 0.6
• Empathy → eyeSquint 0.4, browInnerUp 0.5

Head tilt and lean are also driven by the blend — curiosity tilts the head, patience leans slightly back.

This architecture means the avatar feels responsive and emotionally coherent without any hand-authored animation triggers.

Skills

Skills are self-contained capability bundles that extend the agent's tool set. Each skill lives in its own directory:

skills/wave/
├── SKILL.md        # Human-readable description and usage instructions
├── tools.json      # Tool definitions (name, description, input JSON schema)
└── handlers.js     # Async handler functions (default export)

tools.json example:

[
	{
		"name": "wave",
		"description": "Plays a waving gesture on the avatar for the specified duration.",
		"inputSchema": {
			"type": "object",
			"properties": {
				"duration_ms": { "type": "integer", "minimum": 500, "maximum": 5000 }
			}
		}
	}
]

handlers.js example:

export default {
	async wave(args, ctx) {
		const { viewer, speak } = ctx;
		await viewer.playClipByName('wave');
		return { ok: true, output: 'Waved!' };
	},
};

Skills are loaded from the agent manifest at runtime. The SkillRegistry supports three trust modes:

• any — install skills from any source (development only)
• owned-only — only skills the agent owner has registered
• whitelist — only approved skill URIs

Skills are distributed over IPFS, Arweave, or HTTP. The public skills registry is at /public/skills-index.json.

Memory

src/memory/index.js implements a file-based memory system (mirroring this project's own Claude memory system). Memories are Markdown files with YAML frontmatter, organized by type:

---
type: user
key: user_role
name: User's Role
created: 2024-01-15T10:30:00Z
salience: 0.95
---

User is a game developer interested in character animation.

A MEMORY.md index file is auto-maintained. At the start of each conversation turn, the memory store is scanned and high-salience entries are injected into the system prompt.

Storage modes:

• local — stored in the browser's local storage (default for development)
• remote — persisted per-agent via /api/agent-memory (owner-only)
• ipfs — pinned to IPFS via Pinata or Web3.Storage
• encrypted-ipfs — encrypted before pinning (user holds the key)
• none — stateless, no memory between sessions

Memory types (user, feedback, project, reference) follow the same taxonomy used by this codebase's own Claude guidelines.

Plugging a custom memory backend

You don't fork Memory to add a vector store or episodic log — register a backend and select it by name. Built-in modes are unchanged; your mode is just another option.

import { Memory } from 'https://three.ws/agent-3d/latest/agent-3d.js';

Memory.registerBackend('vector', {
	async load({ namespace }) {
		const rows = await myVectorStore.fetchAll(namespace);
		return { files: Object.fromEntries(rows.map((r) => [r.filename, r.markdown])) };
	},
	async persist(memory) {          // after every write()/note()
		await myVectorStore.replace(memory.namespace, [...memory.files]);
		await myEpisodicLog.replace(memory.namespace, memory.timeline);
	},
	async recall(query, memory, { limit = 5 } = {}) {  // real semantic search
		const m = await myVectorStore.search(memory.namespace, query, limit);
		return m.map((x) => ({ file: x.filename, meta: x.meta, body: x.body, score: x.score }));
	},
});

<agent-3d src="agent://…" memory="vector"></agent-3d>

Only load is required; persist makes it durable, recall makes search semantic (it falls back to substring matching if it throws). To swap only the ranker while keeping built-in storage, point manifest.json → memory.retriever at a skill instead. Full reference: specs/MEMORY_SPEC.md → Custom backends.

Memory snapshot contract

memory.snapshot() returns a synchronous, JSON-safe memory/0.1 object so embedded widgets can serialize/deserialize state across page reloads; Memory.fromSnapshot(snap, { mode, namespace }) rehydrates it (rebuilding the index if absent).

sessionStorage.setItem('agent-mem', JSON.stringify(agent.memory.snapshot()));
// …after reload:
const restored = Memory.fromSnapshot(JSON.parse(sessionStorage.getItem('agent-mem')));

Web Component & Embedding

The <agent-3d> custom element (src/element.js) is the primary distribution mechanism. It lazy-boots on intersection (IntersectionObserver), so off-screen agents don't load until visible.

Basic usage:

<script src="https://three.ws/agent-3d/latest/agent-3d.js"></script>

<agent-3d
	body="https://example.com/my-avatar.glb"
	brain="https://example.com/manifest.json"
	mode="chat"
></agent-3d>

Key attributes:

The element fires a postMessage API for host-page communication (documented in specs/EMBED_HOST_PROTOCOL.md). Hosts can send events to the agent and receive speak, think, and skill-done events back.

Versioned CDN bundles are published at /agent-3d/x.y.z/agent-3d.js. Use latest for auto-updates or pin to a version for stability:

<script src="https://three.ws/agent-3d/1.5.2/agent-3d.js"></script>

Iframe quickstart with the embed SDK

For when you want a chromeless iframe that you control from the parent page (rather than the <agent-3d> web component), drop in the embed SDK:

<iframe
	id="agent"
	src="https://three.ws/agent/abc123/embed"
	style="width:480px;height:600px;border:0"
></iframe>
<script src="https://three.ws/embed-sdk.js"></script>
<script>
	const bridge = Agent3D.connect(document.getElementById('agent'), {
		agentId: 'abc123',
		onReady: ({ name }) => console.log('agent ready:', name),
		onAction: (action) => console.log('agent action:', action),
		onError: (err) => console.error('embed error:', err),
	});

	// Drive the agent
	bridge.send({ type: 'speak', payload: { text: 'Hello!' } });
	bridge.ping().then((rttMs) => console.log('rtt', rttMs, 'ms'));
</script>

Origin contract. The SDK derives the iframe's origin from iframe.src and refuses to start if it can't (no wildcard targets, ever). The iframe locks onto the parent's origin from the first authenticated message it sees and ignores any later messages from a different origin. See specs/EMBED_SPEC.md §"Bridge origin model" for the full rules.

Typed host bridge (npm-friendly)

For TypeScript/bundler workflows, import EmbedHostBridge directly:

import { EmbedHostBridge } from 'three-ws/embed-host-bridge';

const iframe = document.getElementById('agent');
const bridge = new EmbedHostBridge({
	iframe,
	agentId: 'abc123',
	allowedOrigin: new URL(iframe.src).origin, // required, never '*'
});

await bridge.ready;
await bridge.speak('Hello world');
const off = bridge.on('action', (a) => console.log(a));

// Clean up when done.
off();
bridge.destroy();

Both surfaces speak the same v1 wire protocol — pick the one that fits your stack.

Widget System

The Widget Studio (/studio) lets anyone build a shareable, embeddable 3D experience without writing code. Pick an avatar, pick a widget type, configure it, and get an iframe snippet.

Five widget types:

Each widget has:

• A public URL at /w/<id> with server-rendered Open Graph metadata for rich link previews
• An oEmbed endpoint at /api/widgets/oembed for WordPress, Ghost, Notion embedding
• An iframe embed URL at /api/widgets/<id>/view
• A view counter tracked at /api/widgets/<id>/stats
• A duplicate API at /api/widgets/<id>/duplicate

Widgets are stored as JSON config in Postgres, pointing at an avatar in R2.

Embed Editor

The Embed Editor at /embed-editor is a WYSIWYG configurator for the <agent-3d> element. Pick an avatar from a modal grid with lazy-loaded 3D thumbnails, choose an animation from the dock, frame the camera with face-camera mode, set a background (transparent, glow, solid), and copy a ready-to-paste snippet.

The editor produces video-ready output for marketing assets and a copy-paste snippet for production use. Built as a single Vite-compiled bundle, no separate framework runtime.

Pose Studio

/pose-studio is a 3D pose-reference tool inspired by setpose.com. It builds a Three.js scene with an articulated mannequin, orbit camera, ground + grid, and a control panel that lets you pick presets, drag joints to pose them, fine-tune with sliders, swap body type, add floor props, change lighting and FOV, and export a PNG screenshot.

Poses author cleanly into the avatar runtime via the play_clip tool — the agent can adopt any saved pose on demand. Exported PNGs are useful as marketing renders or as reference frames for downstream image/video pipelines.

Launchpad

The Launchpad at /launchpad is a hosted-page builder for token launches, agent debuts, and drop campaigns. Each published page lives at a public URL like /p/<slug> with full Open Graph metadata for sharing.

Launchpad templates are JSON-configured and can embed any combination of <agent-3d> widget, x402 paid endpoint, or pump.fun launch button. Pages are stored in Postgres and served as static HTML with hydration for interactive elements.

The Club

/club is a multiplayer 3D venue — a pole-club scene with rigged dancers, audio tracks, spotlights, mirror-ball cube cam, and on-chain tips.

Stack:

• Venue GLB + HDRI lit by four spotlights; bloom + chromatic aberration on the high tier
• Audio tracks streamed from R2 with synchronized playback across clients
• Camera state machine — DJ booth, overhead, dance-floor, follow-cam — sequenced per track
• Performance profile detector picks high / medium / low from navigator.deviceMemory, hardwareConcurrency, pointer: coarse, and the UA string
• Frame-budget watchdog auto-downgrades the profile if sustained slow frames are detected

Economics:

• Tips API at /api/club/tips — viewers tip dancers in USDC via x402 (CDP-settled, Permit2-gasless sibling available)
• Leaderboard at /api/club/leaderboard with windowed top-tipper rankings
• Hourly payouts cron sweeps the tips ledger into the dancers' treasury wallets

Detail: performance notes, venue plan, and release checklist live in docs/internal/ alongside other internal working docs.

Walk & Multiplayer

/walk is an authoritative multiplayer walk scene. Players join a shared 3D space, see each other's avatars in real time, and emit gestures over a WebSocket connection.

Vercel doesn't host long-lived WebSockets, so the multiplayer server lives in its own workspace at multiplayer/ — a Colyseus server packaged with a Fly.io fly.toml and Dockerfile. The Vite client at /walk autodiscovers the server (ws://localhost:2567 in dev, your deployed host in prod).

# Run both servers together
npm run dev:walk-all     # Vite (:3000) + Colyseus (:2567)

WalkRoom (multiplayer/src/rooms/WalkRoom.js) is the authoritative state container — position, rotation, gesture, presence. Origin allow-listing is enforced at the WS upgrade (ALLOWED_ORIGINS env, with *.vercel.app and *.three.ws always permitted for preview deploys). The same Colyseus server also runs a per-account social hub (multiplayer/src/social-hub.js) for presence and live event delivery.

Coin Communities

Every Solana token gets a live 3D world. Coin Communities turns a mint address into a shared multiplayer space: pick the same coin as someone else and you land together, walk around, emote, voice-chat, build with voxels, and watch the live market-cap chart on an in-world screen.

How it works

• Real pump.fun data, no mocks. The lobby and coin profiles pull live trending coins, search results, bonding-curve pricing, and recent trades from the pump.fun feed.
• Bring any avatar. Use a default, an uploaded GLB/VRM, or paste a model URL. The same rig (src/game/avatar-rig.js) drives /play, /walk, and /city with no drift.
• Realtime presence + chat. Each coin is its own room. Town chat is backed by the CoinCommunities service — reads work out of the box; posting unlocks behind X-OAuth sign-in + a linked wallet. If CC_API_KEY is unset, chat renders its designed locked state.
• Voxel building & spatial voice. Collaborative block placement (server-capped) and optional geofenced WebRTC voice (src/game/voice-chat.js).
• Holder-gated rooms. A coin can require token holders (tier holders vs general); gating is enforced server-side via a sealed play-pass.

Key files: src/communities.js (lobby), src/game/coincommunities.js + coincommunities-ui.js (3D scene + HUD), src/game/community-net.js (socket bridge), api/community/* (worlds, messages, ws-ticket, capabilities, me), api/_lib/coin-communities.js (CoinCommunities SDK client).

City

/city is a free-roam 3D city scene — a walkable urban world with a follow camera, map, and player controller, built on the same Three.js stack as the rest of the platform.

Key files: src/city/city-world.js (scene + render loop), city-map.js (layout), city-player.js (movement/controller), city-camera.js (follow cam), city.css.

Friends, Presence & Social

A full account-level social layer spans the multiplayer surfaces. Friendships are durable; presence is volatile — and both are keyed to the account, not the ephemeral session, so they survive reconnects and realm changes.

Friends are stored in Postgres (friendships, direct_messages, user_mutes — see migration api/_lib/migrations/2026-06-01-friends.sql); presence lives in Upstash Redis and self-heals if a process dies. Muting is send-side only — a muted account is never told it was muted. The friends panel UI (src/friends.js, src/game/friends-panel.js) surfaces requests, DM threads, and "Online" / "Offline" status inside /play. The src/social/ module adds sentiment + X-post-impact scoring used by community surfaces.

Voice Lab & Mocap Studio

Two creator tools sit alongside Pose Studio:

• Voice Lab (/voice, src/voice-lab.js) — audition and bind voices to an agent, building on the Voice & Persona Hub.
• Mocap Studio (/mocap-studio, src/mocap-studio.js, api/mocap/) — capture and retarget motion onto a rigged avatar, exporting reusable animation clips.

x402 Payments

three.ws is a first-class x402 host. Agents can both pay for and expose paid endpoints. Settlement runs on Base, BSC, and Solana; the bazaar at /x402 is the discovery surface.

Payment rails

Every CDP-settled endpoint ships a Permit2 sibling that accepts an EIP-2612 permit instead of an upfront approval — the buyer signs once, and the relayer pays gas. Wire-level checks live in tests/e2e/ and exercise the buyer/seller flow end-to-end.

Paid endpoints

Bazaar, SKUs, and subscriptions

How to expose a paid endpoint

import { paidEndpoint } from './_lib/x402-paid-endpoint.js';

export default paidEndpoint({
	price: '0.10', // USDC
	chain: 'base', // base | bsc | solana
	network: 'mainnet',
	resource: 'https://three.ws/api/your-endpoint',
	description: 'What the buyer is paying for',
	handler: async (req, res, { payer }) => {
		// payer is verified — settle the request
		res.json({ ok: true, payer });
	},
});

The helper handles the 402 challenge, Permit2 sibling, receipt write-back, idempotency-token enforcement, and CSRF/SSRF guards. See api/_lib/x402-paid-endpoint.js.

Wire checks

• Wire-level CORS, CDP, and Permit2 sibling checks: tests/e2e/
• Offer receipts schema + buyer fetch: api/_lib/x402-buyer-fetch.js
• Error envelope: full 402 body returned in the PAYMENT-REQUIRED header

A2A — Agent-to-Agent Protocol

Agents transact with each other directly through an A2A bridge that sits on top of the MCP server and x402 payments.

How it works

When agent A wants to call a paid tool from agent B:

1. Discover — A resolves B's DID via POST /api/x402/did, receiving B's MCP endpoint URL and payment wallet address.
2. Call — A sends a tools/call JSON-RPC request to B's MCP endpoint.
3. Pay — B's server returns 402 Payment Required with a USDC price. A's SDK settles the x402 payment on-chain (Base or Solana) and retries with the payment proof in the X-PAYMENT header.
4. Execute — B verifies the payment, runs the tool, and writes a signed receipt to api/a2a/receipts.
5. Ledger — Both sides accumulate a row in api/a2a/spending — A for outbound spend, B for inbound revenue.

Agent wallets sign with EIP-7710 delegated permissions — the delegated signer acts on behalf of the agent's root key without ever exposing it.

SIWX (Sign-In with X-chain) brokers cross-chain identity for paid sessions: an agent on Base proves ownership of a Solana wallet (or vice versa) to unlock chain-specific paid endpoints.

Talk Mode & Lip-Sync

The talk interaction mode wires together the LLM runtime, ElevenLabs TTS, and an audio-driven ARKit-52 lip-sync driver that maps live audio amplitude + formant analysis onto the 52 standard ARKit blendshapes.

When the agent speaks, the driver runs at ~60fps and drives mouthClose, jawOpen, mouthSmileLeft/Right, and the rest of the ARKit-52 set — the Empathy Layer's emotional morphs continue to blend on top, so the avatar simultaneously emotes and articulates. Unit tests for the ARKit-52 mapping live in tests/src/arkit-morphs.test.js.

Activating talk mode

Set mode="talk" on the <agent-3d> element and supply an ElevenLabs voice ID in the agent manifest:

{
  "voice": {
    "tts": { "provider": "elevenlabs", "voiceId": "YOUR_VOICE_ID" },
    "stt": { "provider": "browser", "language": "en-US" }
  }
}

Pipeline (step by step)

1. User speaks → getUserMedia captures audio → Web Speech API produces a text transcript.
2. Transcript enters the LLM tool-loop; the final reply text is sent to ElevenLabs TTS.
3. The returned AudioBuffer is piped through a Web Audio API AnalyserNode.
4. The lip-sync driver (src/voice/lipsync-driver.js) samples the analyser every animation frame, extracts amplitude and spectral centroid, and maps them to ARKit-52 blendshape weights.
5. Weights are applied directly to the loaded GLB's morph targets via src/voice/avatar-morph-target.js — no scene re-render required.
6. The Empathy Layer injects its emotional morph weights in the same frame, so articulation and emotion blend simultaneously without fighting each other.

The driver is source-agnostic: it accepts any AudioBuffer, so it works identically with ElevenLabs, browser TTS, or a pre-recorded clip. The canonical ARKit-52 blendshape table lives in src/voice/arkit-blendshapes.js; per-rig binding (mapping standard names to the specific morph targets in a loaded GLB) is handled by src/voice/avatar-morph-target.js.

Solana Mobile (Seeker)

three.ws ships with Mobile Wallet Adapter (MWA) wired into the web app and a release pipeline for the Solana Mobile dApp Store.

Wallet detection priority

On Seeker / Saga hardware the app prefers seed-vault-backed signing — private keys never leave the secure element. On standard Android or desktop, the app falls back through WalletConnect and then to browser-extension wallets automatically, with no code change required.

What MWA unlocks on Seeker hardware

• x402 USDC payments signed from the seed vault without any browser extension
• Metaplex Core agent mints (Solana on-chain registration) without leaving the app
• SPL Memo attestations (reputation and validation) with hardware-secured signatures
• SIWS (Sign-In with Solana) sessions authenticated at the chip level, not the software layer

Release pipeline

• dApp Store listing assets, icons, and staging copy live under public/seeker/
• Release pipeline scripts handle build → sign → APK submission for dApp Store updates
• The listing targets Seeker-first and is compatible with Saga Gen 1 and Gen 2

Selfie Reconstruction Pipeline (Phase 1)

Anyone takes 3 selfies (left, center, right) and receives a rigged, animatable 3D avatar in under a minute. The pipeline ships native — no third-party black box.

Reconstruction inference runs against the same Anthropic-token-billed Vercel function pool as the agent runtime, with optional offload to the Livepeer Inference Network (see below) for GPU-heavy steps.

Livepeer Inference Network (Phase 4)

three.ws is wiring the Livepeer decentralized GPU network as an alternative inference backend for avatar reconstruction and agent conversations.

• Open protocol: model weights, GPU runtime, signed responses
• Onchain settlement: pay-per-token with cryptographic receipts, mediated by the same x402 rails described above
• Node operator client (Docker + GPU drivers) with onchain registration
• Federation with existing decentralized compute networks where appropriate

The Livepeer dependency landed early so the Phase 1 selfie pipeline can switch its heaviest step (multi-view face fitting) onto external GPU nodes without touching the rest of the system. The goal: ≥50% of production agent traffic served by independent node operators with latency parity to centralized inference.

Voice & Persona Hub (Phase 2)

The avatar isn't just you — the agent acts like you. The Voice & Persona Hub captures the inputs that turn a body into a personality.

| Surface | Path