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.

58.1 KB
Raw Blame
// GET /openapi.json — x402 OpenAPI discovery document
// Preferred over /.well-known/x402 by x402scan and AgentCash (agentcash.dev).
//
// AgentCash's @agentcash/discovery validator reads payable operations from
// here. For an operation's `x-payment-info` to parse, BOTH `price` and
// `protocols` must be present (StructuredPaymentInfoSchema requires the pair) —
// a structured `price` object with no sibling `protocols` is silently dropped,
// reported as PRICE_MISSING_ON_PAID + PROTOCOLS_MISSING_ON_PAID. We advertise
// only x402 because that is the rail this server actually settles (Base /
// Arbitrum / Solana / BSC USDC via the facilitators in api/_lib/x402-spec.js).
// MPP (Stripe/Tempo) is not implemented, so it is intentionally not advertised
// — discovery must never point agents at a payment rail we cannot honor.

import { env } from './_lib/env.js';
import { cors, json, method, wrap } from './_lib/http.js';
import { providerCatalog } from './v1/_providers.js';
import { PAID_SERVICES } from './_lib/service-catalog/services/index.js';
import { agentsV1Paths, AGENTS_V1_TAGS } from './_lib/agents-v1/openapi.js';

// Single source of truth for the protocol list on every paid operation. Each
// entry is one supported payment protocol; per-network payment lanes (Base /
// Solana / Arbitrum / BSC USDC) are advertised at runtime in the 402 challenge
// `accepts[]` array — see api/_lib/x402-spec.js `paymentRequirements()`.
const X402_PROTOCOLS = [{ x402: {} }];

// Every /api/x402/* operation is gated by payment, not by a credential: the
// caller settles the 402 challenge in USDC and needs no key, token, or account.
// OpenAPI spells that out as an explicit empty security list, and declaring it
// beats omitting `security` twice over. An operation with no `security` inherits
// the root-level list, which this document deliberately does not set, so
// validators report undefined auth; and agent tooling that infers an auth mode
// from the security list reads the omission as "unknown" rather than "public,
// pay-per-call". Payment stays advertised where it belongs: each operation's
// `x-payment-info` plus its documented 402 response.
const PAYMENT_ONLY_SECURITY = [];

// USDC atomics (6 decimals) → a decimal string, trimmed to the shortest
// precision that round-trips (min 2 places) — mirrors the formatting already
// used by hand-authored entries below ('0.001', '5.00', …).
function formatUsd(atomics) {
	const n = Number(atomics) / 1e6;
	if (!Number.isFinite(n)) return '0.00';
	let s = n.toFixed(6).replace(/0+$/, '').replace(/\.$/, '');
	const [, dec = ''] = s.split('.');
	if (!s.includes('.')) s += '.00';
	else if (dec.length < 2) s += '0'.repeat(2 - dec.length);
	return s;
}

// GET /api/v1/x/{provider}/{endpoint} paths, rendered live from the registry
// (api/v1/_providers.js `providerCatalog()`) — never hand-enumerated, so this
// document can never drift from the real aggregated endpoint surface no
// matter which provider prompts have or haven't landed. See docs/api-
// reference.md "Unified API — /api/v1/x aggregator" for the full billing-lane
// writeup and the public storefront at /crypto-api.
function aggregatorPaths() {
	const paths = {};
	for (const provider of providerCatalog()) {
		for (const ep of provider.endpoints) {
			const priceUsd = formatUsd(ep.price_usdc_atomics);
			const billing =
				'Billing lanes, in order: ' +
				(ep.free
					? `free tier (${ep.free.perMin}/min, ${ep.free.perDay}/day per IP, no credentials) → `
					: '') +
				`x402 pay-per-call ($${priceUsd} USDC via HTTP 402, no credentials) — or send your own upstream ` +
				`key via BYOK, or authenticate with a three.ws API key / OAuth session / browser session for the plan lane.`;
			const description = `${ep.summary} ${billing}`;

			const operation = {
				operationId: `v1_x_${provider.id}_${ep.id}`.replace(/[^a-zA-Z0-9_]/g, '_'),
				summary: `${provider.name}: ${ep.summary}`,
				description,
				tags: ['Crypto API (aggregator)'],
				// Free-tier endpoints declare `security: []` (explicitly public) and
				// carry NO x-payment-info: discovery auditors (x402scan's crawler,
				// @agentcash/discovery inferAuthMode) classify any operation with
				// x-payment-info as "paid" and then require a 402 on a bare probe —
				// but these answer a bare probe 200 from the free lane, so the paid
				// classification got all 29 skipped as "no valid x402 response"
				// during x402scan registration. Public + the billing prose above
				// registers them as public endpoints; the x402 overage lane still
				// exists at runtime and stays documented in `description`. Endpoints
				// with no free tier ARE pay-first (bare probe → 402), so they keep
				// structured x-payment-info (AgentCash) and the optional-auth modes.
				...(ep.free
					? { security: [] }
					: {
							security: [{}, { bearerAuth: [] }, { apiKeyAuth: [] }],
							'x-payment-info': {
								price: { mode: 'fixed', currency: 'USD', amount: priceUsd },
								protocols: X402_PROTOCOLS,
							},
						}),
				responses: {
					200: { description: 'Normalized upstream response, wrapped as { data, _meta }' },
					400: { description: 'Missing or invalid parameter' },
					402: { description: 'Payment Required (x402) — no credentials and free quota (if any) exhausted' },
					404: { description: 'Unknown provider/endpoint pair' },
					429: { description: 'Rate limited' },
				},
			};

			if (ep.method === 'POST') {
				operation.requestBody = {
					required: true,
					content: {
						'application/json': {
							schema: {
								type: 'object',
								description: Object.entries(ep.params || {})
									.map(([k, v]) => `${k}: ${v}`)
									.join('; ') || 'Forwarded as-is to the upstream JSON body.',
							},
						},
					},
				};
			} else {
				operation.parameters = Object.entries(ep.params || {}).map(([name, desc]) => ({
					name,
					in: 'query',
					required: typeof desc === 'string' && /\(required\)/.test(desc),
					schema: { type: 'string' },
					description: desc,
				}));
			}

			paths[ep.path] = { [ep.method.toLowerCase()]: operation };
		}
	}
	return paths;
}

