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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// Consolidated /.well-known/* handler.
// Dispatches on ?name= query param set by vercel.json rewrites.
import { readFileSync } from 'node:fs';
import { join } from 'node:path';
import { cors, json, method, wrap, error } from './_lib/http.js';
import { env } from './_lib/env.js';
import { REGISTERABLE_SCOPES, SUPPORTED_SCOPES } from './_lib/oauth-scopes.js';
import { hostedMcpPath, mcpResourceFor } from './_lib/mcp-resources.js';
import {
paymentRequirements,
bazaarExtension,
build402Body,
declareEip2612GasSponsoringExtension,
declareErc20ApprovalGasSponsoringExtension,
permit2VariantOf,
baseSettleable,
solanaSettleable,
NETWORK_BASE_MAINNET,
NETWORK_SOLANA_MAINNET,
} from './_lib/x402-spec.js';
import {
declareHttpDiscovery,
declareMcpDiscovery,
withService,
} from './_lib/x402/bazaar-helpers.js';
import { TOOL_CATALOG } from './_mcp/catalog.js';
import { STUDIO_CHALLENGE } from './_mcp3d/discovery.js';
import { TOOL_CATALOG as STUDIO_TOOL_CATALOG } from './_mcp3d/catalog.js';
import { priceFor as studioPriceFor } from './_mcp3d/pricing.js';
import { priceFor } from './_lib/pump-pricing.js';
import { priceFor as datapointPriceFor } from './_lib/x402-prices.js';
import {
DATAPOINT_FAMILIES,
DATAPOINT_DEFAULT_ATOMICS,
datapointDescription,
allChains,
allStablecoins,
allCategories,
allDexes,
allFees,
allDerivativeExchanges,
} from './_lib/market-data/datapoints.js';
import { fetchMarketsTable } from './_lib/market-fallbacks.js';
import { buildProtocols } from './defi/protocols.js';
import { loadYieldPools } from './defi/yields.js';
import { buildExchanges } from './coin/exchanges.js';
import { FORGE_OUTPUT_EXAMPLE } from './_lib/forge-listing.js';
import { listBazaarServices, serviceResourceUrl } from './_lib/agent-paid-services.js';
import { listActiveAgentServices, CALL_INPUT_EXAMPLE, CALL_INPUT_SCHEMA, CALL_OUTPUT_EXAMPLE, serviceNameFor } from './_lib/agent-api-service.js';
import { buildRequirements } from './_lib/x402-paid-endpoint.js';
import { toBazaarDiscovery } from './_lib/service-catalog/index.js';
// ── agent-attestation-schemas ─────────────────────────────────────────────────
const COMMON = {
v: { type: 'integer', const: 1 },
kind: { type: 'string' },
agent: { type: 'string', description: 'Metaplex Core asset pubkey (base58)' },
ts: { type: 'integer', description: 'Unix seconds when attestation was created' },
};
const SCHEMAS = {
'threews.feedback.v1': {
description: 'Client → agent feedback.',
required: ['v', 'kind', 'agent', 'score'],
properties: {
...COMMON,
score: { type: 'integer', minimum: 1, maximum: 5 },
task_id: { type: 'string' },
uri: { type: 'string', format: 'uri' },
},
},
'threews.validation.v1': {
description:
'Validator attestation. Two forms: a task validation (task_hash) or a ' +
'glTF/GLB schema validation of the agent model (subkind "glb-schema", ' +
'carrying proof_hash + proof_uri) — the Solana analog of the EVM ' +
'ValidationRegistry validationResponse.',
required: ['v', 'kind', 'agent', 'passed'],
properties: {
...COMMON,
passed: { type: 'boolean' },
subkind: { type: 'string', enum: ['glb-schema'], description: 'Present for model (glTF/GLB schema) validations.' },
task_hash: { type: 'string', description: 'Task validation form: sha256 of the validated task.' },
proof_hash: { type: 'string', description: 'Model form: sha256 of the canonical validation report JSON.' },
proof_uri: { type: 'string', description: 'Model form: URL to the full pinned validation report.' },
model_sha256: { type: 'string', description: 'Model form: sha256 of the GLB bytes.' },
source: { type: 'string' },
uri: { type: 'string', format: 'uri' },
},
},
'threews.task.v1': {
description: 'Client posts a task offer to an agent.',
required: ['v', 'kind', 'agent', 'task_id', 'scope_hash'],
properties: {
...COMMON,
task_id: { type: 'string' },
scope_hash: { type: 'string' },
uri: { type: 'string', format: 'uri' },
},
},
'threews.accept.v1': {
description: 'Agent accepts a task.',
required: ['v', 'kind', 'agent', 'task_id'],
properties: { ...COMMON, task_id: { type: 'string' } },
},
'threews.revoke.v1': {
description: 'Revoke a previous attestation.',
required: ['v', 'kind', 'agent', 'target_signature'],
properties: { ...COMMON, target_signature: { type: 'string' }, reason: { type: 'string' } },
},
'threews.dispute.v1': {
description: 'Agent owner disputes a feedback or validation.',
required: ['v', 'kind', 'agent', 'target_signature'],
properties: {
...COMMON,
target_signature: { type: 'string' },
reason: { type: 'string' },
uri: { type: 'string', format: 'uri' },
},
},
};
function handleAttestationSchemas(req, res) {
return json(
res,
200,
{
version: 1,
transport: {
type: 'spl-memo',
program: 'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr',
note: 'Each attestation is a signed memo tx with the agent asset pubkey as a non-signer key.',
},
schemas: SCHEMAS,
discovery: {
list_endpoint: '/api/agents/solana-attestations?asset=<pubkey>&kind=...',
reputation_endpoint: '/api/agents/solana-reputation?asset=<pubkey>',
validation_endpoint: '/api/agents/solana-validation?asset=<pubkey>',
},
},
{ 'cache-control': 'public, max-age=300' },
);
}
// ── oauth-authorization-server ────────────────────────────────────────────────
function handleOauthAuthServer(req, res) {
const base = env.APP_ORIGIN;
return json(
res,
200,
{
issuer: base,
authorization_endpoint: `${base}/oauth/authorize`,
token_endpoint: `${base}/api/oauth/token`,
registration_endpoint: `${base}/api/oauth/register`,
revocation_endpoint: `${base}/api/oauth/revoke`,
introspection_endpoint: `${base}/api/oauth/introspect`,
response_types_supported: ['code'],
grant_types_supported: ['authorization_code', 'refresh_token'],
code_challenge_methods_supported: ['S256'],
token_endpoint_auth_methods_supported: [
'none',
'client_secret_basic',
'client_secret_post',
],
// Everything this AS can issue: the self-registerable scopes plus the
// USE-21 auth-hints scopes paid endpoints accept for Bearer bypass.
scopes_supported: [...SUPPORTED_SCOPES],
service_documentation: `${base}/docs/mcp`,
ui_locales_supported: ['en'],
},
{ 'cache-control': 'public, max-age=300' },
);
}
// ── oauth-protected-resource ──────────────────────────────────────────────────
// The root document describes the platform resource (/api/mcp). RFC 9728 §3.1
// path insertion (/.well-known/oauth-protected-resource/api/mcp-3d, routed here
// with ?path=) describes one hosted MCP server, whose `resource` must be that
// server's own URL: an MCP client refuses to sign in when the metadata names a
// resource that does not cover the URL it connected to.
function handleOauthProtectedResource(req, res) {
const requestedPath = req.query?.path ?? new URL(req.url, 'http://x').searchParams.get('path');
if (requestedPath && !hostedMcpPath(requestedPath)) {
return error(res, 404, 'not_found', `no protected resource at ${String(requestedPath).slice(0, 64)}`);
}
const resource = requestedPath ? mcpResourceFor(requestedPath) : env.MCP_RESOURCE;
return json(
res,
200,
{
resource,
authorization_servers: [env.APP_ORIGIN],
bearer_methods_supported: ['header'],
resource_documentation: `${env.APP_ORIGIN}/docs/mcp`,
// Exactly what /api/oauth/register will keep for a self-registering
// client. A discovery-driven MCP client reads its scope list from
// here, so a scope missing from this array is a scope it never asks
// for: publishing fewer than the endpoint grants left the whole
// agent-wallet server (wallet:read / wallet:write / services:write)
// unreachable through the documented flow.
scopes_supported: [...REGISTERABLE_SCOPES],
},
{ 'cache-control': 'public, max-age=300' },
);
}
// ── x402 ─────────────────────────────────────────────────────────────────────
function handleX402(req, res) {
const mcpResource = `${env.APP_ORIGIN}/api/mcp`;
const mcpService = withService({
serviceName: 'three.ws MCP',
tags: ['mcp', '3d', 'gltf', 'solana', 'agent'],
});
const body = build402Body({
resourceUrl: mcpResource,
accepts: paymentRequirements(mcpResource),
serviceName: mcpService.serviceName,
tags: mcpService.tags,
iconUrl: mcpService.iconUrl,
});
return json(
res,
200,
{
...body,
schemes: ['pump-agent-payments', 'x402', 'x402-v2'],
pump_agent_payments: {
prep: '/api/pump/accept-payment-prep',
confirm: '/api/pump/accept-payment-confirm',
balances: '/api/pump/balances',
},
},
{ 'cache-control': 'public, max-age=300' },
);
}
// ── x402 Bazaar discovery (/.well-known/x402.json) ───────────────────────────
// Crawled by agentic.market / Bazaar to index our paid endpoints.
// Schema: https://x402.org/schemas/discovery.json
const RAW_AMOUNT_TO_USDC = (raw) => {
const n = Number(raw || 0) / 1_000_000;
const decimals = n < 0.01 ? 4 : 2;
const s = n.toFixed(decimals);
const trimmed = s.includes('.') ? s.replace(/0+$/, '').replace(/\.$/, '') : s;
return `$${trimmed}`;
};
// Build the per-endpoint `accepts` block for a given USDC atomics price.
// Each new /api/x402/* endpoint has its own price set in its handler via
// paidEndpoint(priceAtomics); the discovery doc has to mirror that or
// agentic.market shows the wrong price to potential buyers.
// Push an EVM accept entry followed by its Permit2 sibling so the Bazaar
// discovery doc mirrors the live 402 response exactly (EIP-3009 first,
// Permit2 second). Non-EVM entries get no sibling.
function pushAcceptWithPermit2Sibling(out, accept) {
out.push(accept);
const sibling = permit2VariantOf(accept);
if (sibling) out.push(sibling);
}
// Per-resource extensions for the discovery catalog. The bazaar entry is
// always present; the two gasless-Permit2-onboarding extensions are added
// whenever any accept in the list opts into the Permit2 transfer method.
// EIP-2612 covers tokens that implement `permit()` (USDC, DAI, ...); the
// ERC-20 approval variant covers tokens that don't. Both let the facilitator
// sponsor the approve() so the payer never broadcasts the approval tx.
// Normalize the second arg into a spec-shaped v2 bazaar extension
// ({discoverable, info, schema}). Catalog entries historically passed a raw
// {method, discoverable, input, inputSchema} descriptor straight through,
// which facilitator validators reject as a malformed discovery extension —
// every REST row was silently uncatalogable while the MCP rows (already
// spec-shaped) validated fine. Already-proper extensions (bazaarExtension(),
// declareMcpDiscovery(), STUDIO_CHALLENGE.bazaar) pass through untouched.
function extensionsForAccepts(accepts, bazaar) {
const normalized =
bazaar && bazaar.info && bazaar.schema
? bazaar
: declareHttpDiscovery({
method: bazaar?.method || 'GET',
input: bazaar?.input,
inputSchema: bazaar?.inputSchema,
// Catalog descriptors that carry their own output example declare it
// here; older entries get theirs backfilled by addOutputExample.
output: bazaar?.output,
});
const exts = { bazaar: normalized };
if (accepts.some((a) => a?.extra?.assetTransferMethod === 'permit2')) {
Object.assign(
exts,
declareEip2612GasSponsoringExtension(),
declareErc20ApprovalGasSponsoringExtension(),
);
}
return exts;
}
// Build the accepts[] block for a discovery-catalog entry. `resourceUrl` is
// echoed on every accept so reviewers + wallet/facilitator spend logs can
// reconcile each accept entry against the resource it gates, without having
// to walk back to the parent resource[] entry.
function acceptsForPrice(amountAtomics, resourceUrl) {
const out = [];
const price = RAW_AMOUNT_TO_USDC(amountAtomics);
// Solana-first platform default — the Solana accept leads so first-accept
// clients and marketplaces treat it as the primary rail; Base follows.
// Solana only when settlement is fulfillable — solanaSettleable() confirms the
// self-facilitator can co-sign (its X402_FEE_PAYER_SECRET_BASE58 is loaded), so
// the catalog never lists a Solana rail the live 402 now drops. See
// solanaSettleable() / baseSettleable() in x402-spec.js.
if (env.X402_PAY_TO_SOLANA && solanaSettleable()) {
out.push({
scheme: 'exact',
network: NETWORK_SOLANA_MAINNET,
network_label: 'solana-mainnet',
amount: String(amountAtomics),
price,
payTo: env.X402_PAY_TO_SOLANA,
asset: env.X402_ASSET_MINT_SOLANA,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
});
}
// Base only when a WORKING facilitator will settle it (CDP creds or the
// X402_ADVERTISE_BASE opt-in). A bare facilitator URL is not enough — the prod
// host was decommissioned and 404s /verify, so an unsettleable Base accept would
// drift from the live 402 (which now drops Base) and hand buyers a catalog rail
// that 502s at verify. See baseSettleable().
if (env.X402_PAY_TO_BASE && baseSettleable()) {
pushAcceptWithPermit2Sibling(out, {
scheme: 'exact',
network: NETWORK_BASE_MAINNET,
network_label: 'base-mainnet',
amount: String(amountAtomics),
price,
payTo: env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USD Coin', version: '2', decimals: 6 },
});
}
return out;
}
// USE-13: one Bazaar catalog row per priced MCP tool. Facilitators key MCP
// rows on (resource, toolName) so each priced tool needs its own row; the
// shared `/api/mcp` resource alone would collapse them into one entry. We
// only emit rows for priced tools (otherwise the row would advertise a paid
// catalog entry for a free tool and confuse buyers about what's actually
// gated). Falls back to the canonical `mcp://tool/<name>` identifier when
// the spec wants a logical resource that distinguishes tools at the URL
// level, while the actual call still goes to the server's own path.
// Generic over the server: pass the endpoint path/url, its accepts, its
// service metadata, its tool catalog, and its per-tool pricing lookup —
// /api/mcp and /api/mcp-3d both feed through here.
function buildMcpToolItems({ path, mcpUrl, mcpAccepts, mcpService, catalog, priceForTool }) {
const items = [];
for (const tool of catalog) {
const pricing = priceForTool(tool.name);
if (!pricing) continue;
const exampleArgs = exampleArgsForTool(tool);
const discovery = declareMcpDiscovery({
toolName: tool.name,
description: tool.description,
// MCP 2025-06-18 transport: Streamable HTTP is the default for
// these servers; SSE clients still work through the same path.
transport: 'streamable-http',
inputSchema: tool.inputSchema,
example: exampleArgs,
});
items.push({
type: 'mcp',
path,
url: mcpUrl,
toolName: tool.name,
method: 'POST',
description: tool.description,
mimeType: 'application/json',
serviceName: mcpService.serviceName,
tags: mcpService.tags,
iconUrl: mcpService.iconUrl,
pricing: {
amount_usdc: pricing.amount_usdc,
currency: 'USDC',
description: pricing.description,
},
accepts: mcpAccepts,
extensions: extensionsForAccepts(mcpAccepts, discovery),
});
}
return items;
}
// Synthesize a minimal example arguments object that satisfies the tool's
// inputSchema.required fields. We use type-appropriate placeholders rather
// than the full schema so the example stays short — facilitators index it
// for search relevance, not exact matching.
function exampleArgsForTool(tool) {
const props = tool.inputSchema?.properties || {};
const required = tool.inputSchema?.required || [];
const out = {};
for (const key of required) {
const def = props[key] || {};
if (def.type === 'integer' || def.type === 'number') out[key] = def.default ?? 1;
else if (def.type === 'boolean') out[key] = def.default ?? true;
else if (def.type === 'array') out[key] = [];
else out[key] = def.default ?? `example-${key}`;
}
return out;
}
// Agent-published paid services (the `monetize_endpoint` tool). Each active,
// bazaar-listed row in agent_paid_services becomes a discovery catalog entry so
// facilitators — and therefore find_services / the bazaar — index the agent's
// endpoint the moment it's published. The advertised payTo is the agent's OWN
// payout wallet, mirroring the live 402 that api/x402/service.js serves.
//
// Never throws: a DB hiccup (or no DB, as in unit tests) yields an empty list so
// the static catalog still renders. Capped by listBazaarServices().
async function buildAgentServiceItems(origin) {
let rows;
try {
rows = await listBazaarServices({ limit: 200 });
} catch (err) {
console.error('[wk/x402-discovery] agent services unavailable', err?.message || err);
return [];
}
const items = [];
for (const row of rows) {
const url = serviceResourceUrl(row.slug);
const price = RAW_AMOUNT_TO_USDC(row.price_atomics);
const accepts = [];
if (row.network === 'base' && row.payout_address && env.X402_ASSET_ADDRESS_BASE && baseSettleable()) {
pushAcceptWithPermit2Sibling(accepts, {
scheme: 'exact',
network: NETWORK_BASE_MAINNET,
network_label: 'base-mainnet',
amount: String(row.price_atomics),
price,
payTo: row.payout_address,
asset: env.X402_ASSET_ADDRESS_BASE,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: url,
extra: { name: 'USD Coin', version: '2', decimals: 6 },
});
} else if (
row.network === 'solana' &&
row.payout_address &&
env.X402_ASSET_MINT_SOLANA &&
env.X402_FEE_PAYER_SOLANA &&
solanaSettleable()
) {
accepts.push({
scheme: 'exact',
network: NETWORK_SOLANA_MAINNET,
network_label: 'solana-mainnet',
amount: String(row.price_atomics),
price,
payTo: row.payout_address,
asset: env.X402_ASSET_MINT_SOLANA,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: url,
extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
});
}
// No advertisable accept (missing payout / env for this network) → skip,
// matching the live 402 which would also refuse to advertise it.
if (!accepts.length) continue;
const inputSchema = row.input_schema || { type: 'object', additionalProperties: true };
items.push({
path: `/api/x402/service/${row.slug}`,
url,
method: row.target_method,
description: row.description,
mimeType: 'application/json',
serviceName: row.name,
tags: ['agent', 'monetized', row.network],
accepts,
extensions: extensionsForAccepts(accepts, {
method: row.target_method,
discoverable: true,
input: {},
inputSchema,
}),
});
}
return items;
}
// Whole agents sold as paid APIs (POST /api/x402/agents/:id, switched on from
// the agent wallet's Earn tab). One entry per agent on sale, built with the SAME
// buildRequirements() call the live route makes, so the advertised accepts
// (Solana USDC to the agent's own payout wallet, the owner's price) are exactly
// what the 402 will ask for. Never throws: a DB hiccup yields no rows and the
// rest of the catalog still renders.
async function buildSellableAgentItems() {
let services;
try {
services = await listActiveAgentServices({ limit: 200 });
} catch (err) {
console.error('[wk/x402-discovery] agent API services unavailable', err?.message || err);
return [];
}
const items = [];
for (const svc of services) {
let accepts;
try {
accepts = buildRequirements({
priceAtomics: svc.price_atomics,
networks: ['solana'],
resourceUrl: svc.url,
payToOverride: { solana: svc.pay_to },
acceptThree: false,
}).map((a) => ({
...a,
network_label: 'solana-mainnet',
price: RAW_AMOUNT_TO_USDC(a.amount),
asset_symbol: 'USDC',
}));
} catch (err) {
// Solana settlement is not configured on this deploy, so the live route
// would refuse too. Skip rather than advertise an unpayable entry.
console.error('[wk/x402-discovery] agent API accepts unavailable', err?.message || err);
return [];
}
items.push({
path: svc.path,
url: svc.url,
method: 'POST',
description: `${svc.description} (one turn with ${svc.name} on three.ws)`,
mimeType: 'application/json',
serviceName: serviceNameFor({ name: svc.name }),
tags: ['agent', 'chat', 'pay-per-call', 'solana'],
accepts,
extensions: extensionsForAccepts(accepts, {
method: 'POST',
discoverable: true,
input: CALL_INPUT_EXAMPLE,
inputSchema: CALL_INPUT_SCHEMA,
output: { type: 'json', example: CALL_OUTPUT_EXAMPLE },
}),
});
}
return items;
}
// Datapoint fabric (/api/x402/d/<family>/<id>/<metric>) — 400k+ addressable
// single-datapoint endpoints served by one dynamic route. Every one already
// exists and settles; the discovery doc advertises a WIDE enumerated slice so
// indexers (x402scan, the Bazaar, 402index's well-known reader) surface
// thousands of concrete datapoint URLs — top coins × every metric, every chain,
// top protocols / stablecoins / pools / exchanges × their metrics, plus every
// no-id metric. Ids come from the SAME live cached feeds the paid route resolves
// against (nothing hardcodes a third-party asset); each family retains its last
// good rows when its feed fails, so a hiccup refreshes the catalog in place
// instead of shrinking it under a paging crawler, and the whole result is
// memoized so a discovery request never triggers a rebuild storm. Set
// X402_DISCOVERY_DATAPOINTS_WIDE=false to fall back to the small headline slice,
// or tune any per-family cap via X402_DISCOVERY_<FAMILY>_IDS. The fabric serves
// every id regardless of what's enumerated here; /api/x402/d walks the full space.
const DP_WIDE = env.X402_DISCOVERY_DATAPOINTS_WIDE !== 'false';
const dpIntEnv = (key, dflt) => {
const n = Number.parseInt(process.env[key] ?? '', 10);
return Number.isFinite(n) && n >= 0 ? n : dflt;
};
// Per-family enumeration caps (id count). Defaults advertise ~4,800 concrete
// datapoint endpoints; every id resolves against a cached feed so render stays
// bounded, and the built array is memoized for DP_TTL_MS.
const DP_CAPS = {
coin: dpIntEnv('X402_DISCOVERY_COIN_IDS', 100),
protocol: dpIntEnv('X402_DISCOVERY_PROTOCOL_IDS', 100),
chain: dpIntEnv('X402_DISCOVERY_CHAIN_IDS', 150),
stablecoin: dpIntEnv('X402_DISCOVERY_STABLECOIN_IDS', 100),
pool: dpIntEnv('X402_DISCOVERY_POOL_IDS', 60),
exchange: dpIntEnv('X402_DISCOVERY_EXCHANGE_IDS', 60),
category: dpIntEnv('X402_DISCOVERY_CATEGORY_IDS', 80),
dex: dpIntEnv('X402_DISCOVERY_DEX_IDS', 60),
fees: dpIntEnv('X402_DISCOVERY_FEES_IDS', 80),
'derivative-exchange': dpIntEnv('X402_DISCOVERY_DERIVATIVE_EXCHANGE_IDS', 40),
};
// The token / token-security families resolve ANY contract at runtime, so there
// is no finite id list to enumerate. Advertise the capability with $THREE — the
// platform's own coin — as the worked example id (it resolves to a live 402),
// and let the free /api/x402/d catalog document the unbounded address space.
const DP_TOKEN_EXAMPLE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
const DP_TTL_MS = dpIntEnv('X402_DISCOVERY_DATAPOINTS_TTL_MS', 900_000); // 15 min
// Coin has 20 metrics; enumerating all × 100 coins alone is 2,000 rows and
// bloats the doc past what some crawlers ingest. Advertise the high-value
// headline metrics for coins (breadth of assets matters more than niche metrics
// like watchlist-users); the fabric still serves every metric for every coin.
// Every other family enumerates all its metrics (each has ≤7).
const DP_COIN_METRICS = [
'price', 'market-cap', 'fdv', 'volume-24h', 'change-24h',
'change-7d', 'rank', 'ath', 'atl', 'circulating-supply',
];
let _dpDiscoveryCache = null; // { origin, items, at }
// Per-family retention, keyed by origin. A crawler reads this catalog by
// offset over ~50 sequential requests, so a family that silently disappears
// mid-sweep does not just hide its own rows: every row after it shifts up an
// offset, and the crawler never reads the tail it already paged past. One
// upstream feed timing out used to drop its whole family (the coin family
// alone is 1,000 rows), shrinking `total` mid-crawl. Each family now keeps its
// last good rows and re-serves them when its feed fails or returns empty, so
// the advertised catalog only ever grows or refreshes in place.
const _dpSliceCache = new Map(); // origin -> Map(family -> rows)
// A synthetic, schema-shaped example value for a metric, derived from its unit.
// The datapoint output.example carries the real label/unit; the value is
// illustrative (all datapoint examples are synthetic by design).
function datapointExampleValue(metricDef) {
const unit = String(metricDef?.unit || '').toLowerCase();
if (unit.includes('usd') || unit.includes('$')) return 1234567.89;
if (unit.includes('bps')) return -3;
if (unit.includes('%') || unit.includes('pct') || unit.includes('percent')) return 2.5;
if (
unit === '' || unit.includes('text') || unit.includes('label') ||
unit.includes('name') || unit.includes('symbol') || unit.includes('class')
)
return metricDef?.label || 'value';
return 42.5;
}
async function buildDatapointItemsUncached(origin) {
const items = [];
const svc = withService({
serviceName: 'three.ws Datapoints',
tags: ['crypto', 'market-data', 'datapoint', 'x402'],
});
// `push` writes into whichever collector is active: `items` directly for the
// always-present families, or a family-scoped buffer while `slice` runs.
let target = items;
const sliceCache = _dpSliceCache.get(origin) ?? new Map();
_dpSliceCache.set(origin, sliceCache);
// Run one family's enumeration into its own buffer. Rows land in the catalog
// when the feed produced any; otherwise the family's last good rows do, so a
// transient upstream failure cannot shrink the catalog under a crawler.
const slice = async (family, fn) => {
const rows = [];
target = rows;
try {
await fn();
} catch (err) {
console.error(`[wk/x402-discovery] ${family} slice`, err?.message || err);
} finally {
target = items;
}
if (rows.length > 0) {
sliceCache.set(family, rows);
items.push(...rows);
return;
}
const retained = sliceCache.get(family);
if (retained?.length) {
console.error(`[wk/x402-discovery] ${family} slice empty, serving retained rows`);
items.push(...retained);
}
};
const push = (family, id, metric) => {
const familyDef = DATAPOINT_FAMILIES[family];
const metricDef = familyDef.metrics[metric];
const priceAtomics = datapointPriceFor(`datapoint-${family}`, DATAPOINT_DEFAULT_ATOMICS);
const path =
id != null
? `/api/x402/d/${family}/${encodeURIComponent(id)}/${metric}`
: `/api/x402/d/${family}/${metric}`;
const url = `${origin}${path}`;
const accepts = acceptsForPrice(priceAtomics, url);
target.push({
path,
url,
method: 'GET',
description: datapointDescription({ family, metric, priceAtomics }),
mimeType: 'application/json',
serviceName: svc.serviceName,
tags: [...svc.tags.slice(0, 4), family].slice(0, 5),
iconUrl: svc.iconUrl,
accepts,
extensions: extensionsForAccepts(accepts, {
method: 'GET',
discoverable: true,
input: {},
inputSchema: { type: 'object', properties: {} },
output: {
example: {
family,
...(id != null ? { id } : {}),
metric,
label: metricDef.label,
unit: metricDef.unit,
value: datapointExampleValue(metricDef),
as_of: '2026-07-11T00:00:00.000Z',
source: 'three.ws market-data',
},
},
}),
});
};
const metricsOf = (family) => Object.keys(DATAPOINT_FAMILIES[family].metrics);
// Every metric of the no-id families — static, always present.
for (const family of ['global', 'fear-greed', 'gas']) {
for (const metric of metricsOf(family)) push(family, null, metric);
}
// Small headline slice when wide enumeration is disabled — reproduces the
// original catalog (top 20 coins × 3 metrics, top 10 protocols × tvl).
if (!DP_WIDE) {
await slice('coin', async () => {
const { rows } = await fetchMarketsTable({ page: 1, perPage: 20, category: '' });
for (const row of rows) for (const metric of ['price', 'market-cap', 'change-24h']) if (row.id) push('coin', row.id, metric);
});
await slice('protocol', async () => {
const { protocols } = await buildProtocols();
for (const p of protocols.slice(0, 10)) if (p.slug) push('protocol', p.slug, 'tvl');
});
return items;
}
// ── Wide enumeration: real ids from the cached feeds × every family metric ──
// Top coins by market cap (CoinGecko markets table, one cached page ≤100).
await slice('coin', async () => {
const { rows } = await fetchMarketsTable({ page: 1, perPage: Math.min(DP_CAPS.coin, 100), category: '' });
const all = new Set(metricsOf('coin'));
const metrics = DP_COIN_METRICS.filter((m) => all.has(m));
for (const row of rows.slice(0, DP_CAPS.coin)) {
if (!row.id) continue;
for (const metric of metrics) push('coin', row.id, metric);
}
});
// Top protocols by TVL (DeFiLlama).
await slice('protocol', async () => {
const { protocols } = await buildProtocols();
const metrics = metricsOf('protocol');
for (const p of protocols.slice(0, DP_CAPS.protocol)) {
if (!p.slug) continue;
for (const metric of metrics) push('protocol', p.slug, metric);
}
});
// Every chain (DeFiLlama /v2/chains — ~350, fully enumerable).
await slice('chain', async () => {
const chains = [...(await allChains()).values()].map((c) => c?.name).filter(Boolean);
const metrics = metricsOf('chain');
for (const name of chains.slice(0, DP_CAPS.chain)) {
for (const metric of metrics) push('chain', name, metric);
}
});
// Top stablecoins by supply (DeFiLlama). The map keys id AND symbol to the
// same row — enumerate each once by its canonical id (matches d/index.js).
await slice('stablecoin', async () => {
const seen = new Set();
const ids = [];
for (const [key, row] of (await allStablecoins()).entries()) {
if (seen.has(row)) continue;
seen.add(row);
ids.push(/^\d+$/.test(key) ? key : row.symbol || key);
if (ids.length >= DP_CAPS.stablecoin) break;
}
const metrics = metricsOf('stablecoin');
for (const id of ids) for (const metric of metrics) push('stablecoin', id, metric);
});
// Top yield pools by TVL (DeFiLlama yields — pre-sorted TVL desc).
await slice('pool', async () => {
const { pools } = await loadYieldPools();
const metrics = metricsOf('pool');
for (const p of pools.slice(0, DP_CAPS.pool)) {
if (!p.pool) continue;
for (const metric of metrics) push('pool', p.pool, metric);
}
});
// Top exchanges by trust rank (CoinGecko /exchanges).
await slice('exchange', async () => {
const { exchanges } = await buildExchanges();
const metrics = metricsOf('exchange');
for (const e of exchanges.slice(0, DP_CAPS.exchange)) {
if (!e.id) continue;
for (const metric of metrics) push('exchange', e.id, metric);
}
});
// Sector categories (CoinGecko categories, market-cap desc).
await slice('category', async () => {
const metrics = metricsOf('category');
let n = 0;
for (const id of (await allCategories()).keys()) {
if (n++ >= DP_CAPS.category) break;
for (const metric of metrics) push('category', id, metric);
}
});
// Top DEXs by 24h volume (DeFiLlama).
await slice('dex', async () => {
const metrics = metricsOf('dex');
let n = 0;
for (const slug of (await allDexes()).keys()) {
if (n++ >= DP_CAPS.dex) break;
for (const metric of metrics) push('dex', slug, metric);
}
});
// Top protocols by fees/revenue (DeFiLlama).
await slice('fees', async () => {
const metrics = metricsOf('fees');
let n = 0;
for (const slug of (await allFees()).keys()) {
if (n++ >= DP_CAPS.fees) break;
for (const metric of metrics) push('fees', slug, metric);
}
});
// Derivative (perp) venues by open interest (CoinGecko).
await slice('derivative-exchange', async () => {
const metrics = metricsOf('derivative-exchange');
let n = 0;
for (const id of (await allDerivativeExchanges()).keys()) {
if (n++ >= DP_CAPS['derivative-exchange']) break;
for (const metric of metrics) push('derivative-exchange', id, metric);
}
});
// Per-contract token market + security — advertised via the $THREE worked
// example (the families resolve any address at runtime; no id list to walk).
for (const metric of metricsOf('token')) push('token', DP_TOKEN_EXAMPLE_MINT, metric);
for (const metric of metricsOf('token-security')) push('token-security', DP_TOKEN_EXAMPLE_MINT, metric);
return items;
}
// Memoized wrapper: the slice rebuilds at most once per DP_TTL_MS per origin. A
// total-failure rebuild serves the last good cache (or an empty block) rather
// than dropping — or hammering upstreams on — every discovery request.
async function buildDatapointItems(origin) {
const now = Date.now();
if (_dpDiscoveryCache && _dpDiscoveryCache.origin === origin && now - _dpDiscoveryCache.at < DP_TTL_MS) {
return _dpDiscoveryCache.items;
}
try {
const items = await buildDatapointItemsUncached(origin);
_dpDiscoveryCache = { origin, items, at: now };
return items;
} catch (err) {
console.error('[wk/x402-discovery] datapoint build failed', err?.message || err);
if (_dpDiscoveryCache?.items) return _dpDiscoveryCache.items;
return [];
}
}
// ── output.example backfill ──────────────────────────────────────────────────
// Indexers (agentic.market / x402scan) render and rank a resource by its
// response example. A resource with no `bazaar.info.output.example` still
// catalogs, but ranks poorly and shows an empty result card — the verifier
// (`scripts/verify-x402-discovery.mjs`) flags every one as a warning. These maps
// are the single source of a realistic, schema-shaped success example for each
// paid endpoint so the catalog renders fully everywhere it's indexed.
//
// Every value here is SYNTHETIC: $THREE (the only coin) or an obviously-fake
// placeholder address — never a real third-party mint/creator/holder. Examples
// mirror the actual 200-response keys each handler emits (post-settlement).
const REST_OUTPUT_EXAMPLES = Object.freeze({
'/api/x402/model-check': {
url: 'https://three.ws/avatars/mannequin.glb',
fetchedBytes: 1572864,
model: {
container: 'glb',
generator: 'three.ws CharacterStudio v1.5',
version: '2.0',
extensionsUsed: ['KHR_materials_unlit'],
extensionsRequired: [],
counts: {
scenes: 1,
nodes: 18,
meshes: 6,
materials: 4,
textures: 3,
animations: 1,
skins: 1,
totalVertices: 12480,
totalTriangles: 24812,
},
},
suggestions: [
{
id: 'texture_size',
severity: 'info',
message: 'All textures are within 1024x1024 — good for mobile.',
},
],
},
'/api/x402/token-intel': {
mint: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
symbol: 'THREE',
name: 'three.ws',
chain: 'solana',
price_usd: 0.003685,
change_24h: 12.4,
market_cap_usd: 3685000,
liquidity_usd: 412000,
volume_24h_usd: 1268079,
momentum: { m5: 0.3, h1: 1.8, h6: 6.1, h24: 12.4 },
signal: 'bullish',
headline: 'THREE climbs +12.40% — moderate upside',
rationale:
'THREE is up +12.40% over 24 h, trading at $0.003685. Volume is healthy against liquidity; participation is real. Buyers dominate the tape. The last hour confirms the trend.',
confidence: 0.86,
risk: {
score: 8,
level: 'low',
summary: 'THREE clears the basic depth, age, and flow checks.',
factors: [
{ label: 'Liquidity', status: 'low', detail: '$412,000 pooled — healthy depth.' },
{ label: 'Age', status: 'low', detail: 'Pair is 240d old — established.' },
{ label: 'Float', status: 'low', detail: 'Cap is 8.9× liquidity — well backed.' },
{ label: 'Flow', status: 'low', detail: '63% of 24 h trades are buys — net accumulation.' },
],
},
ts: '2026-06-12T10:00:00Z',
},
'/api/x402/analytics': {
ok: true,
report: 'clubs',
period: '24h',
generated_at: '2026-06-27T18:42:09.000Z',
metrics: {
active_clubs: 3,
total_clubs: 4,
members: 27,
tips: { count: 41, volume_atomics: '410000', volume_usdc: 0.41 },
cover_charges: { count: 12, atomics: '120000', usdc: 0.12 },
},
top_clubs: [
{ dancer: '1', display_name: 'Nyx', volume_atomics: '190000', volume_usdc: 0.19, tips: 19 },
],
},
'/api/x402/api-key-health': {
valid: true,
scopes: ['internal', 'autonomous_loop', 'bypass_x402'],
expires_at: null,
key_type: 'internal',
source: 'env',
key_prefix: null,
rate_limit_per_minute: null,
checked_at: '2026-06-28T12:00:00Z',
},
'/api/x402/auth-health': {
all_pass: true,
failed_step: null,
latency_ms: 38,
steps: {
create: { pass: true, latency_ms: 8 },
validate: { pass: true, latency_ms: 3 },
refresh: { pass: true, latency_ms: 11 },
expire: { pass: true, latency_ms: 2 },
},
ts: '2026-06-28T00:00:00Z',
},
'/api/x402/avatar-optimize-batch': {
analyzed: 50,
critical_count: 12,
warn_count: 38,
info_count: 91,
total_size_bytes: 82000000,
avatars: [
{
id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
name: 'My Avatar',
size_bytes: 2100000,
critical_count: 1,
warn_count: 3,
info_count: 5,
top_suggestion: 'Apply Draco compression to reduce geometry size by ~60%',
},
],
},
'/api/x402/pipeline-rig': {
stage: 'rig',
input_url: 'https://three.ws/avatars/mannequin.glb',
output_url: 'https://three.ws/cdn/x402-pipeline/rig/abc123.glb',
bytes: 1940112,
persisted: true,
rig_type: 'biped',
},
'/api/x402/pipeline-remesh': {
stage: 'remesh',
input_url: 'https://three.ws/avatars/mannequin.glb',
output_url: 'https://three.ws/cdn/x402-pipeline/remesh/abc123.glb',
bytes: 812044,
persisted: true,
remesh_mode: 'quad',
operation: 'full',
face_count: 20000,
quad_ratio: 0.98,
textured: true,
},
'/api/x402/pipeline-gameready': {
stage: 'gameready',
input_url: 'https://three.ws/avatars/mannequin.glb',
output_url: 'https://three.ws/cdn/x402-pipeline/gameready/abc123.glb',
bytes: 640220,
persisted: true,
topology: 'quad',
poly_budget: 12000,
face_count: 12000,
quad_ratio: 0.97,
textured: true,
},
'/api/x402/pipeline-stylize': {
stage: 'stylize',
input_url: 'https://three.ws/avatars/mannequin.glb',
output_url: 'https://three.ws/cdn/x402-pipeline/stylize/abc123.glb',
bytes: 512880,
persisted: true,
style: 'voxel',
resolution: 48,
face_count: 18240,
},
'/api/x402/pipeline-rembg': {
stage: 'rembg',
input_url: 'https://three.ws/avatars/thumbs/default.png',
output_url: 'https://three.ws/cdn/x402-pipeline/rembg/abc123.png',
bytes: 284112,
persisted: true,
model: 'rmbg2',
},
'/api/x402/bazaar-feed': {
filter: 'new',
limit: 10,
count: 3,
listings: [
{
id: 'http:https://svc.example/x402',
name: 'Example Feed',
price: '0.001 USDC',
first_seen: '2026-06-28T00:00:00Z',
},
],
activity: {
new_24h: 3,
new_7d: 9,
daily_avg_7d: 1.29,
signal: 'active',
headline: '3 new bazaar listings in 24 h',
confidence: 0.65,
},
generated_at: '2026-06-28T10:00:00Z',
},
'/api/x402/billboard': {
ok: true,
coin: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
image: 'https://three.ws/og-image.png',
caption: 'gm from the gallery',
slotHours: 6,
startsAt: '2026-06-28T18:42:09.000Z',
endsAt: '2026-06-29T00:42:09.000Z',
payer: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
network: 'solana',
amountAtomics: '50000',
asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
},
'/api/x402/cross-chain': {
mode: 'bridge_status',
bridges: [
{ chain: 'wormhole', status: 'operational', latency_ms: 210, provider: 'wormholescan' },
{ chain: 'lifi', status: 'operational', latency_ms: 334, provider: 'li.fi' },
{ chain: 'debridge', status: 'degraded', latency_ms: 1870, provider: 'dln.trade' },
],
down_count: 0,
signal: 'neutral',
headline: 'All Solana bridges operational',
confidence: 0.82,
ts: '2026-06-28T12:00:00Z',
},
'/api/x402/did': {
verified: true,
latency_ms: 142,
did: 'did:three:canary',
mode: 'verify',
resolved_did: 'did:web:three.ws',
http_status: 200,
within_latency: true,
malformed: false,
configured: true,
checks: {
is_object: true,
has_did_context: true,
has_did_id: true,
has_verification_method: true,
assertion_resolves: true,
has_x402_service: true,
valid: true,
},
ts: '2026-06-27T10:00:00Z',
},
'/api/x402/feed-health': {
feed: 'changelog_rss',
valid: true,
item_count: 1241,
latest_title: 'x402 Volume Analytics — the platform measures its own payment economy',
title_match: true,
fetch_ms: 312,
checked_at: '2026-06-28T12:00:00.000Z',
},
'/api/x402/llm-proxy': {
content: '1, 2, 3.',
model: 'llama-3.3-70b-versatile',
provider: 'groq',
latency_ms: 312,
tokens_used: 11,
input_tokens: 5,
output_tokens: 6,
},
'/api/x402/mcp-tool-catalog': {
ok: true,
mode: 'discover',
total_tools: 24,
priced_tools: 11,
free_tools: 13,
new_tools: [
{ name: 'segment_model', description: 'Split a mesh into named parts', priced: true, price_usdc: 0.04, input_fields: 2 },
],
changed_tools: [
{ name: 'render_avatar', change: 'price', price_usdc: 0.005, prev_price_usdc: 0.003 },
],
removed_tools: [],
ts: '2026-06-27T10:00:00.000Z',
},
'/api/x402/model-validation-sweep': {
ok: true,
avatar_id: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
avatar_name: 'Realistic Male',
score: 82,
has_errors: false,
missing_bones: false,
counts: {
scenes: 1,
nodes: 22,
meshes: 4,
materials: 3,
textures: 5,
animations: 12,
skins: 1,
totalVertices: 8432,
totalTriangles: 14200,
indexedPrimitives: 4,
nonIndexedPrimitives: 0,
},
extensions_used: ['KHR_draco_mesh_compression'],
file_size_bytes: 1572864,
inspected_at: '2026-06-27T10:00:00.000Z',
},
'/api/x402/notify': {
delivered: true,
channel: 'canary',
latency_ms: 18,
notification_id: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
message: 'x402 loop heartbeat',
priority: 'low',
payer: null,
ts: '2026-06-28T10:00:00Z',
},
'/api/x402/pay-by-name': {
data: {
name: 'nich.threews.sol',
address: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
verified: true,
source: 'sns',
},
},
'/api/x402/rate-limit-probe': {
endpoint: '/api/x402/forge',
remaining_calls: 42,
reset_at: '2026-06-29T00:00:00.000Z',
limit: 500,
daily_cap_atomic: 5000000,
daily_spent_atomic: 4580000,
remaining_capacity_atomic: 420000,
price_atomic: 10000,
cooldown_active: false,
cooldown_ttl_seconds: null,
},
'/api/x402/schema-check': {
ok: true,
api: 'changelog_json',
valid: true,
version: '2026-06-28',
entry_count: 42,
schema_errors: [],
fetched_at: '2026-06-28T12:00:00.000Z',
},
'/api/x402/solana-register-health': {
tool: 'solana_register',
healthy: true,
network: 'mainnet',
canary_agent_id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
asset: 'THREEsynthetic1111111111111111111111111111',
identity_pda: 'AgentRegyPDA11111111111111111111111111111111',
registration_uri: 'https://three.ws/api/agents/7b9a4f30/registration.json',
checks: {
indexed: true,
registry_enrolled: true,
asset_onchain: true,
identity_pda_onchain: true,
},
rpc_latency_ms: 184,
checked_at: '2026-06-27T18:00:00Z',
},
'/api/x402/spend-session': {
ok: true,
mode: 'canary',
created: true,
consumed: true,
latency_ms: 12,
session_id: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
budget: 0.01,
payer: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
network: 'solana',
amountAtomics: '10000',
asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
},
'/api/x402/telegram-health': {
bot: 'changelog',
reachable: true,
bot_id: 7234567890,
bot_username: 'three_ws_bot',
latency_ms: 142,
reason: null,
checked_at: '2026-06-28T12:00:00.000Z',
},
'/api/x402/wallet-connect': {
mode: 'health',
session_created: true,
latency_ms: 83,
slow: false,
nonce_valid: true,
domain: 'three.ws',
reason: null,
checked_at: '2026-06-28T00:00:00Z',
},
'/api/x402/agent-reputation': {
subject: 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',
subjectType: 'solana_mint',
score: 71,
tier: 'high',
signals: {
dimensions: {
activity: { available: true, weight: 25, norm: 0.62, points: 16, value: 124 },
age: { available: true, weight: 15, norm: 0.48, points: 7, days: 176 },
counterparties: { available: true, weight: 15, norm: 0.72, points: 11, value: 18 },
holdings: { available: true, weight: 10, norm: 1, points: 10, usd: 412000 },
reliability: { available: true, weight: 15, norm: 0.98, points: 15, failure_rate: 0.02 },
attestations: { available: true, weight: 20, norm: 0.6, points: 12, count: 6, avg_feedback: null },
},
weight_considered: 100,
},
evidence: [
{ kind: 'solana_token', ref: 'https://solscan.io/token/FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump' },
{ kind: 'threews_agent', ref: '/agents/7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55' },
],
caveats: [],
ts: '2026-07-07T00:00:00Z',
},
'/api/x402/agent-bouncer': {
ok: true,
admitted: true,
banned: false,
tier: 'trusted',
reason: null,
reasons: [],
newcomer: false,
agent_id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
name: 'Helios',
visits: 4,
reputation: {
deployed_mints: 2,
payments: { confirmed_count: 142, distinct_payers: 87, failure_rate: 0.021 },
distributions: { confirmed: 12, failed: 1, success_rate: 0.923 },
},
policy: {
minPayments: 10,
minDistinctPayers: 3,
maxFailureRate: 0.2,
allowNewcomers: true,
},
fetchedAt: '2026-06-22T17:00:00.000Z',
},
'/api/x402/onchain-identity-verify': {
claim: {
identity: 'vitalik.eth',
address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
chain: 'eip155:1',
},
identity_type: 'ens',
verified: true,
method: 'ens-resolution',
evidence: [
{
kind: 'ens_forward_resolution',
ref: 'vitalik.eth',
detail: 'resolves to 0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
},
],
caveats: [],
ts: '2026-07-07T00:00:00.000Z',
},
'/api/x402/pump-launch': {
mint: 'HEL1oXyzABCDEFGHJKLMNopqrstuvwxyZ12345abcdef',
signature: '5xYExampleTxSignatureDoNotUse...',
creator: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
name: 'Helios',
symbol: 'HELIO',
metadataUri: 'https://ipfs.io/ipfs/QmExampleMetadataCid',
network: 'mainnet',
pumpfun_url: 'https://pump.fun/coin/HEL1oXyzABCDEFGHJKLMNopqrstuvwxyZ12345abcdef',
vanity_prefix: 'HEL',
vanity_iterations: 4821,
},
// Sourced from the shared forge listing so the discovery output example
// matches the live 402's exactly (backend field included).
'/api/x402/forge': FORGE_OUTPUT_EXAMPLE,
'/api/x402/skill-marketplace': {
skill_filter: 'inspect_model',
count: 1,
cheapest: {
agent_name: 'Helios',
skill: 'inspect_model',
amount_atomics: '10000',
chain: 'solana',
},
listings: [
{
agent_id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55',
agent_name: 'Helios',
skill: 'inspect_model',
amount_atomics: '10000',
mint_decimals: 6,
chain: 'solana',
trial_uses: 1,
time_pass_hours: 24,
},
],
indexed_at: '2026-05-14T17:00:00Z',
},
'/api/x402/symbol-availability': {
ticker: 'HELIO',
network: 'mainnet',
exact_collision: false,
exact_matches: [],
similar: [
{
ticker: 'HELIOS',
mint: 'C3vQABCDEFGHJKLMNopqrstuvwxyZ12345abcdefghi',
name: 'Helios',
similarity: 0.71,
},
],
recommendation: 'available — one near-match exists at similarity 0.71',
indexed_at: '2026-05-14T17:00:00Z',
},
'/api/x402/vanity': {
address: 'SoEXAMPLEdoNotUse1111111111111111111111111111',
prefix: 'So',
suffix: null,
ignoreCase: false,
format: 'keypair',
secretKeyBase58: '<example only — the live endpoint returns the ground secret key here>',
mnemonic: null,
wordCount: null,
derivationPath: null,
attempts: 160,
durationMs: 6,
expectedAttempts: 58,
network: 'solana',
explorerUrl: 'https://solscan.io/account/SoEXAMPLEdoNotUse1111111111111111111111111111',
verifyUrl: 'https://three.ws/vanity/verify',
serviceKeyUrl: 'https://three.ws/.well-known/three-vanity.json',
},
'/api/x402/vanity-verifiable': {
protocol: 'three-vanity/v1',
receiptType: 'grind-receipt',
address: 'SoEXAMPLEdoNotUse1111111111111111111111111111',
pattern: { prefix: 'So', suffix: null, ignoreCase: false },
commitment: 'sha256:0000000000000000000000000000000000000000000000000000000000000000',
winningIndex: 3041,
attempts: 3042,
sealed: false,
servicePublicKey: '3WzwpVSmSExamplePublicKeyDoNotUse',
signature: 'ed25519:abcdef1234567890...',
network: 'solana',
verifyUrl: 'https://three.ws/vanity/verify',
serviceKeyUrl: 'https://three.ws/.well-known/three-vanity.json',
},
'/api/x402/vanity-premium': {
address: 'PUMPEXAMPLEdoNotUse1111111111111111111111111',
prefix: 'PUMP',
suffix: null,
patternLabel: 'PUMP…',
rarityTier: 'rare',
format: 'keypair',
priceUsd: 12,
secretKeyBase58: '<delivered once — ciphertext destroyed on delivery>',
delivery: 'once',
network: 'solana',
explorerUrl: 'https://solscan.io/account/PUMPEXAMPLEdoNotUse1111111111111111111111111',
custodyNotice:
'Platform-generated key delivered once — use as a token mint or sweep to self-generated custody, not as a treasury.',
},
'/api/x402/asset-download': {
ok: true,
slug: 'pole-dancer-rumba',
title: 'Pole Dancer (Rumba)',
mimeType: 'model/gltf-binary',
sizeBytes: 6492840,
expiresAt: '2026-05-21T18:48:09.000Z',
downloadUrl: 'https://three-ws-public.r2.dev/assets/pole-dancer-rumba.glb?X-Amz-Algorithm=...',
},
'/api/x402/skill-call': {
ok: true,
skill: { slug: 'wallet-balance', name: 'Wallet Balance', category: 'crypto' },
tools: [{ type: 'function', function: { name: 'get_balance', description: 'Fetch balances.' } }],
content: '# Wallet Balance\n\nUse get_balance to fetch token balances...',
calledAt: '2026-05-31T18:48:09.000Z',
},
'/api/x402/cosmetic-purchase': {
ok: true,
id: 'skin-midnight',
name: 'Midnight',
slot: 'skin',
rarity: 'legendary',
account: 'g_5f3c9a21b8',
owned: true,
newlyOwned: true,
network: 'solana',
amountAtomics: '3000000',
},
'/api/x402/animation-download': {
ok: true,
id: '00000000-0000-0000-0000-000000000000',
slug: 'spin-kick-combo',
name: 'Spin Kick Combo',
mimeType: 'model/gltf-binary',
sizeBytes: 248400,
expiresAt: '2026-06-15T18:48:09.000Z',
downloadUrl: 'https://three.ws/cdn/u/spin-kick-combo.glb?X-Amz-Algorithm=...',
},
'/api/x402/club-cover': {
ok: true,
admitted: true,
banned: false,
tier: 'regular',
visits: 4,
passId: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
issuedAt: '2026-06-15T18:42:09.000Z',
expiresAt: '2026-06-16T00:42:09.000Z',
network: 'solana',
amountAtomics: '10000',
},
// Only advertised when CDP creds are present (its sole accept is a Permit2
// sibling), so it never appears in the public non-CDP catalog — but include
// its example so the catalog stays green in CDP-credentialed environments.
'/api/x402/permit2-paid-demo': {
ok: true,
demo: 'permit2-eip2612-gas-sponsoring',
method: 'permit2',
supportsEip2612: true,
payer: '0x1111111111111111111111111111111111111111',
network: 'eip155:8453',
asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
amountAtomics: '1000',
transaction: '0x9c0a7e5ad5c9c0bb6f04f6ad9c52f4f44bb6c5d9c0a7e5ad5c9c0bb6f04f6ad9',
explorer:
'https://basescan.org/tx/0x9c0a7e5ad5c9c0bb6f04f6ad9c52f4f44bb6c5d9c0a7e5ad5c9c0bb6f04f6ad9',
settledAt: '2026-06-15T18:42:09.000Z',
},
});
// MCP tool result examples, keyed by toolName. Wrapped in the same JSON-RPC 2.0
// CallToolResult envelope the live /api/mcp + /api/mcp-3d transports return, so
// the example mirrors exactly what a buyer's MCP client receives.
const MCP_TOOL_OUTPUT_SUMMARIES = Object.freeze({
render_avatar: { ok: true, scene: 'avatar', format: 'glb', url: 'https://three.ws/cdn/avatar-preview.glb' },
validate_model: { ok: true, warnings: [], errors: [], meta: { vertices: 12480, triangles: 24812 } },
inspect_model: { container: 'glb', meshes: 6, materials: 4, animations: 1, vertices: 12480 },
optimize_model: { ok: true, before: { bytes: 1572864 }, after: { bytes: 640000 }, savedPct: 59 },
apply_animation: { ok: true, clip: 'walk', format: 'glb', url: 'https://three.ws/cdn/animated.glb' },
text_to_3d: { job_id: 'f1.eyJwIjoiZXhhbXBsZSJ9.sig', status: 'queued', poll_url: '/api/forge?job=f1.eyJwIjoiZXhhbXBsZSJ9.sig' },
image_to_3d: { job_id: 'f1.eyJpIjoiZXhhbXBsZSJ9.sig', status: 'queued', poll_url: '/api/forge?job=f1.eyJpIjoiZXhhbXBsZSJ9.sig' },
remove_background: { ok: true, image_url: 'https://three.ws/cdn/cutout.png' },
remesh_model: { ok: true, glb_url: 'https://three.ws/cdn/remeshed.glb', triangles: 20000 },
stylize_model: { ok: true, glb_url: 'https://three.ws/cdn/stylized.glb', style: 'voxel' },
segment_model: { ok: true, parts: ['head', 'torso', 'legs'], glb_url: 'https://three.ws/cdn/segmented.glb' },
retexture_model: { ok: true, glb_url: 'https://three.ws/cdn/retextured.glb' },
retexture_region: { ok: true, glb_url: 'https://three.ws/cdn/retextured-region.glb', region: 'face' },
auto_rig_model: { ok: true, glb_url: 'https://three.ws/cdn/rigged.glb', bones: 52 },
pose_model: { ok: true, glb_url: 'https://three.ws/cdn/posed.glb', pose: 't-pose' },
direct_prompt: { job_id: 'f1.eyJkIjoiZXhhbXBsZSJ9.sig', status: 'queued', poll_url: '/api/forge?job=f1.eyJkIjoiZXhhbXBsZSJ9.sig' },
generate_material: { ok: true, material_url: 'https://three.ws/cdn/material.glb' },
cad_generate: {
id: '0b4b6e61-42aa-424d-8aef-2bddbd9b7abb',
title: 'Raspberry Pi 4 Case Base',
url: 'https://three.ws/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb',
files: { step: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/part.step', stl: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/part.stl', glb: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/part.glb' },
metrics: { size_mm: [100, 75, 12], volume_mm3: 21623.8631, solids: 1, valid: true },
params: [{ name: 'WIDTH', label: 'Overall width', value: 100, min: 80, max: 120, step: 1, unit: 'mm' }],
},
cad_rebuild: {
id: '0b4b6e61-42aa-424d-8aef-2bddbd9b7abb',
key: '1mf1luf',
url: 'https://three.ws/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb?v=1mf1luf',
values: { WIDTH: 112 },
files: { step: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/v/1mf1luf/part.step', stl: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/v/1mf1luf/part.stl', glb: 'https://pub-2534e921bf9c4314addcd4d8a6e98b7b.r2.dev/cad/0b4b6e61-42aa-424d-8aef-2bddbd9b7abb/v/1mf1luf/part.glb' },
cached: false,
},
search_public_avatars: {
count: 2,
avatars: [
{ id: '7b9a4f30-2d11-4e2d-9d12-1cdb1f6a3a55', slug: 'midnight-robot', name: 'Midnight Robot', tags: ['robot', 'sci-fi'], thumbnail_url: 'https://three.ws/cdn/avatars/midnight-robot.png' },
{ id: 'c1e8a902-5b44-4f0a-8e21-7d3f0c2b1a90', slug: 'anime-dancer', name: 'Anime Dancer', tags: ['anime', 'dancer'], thumbnail_url: 'https://three.ws/cdn/avatars/anime-dancer.png' },
],
},
solana_agent_reputation: {
asset: 'AgEntWa11etExamp1eDoNotUse111111111111111111',
network: 'mainnet',
feedback: { total: 142, verified: 118 },
score: { average: 4.6, verified_average: 4.8 },
validation: { passed: 8, failed: 1 },
tasks: { accepted: 96, disputed: 2 },
indexed_at: '2026-05-14T17:00:00Z',
},
capture_scene: {
job_id: 'v2s.eyJ2IjoiZXhhbXBsZSJ9.sig',
status: 'queued',
source_video_url: 'https://three.ws/cdn/sample-room-walkthrough.mp4',
mode: 'streaming',
eta_seconds: 180,
},
// Mirrors mintTokenized3dAsset()'s structuredContent in api/_mcp/tools/tokenize.js.
mint_3d_asset: {
status: 'minted',
idempotent: false,
name: 'Midnight Robot',
network: 'devnet',
mint: 'M1ntExamp1eDoNotUse1111111111111111111111111',
explorer_asset_url: 'https://core.metaplex.com/explorer/M1ntExamp1eDoNotUse1111111111111111111111111?env=devnet',
explorer_tx_url: 'https://explorer.solana.com/tx/5synthetictransactionsignature111111111111111111111111111111111111111111111111111111?cluster=devnet',
viewer_url: 'https://three.ws/viewer?src=https%3A%2F%2Fthree.ws%2Fcdn%2Favatars%2Fmidnight-robot.glb',
royalty: { percent: 5, requested_basis_points: 500, cap_basis_points: 1000, capped: false },
},
// Mirrors handleAnchor()'s structuredContent in api/_mcp3d/tools/provenance.js.
anchor_provenance: {
status: 'anchored',
glbSha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
credentialHash: '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
issuer: 'AtteStIssuerExamp1eDoNotUse11111111111111111',
anchor: {
tx: '5synthetictransactionsignature111111111111111111111111111111111111111111111111111111',
cluster: 'devnet',
explorerUrl: 'https://explorer.solana.com/tx/5synthetictransactionsignature111111111111111111111111111111111111111111111111111111?cluster=devnet',
},
},
});
// Wrap a tool result summary in the JSON-RPC CallToolResult envelope.
function mcpResultExample(summary) {
return {
jsonrpc: '2.0',
id: 1,
result: { content: [{ type: 'text', text: JSON.stringify(summary) }] },
};
}
// Backfill bazaar.info.output.example on one resource that lacks it, from the
// maps above. Mutates the already-built bazaar extension in place (the root info
// schema permits the extra `output` field — verified against both the REST and
// MCP meta-schemas) and returns the resource so it composes as an array .map().
// Resources that already carry an output example (the /api/mcp + /api/mcp-3d
// transport rows) are left untouched. Agent-published dynamic listings get a
// generic settled-result example so they catalog fully too.
function addOutputExample(r) {
const info = r?.extensions?.bazaar?.info;
if (!info || info.output?.example !== undefined) return r;
let example;
if (r.toolName && MCP_TOOL_OUTPUT_SUMMARIES[r.toolName]) {
example = mcpResultExample(MCP_TOOL_OUTPUT_SUMMARIES[r.toolName]);
} else if (REST_OUTPUT_EXAMPLES[r.path]) {
example = REST_OUTPUT_EXAMPLES[r.path];
} else if (typeof r.path === 'string' && r.path.startsWith('/api/x402/service/')) {
// Agent-published listing: the response shape is the agent's own, so
// advertise a generic settled envelope rather than a fabricated body.
example = { ok: true, paid: true, result: {} };
}
if (example !== undefined) info.output = { type: 'json', example };
return r;
}
// Builds the full x402 discovery document served at /.well-known/x402.json.
// Exported so the self-facilitator's GET /discovery/resources action
// (api/x402-facilitator/[action].js) can project the same catalog into the
// facilitator-standard ListDiscoveryResourcesResponse consumed by x402scan's
// crawler — one catalog, two wire formats, no drift.
export async function buildX402DiscoveryDoc() {
const origin = env.APP_ORIGIN;
const mcpUrl = `${origin}/api/mcp`;
const mcp3dUrl = `${origin}/api/mcp-3d`;
const price = RAW_AMOUNT_TO_USDC(env.X402_MAX_AMOUNT_REQUIRED);
// Build the MCP accept list (Base + Solana). `resource` is echoed on every
// accept so reviewers + spend logs can reconcile the entry against the
// resource it gates without walking back to the parent resource[] entry.
function buildMcpAccepts(resourceUrl) {
const out = [];
// Solana-first platform default — Solana leads, Base follows. Gated on
// solanaSettleable() so the catalog never advertises a Solana rail the live
// 402 drops when the self-facilitator's co-signing secret is missing.
if (env.X402_PAY_TO_SOLANA && solanaSettleable()) {
out.push({
scheme: 'exact',
network: NETWORK_SOLANA_MAINNET,
network_label: 'solana-mainnet',
amount: env.X402_MAX_AMOUNT_REQUIRED,
price,
payTo: env.X402_PAY_TO_SOLANA,
asset: env.X402_ASSET_MINT_SOLANA,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
});
}
// Base only when settleable (CDP creds or the X402_ADVERTISE_BASE opt-in) —
// else the catalog would advertise a rail the live 402 now drops. See baseSettleable().
if (env.X402_PAY_TO_BASE && baseSettleable()) {
pushAcceptWithPermit2Sibling(out, {
scheme: 'exact',
network: NETWORK_BASE_MAINNET,
network_label: 'base-mainnet',
amount: env.X402_MAX_AMOUNT_REQUIRED,
price,
payTo: env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', version: '2', decimals: 6 },
});
}
return out;
}
// model-check is CDP-Bazaar-cataloged.
// CDP supports Base mainnet + Arbitrum One; advertise both here so
// agentic.market shows the same network options buyers will see in the
// live 402 challenge. Each EVM entry gets a Permit2 sibling so
// EIP-2612-aware clients can pick the gasless Permit2-via-EIP-2612 path.
const ARB_USDC = env.X402_ASSET_ADDRESS_ARBITRUM;
function buildBazaarAccepts(resourceUrl) {
const out = [];
// Solana-first platform default — Solana leads the catalog entry. The
// Base + Arbitrum accepts still follow so CDP keeps processing an EVM
// verify+settle for agentic.market cataloging.
if (env.X402_PAY_TO_SOLANA) {
out.push({
scheme: 'exact',
network: NETWORK_SOLANA_MAINNET,
network_label: 'solana-mainnet',
amount: env.X402_MAX_AMOUNT_REQUIRED,
price,
payTo: env.X402_PAY_TO_SOLANA,
asset: env.X402_ASSET_MINT_SOLANA,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', decimals: 6, feePayer: env.X402_FEE_PAYER_SOLANA },
});
}
// Base + Arbitrum are CDP-settled EVM rails; advertise them only when a
// working facilitator is configured (CDP creds or the X402_ADVERTISE_BASE
// opt-in). Without one the live 402 drops Base, so an ungated catalog entry
// would drift and 502.
if (env.X402_PAY_TO_BASE && baseSettleable()) {
pushAcceptWithPermit2Sibling(out, {
scheme: 'exact',
network: NETWORK_BASE_MAINNET,
network_label: 'base-mainnet',
amount: env.X402_MAX_AMOUNT_REQUIRED,
price,
payTo: env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', version: '2', decimals: 6 },
});
}
if (env.X402_PAY_TO_BASE && ARB_USDC && baseSettleable()) {
pushAcceptWithPermit2Sibling(out, {
scheme: 'exact',
network: 'eip155:42161',
network_label: 'arbitrum-one',
amount: env.X402_MAX_AMOUNT_REQUIRED,
price,
payTo: env.X402_PAY_TO_BASE,
asset: ARB_USDC,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', version: '2', decimals: 6 },
});
}
return out;
}
const mcpAccepts = buildMcpAccepts(mcpUrl);
const mcp3dAccepts = buildMcpAccepts(mcp3dUrl);
// Service metadata for the two MCP transport entries. Every static
// /api/x402/* resource entry now derives from the unified service catalog
// (api/_lib/service-catalog/) — its per-service descriptors carry each
// route's serviceName/tags, which used to be mapped inline here.
const mcpService = withService({
serviceName: 'three.ws MCP',
tags: ['mcp', '3d', 'gltf', 'solana', 'agent'],
});
// USE-13: per-tool MCP catalog entries. Each priced tool is its own
// catalog row keyed on (resource, toolName) so search can find them
// individually instead of all hiding behind the parent /api/mcp resource.
// Built from the live TOOL_CATALOG so adding a new priced tool only
// requires a pricing entry; the discovery shape follows automatically.
const mcpToolItems = buildMcpToolItems({
path: '/api/mcp',
mcpUrl,
mcpAccepts,
mcpService,
catalog: TOOL_CATALOG,
priceForTool: priceFor,
});
// 3D Studio paid tools — one row per priced tool so "text to 3d" searches
// on facilitators land on the tool, not just the transport. Service
// identity comes from STUDIO_CHALLENGE (same source as the live 402).
const studioService = {
serviceName: STUDIO_CHALLENGE.serviceName,
tags: STUDIO_CHALLENGE.tags,
iconUrl: STUDIO_CHALLENGE.iconUrl,
};
const studioToolItems = buildMcpToolItems({
path: '/api/mcp-3d',
mcpUrl: mcp3dUrl,
mcpAccepts: mcp3dAccepts,
mcpService: studioService,
catalog: STUDIO_TOOL_CATALOG,
priceForTool: studioPriceFor,
});
// Every static /api/x402/* resource entry, derived from the unified
// service catalog (one descriptor per service — the single source of truth
// both storefronts read; see specs/service-catalog.md). The env-aware
// accepts builders stay here so the advertised rails keep matching the
// live 402 exactly.
const x402CatalogItems = toBazaarDiscovery({
origin,
extensionsForAccepts,
acceptsFor(service, url) {
// model-check is CDP-Bazaar-cataloged: Base + Arbitrum + Solana.
if (service.acceptsBuilder === 'cdp-bazaar') return buildBazaarAccepts(url);
if (service.acceptsBuilder === 'permit2-only') {
// Permit2-only demo: skip the EIP-3009 entry that acceptsForPrice
// would push first, so SDK clients are forced through the gasless
// EIP-2612 → settleWithPermit path the endpoint is meant to prove.
// permit2VariantOf returns null without CDP creds, in which case we
// omit the resource from discovery (matches the runtime 402 behavior).
const baseAccept = env.X402_PAY_TO_BASE
? {
scheme: 'exact',
network: NETWORK_BASE_MAINNET,
network_label: 'base-mainnet',
amount: service.priceAtomics,
price: RAW_AMOUNT_TO_USDC(service.priceAtomics),
payTo: env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
asset_symbol: 'USDC',
maxTimeoutSeconds: 60,
resource: url,
extra: { name: 'USD Coin', version: '2', decimals: 6 },
}
: null;
const permit2 = baseAccept ? permit2VariantOf(baseAccept) : null;
return permit2 ? [permit2] : null;
}
return acceptsForPrice(service.priceAtomics, url);
},
});
// Agent-published paid services — dynamic, one entry per active listing.
const agentServiceItems = await buildAgentServiceItems(origin);
const sellableAgentItems = await buildSellableAgentItems();
const datapointItems = await buildDatapointItems(origin);
return {
$schema: 'https://x402.org/schemas/discovery.json',
service: {
name: 'three.ws',
legal_name: 'three.ws',
tagline: '3D generation + crypto data + launch/trust tools for AI agents.',
description:
'three.ws — 3D generation + crypto data + launch/trust tools for AI agents. ' +
'Free Crypto Data API (token snapshots, security checks, holders, whales, trending, wallets — keyless) and free text→3D generation; ' +
'pay-per-call for Forge Pro, rigged avatars, vanity addresses, pump.fun token launches, and cross-chain trust checks (agent reputation, on-chain identity verify). ' +
'Reachable as paid REST endpoints (x402 v2) and MCP tool calls. USDC on Solana, Base, and Arbitrum mainnet.',
operator: 'three.ws',
mission:
'Give autonomous agents the tools they reach for mid-task — 3D assets, crypto data, launches, and trust — machine-native over HTTP 402.',
website: origin,
docs: `${origin}/docs/start-here`,
skill_md: `${origin}/.well-known/skill.md`,
repository: 'https://github.com/nirholas/three.ws',
contact: `${origin}/`,
tags: [
'x402',
'x402-v2',
'mcp',
'agent-first',
'3d',
'text-to-3d',
'crypto-data',
'trust',
'token-launch',
'solana',
'base',
'arbitrum',
'usdc',
],
categories: ['3D', 'AI', 'Crypto', 'Data', 'Utility'],
environment: 'apex',
origin,
},
// `.filter(Boolean)` drops any resource whose IIFE returned null —
// e.g. permit2-paid-demo is omitted when CDP creds are missing,
// matching the runtime 402 behavior so we don't catalog a route that
// would fail at first paid call. The trailing .map(addOutputExample)
// backfills a realistic response example onto every entry so indexers
// render and rank each one (no empty result cards, no verifier warnings).
resources: [
{
path: '/api/mcp',
url: mcpUrl,
method: 'POST',
description:
'MCP 2025-06-18 Streamable HTTP transport — 3D avatar viewer, glTF model validation/inspection/optimization, and Solana agent data exposed as MCP tools. JSON-RPC 2.0 batch-aware. Currency: USDC.',
mimeType: 'application/json',
serviceName: mcpService.serviceName,
tags: mcpService.tags,
iconUrl: mcpService.iconUrl,
accepts: mcpAccepts,
extensions: extensionsForAccepts(mcpAccepts, bazaarExtension()),
links: {
openapi: `${origin}/openapi.json`,
docs: `${origin}/docs/mcp`,
agent_card: `${origin}/.well-known/agent-card.json`,
payment_config: `${origin}/.well-known/x402`,
},
},
{
path: '/api/mcp-3d',
url: mcp3dUrl,
method: 'POST',
description: STUDIO_CHALLENGE.description,
mimeType: 'application/json',
serviceName: STUDIO_CHALLENGE.serviceName,
tags: STUDIO_CHALLENGE.tags,
iconUrl: STUDIO_CHALLENGE.iconUrl,
accepts: mcp3dAccepts,
extensions: extensionsForAccepts(mcp3dAccepts, STUDIO_CHALLENGE.bazaar),
links: {
docs: `${origin}/docs/mcp-3d-studio`,
payment_config: `${origin}/.well-known/x402`,
},
},
// Every static /api/x402/* entry (model-check through wallet-connect),
// generated from the unified service catalog in catalog order. Editing
// a listing = editing api/_lib/service-catalog/services/<slug>.js.
...x402CatalogItems,
// USE-13: one Bazaar catalog row per priced MCP tool. The shared
// `/api/mcp` and `/api/mcp-3d` resources above are the transport
// entries; these are the individual paid tools facilitators
// index by toolName.
...mcpToolItems,
...studioToolItems,
// Agent-published paid endpoints (monetize_endpoint). Dynamic —
// one entry per active agent_paid_services listing.
...agentServiceItems,
// Whole agents sold as paid APIs (Earn tab switch). Dynamic, one
// entry per public agent whose owner turned the service on.
...sellableAgentItems,
// Datapoint fabric (/api/x402/d/…): a curated, runtime-derived
// slice of the 400k+ addressable single-datapoint endpoints, so
// indexers surface the fabric; the full id space is enumerated
// free at /api/x402/d.
...datapointItems,
]
.filter(Boolean)
.map(addOutputExample),
};
}
async function handleX402Discovery(req, res) {
return json(res, 200, await buildX402DiscoveryDoc(), {
'cache-control': 'public, max-age=300',
});
}
// ── dispatcher ────────────────────────────────────────────────────────────────
// LobeChat manifest. Single source of truth is the static file at
// public/lobehub/plugin.json (also served by /api/lobehub/manifest); this
// alias serves it at the /.well-known/chat-plugin.json URL the chat-plugin
// README documents for the LobeChat plugin-store install flow. It previously
// served a hardcoded pre-launch manifest with no `api` tools and no `ui.url`,
// which installed as a plugin that could do nothing.
let lobeChatManifest;
try {
lobeChatManifest = JSON.parse(
readFileSync(join(process.cwd(), 'public/lobehub/plugin.json'), 'utf8'),
);
} catch (err) {
console.error('[wk/chat-plugin] failed to load manifest', err);
}
function handleChatPlugin(req, res) {
if (!lobeChatManifest) return error(res, 500, 'internal_error', 'manifest unavailable');
return json(res, 200, lobeChatManifest, { 'cache-control': 'public, max-age=3600' });
}
// SperaxOS / plugin.delivery manifest. Single source of truth is the static
// file at public/sperax/manifest.json (also served verbatim at /sperax/manifest.json);
// this alias adds cross-origin headers so the marketplace + browser validators
// can fetch it from /.well-known/sperax-plugin.json.
let speraxManifest;
try {
speraxManifest = JSON.parse(
readFileSync(join(process.cwd(), 'public/sperax/manifest.json'), 'utf8'),
);
} catch (err) {
console.error('[wk/sperax-plugin] failed to load manifest', err);
}
function handleSperaxPlugin(req, res) {
if (!speraxManifest) return error(res, 500, 'internal_error', 'manifest unavailable');
return json(res, 200, speraxManifest, { 'cache-control': 'public, max-age=3600' });
}
// ── three-vanity (/.well-known/three-vanity.json) ────────────────────────────
// Publishes the provably-fair vanity grinder's service identity: the long-lived
// Ed25519 public key that signs every verifiable-grind receipt, the protocol
// version, and the scheme ids. The SDK + CLI + /vanity/verify page pin this key
// so a buyer can prove a receipt really came from three.ws. The SECRET seed
// never leaves the server — only the public key is published here.
async function handleThreeVanity(req, res) {
let identity;
try {
const mod = await import('./_lib/vanity-service-key.js');
identity = await mod.getServiceIdentity();
} catch (err) {
console.error('[wk/three-vanity] service key unavailable', err?.message || err);
return error(res, 500, 'service_key_unavailable', 'vanity service key not configured');
}
const origin = env.APP_ORIGIN;
return json(
res,
200,
{
protocol: 'three-vanity/v1',
protocols: ['three-vanity/v1', 'three-pog/v1'],
description:
'Provably-fair Solana vanity grinding. Keys are ground under a commit-reveal ' +
'seed-mixing protocol (three-vanity/v1) and/or attested with a proof-of-grind ' +
'certificate (three-pog/v1). Both are signed by the attestation key below and ' +
'verified entirely client-side — nothing here is trusted, everything is recomputed.',
serviceKey: {
curve: 'ed25519',
keyId: identity.keyId,
publicKeyBase58: identity.publicKeyBase58,
publicKeyHex: identity.publicKeyHex,
use: 'receipt-signing, proof-of-grind-attestation',
},
// Rotation-aware verifier keyring: the set of attestation keys a verifier
// should accept. On rotation, the retiring key stays here (with a
// `retired` flag/date) until all in-flight certs age out, so historical
// proofs keep verifying. Today there is one active key.
keyring: [
{
keyId: identity.keyId,
curve: 'ed25519',
publicKeyBase58: identity.publicKeyBase58,
status: 'active',
},
],
schemes: {
commitment: 'sha256(domain‖serverSeed)',
seedMix: 'hkdf-sha256(serverSeed‖clientSeed‖requestNonce)',
candidate: 'hmac-sha256(masterSeed, domain‖uint64_be(index)) → ed25519 seed',
signature: 'ed25519',
sealedEnvelope: 'x25519-hkdf-sha256-aes256gcm/v1',
proofOfGrind: 'ed25519 over canonical(three-pog/cert/v1 ‖ sorted-json(core))',
splitKeyNonCustody: 'P1 + a2·B == address (recomputed from public points)',
},
endpoints: {
grind: `${origin}/api/x402/vanity`,
verifiableGrind: `${origin}/api/x402/vanity-verifiable`,
certRegistry: `${origin}/api/vanity/cert`,
verifyPage: `${origin}/vanity/verify`,
},
documentation: `${origin}/vanity/verify`,
protocolSpec: 'https://github.com/nirholas/three.ws/blob/main/docs/PROTOCOL-vanity.md',
},
{ 'cache-control': 'public, max-age=300' },
);
}
// ── apple-app-site-association (/.well-known/apple-app-site-association) ──────
//
// The file iOS fetches to decide whether a https://three.ws link opens the app
// instead of Safari (universal links) and whether the login form in the app's
// WebView may offer a saved three.ws password (webcredentials). Apple's CDN
// requires it over TLS at exactly this path, with no redirect, no .json
// extension, and a JSON content type; every one of those is why it is served
// from here rather than dropped in public/.well-known/ next to assetlinks.json,
// which the static route would hand back with the wrong headers.
//
// The app identifier is "<TeamID>.<bundle id>" and the Team ID is only knowable
// once the Apple Developer account exists, so it comes from APPLE_TEAM_ID on the
// Cloud Run service. Until that is set the endpoint answers 503 rather than
// publishing an association for a team that cannot sign anything: a wrong
// appIDs entry fails silently on device (links just keep opening in Safari),
// and an honest 503 is the only version of this that is debuggable.
const IOS_BUNDLE_ID = 'ws.three.app';
function handleAppleAppSiteAssociation(req, res) {
const teamId = env.APPLE_TEAM_ID;
if (!teamId) {
return error(
res,
503,
'not_configured',
'APPLE_TEAM_ID is not set on this deployment, so no app association can be published',
);
}
const appId = `${teamId}.${IOS_BUNDLE_ID}`;
return json(
res,
200,
{
applinks: {
details: [
{
appIDs: [appId],
components: [
// The API is data, not a screen. Handing /api/* to the app
// would swallow OAuth redirects and x402 callbacks that have
// to complete in the browser that started them.
{ '/': '/api/*', exclude: true, comment: 'API surface stays in the browser' },
// Embeds are meant to render inside someone else's page.
{ '/': '/embed*', exclude: true, comment: 'third-party embeds stay on the web' },
{ '/': '/widget*', exclude: true, comment: 'third-party embeds stay on the web' },
{ '/': '/*' },
],
},
],
},
webcredentials: { apps: [appId] },
},
{
// Apple caches this aggressively at the CDN either way; a short TTL keeps
// a Team ID correction from taking a day to reach devices.
'cache-control': 'public, max-age=300',
},
);
}
const DISPATCH = {
'agent-attestation-schemas': handleAttestationSchemas,
'three-vanity': handleThreeVanity,
'chat-plugin': handleChatPlugin,
'sperax-plugin': handleSperaxPlugin,
'oauth-authorization-server': handleOauthAuthServer,
'oauth-protected-resource': handleOauthProtectedResource,
x402: handleX402,
'x402-discovery': handleX402Discovery,
'apple-app-site-association': handleAppleAppSiteAssociation,
};
// Public discovery docs (x402, x402-discovery, chat-plugin, agent-attestation-schemas)
// must be readable cross-origin so browser-based validators (agentic.market,
// x402scan, bazaar) can fetch them. OAuth metadata stays restricted.
const PUBLIC_DISCOVERY = new Set([
'x402',
'x402-discovery',
'chat-plugin',
'sperax-plugin',
'agent-attestation-schemas',
'three-vanity',
]);
export default wrap(async (req, res) => {
const name = req.query?.name ?? new URL(req.url, 'http://x').searchParams.get('name');
const corsOpts = PUBLIC_DISCOVERY.has(name)
? { methods: 'GET,OPTIONS', origins: '*' }
: { methods: 'GET,OPTIONS' };
if (cors(req, res, corsOpts)) return;
if (!method(req, res, ['GET'])) return;
const fn = Object.hasOwn(DISPATCH, name) ? DISPATCH[name] : null;
// Echo at most a label's worth of the caller's input. Unbounded reflection let
// a 5 KB ?name= come straight back in the 404 body (and into the access log),
// which is free amplification for anyone pointing a scraper at /.well-known.
if (!fn) return error(res, 404, 'not_found', `unknown well-known resource: ${String(name ?? 'null').slice(0, 64)}`);
return fn(req, res);
});