three.ws

# three.ws   

[**Website**](https://three.ws) · [**X / Twitter**](https://x.com/trythreews) · [**GitHub**](https://github.com/nirholas/three.ws) · [**$THREE on pump.fun**](https://pump.fun/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump)

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**](https://three.ws/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](https://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 ↓](#forge--text--image-to-3d)

### $THREE

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

| | |
| --- | --- |
| **Token** | `$THREE` |
| **Contract Address (CA)** | `FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump` |
| **Network** | Solana |
| **Trade** | [pump.fun](https://pump.fun/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump) |

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

---

## Table of Contents

- [What is three.ws?](#what-is-threews)
- [Vision](#vision)
- [Roadmap](#roadmap)
- [Key Features](#key-features)
- [Forge — Text & Image to 3D](#forge--text--image-to-3d)
- [Platform Pages](#platform-pages)
- [Cloud Marketplaces](#cloud-marketplaces)
- [Ecosystem Directories](#ecosystem-directories)
- [IBM watsonx & Granite](#ibm-watsonx--granite)
- [Screenshots](#screenshots)
- [Architecture](#architecture)
    - [Design Docs & Specs](#design-docs--specs)
- [Tech Stack](#tech-stack)
    - [Browser Support](#browser-support)
- [Getting Started](#getting-started)
- [Examples](#examples)
- [Tutorials](#tutorials)
- [Project Structure](#project-structure)
- [The Agent System](#the-agent-system)
    - [Event Bus (Agent Protocol)](#event-bus-agent-protocol)
    - [LLM Runtime](#llm-runtime)
    - [Empathy Layer](#empathy-layer)
    - [Skills](#skills)
    - [Memory](#memory)
- [Web Component & Embedding](#web-component--embedding)
- [Widget System](#widget-system)
- [Embed Editor](#embed-editor)
- [Pose Studio](#pose-studio)
- [Launchpad](#launchpad)
- [The Club](#the-club)
- [Walk & Multiplayer](#walk--multiplayer)
- [Coin Communities](#coin-communities)
- [City](#city)
- [Friends, Presence & Social](#friends-presence--social)
- [In-Game Economy](#in-game-economy)
- [Voice Lab & Mocap Studio](#voice-lab--mocap-studio)
- [x402 Payments](#x402-payments)
- [A2A — Agent-to-Agent Protocol](#a2a--agent-to-agent-protocol)
- [Talk Mode & Lip-Sync](#talk-mode--lip-sync)
- [Solana Mobile (Seeker)](#solana-mobile-seeker)
- [Selfie Reconstruction Pipeline (Phase 1)](#selfie-reconstruction-pipeline-phase-1)
- [Livepeer Inference Network (Phase 4)](#livepeer-inference-network-phase-4)
- [Voice & Persona Hub (Phase 2)](#voice--persona-hub-phase-2)
- [WASM Vanity Grinder](#wasm-vanity-grinder)
- [News CMS & Syndication](#news-cms--syndication)
- [Security Hardening](#security-hardening)
- [Developer SDKs](#developer-sdks)
- [Claude Code Integration](#claude-code-integration)
- [Demos Hub](#demos-hub)
- [Skill Library](#skill-library)
- [Animation System](#animation-system)
- [Avatar Accessories & Coin Launchpad](#avatar-accessories--coin-launchpad)
- [Brain Proxy & LLM Routing](#brain-proxy--llm-routing)
- [API Reference](#api-reference)
- [Authentication & OAuth 2.1](#authentication--oauth-21)
- [MCP Server](#mcp-server)
- [On-Chain Identity (ERC-8004 + Metaplex Core)](#on-chain-identity-erc-8004--metaplex-core)
- [Pump.fun Integration](#pumpfun-integration)
- [Database Schema](#database-schema)
- [Build & Deployment](#build--deployment)
    - [Versioning & Compatibility](#versioning--compatibility)
- [Environment Variables](#environment-variables)
- [Testing](#testing)
- [FAQ & Troubleshooting](#faq--troubleshooting)
- [Contributing](#contributing)
- [Contributors](#contributors)
- [License](#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](https://three.ws/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](https://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 | Theme                                                                                  | Status                                                                                                         |
| ----- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **0** | Platform foundations (viewer, runtime, ERC-8004 + Metaplex Core identity, embed layer) | ✅ Shipped                                                                                                     |
| **1** | Selfie → Avatar engine (3-photo capture, hosted inference)                             | 🟡 In progress — capture UX + quality gates shipped; GPU reconstruction backend wiring                         |
| **2** | Agent personalization + voice cloning                                                  | 🟡 In progress — voice clone, persona, memory seeds shipped behind `/demos`; main-flow integration next        |
| **3** | Onchain economy (agent tokens, reputation markets, royalties)                          | 🟡 Scaffolding — bonding-curve sim, EAS-reputation viewer, 0xsplits + EAS SDKs landed; contracts + audits next |
| **4** | Open inference network (decentralized GPU layer)                                       | 🔮 Future — livepeer dep landed for early experimentation                                                      |

---

### Phase 0 — Foundations _(Shipped)_

The full stack is live at [three.ws](https://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