// Every paid /api/x402/* operation, projected from the service catalog
// (api/_lib/service-catalog/services/), which is already the written-once
// source of truth the x402 discovery doc and the OKX storefront render from.
//
// Why this exists: the operations below used to be hand-authored one by one,
// and 24 of the catalog's 75 live paid services ever got an entry. That is not
// cosmetic. x402scan registers an origin by reading THIS document, and
// AgentCash's validator reads payable operations from it too, so a service
// missing here is a service neither directory can list no matter how valid its
// live 402 challenge is (measured 2026-09-02: 52 live paid endpoints answered a
// spec-valid 402 in production while being absent from both this document and
// the x402scan origin listing).
//
// The projection is spread BEFORE the hand-authored paths, so any route with a
// richer hand-written operation keeps it verbatim and this only fills the gaps.
//
// A service with `free: true` (a daily per-IP quota in front of the same x402
// lane, e.g. the keyless x402-suite ports) used to be skipped here entirely,
// so its route never appeared in this document at all. That is strictly worse
// than the aggregator's own free-tier handling just above: a bare probe can
// legitimately answer 200 while quota remains, so it keeps `security: []` and
// no `x-payment-info` for the same reason given in aggregatorPaths() above
// (x402scan's crawler classifies any x-payment-info operation as paid and
// then requires a 402 on a bare probe), but it now gets a path entry, with
// the free-then-paid billing lanes already spelled out in `service.description`.
function catalogPaidPaths() {
	const paths = {};
	for (const service of PAID_SERVICES) {
		if (service.status !== 'live') continue;
		// Same gate the hand-authored permit2 entry below applies: the Permit2-only
		// lane is unpayable without CDP credentials, so never advertise it then.
		if (
			service.acceptsBuilder === 'permit2-only' &&
			!(env.CDP_API_KEY_ID && env.CDP_API_KEY_SECRET)
		)
			continue;

		const operation = {
			operationId: `x402_${service.slug.replace(/-/g, '_')}`,
			security: service.free ? [] : PAYMENT_ONLY_SECURITY,
			summary: `${service.free ? 'Free + paid' : 'Paid'}: ${service.title}`,
			description: service.description,
			responses: {
				200: { description: `${service.serviceName} result JSON` },
				400: { description: 'Validation error' },
				402: { description: 'Payment Required (x402)' },
			},
			...(service.free
				? {}
				: {
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: formatUsd(service.priceAtomics) },
							protocols: X402_PROTOCOLS,
						},
					}),
		};

		if (service.method === 'POST') {
			operation.requestBody = {
				required: true,
				content: {
					'application/json': {
						schema: service.inputSchema,
						...(service.input !== undefined ? { example: service.input } : {}),
					},
				},
			};
		} else {
			operation.parameters = queryParameters(service.inputSchema);
		}

		paths[service.path] = { [service.method.toLowerCase()]: operation };
	}
	return paths;
}

// A catalog descriptor's JSON Schema, flattened into OpenAPI query parameters.
// The per-property `description` moves up to the parameter (where tooling shows
// it) and the rest of the property schema rides along as the parameter schema,
// so enums, formats and defaults survive into the document.
function queryParameters(inputSchema) {
	const properties = inputSchema?.properties || {};
	const required = new Set(inputSchema?.required || []);
	return Object.entries(properties).map(([name, propertySchema]) => {
		const { description, ...schema } = propertySchema || {};
		return {
			name,
			in: 'query',
			required: required.has(name),
			schema: Object.keys(schema).length ? schema : { type: 'string' },
			...(description ? { description } : {}),
		};
	});
}


