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/v1/ — the unified three.ws API
Two things live here:
- The platform's own versioned API (
api/v1/index.js,resolve.js,sentiment.js,agents/,ai/,market/,pump/,token/) — first-party endpoints three.ws built. - The aggregator (
api/v1/x/[...slug].js+api/v1/_providers.js) — a growing bundle of third-party crypto/DeFi/on-chain APIs (CoinGecko, DefiLlama, Jupiter, DexScreener, Solana RPC, …) re-offered as one bill under/api/v1/x/<provider>/<endpoint>. This README is about the aggregator.
- Public storefront:
/crypto-api— live provider/ endpoint table, quickstart, and links, rendered from the same registry as everything below. - Machine-readable spec:
/openapi.json— generated fromproviderCatalog()(seeapi/openapi-json.jsaggregatorPaths()). - Human docs:
docs/api-reference.md§ "Unified API —/api/v1/xaggregator" — the full billing-lane writeup, free-quota table, and one curl per provider. - Discovery, live:
GET /api/v1/x— every provider + endpoint, in JSON, straight from production.GET /api/v1(api/v1/index.js) folds this in under anaggregatorkey alongside the platform's first-party endpoints.
Why an aggregator
An agent that needs a token's price, a swap quote, a chain's TVL, and an ENS lookup
shouldn't juggle four API keys and four rate limits. api/v1/x fronts them all: one base
URL, one discovery call, four billing lanes, and per-endpoint response shaping so a caller
gets normalized JSON instead of each upstream's raw (and often huge) payload.
How a request resolves
GET /api/v1/x # discovery — no provider, lists everything
GET /api/v1/x/<provider>/<endpoint>?… # most endpoints
POST /api/v1/x/<provider>/<endpoint> # a few (e.g. openai/chat)
One catch-all route, api/v1/x/[...slug].js, handles every provider —
adding a provider or endpoint never means a new route file. Each request is dispatched
through api/_lib/aggregator.js (executeUpstream,
resolveUpstreamKey, getPaidHandler) after billing-lane selection, in this order:
| Lane | Trigger | What happens |
|---|---|---|
| free | no credentials, endpoint descriptor carries a free quota |
served against a real per-(provider, endpoint, IP) quota — see serveFreeLane in x/[...slug].js |
| BYOK | caller sends the provider's own key header (e.g. x-provider-key) |
pure pass-through to the upstream with the caller's key — no markup, no key custody |
| plan | caller authenticates (three.ws API key / OAuth token / session) | uses the platform's own upstream key, billed against the caller's plan |
| x402 | none of the above, or the free quota is exhausted | standard HTTP 402 challenge — pay per call in USDC, then retry with X-PAYMENT |
The free lane exists specifically so "free API" is true, not marketing copy: a scripted
curl with zero setup gets real data back, and the exact same URL upgrades in place once
the caller adds a key, a payment, or a session — no dead end, no separate "upgrade" endpoint.
The provider registry — descriptor contract
api/v1/_providers.js is the single source of truth. Every consumer of the
aggregator — the catch-all route, providerCatalog() (discovery JSON), the OpenAPI generator,
the /crypto-api storefront, and the docs — reads this file at runtime/build time. Nothing
downstream hand-enumerates endpoints. Add a descriptor here and it appears everywhere with
zero other edits.
{
id: 'coingecko', // url-safe slug — first path segment under /api/v1/x
name: 'CoinGecko', // human label
category: 'crypto-market-data', // grouping for discovery
base: 'https://api.coingecko.com/api/v3', // upstream base URL, no trailing slash
bases: async () => [...], // OPTIONAL: interchangeable alternate hosts (see below)
requiresKey: false, // true when the upstream needs a key to function at all
envVar: 'COINGECKO_API_KEY', // env var holding three.ws's own platform key (or null)
byokHeader: 'x-provider-key', // header a caller uses to supply THEIR OWN key (or null)
applyKey: (headers, url, key) => { /* place the key where the upstream wants it */ },
endpoints: [
{
id: 'price', // url-safe slug — second path segment
method: 'GET', // caller-facing verb (what api/v1/x/[...slug].js requires)
path: '/simple/price', // string, or (query) => string for path params
query: (q) => ({ ids: required(q.ids, 'ids'), vs_currencies: q.vs_currencies || 'usd' }),
transform: (data) => data, // (data) => normalized response — default passthrough
free: { perMin: 30, perDay: 2000 }, // unauthenticated per-IP quota, or omit for none
priceAtomics: '1000', // x402 price in USDC atomics (6 decimals; "1000" = $0.001)
scope: 'agents:read', // three.ws OAuth scope required for the plan-billing path
summary: 'Spot price for one or more coins in any fiat/crypto.', // one line for discovery
params: { ids: 'comma-separated CoinGecko coin ids… (required)' }, // documented inputs
},
],
}
Full field-by-field contract, including upstreamMethod (for a caller-facing GET that drives
an upstream POST, e.g. Solana's single JSON-RPC endpoint) and body, is documented inline at
the top of _providers.js — read it before adding a descriptor.
bases — upstream failover
Set bases only when the provider fronts a pool of interchangeable hosts that answer the
same requests, the way solana fronts the platform's RPC pool. It is an async function
returning a priority-ordered list of base URLs.
When it is set, a retryable failure on base (HTTP 429, an upstream 5xx, or an unreachable
host) moves the call to the next host instead of surfacing to the caller; a 4xx other than 429
is the caller's own mistake and is never retried. At most three hosts are tried per call, and a
host that just failed is skipped for 30 seconds so only the first request of an outage pays the
discovery cost. A provider without bases makes exactly one attempt, as it always did.
Do not use it to point at a different upstream vendor: a fallback host must return the same
response shape, because the endpoint's transform() runs on whatever answers.
Adding a provider or endpoint
- Add a descriptor (or a new
endpointsentry on an existing one) toPROVIDERSin_providers.js. No new route file — the catch-all resolves it. - Keep
transform()slim: several upstreams (DexScreener, DefiLlama's/protocols, CoinGecko's/coins/{id}) return multi-hundred-KB payloads; every existing descriptor trims to the fields an agent actually reasons over. Follow that pattern. - Set
free: { perMin, perDay }if the upstream's own keyless tier can absorb it — this is what makes the endpoint discoverable and usable with zero setup. Omit it for endpoints with real per-call cost (e.g.openai/chat) or an upstream that requires a key to function at all. docs/api-reference.md§ "Unified API" lists providers and quotas by hand today — update it alongside_providers.js(the free-quota table there is not yet auto-generated).tests/openapi-aggregator.test.jsfails the build if a registered endpoint is missing from the generated OpenAPI doc — run it after adding a descriptor.- Add a
data/changelog.jsonentry (tagfeature) if the new provider is user-visible.
Related files
api/v1/index.js—GET /api/v1, foldsproviderCatalog()into the platform's own endpoint discovery document.api/v1/x/[...slug].js— the aggregator front door: billing-lane selection, rate limiting, usage recording.api/_lib/aggregator.js—executeUpstream,resolveUpstreamKey,getPaidHandler: the shared engine every provider runs through.api/_lib/x402-paid-endpoint.js— the x402 challenge/ settlement machinerygetPaidHandlerwraps around a provider endpoint.api/openapi-json.js—GET /openapi.json;aggregatorPaths()renders every/api/v1/x/*path fromproviderCatalog().pages/crypto-api.html— the public storefront (/crypto-api).