Skip to content

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.

8.7 KB
Raw Blame

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/agents
  • api/avatars/index.js -> /api/avatars
  • api/agents/[id].js -> /api/agents/:id
  • api/erc8004/[action].js -> /api/erc8004/:action
  • api/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 (the sql tagged-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: tool catalog, 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), plus by-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].js dispatcher, plus register-confirm.js.
  • sns.js, sns-subdomain.js, threews/ — Solana Name Service (.sol resolve + reverse-lookup, cached) and three.ws subdomains.

Avatars and 3D

  • avatars/, avatar/ — avatar CRUD plus avatar/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): POST tool calls, GET SSE, DELETE terminate. 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.js files (a-og, app-og, avatar-og, u-og, walk-og) — embed resolution, oEmbed, Open Graph image/page generation.
  • artifact.js — Claude-Artifact bundle endpoint (see specs/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.name selects the job. Schedules are declared in vercel.json under crons, 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 staggered run-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: Bearer header; 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.