// Pure document builder, factored out so api/_lib/skill-md.js (the
// /skill.md generator) can read the exact same paid-operation catalog this
// endpoint serves, instead of re-deriving it or faking an HTTP round trip.
export function buildOpenApiDoc(origin = env.APP_ORIGIN) {
	return (
		{
			openapi: '3.1.0',
			info: {
				title: 'three.ws API',
				version: '1.0.0',
				description:
					'API for 3D avatar management, AI agent identity, and MCP tool access.',
				contact: {
					email: '[email protected]',
				},
				// Proprietary, not an SPDX identifier, so this carries `url` rather
				// than `license.identifier`. Generators that surface licensing (Redocly,
				// Scalar, SDK codegen) otherwise render the API as unlicensed, which
				// reads as "public domain" to anyone bundling our spec into a client.
				license: {
					name: 'Proprietary (all rights reserved)',
					url: 'https://github.com/nirholas/three.ws/blob/main/LICENSE',
				},
				'x-guidance':
					'Use POST /api/mcp to interact with the MCP server. Send a JSON-RPC 2.0 request body. ' +
					'Authenticate with a Bearer access token obtained via OAuth 2.1 at ' +
					origin +
					'/oauth/authorize, or use a Bearer API key from the dashboard. ' +
					'Available MCP tools: list_my_avatars, get_avatar, search_public_avatars, ' +
					'render_avatar, delete_avatar, validate_model, inspect_model, optimize_model. ' +
					'Paid REST endpoints under /api/x402/* settle in USDC over ' +
					'x402 (HTTP 402); pay programmatically with @x402/fetch — no API key required. ' +
					'GET /api/v1/x/{provider}/{endpoint} (tag "Crypto API (aggregator)" below) bundles ' +
					'CoinGecko, DefiLlama, Jupiter, DexScreener, Solana RPC and more behind one bill — ' +
					'free tier, BYOK, a three.ws plan, or x402, in that order. Storefront: ' +
					origin +
					'/crypto-api. Discovery: GET /api/v1/x.',
			},
			servers: [{ url: origin }],
			tags: [
				{
					name: 'Crypto API (aggregator)',
					description:
						'Third-party crypto/DeFi/on-chain APIs re-offered as one bill under /api/v1/x — ' +
						'rendered live from the provider registry (api/v1/_providers.js). See /crypto-api ' +
						'and docs/api-reference.md § Unified API.',
				},
				...AGENTS_V1_TAGS,
			],
			components: {
				securitySchemes: {
					bearerAuth: {
						type: 'http',
						scheme: 'bearer',
						description:
							'Bearer token in the Authorization header. Obtain one via OAuth 2.1 at ' +
							origin +
							'/oauth/authorize, use an API key from the dashboard, or exchange a ' +
							'wallet SIWX (CAIP-122) session for an access token.',
					},
					// Dashboard-issued API key, sent as `Authorization: Bearer <key>`.
					// Declared as an apiKey scheme (in addition to bearerAuth) so agent
					// tooling — which classifies an operation's auth mode from the
					// security scheme `type` — recognizes these routes as key-protected
					// rather than reporting "no auth mode". Functionally equivalent to a
					// bearer token for programmatic callers that prefer a static key.
					apiKeyAuth: {
						type: 'apiKey',
						in: 'header',
						name: 'Authorization',
						description:
							'Dashboard API key sent as `Authorization: Bearer <key>`. Equivalent ' +
							'to the OAuth bearer token; intended for programmatic agents.',
					},
				},
			},
			paths: {
				// Rendered live from the provider registry — see aggregatorPaths()
				// above. Spread first so a duplicate key below always wins (none
				// today: aggregator paths live under /api/v1/x/*, hand-authored
				// paths don't).
				...aggregatorPaths(),
				// Projected from the service catalog, spread before the hand-authored
				// operations below so a richer hand-written entry always wins.
				...catalogPaidPaths(),
				...agentsV1Paths(),
				'/api/mcp': {
					post: {
						operationId: 'mcp_call',
						summary: 'MCP tool call',
						description:
							'JSON-RPC 2.0 request to the MCP server. Supports tools for 3D avatar management, model validation, inspection, and optimization.',
						// Pay-first, credentials optional: the same shape the aggregator's
						// paid lanes use above. A bare probe answers 402 with a full x402
						// challenge, so a caller settles in USDC and needs no key, token,
						// or account; a bearer token or API key is accepted but never
						// required. Listing only the two credential schemes (no leading
						// `{}`) reads to OpenAPI tooling as "auth is mandatory, pick one",
						// which sends agents off to obtain a token they do not need.
						security: [{}, { bearerAuth: [] }, { apiKeyAuth: [] }],
						requestBody: {
							required: true,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										required: ['jsonrpc', 'method'],
										properties: {
											jsonrpc: {
												type: 'string',
												enum: ['2.0'],
											},
											id: {
												oneOf: [{ type: 'string' }, { type: 'number' }],
											},
											method: {
												type: 'string',
												description:
													'MCP method name, e.g. "tools/call" or "initialize".',
											},
											params: {
												type: 'object',
												description: 'Method-specific parameters.',
											},
										},
									},
								},
							},
						},
						responses: {
							200: { description: 'JSON-RPC 2.0 response' },
							401: { description: 'Unauthorized — missing or invalid token' },
							402: { description: 'Payment Required' },
							429: { description: 'Rate limited' },
						},
						'x-payment-info': {
							price: {
								mode: 'fixed',
								currency: 'USD',
								amount: '0.001',
							},
							protocols: X402_PROTOCOLS,
						},
					},
					// Session teardown, part of the MCP Streamable HTTP transport and
					// advertised in this route's own `allow` header. The server is
					// stateless per request; the Mcp-Session-Id it issues on initialize
					// only attributes calls to a client, so ending one answers 204. Any
					// other id names a session this server never issued and gets the
					// transport's 404 "start a new session" instead.
					delete: {
						operationId: 'mcp_terminate_session',
						security: [],
						summary: 'Terminate an MCP session',
						description:
							'Ends the caller\'s MCP session. This server handles every request statelessly, so no session state is held and a plain DELETE is a successful no-op.',
						parameters: [
							{
								name: 'Mcp-Session-Id',
								in: 'header',
								required: false,
								schema: { type: 'string' },
								description:
									'Session to end: the Mcp-Session-Id this server returned on initialize. Any other value names a session it does not hold.',
							},
						],
						responses: {
							204: { description: 'Session ended; no content' },
							404: {
								description:
									'Unknown session: the supplied Mcp-Session-Id was never issued by this server, so the client should start a new session',
							},
						},
					},
				},
				'/api/avatars': {
					get: {
						operationId: 'list_avatars',
						summary: 'List my avatars',
						security: [{ bearerAuth: [] }, { apiKeyAuth: [] }],
						responses: {
							200: { description: 'Array of avatar objects' },
							401: { description: 'Unauthorized' },
						},
					},
					post: {
						operationId: 'create_avatar',
						summary: 'Register an uploaded avatar',
						security: [{ bearerAuth: [] }, { apiKeyAuth: [] }],
						requestBody: {
							required: true,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										required: ['storage_key', 'name', 'content_type'],
										properties: {
											storage_key: { type: 'string' },
											name: { type: 'string', maxLength: 100 },
											description: { type: 'string', maxLength: 500 },
											content_type: {
												type: 'string',
												enum: ['model/gltf-binary', 'model/gltf+json'],
											},
											visibility: {
												type: 'string',
												enum: ['private', 'unlisted', 'public'],
											},
											tags: {
												type: 'array',
												items: { type: 'string' },
											},
										},
									},
								},
							},
						},
						responses: {
							201: { description: 'Avatar created' },
							401: { description: 'Unauthorized' },
						},
					},
				},
				'/api/avatars/public': {
					get: {
						operationId: 'browse_public_avatars',
						summary: 'Browse public avatars',
						security: [],
						parameters: [
							{ name: 'q', in: 'query', schema: { type: 'string' } },
							{
								name: 'limit',
								in: 'query',
								schema: { type: 'integer', default: 20, maximum: 100 },
							},
							{ name: 'cursor', in: 'query', schema: { type: 'string' } },
						],
						responses: {
							200: { description: 'Paginated list of public avatars' },
							405: { description: 'Method not allowed (GET only)' },
						},
					},
				},
				'/api/agents': {
					get: {
						operationId: 'list_agents',
						summary: 'List my agents',
						security: [{ bearerAuth: [] }, { apiKeyAuth: [] }],
						responses: {
							200: { description: 'Array of agent identity objects' },
							401: { description: 'Unauthorized' },
						},
					},
				},
				'/api/healthz': {
					get: {
						operationId: 'healthz',
						summary: 'Service liveness',
						description:
							'Lightweight liveness probe with uptime + service version. No auth.',
						security: [],
						responses: {
							200: { description: 'Health summary JSON' },
							405: { description: 'Method not allowed (GET only)' },
						},
					},
				},
				'/api/pump/curve': {
					get: {
						operationId: 'pump_curve',
						summary: 'Pump.fun bonding-curve snapshot',
						description:
							'Returns raw bonding-curve state, current spot price + market cap, and graduation progress for a Pump.fun token. Public, edge-cached for 10s.',
						security: [],
						parameters: [
							{
								name: 'mint',
								in: 'query',
								required: true,
								schema: { type: 'string' },
								description: 'Base58 SPL mint address',
							},
							{
								name: 'network',
								in: 'query',
								schema: { type: 'string', enum: ['mainnet', 'devnet'] },
							},
						],
						responses: {
							200: { description: 'Bonding curve snapshot' },
							400: { description: 'Bad mint' },
							404: { description: 'No bonding curve for that mint' },
						},
					},
				},
				'/api/pump/quote-sdk': {
					get: {
						operationId: 'pump_quote_sdk',
						summary: 'Pump.fun buy/sell quote (SDK-precise)',
						description:
							'Deterministic buy or sell quote computed via @nirholas/pump-sdk on the live bonding curve. Returns output amount, price impact %, and a market context block.',
						security: [],
						parameters: [
							{
								name: 'mint',
								in: 'query',
								required: true,
								schema: { type: 'string' },
							},
							{
								name: 'side',
								in: 'query',
								required: true,
								schema: { type: 'string', enum: ['buy', 'sell'] },
							},
							{
								name: 'amount',
								in: 'query',
								required: true,
								schema: { type: 'number', minimum: 0 },
								description:
									'For buy: SOL. For sell: tokens (UI units, 6 decimals).',
							},
							{
								name: 'network',
								in: 'query',
								schema: { type: 'string', enum: ['mainnet', 'devnet'] },
							},
						],
						responses: {
							200: {
								description: 'Quote payload with input/output and priceImpactPct',
							},
							400: { description: 'Validation error' },
							404: { description: 'No bonding curve for that mint' },
						},
					},
				},
				'/api/x402/agent-reputation': {
					get: {
						operationId: 'x402_agent_reputation',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Agent Reputation snapshot',
						description:
							"Pay $0.01 USDC to retrieve a three.ws agent's reputation snapshot synthesized from pump_agent_payments, distribute/buyback success history, and signed Solana memo attestations.",
						parameters: [
							{
								name: 'agent_id',
								in: 'query',
								required: true,
								schema: { type: 'string', format: 'uuid' },
							},
						],
						responses: {
							200: { description: 'Reputation snapshot JSON' },
							400: { description: 'Missing or invalid agent_id' },
							402: { description: 'Payment Required (x402)' },
							404: { description: 'agent_id not found' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.01' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/onchain-identity-verify': {
					get: {
						operationId: 'x402_onchain_identity_verify',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Verify counterparty agent ownership claim',
						description:
							'Pay $0.005 USDC to verify whether a three.ws agent_id actually owns/deployed a given contract or mint on a given CAIP-2 chain, using the canonical meta.onchain unified index.',
						parameters: [
							{
								name: 'agent_id',
								in: 'query',
								required: true,
								schema: { type: 'string', format: 'uuid' },
							},
							{
								name: 'chain',
								in: 'query',
								required: true,
								schema: { type: 'string' },
							},
							{
								name: 'contract_or_mint',
								in: 'query',
								required: true,
								schema: { type: 'string' },
							},
						],
						responses: {
							200: { description: 'Verification result JSON' },
							400: { description: 'Missing or invalid parameters' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.005' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/pump-agent-audit': {
					get: {
						operationId: 'x402_pump_agent_audit',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Operational audit of a pump.fun agent-payments token',
						description:
							'Pay $0.02 USDC to retrieve a full operational audit of a pump.fun mint: USDC paid in, distinct payers, distribute/buyback success history, latest error reasons, and derived risk flags.',
						parameters: [
							{
								name: 'mint',
								in: 'query',
								required: true,
								schema: { type: 'string', minLength: 32, maxLength: 44 },
							},
						],
						responses: {
							200: { description: 'Audit JSON' },
							400: { description: 'Missing or invalid mint' },
							402: { description: 'Payment Required (x402)' },
							404: { description: 'Mint not indexed' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.02' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/skill-marketplace': {
					get: {
						operationId: 'x402_skill_marketplace',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Browse the three.ws skill marketplace',
						description:
							'Pay $0.001 USDC to list active skill listings with prices across all three.ws agents. Optional skill filter returns the cheapest provider for that capability.',
						parameters: [
							{ name: 'skill', in: 'query', schema: { type: 'string' } },
							{
								name: 'limit',
								in: 'query',
								schema: { type: 'integer', minimum: 1, maximum: 200 },
							},
						],
						responses: {
							200: { description: 'Marketplace listings JSON' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.001' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/symbol-availability': {
					get: {
						operationId: 'x402_symbol_availability',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Check pump.fun ticker collisions before launch',
						description:
							'Pay $0.001 USDC to check whether a candidate ticker collides with any three.ws-indexed pump.fun mint. Returns exact matches plus trigram-similar tickers and a recommendation.',
						parameters: [
							{
								name: 'ticker',
								in: 'query',
								required: true,
								schema: { type: 'string', minLength: 1, maxLength: 32 },
							},
							{
								name: 'network',
								in: 'query',
								schema: { type: 'string', enum: ['mainnet', 'devnet'] },
							},
						],
						responses: {
							200: { description: 'Symbol availability JSON' },
							400: { description: 'Missing or invalid ticker' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.001' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/mint-to-mesh-batch': {
					post: {
						operationId: 'x402_mint_to_mesh_batch',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Batch 1–10 mints → themed binary glTF cubes',
						description:
							'Pay $0.05 USDC to resolve 1–10 Solana SPL mints to themed binary glTF cubes in a single call. Per-mint failures report ok:false instead of failing the whole batch.',
						requestBody: {
							required: true,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										required: ['mints'],
										properties: {
											mints: {
												type: 'array',
												minItems: 1,
												maxItems: 10,
												items: {
													type: 'string',
													minLength: 32,
													maxLength: 44,
												},
											},
										},
									},
								},
							},
						},
						responses: {
							200: { description: 'Batch mesh JSON' },
							400: { description: 'Missing or invalid body' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.05' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/model-check': {
					get: {
						operationId: 'x402_model_check',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: glTF/GLB structural stats + optimization recommendations',
						description:
							'Pay $0.001 USDC to fetch a glTF/GLB model from a URL and return structural stats (vertex/triangle counts, materials, textures, animations, extensions) plus a prioritized list of optimization recommendations.',
						parameters: [
							{
								name: 'url',
								in: 'query',
								required: true,
								schema: { type: 'string', format: 'uri' },
								description: 'Public HTTPS URL of a glTF/GLB model.',
							},
						],
						responses: {
							200: { description: 'Inspection + recommendation JSON' },
							400: { description: 'Missing or invalid url' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.001' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/mint-to-mesh': {
					get: {
						operationId: 'x402_mint_to_mesh',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Single Solana mint → themed binary glTF cube',
						description:
							'Pay $0.001 USDC to resolve a Solana fungible-token mint to a binary glTF (GLB) cube themed for that token. Color is hashed from the mint; the Metaplex JSON image, when present, is embedded as a baseColor texture.',
						parameters: [
							{
								name: 'mint',
								in: 'query',
								required: true,
								schema: { type: 'string', minLength: 32, maxLength: 44 },
								description: 'Base58 SPL mint address on Solana mainnet.',
							},
						],
						responses: {
							200: { description: 'Themed GLB JSON envelope' },
							400: { description: 'Missing or invalid mint' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.001' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/forge': {
					// Free discovery lane. The handler answers GET with the price
					// catalog and input schema and never generates or charges, so an
					// agent can read the tiers before committing USDC. Documenting only
					// `post` hid that from every spec reader and made the free lane look
					// like an undocumented side effect.
					get: {
						operationId: 'x402_forge_pricing',
						security: [],
						summary: 'Forge pricing and input schema (free, no payment)',
						description:
							'Free price/usage discovery for the Forge generation lane. Returns the per-tier USDC pricing, the accepted request body schema, and the free poll endpoint. No payment, no credentials, and no generation. POST the same path to actually generate.',
						responses: {
							200: {
								description: 'Price catalog and input schema',
								content: {
									'application/json': {
										schema: {
											type: 'object',
											required: ['route', 'method', 'input_schema', 'pricing_usdc'],
											properties: {
												route: { type: 'string' },
												description: { type: 'string' },
												method: { type: 'string', description: 'The verb that performs generation: POST.' },
												input_schema: { type: 'object', description: 'JSON Schema for the POST request body.' },
												poll: { type: 'string', description: 'Free endpoint for polling a job to completion.' },
												pricing_usdc: {
													type: 'array',
													description: 'One entry per quality tier.',
													items: {
														type: 'object',
														required: ['tier', 'price_usdc'],
														properties: {
															tier: { type: 'string', enum: ['draft', 'standard', 'high'] },
															price_usdc: { type: 'string' },
														},
													},
												},
											},
										},
									},
								},
							},
							400: { description: 'A ?job= query landed here; poll on GET /api/forge?job=<id> instead' },
						},
					},
					post: {
						operationId: 'x402_forge_generate',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: text→3D / image→3D generation (returns a job token)',
						description:
							'Pay per quality tier in USDC ($0.05 draft / $0.15 standard / $0.50 high) to generate a 3D model. Submit a prompt for text→3D, or up to four public https reference views of one object for image→3D. Runs the FLUX→TRELLIS pipeline. The response returns a job token; poll it for FREE at GET /api/forge?job=<id> to retrieve the finished GLB URL. The 402 challenge quotes the exact price for the requested tier.',
						requestBody: {
							required: false,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										properties: {
											prompt: {
												type: 'string',
												minLength: 3,
												maxLength: 1000,
												description: 'Describe one subject for text→3D. Omit when supplying image_urls.',
											},
											image_urls: {
												type: 'array',
												items: { type: 'string', format: 'uri' },
												minItems: 1,
												maxItems: 6,
												description: 'Up to six public https reference views of one object for image→3D.',
											},
											tier: { type: 'string', enum: ['draft', 'standard', 'high'], default: 'standard' },
											aspect_ratio: { type: 'string', enum: ['1:1', '4:3', '3:4', '16:9', '9:16'], default: '1:1' },
										},
									},
								},
							},
						},
						responses: {
							200: {
								description: 'Generation job accepted; poll poll_url for the GLB',
								content: {
									'application/json': {
										schema: {
											type: 'object',
											required: ['job_id', 'status', 'poll_url'],
											properties: {
												job_id: { type: 'string' },
												status: { type: 'string' },
												poll_url: { type: 'string', description: 'Free, provider-aware status endpoint.' },
												mode: { type: 'string', enum: ['text_to_3d', 'image_to_3d'] },
												tier: { type: 'string' },
												backend: { type: 'string' },
												eta_seconds: { type: 'integer' },
												price_usdc: { type: 'string' },
											},
										},
									},
								},
							},
							400: { description: 'Missing or invalid input' },
							402: { description: 'Payment Required (x402)' },
							503: { description: 'Generation backend not configured' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.15' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				// Permit2 settlement runs exclusively through CDP's
				// x402ExactPermit2Proxy, so without CDP credentials the route's 402
				// carries an empty accepts[] — unpayable. Advertise it only when the
				// lane is actually honorable (same principle as omitting MPP above).
				...(env.CDP_API_KEY_ID && env.CDP_API_KEY_SECRET
					? {
							'/api/x402/permit2-paid-demo': {
								get: {
									operationId: 'x402_permit2_paid_demo',
									security: PAYMENT_ONLY_SECURITY,
									summary: 'Paid: Gasless Permit2 + EIP-2612 settlement demo',
									description:
										"Pay $0.001 USDC via the Permit2-only path so a wallet holding USDC but zero ETH can complete the flow. CDP's x402ExactPermit2Proxy submits the EIP-2612 permit + Permit2 transfer atomically; the response surfaces the on-chain tx hash and a Basescan link.",
									parameters: [],
									responses: {
										200: { description: 'Settlement summary with tx hash' },
										402: { description: 'Payment Required (x402)' },
									},
									'x-payment-info': {
										price: { mode: 'fixed', currency: 'USD', amount: '0.001' },
										protocols: X402_PROTOCOLS,
									},
								},
							},
						}
					: {}),
				'/api/x402/three-intel': {
					get: {
						operationId: 'x402_three_intel',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Live $THREE market intel from the Town Oracle',
						description:
							'Pay $0.01 USDC for live $THREE market intel: price, 24 h change, market cap, ' +
							'liquidity, 24 h volume, and a bullish / bearish / neutral signal with a ' +
							'two-sentence rationale. Powered by live DexScreener data — the same oracle ' +
							'behind the paid intel kiosk in the $THREE town on three.ws/play.',
						parameters: [],
						responses: {
							200: { description: '$THREE market intel JSON' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.01' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/dance-tip': {
					get: {
						operationId: 'x402_dance_tip',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Tip a 3D dancer to perform a routine on the club stage',
						description:
							'Pay $0.001 USDC to tip a dancer to perform one routine on the three.ws 3D club stage. ' +
							'Pick a stage slot (1–4) and a style: free-floor (rumba, silly, thriller, capoeira, hiphop) ' +
							'or pole choreography (spin, climb, combo). Returns a performance ticket the /club page ' +
							'consumes to spawn the dancer and play the routine.',
						parameters: [
							{
								name: 'dancer',
								in: 'query',
								required: true,
								schema: { type: 'string', enum: ['1', '2', '3', '4'] },
								description: 'Stage slot — which of the four dancers performs.',
							},
							{
								name: 'dance',
								in: 'query',
								required: true,
								schema: {
									type: 'string',
									enum: [
										'rumba',
										'silly',
										'thriller',
										'capoeira',
										'hiphop',
										'spin',
										'climb',
										'combo',
									],
								},
								description:
									'Performance style. Free-floor styles (rumba, silly, thriller, capoeira, hiphop) play a single looped clip; pole-choreography styles (spin, climb, combo) chain a sequence of clips.',
							},
						],
						responses: {
							200: { description: 'Performance ticket JSON' },
							400: { description: 'Missing or invalid parameters' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.001' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/asset-download': {
					get: {
						operationId: 'x402_asset_download',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Unlock a 3D asset (GLB / avatar / accessory)',
						description:
							'Pay in USDC once to unlock a 3D asset hosted on R2. Wallets that already paid can re-download for free by signing in with SIWX (CAIP-122). Each asset has its own price and creator payout address; the response carries a short-lived presigned R2 URL.',
						parameters: [
							{
								name: 'slug',
								in: 'query',
								required: true,
								schema: { type: 'string', minLength: 1, maxLength: 128 },
								description: 'Unique asset slug from the paid_assets catalog.',
							},
						],
						responses: {
							200: { description: 'Presigned R2 download URL' },
							400: { description: 'Missing or invalid slug' },
							402: { description: 'Payment Required (x402)' },
							404: { description: 'Asset not found' },
						},
						'x-payment-info': {
							// Per-asset pricing: the live 402 challenge reflects the exact
							// USDC price of the requested asset's paid_assets row. Declared
							// `dynamic` (the only non-fixed price mode discovery accepts —
							// `variable` is not a recognized mode); bounds span the catalog.
							price: { mode: 'dynamic', currency: 'USD', min: '0.01', max: '100.00' },
							protocols: X402_PROTOCOLS,
							note: 'Each asset declares its own USDC price; the live 402 challenge reflects the per-asset row.',
						},
					},
				},
				'/api/x402/pump-launch': {
					post: {
						operationId: 'x402_pump_launch',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Deploy a new pump.fun token in one call',
						description:
							'Pay $5.00 USDC to deploy a brand-new pump.fun token. Supply name + symbol and either a pre-pinned metadataUri or an imageUrl (the server pins the image + descriptor to pump.fun IPFS). The server fronts the SOL deploy cost and signs the create-coin tx, so the buyer needs no SOL and no account. Creator rewards accrue to any Solana wallet you nominate; an optional vanity prefix/suffix grinds a custom mint address. Returns mint + tx signature + pump.fun URL.',
						requestBody: {
							required: true,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										required: ['name', 'symbol'],
										properties: {
											name: { type: 'string', maxLength: 32 },
											symbol: { type: 'string', maxLength: 10 },
											metadataUri: {
												type: 'string',
												maxLength: 2048,
												description:
													'Pre-pinned metadata URI. Provide this or imageUrl.',
											},
											imageUrl: {
												type: 'string',
												maxLength: 2048,
												description:
													'Image URL to pin to pump.fun IPFS. Provide this or metadataUri.',
											},
											description: { type: 'string', maxLength: 2000 },
											creator: {
												type: 'string',
												minLength: 32,
												maxLength: 44,
												description:
													'Solana wallet that receives creator rewards.',
											},
											vanityPrefix: { type: 'string', maxLength: 5 },
											vanitySuffix: { type: 'string', maxLength: 5 },
										},
									},
								},
							},
						},
						responses: {
							200: { description: 'Deploy result: mint, tx signature, pump.fun URL' },
							400: { description: 'Missing or invalid body' },
							402: { description: 'Payment Required (x402)' },
							503: { description: 'Launcher not configured' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '5.00' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/vanity': {
					get: {
						operationId: 'x402_vanity',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Grind a vanity Solana keypair',
						description:
							'Pay to generate a brand-new Solana keypair whose Base58 address starts with a chosen prefix and/or ends with a chosen suffix. Returns the public address and its secret key (Base58 + 64-byte array) so it imports into any Solana wallet. Ground fresh per request in a Rust/WASM ed25519 engine and never stored. Difficulty-tiered price ($0.01 for 1 char, $0.05 for 2, $0.25 for 3); combined pattern capped at 3 Base58 characters. Settlement runs only after a successful grind, so an exhausted budget costs nothing.',
						parameters: [
							{
								name: 'prefix',
								in: 'query',
								schema: { type: 'string', maxLength: 3 },
								description:
									'Base58 characters the address must start with (excludes 0, O, I, l). Combined with suffix, max 3. Provide prefix and/or suffix.',
							},
							{
								name: 'suffix',
								in: 'query',
								schema: { type: 'string', maxLength: 3 },
								description:
									'Base58 characters the address must end with. Combined with prefix, max 3.',
							},
							{
								name: 'ignoreCase',
								in: 'query',
								schema: { type: 'string', enum: ['0', '1', 'true', 'false'] },
								description:
									'When 1/true, match case-insensitively (faster, less specific).',
							},
						],
						responses: {
							200: { description: 'Keypair JSON: address + secret key' },
							400: { description: 'Missing prefix/suffix or pattern too long' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							// Difficulty-tiered: $0.01 (1 char) → $0.25 (3 chars). The live
							// 402 quotes the exact price for the requested pattern length.
							price: { mode: 'dynamic', currency: 'USD', min: '0.01', max: '0.25' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/fact-check': {
					post: {
						operationId: 'x402_fact_check',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Real-time fact check with sourced verdict',
						description:
							'Pay $0.10 USDC to verify a factual claim. The server generates search queries, runs multi-source web search, extracts per-source stance with an LLM, computes a weighted verdict + confidence, and returns the supporting sources plus a SHA-256 attestation of the result.',
						requestBody: {
							required: true,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										required: ['claim'],
										properties: {
											claim: {
												type: 'string',
												minLength: 5,
												maxLength: 1000,
												description: 'The factual claim to verify.',
											},
											strictness: {
												type: 'string',
												enum: ['high', 'medium', 'low'],
												default: 'medium',
												description:
													'high: penalizes low-authority sources. medium: default. low: accepts all sources equally.',
											},
										},
									},
								},
							},
						},
						responses: {
							200: {
								description:
									'Verdict JSON: verdict, confidence, claim, strictness, sources, costBreakdown, attestation',
							},
							400: { description: 'Missing or invalid claim' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.10' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/tutor': {
					post: {
						operationId: 'x402_tutor',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Pay-as-you-learn tutor (one charge per answer)',
						description:
							'Pay $0.01 USDC per answered question. Returns a leveled explanation, key points, a worked example, and a follow-up, plus a running session tab so the UI can render a live itemized invoice. Pass a sessionId to accumulate a tab across questions.',
						requestBody: {
							required: true,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										required: ['question'],
										properties: {
											sessionId: {
												type: 'string',
												maxLength: 100,
												description:
													'Stable session identifier to accumulate a running tab. Omit to start a new session.',
											},
											question: {
												type: 'string',
												minLength: 5,
												maxLength: 2000,
												description: 'The question to be explained.',
											},
											context: {
												type: 'string',
												maxLength: 6000,
												description:
													'Optional code or context to ground the explanation.',
											},
											level: {
												type: 'string',
												enum: ['beginner', 'intermediate', 'expert'],
												default: 'intermediate',
												description:
													'Target expertise level — controls depth and assumed background.',
											},
										},
									},
								},
							},
						},
						responses: {
							200: { description: 'Answer JSON with running session tab' },
							400: { description: 'Missing or invalid question' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.01' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/skill-call': {
					get: {
						operationId: 'x402_skill_call',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Invoke a marketplace skill (pay-per-call)',
						description:
							"Pay the per-call price of a marketplace skill in USDC (Base or Solana) and receive its executable payload: the tool schema and content the calling agent runs. Payment settles straight to the skill author's wallet. Per-call pricing — every invocation is a fresh payment.",
						parameters: [
							{
								name: 'skill',
								in: 'query',
								required: true,
								schema: { type: 'string', minLength: 1, maxLength: 128 },
								description:
									'Unique skill slug from the marketplace_skills catalog.',
							},
						],
						responses: {
							200: { description: 'Skill payload: tool schema + content' },
							400: { description: 'Missing or invalid skill slug' },
							402: { description: 'Payment Required (x402)' },
							404: { description: 'Skill not found' },
							409: { description: 'Skill not currently purchasable' },
						},
						'x-payment-info': {
							// Per-skill pricing from marketplace_skills; the live 402
							// challenge reflects the exact price of the requested skill.
							// Bounds mirror the catalog's enforced range (price_per_call_usd
							// is validated 0–10 in api/skills/index.js; free skills 409).
							price: { mode: 'dynamic', currency: 'USD', min: '0.001', max: '10.00' },
							protocols: X402_PROTOCOLS,
							note: 'Per-call price is set per skill; the live 402 challenge reflects the exact skill price.',
						},
					},
				},
				'/api/x402/agent-bouncer': {
					get: {
						operationId: 'x402_agent_bouncer',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Admit/refuse a counterparty agent at the door',
						description:
							"Pay $0.01 USDC to run the Pole Club door check against a three.ws agent's Solana reputation: confirmed on-chain payments, distinct payers, failure rate, distribute/buyback follow-through, signed attestations, and Club ban/tip ledger. Returns an admit/refuse verdict with a door tier (newcomer / regular / trusted / vip). Vet before you pay, hire, or delegate.",
						parameters: [
							{
								name: 'agent_id',
								in: 'query',
								required: true,
								schema: { type: 'string', format: 'uuid' },
							},
							{
								name: 'min_payments',
								in: 'query',
								required: false,
								schema: { type: 'integer' },
							},
							{
								name: 'min_distinct_payers',
								in: 'query',
								required: false,
								schema: { type: 'integer' },
							},
							{
								name: 'max_failure_rate',
								in: 'query',
								required: false,
								schema: { type: 'number' },
							},
						],
						responses: {
							200: { description: 'Verdict JSON: admitted, tier, reasons, reputation' },
							400: { description: 'Missing or invalid agent_id' },
							402: { description: 'Payment Required (x402)' },
							404: { description: 'agent_id not found' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.01' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/vanity-verifiable': {
					get: {
						operationId: 'x402_vanity_verifiable',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Provably-fair Solana vanity keypair + signed receipt',
						description:
							'Grind a fresh Solana keypair whose Base58 address matches a chosen prefix/suffix, with a commit–reveal receipt signed by the service key (published at /.well-known/three-vanity.json) so the buyer can prove the key was ground fresh and never kept. Pass sealTo=<X25519 pubkey> to ECIES-seal the secret. Difficulty-tiered $0.02–$0.40; combined pattern ≤3 Base58 chars; settlement runs only after a successful grind.',
						parameters: [
							{
								name: 'prefix',
								in: 'query',
								required: false,
								schema: { type: 'string', maxLength: 3 },
								description: 'Base58 prefix the address must start with (excludes 0,O,I,l).',
							},
							{
								name: 'suffix',
								in: 'query',
								required: false,
								schema: { type: 'string', maxLength: 3 },
								description: 'Base58 suffix the address must end with. Combined with prefix ≤3.',
							},
							{
								name: 'sealTo',
								in: 'query',
								required: false,
								schema: { type: 'string' },
								description:
									'Recommended. Your X25519 public key; when set the secret is sealed to it and omitted from the response.',
							},
						],
						responses: {
							200: { description: 'Keypair + signed grind receipt JSON' },
							400: { description: 'Missing prefix/suffix or pattern too long' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'dynamic', currency: 'USD', min: '0.02', max: '0.40' },
							protocols: X402_PROTOCOLS,
							note: 'Difficulty-tiered by pattern length; the live 402 challenge quotes the exact price.',
						},
					},
				},
				'/api/x402/crypto-intel': {
					post: {
						operationId: 'x402_crypto_intel',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Live crypto market signal (agent-to-agent intel)',
						description:
							'Pay $0.01 USDC per call for a live market signal (bullish / bearish / neutral) on a token with current price, 24h change, and a two-sentence rationale. Powered by CoinGecko live prices.',
						requestBody: {
							required: false,
							content: {
								'application/json': {
									schema: {
										type: 'object',
										properties: {
											topic: {
												type: 'string',
												default: 'sol',
												description: 'Token ticker or CoinGecko id: btc, sol, eth, doge, …',
											},
										},
									},
								},
							},
						},
						responses: {
							200: { description: 'Signal JSON: signal, price_usd, change_24h, rationale, confidence' },
							402: { description: 'Payment Required (x402)' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.01' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
				'/api/x402/cosmetic-purchase': {
					get: {
						operationId: 'x402_cosmetic_purchase',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Unlock a premium avatar cosmetic',
						description:
							'Pay once in USDC to unlock a premium avatar cosmetic (skin or emote) for an account, wearable across /play and /walk. Price varies by rarity ($0.25–$3.00). Wallets that already purchased re-confirm for free via SIWX (CAIP-122).',
						parameters: [
							{
								name: 'id',
								in: 'query',
								required: true,
								schema: { type: 'string', minLength: 1, maxLength: 64 },
								description: 'Premium cosmetic id from /api/cosmetics/catalog.',
							},
							{
								name: 'account',
								in: 'query',
								required: true,
								schema: { type: 'string', minLength: 3, maxLength: 64 },
								description: 'Solana wallet address or guest id (g_…) the cosmetic is granted to.',
							},
						],
						responses: {
							200: {
								description: 'Ownership grant JSON',
								content: {
									'application/json': {
										schema: {
											type: 'object',
											required: ['ok', 'id', 'name', 'slot', 'rarity', 'account', 'owned'],
											properties: {
												ok: { type: 'boolean' },
												id: { type: 'string' },
												name: { type: 'string' },
												slot: { type: 'string' },
												rarity: { type: 'string' },
												account: { type: 'string' },
												owned: { type: 'boolean' },
												newlyOwned: { type: 'boolean' },
												payer: { type: ['string', 'null'] },
												network: { type: ['string', 'null'] },
												amountAtomics: { type: ['string', 'null'] },
												asset: { type: ['string', 'null'] },
											},
										},
									},
								},
							},
							400: { description: 'Missing or invalid id/account' },
							402: { description: 'Payment Required (x402)' },
							404: { description: 'Cosmetic not found' },
						},
						'x-payment-info': {
							price: { mode: 'dynamic', currency: 'USD', min: '0.25', max: '3.00' },
							protocols: X402_PROTOCOLS,
							note: 'Per-rarity pricing; the live 402 challenge quotes the exact price for the cosmetic.',
						},
					},
				},
				'/api/x402/animation-download': {
					get: {
						operationId: 'x402_animation_download',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Unlock a 3D avatar animation (GLB)',
						description:
							'Pay once in USDC to unlock a 3D avatar animation (GLB). Each animation has its own price; the response carries a short-lived presigned URL the client fetches directly. Wallets that already paid re-download for free via SIWX.',
						parameters: [
							{
								name: 'id',
								in: 'query',
								required: true,
								schema: { type: 'string', format: 'uuid' },
								description: 'Animation clip UUID from the marketplace animations feed (GET /api/marketplace/animations).',
							},
						],
						responses: {
							200: {
								description: 'Presigned download URL JSON',
								content: {
									'application/json': {
										schema: {
											type: 'object',
											required: ['ok', 'id', 'name', 'mimeType', 'downloadUrl', 'expiresAt'],
											properties: {
												ok: { type: 'boolean' },
												id: { type: 'string', format: 'uuid' },
												slug: { type: 'string' },
												name: { type: 'string' },
												mimeType: { type: 'string' },
												sizeBytes: { type: 'integer', minimum: 0 },
												expiresAt: { type: 'string', format: 'date-time' },
												downloadUrl: { type: 'string', format: 'uri' },
											},
										},
									},
								},
							},
							400: { description: 'Missing or invalid id' },
							402: { description: 'Payment Required (x402)' },
							404: { description: 'Animation not found' },
						},
						'x-payment-info': {
							price: { mode: 'dynamic', currency: 'USD', min: '0.001', max: '10.00' },
							protocols: X402_PROTOCOLS,
							note: 'Per-animation pricing; the live 402 challenge quotes the exact price.',
						},
					},
				},
				'/api/x402/club-cover': {
					get: {
						operationId: 'x402_club_cover',
						security: PAYMENT_ONLY_SECURITY,
						summary: 'Paid: Pole Club cover charge (24h entry token)',
						description:
							'Pay $0.01 USDC to access the three.ws Pole Club. Once payment settles the caller receives an entry token granting access to the live club scene for 24 hours.',
						parameters: [],
						responses: {
							200: { description: 'Entry token JSON with expiry' },
							402: { description: 'Payment Required (x402)' },
							403: { description: 'Caller is banned from the club' },
						},
						'x-payment-info': {
							price: { mode: 'fixed', currency: 'USD', amount: '0.01' },
							protocols: X402_PROTOCOLS,
						},
					},
				},
			},
		}
	);
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	return json(res, 200, buildOpenApiDoc(env.APP_ORIGIN), { 'cache-control': 'public, max-age=300' });
});