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.

48.1 KB
Raw Blame
// api/_lib/x402/ring-catalog.js
//
// The canonical catalog of EVERY paid x402 endpoint on three.ws — the single
// source of truth the ring economy pays against. It replaces the hand-maintained
// `VOLUME_ENDPOINTS` list that had drifted out of sync with the handlers (stale
// methods, wrong bodies, endpoints missing entirely) and silently 405'd or 400'd
// paid requests.
//
// Every entry is derived from reading the handler it points at — the `method`,
// the `query`/`body()` request contract, and the default price all match what
// `api/<path>.js` actually validates, so a rotation call never spends money on a
// request the endpoint would reject. When a new paid endpoint lands, it must be
// added here or tests/x402-ring-catalog.test.js fails (the count-parity guard
// greps every `paidEndpoint(` construction site and asserts each is cataloged).
//
// Consumers:
//   • api/_lib/x402/pipelines/volume-bootstrap-loop.js round-robins rotationPlan()
//   • scripts/x402-ring-coverage-sweep.js records the one-time settle proof per entry
//   • the ring tick drives the same plan at its own cadence
//
// Field contract (see CatalogEntry typedef below):
//   slug                — stable catalog id (usually the pricing slug; a `-…`
//                         suffix disambiguates a second priced surface on one file)
//   sourceFile          — repo-relative handler file (parity + stale-path key)
//   path                — clean route; `api${path}.js` resolves to the handler
//   method              — GET | POST, matching the handler's dispatch
//   query               — GET query params (object) or undefined
//   body()              — POST JSON body (function → object) or () => null
//   priceAtomicDefault  — default price in USDC atomics (6dp), pre env-override
//   priceSlug           — the slug passed to priceFor() (env override key source)
//   tier                — coarse price bucket for rotation filtering
//   kind                — tip | service | intel | health | commerce | settle
//   network             — 'solana' when the handler is Solana-only, else null
//   autobuy             — safe for the ring payer to purchase on a loop?
//   weight              — relative rotation frequency (autobuy entries only)
//   businessEffect      — one line: what a settled call actually does
//   note                — required justification when autobuy === false

// Synthetic, clearly-non-production identifiers used by canary purchases so a
// looped buy never clobbers a real user's record. RING_CANARY_MINT is a valid
// base58 pump-style mint (32–44 chars, no 0/O/I/l) that maps to no real
// coin-world, so the billboard placement it writes is inert. RING_CANARY_UUID is
// a well-formed v4 UUID that resolves to no registered agent (endpoints return a
// truthful "newcomer / not verified" verdict rather than 404).
export const RING_CANARY_MINT = 'Bi11boardRingCanaryMint22222222222222222222';
export const RING_CANARY_UUID = '00000000-0000-4000-8000-000000000001';
// Solana mainnet CAIP-2 chain id (genesis hash), for onchain-identity-verify.
const SOLANA_CAIP2 = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
// $THREE — the platform coin, guaranteed to resolve on the market data feed and
// carry on-chain metadata; used wherever a canary needs a real, resolvable mint.
const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';
// A tiny (364-byte), well-formed 8kHz/mono/16-bit WAV of silence — base64. Used
// as the canary payload for the ASR endpoint so a one-time verification call has
// real, parseable audio bytes without shipping a binary fixture in this file.
const SILENT_WAV_B64 =
	'UklGRmQBAABXQVZFZm10IBAAAAABAAEAQB8AAIA+AAACABAAZGF0YUABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==';

/**
 * @typedef {Object} CatalogEntry
 * @property {string} slug
 * @property {string} sourceFile
 * @property {string} path
 * @property {'GET'|'POST'} method
 * @property {Object} [query]
 * @property {() => (Object|null)} body
 * @property {number} priceAtomicDefault
 * @property {string} priceSlug
 * @property {'settle'|'commerce'|'intel'|'service'|'health'} tier
 * @property {'tip'|'service'|'intel'|'health'|'commerce'|'settle'} kind
 * @property {string|null} network
 * @property {boolean} autobuy
 * @property {number} weight
 * @property {string} businessEffect
 * @property {string} [note]
 */

const NO_BODY = () => null;

// Paid Market Data API family (api/_lib/market-data/) — 17 read-only GET
// endpoints built by one paidEndpoint factory. Every entry shares the same
// shape (intel tier, USDC-atomics default from the registry), so a local
// builder keeps this block honest instead of ~300 hand-copied lines. Queries
// here are the cheapest valid canary per endpoint — a rotation call must
// never 4xx. Rotation budget: only the two family representatives
// (market-pulse, market-global) are autobuy, all 18 share one construction
// rail (endpoint.js) and one fetcher module, so two hourly settles prove the
// whole family's payment path without blowing the ring's calls-per-hour cap;
// the rest get their one-time settle proof from the coverage sweep.
const MARKET_FAMILY_NOTE =
	'Family representative coverage: market-pulse + market-global keep the shared ' +
	'api/_lib/market-data/endpoint.js rail settling hourly; rotating all 18 would ' +
	'exceed the ring hour budget. One-time settle proof via the coverage sweep.';
const marketData = (
	slug,
	businessEffect,
	{ query, priceAtomicDefault = 1_000, autobuy = false } = {},
) => ({
	slug,
	sourceFile: 'api/_lib/market-data/endpoint.js',
	path: `/api/x402/${slug}`,
	method: 'GET',
	...(query ? { query } : {}),
	body: NO_BODY,
	priceAtomicDefault,
	priceSlug: slug,
	tier: 'intel',
	kind: 'intel',
	network: null,
	autobuy,
	weight: 1,
	businessEffect,
	...(autobuy ? {} : { note: MARKET_FAMILY_NOTE }),
});

/** @type {CatalogEntry[]} */
export const RING_CATALOG = [
	// ── settle ────────────────────────────────────────────────────────────────
	{
		slug: 'ring-settle',
		sourceFile: 'api/x402/ring-settle.js',
		path: '/api/x402/ring-settle',
		method: 'POST',
		body: () => ({ note: 'ring-cycle', seq: 1 }),
		priceAtomicDefault: 1_000_000,
		priceSlug: 'ring-settle',
		tier: 'settle',
		kind: 'settle',
		network: 'solana',
		autobuy: true,
		weight: 1,
		businessEffect: 'Real USDC settlement payer→treasury; returns a signed ring-tick receipt. The ring volume primitive (discoverable:false).',
	},

	// ── commerce (tips & goods bought/sold) ─────────────────────────────────────
	{
		slug: 'dance-tip',
		sourceFile: 'api/x402/dance-tip.js',
		path: '/api/x402/dance-tip',
		method: 'GET',
		query: { dancer: '1', dance: 'rumba' },
		body: NO_BODY,
		priceAtomicDefault: 1_000,
		priceSlug: 'dance-tip',
		tier: 'commerce',
		kind: 'tip',
		network: 'solana',
		autobuy: true,
		weight: 2,
		businessEffect: 'Inserts a row into club_tips (the tip ledger feeding visit tiers + club revenue).',
	},
	{
		slug: 'club-cover',
		sourceFile: 'api/x402/club-cover.js',
		path: '/api/x402/club-cover',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 10_000,
		priceSlug: 'club-cover',
		tier: 'intel',
		kind: 'commerce',
		network: 'solana',
		autobuy: true,
		weight: 2,
		businessEffect: 'Charges the door cover (settled USDC → x402_audit_log cover record) and mints an admission pass after a ban/visit check.',
	},
	{
		slug: 'club-cover-snapshot',
		sourceFile: 'api/x402/club-cover.js',
		path: '/api/x402/club-cover',
		method: 'POST',
		body: () => ({ mode: 'snapshot', club: 'three_holders' }),
		priceAtomicDefault: 10_000,
		priceSlug: 'club-cover',
		tier: 'intel',
		kind: 'intel',
		network: 'solana',
		autobuy: true,
		weight: 1,
		businessEffect: 'Reads club_tips into a membership snapshot (revenue/analytics surface).',
	},
	{
		slug: 'billboard',
		sourceFile: 'api/x402/billboard.js',
		path: '/api/x402/billboard',
		method: 'GET',
		query: { coin: RING_CANARY_MINT, caption: 'ring canary placement' },
		body: NO_BODY,
		priceAtomicDefault: 50_000,
		priceSlug: 'billboard',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Writes a billboard placement (Redis billboard:<coin>, 6h TTL). Canary targets a synthetic mint so no real coin-world board is overwritten.',
	},
	{
		slug: 'mint-to-mesh-batch',
		sourceFile: 'api/x402/mint-to-mesh-batch.js',
		path: '/api/x402/mint-to-mesh-batch',
		method: 'POST',
		body: () => ({ mints: [THREE_MINT] }),
		priceAtomicDefault: 50_000,
		priceSlug: 'mint-to-mesh-batch',
		tier: 'commerce',
		kind: 'service',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Fetches token metadata via Solana RPC and returns synthesized GLB bytes (read-only, no state written).',
	},

	// ── intel ───────────────────────────────────────────────────────────────────
	{
		slug: 'pump-agent-audit',
		sourceFile: 'api/x402/pump-agent-audit.js',
		path: '/api/x402/pump-agent-audit',
		method: 'GET',
		query: { limit: '10', sort: 'newest' },
		body: NO_BODY,
		priceAtomicDefault: 20_000,
		priceSlug: 'pump-agent-audit',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Lists recent pump.fun launches cross-referenced against pump_agent_mints (read-only).',
	},
	{
		slug: 'pump-agent-audit-whale',
		sourceFile: 'api/x402/pump-agent-audit.js',
		path: '/api/x402/pump-agent-audit',
		method: 'POST',
		body: () => ({ mode: 'whale_activity', limit: 5 }),
		priceAtomicDefault: 20_000,
		priceSlug: 'pump-agent-audit',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Scans live pump.fun feeds for whale buys and returns an aggregated signal (read-only).',
	},
	{
		slug: 'three-intel',
		sourceFile: 'api/x402/three-intel.js',
		path: '/api/x402/three-intel',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 10_000,
		priceSlug: 'three-intel',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 2,
		businessEffect: 'Returns a live $THREE market signal from DexScreener (read-only).',
	},
	{
		slug: 'crypto-intel',
		sourceFile: 'api/x402/crypto-intel.js',
		path: '/api/x402/crypto-intel',
		method: 'POST',
		body: () => ({ topic: 'sol' }),
		priceAtomicDefault: 10_000,
		priceSlug: 'crypto_intel',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns live market intel for the topic (CoinGecko→Coinbase, read-only).',
	},
	{
		slug: 'token-intel',
		sourceFile: 'api/x402/token-intel.js',
		path: '/api/x402/token-intel',
		method: 'GET',
		query: { mint: THREE_MINT },
		body: NO_BODY,
		priceAtomicDefault: 10_000,
		priceSlug: 'token-intel',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns a token market + risk signal for the mint (DexScreener, read-only).',
	},
	{
		slug: 'defi-radar',
		sourceFile: 'api/x402/defi-radar.js',
		path: '/api/x402/defi-radar',
		method: 'GET',
		query: { limit: '5' },
		body: NO_BODY,
		priceAtomicDefault: 5_000,
		priceSlug: 'defi-radar',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns the composite DeFi snapshot: TVL movers + fee + DEX leaderboards (DeFiLlama, read-only).',
	},
	{
		slug: 'yield-scan',
		sourceFile: 'api/x402/yield-scan.js',
		path: '/api/x402/yield-scan',
		method: 'GET',
		query: { limit: '5' },
		body: NO_BODY,
		priceAtomicDefault: 5_000,
		priceSlug: 'yield-scan',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Screens live DeFi yield pools with APY breakdown + risk flags (DeFiLlama yields, read-only).',
	},
	{
		slug: 'stablecoin-health',
		sourceFile: 'api/x402/stablecoin-health.js',
		path: '/api/x402/stablecoin-health',
		method: 'GET',
		query: { limit: '5' },
		body: NO_BODY,
		priceAtomicDefault: 5_000,
		priceSlug: 'stablecoin-health',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns per-stablecoin peg deviation + supply-flow report with depeg alerts (DeFiLlama, read-only).',
	},
	{
		slug: 'hack-check',
		sourceFile: 'api/x402/hack-check.js',
		path: '/api/x402/hack-check',
		method: 'GET',
		query: { limit: '3' },
		body: NO_BODY,
		priceAtomicDefault: 2_000,
		priceSlug: 'hack-check',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Runs a protocol name against the DeFi exploit database, returns verdict + incidents (read-only).',
	},
	{
		slug: 'market-heatmap',
		sourceFile: 'api/x402/market-heatmap.js',
		path: '/api/x402/market-heatmap',
		method: 'GET',
		query: { limit: '10' },
		body: NO_BODY,
		priceAtomicDefault: 2_000,
		priceSlug: 'market-heatmap',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns the top-coins momentum board + breadth stats (CoinGecko→CoinPaprika failover, read-only).',
	},
	{
		slug: 'gas-oracle',
		sourceFile: 'api/x402/gas-oracle.js',
		path: '/api/x402/gas-oracle',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 1_000,
		priceSlug: 'gas-oracle',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns live fee tiers for Ethereum + Base and Solana priority-fee percentiles (public RPCs, read-only).',
	},
	{
		slug: 'market-mood',
		sourceFile: 'api/x402/market-mood.js',
		path: '/api/x402/market-mood',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 2_000,
		priceSlug: 'market-mood',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns the Fear&Greed × news-sentiment composite mood score with divergence flag (read-only).',
	},
	{
		slug: 'news-pulse',
		sourceFile: 'api/x402/news-pulse.js',
		path: '/api/x402/news-pulse',
		method: 'GET',
		query: { ticker: 'THREE', hours: '24' },
		body: NO_BODY,
		priceAtomicDefault: 2_000,
		priceSlug: 'news-pulse',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Measures live news coverage for one ticker: mentions, velocity, sentiment, headlines (read-only).',
	},
	marketData('market-coins', 'Returns the ranked coin market table with sparklines (CoinGecko→CoinLore failover, read-only).', { query: { per_page: '10' } }),
	marketData('market-coin', 'Returns the full single-coin profile: market stats, links, dev/community metrics (read-only).', { query: { id: 'bitcoin' } }),
	marketData('market-chart', 'Returns a historical USD price series for one coin (read-only).', { query: { id: 'bitcoin', days: '7' } }),
	marketData('market-categories', 'Returns every crypto sector ranked by market cap with 24h change (read-only).'),
	marketData('market-exchanges', 'Returns the top spot exchanges by trust score with USD volume (read-only).'),
	marketData('market-derivatives', 'Returns perpetual futures tickers: funding, open interest, volume (read-only).'),
	marketData('market-global', 'Returns total market cap, volume, dominance + the Fear & Greed index (read-only).', { autobuy: true }),
	marketData('market-gas', 'Returns live ETH gas tiers from on-chain fee history with USD action costs (read-only).'),
	marketData('market-trending', 'Returns the most-searched coins, categories, and NFTs of the last 24h (read-only).'),
	marketData('market-defi', 'Returns the top DeFi protocols by TVL with market totals (DeFiLlama, read-only).'),
	marketData('market-chains', 'Returns every chain ranked by DeFi TVL with market share (DeFiLlama, read-only).'),
	marketData('market-yields', 'Queries ~15k DeFi yield pools with filters and APY history (DeFiLlama, read-only).', { query: { limit: '3' } }),
	marketData('market-stablecoins', 'Returns the top stablecoins by supply with peg health (DeFiLlama, read-only).'),
	marketData('market-fees', 'Returns protocol fee/revenue rankings with market totals (DeFiLlama, read-only).'),
	marketData('market-dex-volumes', 'Returns the top DEXs by 24h volume with market share (DeFiLlama, read-only).'),
	marketData('market-anomalies', 'Returns statistically scored market anomalies from the scanner: price, TVL, stablecoin, funding and open-interest events (read-only).', { query: { limit: '3' } }),
	marketData('market-hacks', 'Returns the searchable DeFi exploit database with loss stats (DeFiLlama, read-only).', { query: { limit: '3' } }),
	marketData('market-pulse', 'Returns the one-call market bundle: global, F&G, top coins, gas, TVL, stables, DEX, fees (read-only).', { priceAtomicDefault: 5_000, autobuy: true }),
	{
		slug: 'agent-reputation',
		sourceFile: 'api/x402/agent-reputation.js',
		path: '/api/x402/agent-reputation',
		method: 'POST',
		body: () => ({ mode: 'sweep', limit: 10 }),
		priceAtomicDefault: 10_000,
		priceSlug: 'agent-reputation',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		// The GET single-agent surface throws on an unknown agent_id; the POST
		// sweep has no record dependency, so the loop uses it.
		businessEffect: 'Sweeps recent agents into a reputation aggregate (read-only).',
	},
	{
		slug: 'agent-bouncer',
		sourceFile: 'api/x402/agent-bouncer.js',
		path: '/api/x402/agent-bouncer',
		method: 'GET',
		query: { agent_id: RING_CANARY_UUID },
		body: NO_BODY,
		priceAtomicDefault: 10_000,
		priceSlug: 'agent-bouncer',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Vets an agent id against the trust ledger; a canary id returns a newcomer verdict (read-only).',
	},
	{
		slug: 'cross-chain',
		sourceFile: 'api/x402/cross-chain.js',
		path: '/api/x402/cross-chain',
		method: 'POST',
		body: () => ({ mode: 'bridge_status' }),
		priceAtomicDefault: 5_000,
		priceSlug: 'cross_chain_bridge_status',
		tier: 'service',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Probes external bridge status APIs and returns a health signal (read-only).',
	},
	{
		slug: 'analytics',
		sourceFile: 'api/x402/analytics.js',
		path: '/api/x402/analytics',
		method: 'POST',
		body: () => ({ report: 'clubs', period: '24h' }),
		priceAtomicDefault: 5_000,
		priceSlug: 'analytics',
		tier: 'service',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Runs a live analytics report (club/marketplace/revenue aggregates, read-only).',
	},
	{
		slug: 'onchain-identity-verify',
		sourceFile: 'api/x402/onchain-identity-verify.js',
		path: '/api/x402/onchain-identity-verify',
		method: 'GET',
		query: { agent_id: RING_CANARY_UUID, chain: SOLANA_CAIP2, contract_or_mint: THREE_MINT },
		body: NO_BODY,
		priceAtomicDefault: 5_000,
		priceSlug: 'onchain-identity-verify',
		tier: 'service',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Checks the agent→onchain ownership index; a canary id returns verified:false (read-only).',
	},
	{
		slug: 'bazaar-feed',
		sourceFile: 'api/x402/bazaar-feed.js',
		path: '/api/x402/bazaar-feed',
		method: 'POST',
		body: () => ({ filter: 'new', limit: 5 }),
		priceAtomicDefault: 1_000,
		priceSlug: 'bazaar-feed',
		tier: 'health',
		kind: 'intel',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns the bazaar service discovery feed (read-only).',
	},

	// ── service ─────────────────────────────────────────────────────────────────
	{
		slug: 'unstoppable-status',
		sourceFile: 'api/agents/unstoppable-status.js',
		path: '/api/agents/unstoppable-status',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 10_000,
		priceSlug: 'unstoppable-status',
		tier: 'intel',
		kind: 'service',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Reads and records the agent treasury status (writes its own revenue ledger only).',
	},
	{
		slug: 'symbol-availability-batch',
		sourceFile: 'api/x402/symbol-availability.js',
		path: '/api/x402/symbol-availability',
		method: 'POST',
		body: () => ({ symbols: ['MOON'], network: 'mainnet' }),
		priceAtomicDefault: 5_000,
		priceSlug: 'symbol-availability-batch',
		tier: 'service',
		kind: 'service',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Checks symbol collisions against pump_agent_mints for a batch (read-only).',
	},
	{
		slug: 'symbol-availability',
		sourceFile: 'api/x402/symbol-availability.js',
		path: '/api/x402/symbol-availability',
		method: 'GET',
		query: { ticker: 'HELIO', network: 'mainnet' },
		body: NO_BODY,
		priceAtomicDefault: 1_000,
		priceSlug: 'symbol-availability',
		tier: 'health',
		kind: 'service',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Checks a single symbol for collision/similarity against pump_agent_mints (read-only).',
	},
	{
		slug: 'skill-marketplace',
		sourceFile: 'api/x402/skill-marketplace.js',
		path: '/api/x402/skill-marketplace',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 1_000,
		priceSlug: 'skill-marketplace',
		tier: 'health',
		kind: 'service',
		network: null,
		autobuy: true,
		weight: 1,
		// Discovery/analytics surface. The actual per-listing purchase + author
		// royalty is skill-call (dynamic, autobuy:false) below.
		businessEffect: 'Returns the skill marketplace catalog (read-only discovery).',
	},
	{
		slug: 'mcp-tool-catalog',
		sourceFile: 'api/x402/mcp-tool-catalog.js',
		path: '/api/x402/mcp-tool-catalog',
		method: 'POST',
		body: () => ({ mode: 'list' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'mcp-tool-catalog',
		tier: 'health',
		kind: 'service',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Returns the MCP tool catalog snapshot in list mode (read-only; discover-mode writes are avoided).',
	},
	{
		slug: 'avatar-optimize-batch',
		sourceFile: 'api/x402/avatar-optimize-batch.js',
		path: '/api/x402/avatar-optimize-batch',
		method: 'POST',
		body: () => ({ limit: 1 }),
		priceAtomicDefault: 1_000,
		priceSlug: 'avatar-optimize-batch',
		tier: 'health',
		kind: 'service',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Analyzes one public avatar GLB and upserts avatar_optimization_results (our own table).',
	},

	// ── health (canary/liveness paid endpoints) ─────────────────────────────────
	{
		slug: 'spend-session',
		sourceFile: 'api/x402/spend-session.js',
		path: '/api/x402/spend-session',
		method: 'POST',
		body: () => ({ mode: 'canary', budget: 0.01 }),
		priceAtomicDefault: 10_000,
		priceSlug: 'spend-session',
		tier: 'intel',
		kind: 'health',
		network: 'solana',
		autobuy: true,
		weight: 1,
		businessEffect: 'Exercises the spend-session create/consume cycle and logs to spend_session_health_log.',
	},
	{
		slug: 'telegram-health',
		sourceFile: 'api/x402/telegram-health.js',
		path: '/api/x402/telegram-health',
		method: 'POST',
		body: () => ({ bot: 'changelog' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'telegram-health',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Probes the Telegram bot getMe endpoint and returns reachability (read-only + self-expiring alert key).',
	},
	{
		slug: 'api-key-health',
		sourceFile: 'api/x402/api-key-health.js',
		path: '/api/x402/api-key-health',
		method: 'POST',
		body: () => ({ scope: 'autonomous_loop' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'api-key-health',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Validates the subscription/internal API key for a scope (read-only).',
	},
	{
		slug: 'did-verify',
		sourceFile: 'api/x402/did.js',
		path: '/api/x402/did',
		method: 'POST',
		body: () => ({ mode: 'verify' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'did_verify',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Resolves and verifies the platform DID document (read-only).',
	},
	{
		slug: 'notify',
		sourceFile: 'api/x402/notify.js',
		path: '/api/x402/notify',
		method: 'POST',
		body: () => ({ channel: 'canary', message: 'ring heartbeat', priority: 'low' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'notify',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Records a notification into canary_notification_log (no external send).',
	},
	{
		slug: 'auth-health',
		sourceFile: 'api/x402/auth-health.js',
		path: '/api/x402/auth-health',
		method: 'POST',
		body: () => ({ mode: 'session_lifecycle' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'auth_health',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Runs the JWT mint/verify/refresh/expire self-test on a synthetic identity (in-process crypto).',
	},
	{
		slug: 'model-validation-sweep',
		sourceFile: 'api/x402/model-validation-sweep.js',
		path: '/api/x402/model-validation-sweep',
		method: 'POST',
		body: () => ({}),
		priceAtomicDefault: 1_000,
		priceSlug: 'model-validation-sweep',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Scores the stalest public avatar and upserts model_quality_scores (our own table).',
	},
	{
		slug: 'rate-limit-probe',
		sourceFile: 'api/x402/rate-limit-probe.js',
		path: '/api/x402/rate-limit-probe',
		method: 'POST',
		body: () => ({ endpoint: '/api/x402/crypto-intel' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'rate-limit-probe',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Probes a target endpoint 402 price + reads the daily spend budget (read-only).',
	},
	{
		slug: 'wallet-connect-health',
		sourceFile: 'api/x402/wallet-connect.js',
		path: '/api/x402/wallet-connect',
		method: 'POST',
		body: () => ({ mode: 'health' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'wallet-connect-health',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Probes the SIWS nonce endpoint and measures latency (read-only).',
	},
	{
		slug: 'solana-register-health',
		sourceFile: 'api/x402/solana-register-health.js',
		path: '/api/x402/solana-register-health',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 1_000,
		priceSlug: 'solana-register-health',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Checks the canary agent registration via Solana RPC and upserts mcp_health_canary (one row).',
	},
	{
		slug: 'feed-health',
		sourceFile: 'api/x402/feed-health.js',
		path: '/api/x402/feed-health',
		method: 'POST',
		body: () => ({ feed: 'changelog_rss' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'feed-health',
		tier: 'health',
		kind: 'health',
		network: 'solana',
		autobuy: true,
		weight: 1,
		businessEffect: 'Fetches and validates the changelog RSS feed against the bundled changelog (read-only).',
	},
	{
		slug: 'schema-check',
		sourceFile: 'api/x402/schema-check.js',
		path: '/api/x402/schema-check',
		method: 'POST',
		body: () => ({ api: 'changelog_json' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'schema-check',
		tier: 'health',
		kind: 'health',
		network: null,
		autobuy: true,
		weight: 1,
		businessEffect: 'Fetches changelog.json and validates it against the published schema (read-only).',
	},

	// ── autobuy:false — covered by one-time verification, not the loop ──────────
	{
		slug: 'news-archive-search',
		sourceFile: 'api/news/archive.js',
		path: '/api/news/archive',
		method: 'GET',
		query: { q: 'bitcoin', limit: '5' },
		body: NO_BODY,
		priceAtomicDefault: 1_000,
		priceSlug: 'news-archive',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Full-text search over the 662k-article crypto-news archive (Sept 2017 →) with sentiment/ticker/date filters.',
		note: 'autobuy:false — freemium rail: 60 searches/day per IP are free, so a ring call usually gets a free 200, not a 402; the paid twin only engages over quota.',
	},
	{
		slug: 'print-order',
		sourceFile: 'api/x402/print-order.js',
		path: '/api/x402/print-order',
		method: 'POST',
		// The catalog floor price, which is also what the probe challenge quotes.
		// A real call is priced by its own signed quote token, so no single number
		// here can be the price of an order.
		body: () => ({ token: null, shipping: null }),
		priceAtomicDefault: 12_000_000,
		priceSlug: 'print-order',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Each settled call opens a REAL manufacturing job: a physical 3D print is produced and shipped to the street address in the request, and an on-chain certificate is issued when it ships.',
		note: 'autobuy:false - a settled call manufactures and ships a physical object to a real address, which cannot be canaried. It is also unbuyable by a loop by construction: the price comes from an HMAC-signed quote token the ring has no way to mint, so a rotation call would be refused pre-settle with a 422.',
	},
	{
		slug: 'knock',
		sourceFile: 'api/x402/knock.js',
		path: '/api/x402/knock',
		method: 'POST',
		body: () => ({ from: 'ring canary', message: 'ring coverage probe' }),
		// The representative probe price the handler quotes when no door is named.
		// A real knock is priced by the recipient's own door row.
		priceAtomicDefault: 50_000,
		priceSlug: 'knock',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Each settled call delivers one paid message to a real person, settling USDC directly to that recipient\'s own wallet rather than to the platform.',
		note: 'autobuy:false - a settled call interrupts a real human being and pays them, and the payout wallet is theirs, not ours. There is also nothing to buy without a ?to= handle: a rotation call with no door gets the probe challenge and can never settle.',
	},
	{
		slug: 'three-buy',
		sourceFile: 'api/x402/three-buy.js',
		path: '/api/x402/three-buy',
		method: 'POST',
		body: () => ({ note: 'microbuy' }),
		priceAtomicDefault: 1_000,
		priceSlug: 'three-buy',
		tier: 'commerce',
		kind: 'commerce',
		network: 'solana',
		autobuy: false,
		weight: 0,
		businessEffect: 'Each settled call executes one small, real USDC→$THREE market buy on Jupiter (buy-only) funded by the micro-buy wallet, then the tokens are swept to the treasury.',
		note: 'autobuy:false — every settled call spends real USDC on a live $THREE market buy (bounded by THREE_MICROBUY_DAILY_CAP_USD). It has its own dedicated driver, api/cron/three-buy-loop.js, so the generic ring rotation must not also fire it.',
	},
	{
		slug: 'pump-launch',
		sourceFile: 'api/x402/pump-launch.js',
		path: '/api/x402/pump-launch',
		method: 'POST',
		body: () => ({ name: 'Helios', symbol: 'HELIO', metadataUri: 'https://ipfs.io/ipfs/QmRingCanaryMetadataPlaceholder' }),
		priceAtomicDefault: 5_000_000,
		priceSlug: 'pump-launch',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Mints a real pump.fun coin on Solana mainnet (~0.022 SOL + a live on-chain token).',
		note: 'autobuy:false — every call deploys a real coin and spends launcher SOL. Verify on devnet or with explicit owner sign-off only.',
	},
	{
		slug: 'endpoint-shopper-run',
		sourceFile: 'api/agents/endpoint-shopper-run.js',
		path: '/api/agents/endpoint-shopper-run',
		method: 'POST',
		body: () => ({ task: 'Summarize the most recent three.ws changelog entry.' }),
		priceAtomicDefault: 10_000,
		priceSlug: 'endpoint-shopper-run',
		tier: 'intel',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Orchestrates downstream paid x402 calls (up to $2) plus an LLM plan/synthesis step.',
		note: 'autobuy:false — spends up to maxCostUsd of additional USDC downstream + real LLM tokens per call.',
	},
	{
		slug: 'fact-check',
		sourceFile: 'api/x402/fact-check.js',
		path: '/api/x402/fact-check',
		method: 'POST',
		body: () => ({ claim: 'The Eiffel Tower is 330 meters tall.', strictness: 'low' }),
		priceAtomicDefault: 100_000,
		priceSlug: 'fact-check',
		tier: 'commerce',
		kind: 'intel',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs a live LLM + web-search + authority-scoring verdict pipeline ($0.10).',
		note: 'autobuy:false — each uncached call burns real LLM tokens + external search quota; priciest catalog intel endpoint.',
	},
	{
		slug: 'llm-proxy',
		sourceFile: 'api/x402/llm-proxy.js',
		path: '/api/x402/llm-proxy',
		method: 'POST',
		body: () => ({ model: 'fast', prompt: 'Count to 3.', max_tokens: 10 }),
		priceAtomicDefault: 5_000,
		priceSlug: 'llm-proxy',
		tier: 'service',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs a real LLM completion through the provider chain (Groq→OpenRouter→NVIDIA→Anthropic).',
		note: 'autobuy:false — every call burns real LLM provider tokens.',
	},
	{
		slug: 'tutor',
		sourceFile: 'api/x402/tutor.js',
		path: '/api/x402/tutor',
		method: 'POST',
		body: () => ({ question: 'Why does recursion overflow the stack?' }),
		priceAtomicDefault: 10_000,
		priceSlug: 'tutor',
		tier: 'intel',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs an LLM tutoring answer and appends to the session tab.',
		note: 'autobuy:false — consumes real LLM tokens and writes a session row per call.',
	},
	{
		slug: 'cosmetic-purchase',
		sourceFile: 'api/x402/cosmetic-purchase.js',
		path: '/api/x402/cosmetic-purchase',
		method: 'GET',
		query: { id: 'legendary_crown', account: 'g_ringcanary' },
		body: NO_BODY,
		priceAtomicDefault: 0,
		priceSlug: 'cosmetic-purchase',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		// Price is per-item from api/_lib/cosmetics.js (priceUsdcAtomicsOf), not a
		// priceFor() default — priceAtomicDefault:0 marks "dynamic, see handler".
		businessEffect: 'Grants durable cosmetic ownership, inserts cosmetic_sales, and may send a real on-chain USDC creator payout.',
		note: 'autobuy:false — writes durable ownership, records a sale, and can trigger a real on-chain USDC payout to a third-party creator wallet; price up to several dollars. Verify once with a known premium item id.',
	},
	{
		slug: 'skill-call',
		sourceFile: 'api/x402/skill-call.js',
		path: '/api/x402/skill-call',
		method: 'GET',
		query: { skill: 'wallet-balance' },
		body: NO_BODY,
		priceAtomicDefault: 0,
		priceSlug: 'skill-call',
		tier: 'service',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		// Price = the listing's price_per_call_usd → atomics; payee = the skill
		// author's wallet. Depends on a live public, priced marketplace_skills row.
		businessEffect: 'Buys one skill call; settles USDC to the skill author and returns the skill payload.',
		note: 'autobuy:false — pays an author-set price to a third-party author wallet and depends on a live listing slug. Verify once against a known public priced skill.',
	},
	{
		slug: 'service',
		sourceFile: 'api/x402/service.js',
		path: '/api/x402/service',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 0,
		priceSlug: 'service',
		tier: 'service',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		// Per-agent-service dispatcher: /api/x402/service/<slug>. Price, payee and
		// upstream are all row-controlled (agent_paid_services), so it can't be
		// swept generically. Path is the base; the real route carries a slug.
		businessEffect: 'Proxies a paid agent service; settles USDC to the agent wallet and returns the upstream result.',
		note: 'autobuy:false — price/payee/upstream are agent-controlled per agent_paid_services row; not a fixed known endpoint.',
	},
	{
		slug: 'agents',
		sourceFile: 'api/x402/agents.js',
		path: '/api/x402/agents',
		method: 'POST',
		body: () => ({ message: 'hello' }),
		priceAtomicDefault: 0,
		priceSlug: 'agents',
		tier: 'service',
		kind: 'service',
		network: 'solana',
		autobuy: false,
		weight: 0,
		// Whole-agent dispatcher: /api/x402/agents/<agentId>. Price and payee are
		// owner-controlled per agent (meta.api_service), so it can't be swept
		// generically. Path is the base; the real route carries an agent id.
		businessEffect: 'Buys one conversational turn with an agent; settles USDC to the agent owner\'s payout wallet and returns the reply.',
		note: 'autobuy:false: price and payee are owner-set per agent and the payment lands in a third-party owner wallet; not a fixed known endpoint.',
	},
	{
		slug: 'animation-download',
		sourceFile: 'api/x402/animation-download.js',
		path: '/api/x402/animation-download',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 0,
		priceSlug: 'animation-download',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Returns a presigned download URL for a paid animation clip and bumps its purchase_count.',
		note: 'autobuy:false — price is per animation_clips row and requires a real listed clip id; verify once against a known priced clip.',
	},
	{
		slug: 'asset-download',
		sourceFile: 'api/x402/asset-download.js',
		path: '/api/x402/asset-download',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 0,
		priceSlug: 'asset-download',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Returns a presigned download URL for a paid asset.',
		note: 'autobuy:false — price is per paid_assets row and requires a real asset slug; verify once against a known asset.',
	},
	{
		slug: 'permit2-paid-demo',
		sourceFile: 'api/x402/permit2-paid-demo.js',
		path: '/api/x402/permit2-paid-demo',
		method: 'GET',
		body: NO_BODY,
		priceAtomicDefault: 1_000,
		priceSlug: 'permit2-paid-demo',
		tier: 'health',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Settles a Base-mainnet Permit2/EIP-2612 USDC payment and returns the tx hash.',
		note: 'autobuy:false — Base-only, Permit2/EIP-2612-only (no Solana accept). The Solana ring payer structurally cannot pay it; verify with an @x402/evm wallet.',
	},

	// ── AI services (v1) — real provider compute per call ───────────────────────
	{
		slug: 'ai-asr',
		sourceFile: 'api/v1/ai/asr.js',
		path: '/api/v1/ai/asr',
		method: 'POST',
		body: () => ({ audio: SILENT_WAV_B64, format: 'wav', language: 'en-US' }),
		priceAtomicDefault: 10_000,
		priceSlug: 'ai-asr',
		tier: 'intel',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Transcribes the sample WAV clip via the NVIDIA NIM Riva ASR lane, paid over x402 (no state written).',
		note: 'autobuy:false — every call burns real NVIDIA NIM Riva ASR compute; not a free read-only ping.',
	},
	{
		slug: 'ai-image',
		sourceFile: 'api/v1/ai/image.js',
		path: '/api/v1/ai/image',
		method: 'POST',
		body: () => ({ prompt: 'a brass owl figurine on a plain white background', aspect_ratio: '1:1' }),
		priceAtomicDefault: 20_000,
		priceSlug: 'ai-image',
		tier: 'intel',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Generates one AI image via the NVIDIA NIM / Vertex / Replicate lane and persists it to R2, paid over x402.',
		note: 'autobuy:false — every call burns real NVIDIA/Vertex/Replicate image-generation compute and persists a new R2 object.',
	},
	{
		slug: 'ai-tts',
		sourceFile: 'api/v1/ai/tts.js',
		path: '/api/v1/ai/tts',
		method: 'POST',
		body: () => ({ text: 'Ring canary heartbeat check.', voice: 'nova' }),
		priceAtomicDefault: 5_000,
		priceSlug: 'ai-tts',
		tier: 'service',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Synthesizes speech via the NVIDIA NIM Magpie TTS lane, paid over x402 (no state written).',
		note: 'autobuy:false — every call burns real NVIDIA NIM Magpie TTS compute.',
	},

	// ── 3D Asset Pipeline stages — real Cloud Run GPU compute per call ──────────
	{
		slug: 'pipeline-rembg',
		sourceFile: 'api/x402/pipeline-rembg.js',
		path: '/api/x402/pipeline-rembg',
		method: 'POST',
		body: () => ({ image_url: 'https://three.ws/og-image.png', model: 'rmbg2' }),
		priceAtomicDefault: 10_000,
		priceSlug: 'pipeline-rembg',
		tier: 'intel',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs a background-removal job against the Cloud Run rembg worker on a real image and persists the cutout PNG.',
		note: 'autobuy:false — every call runs a real Cloud Run GPU rembg worker job and persists a new object; not a cheap read-only ping.',
	},
	{
		slug: 'pipeline-remesh',
		sourceFile: 'api/x402/pipeline-remesh.js',
		path: '/api/x402/pipeline-remesh',
		method: 'POST',
		body: () => ({ glb_url: 'https://three.ws/avatars/default.glb', remesh_mode: 'triangle', target_faces: 20_000 }),
		priceAtomicDefault: 30_000,
		priceSlug: 'pipeline-remesh',
		tier: 'commerce',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs a retopology/decimation job against the Cloud Run remesh worker on a real GLB and persists the output mesh.',
		note: 'autobuy:false — every call runs a real Cloud Run GPU remesh worker job and persists a new GLB.',
	},
	{
		slug: 'pipeline-rig',
		sourceFile: 'api/x402/pipeline-rig.js',
		path: '/api/x402/pipeline-rig',
		method: 'POST',
		body: () => ({ glb_url: 'https://three.ws/avatars/default.glb', rig_type: 'biped' }),
		priceAtomicDefault: 50_000,
		priceSlug: 'pipeline-rig',
		tier: 'commerce',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs an auto-rig job against the avatar-pipeline-controller and persists a skinned, animation-ready GLB.',
		note: 'autobuy:false — every call runs a real auto-rig worker job (the priciest pipeline stage) and persists a new GLB.',
	},
	{
		slug: 'pipeline-stylize',
		sourceFile: 'api/x402/pipeline-stylize.js',
		path: '/api/x402/pipeline-stylize',
		method: 'POST',
		body: () => ({ glb_url: 'https://three.ws/avatars/default.glb', style: 'voxel' }),
		priceAtomicDefault: 30_000,
		priceSlug: 'pipeline-stylize',
		tier: 'commerce',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs a geometric stylize job (voxel/brick/voronoi/lowpoly) against the Cloud Run stylize worker and persists the output GLB.',
		note: 'autobuy:false — every call runs a real Cloud Run GPU stylize worker job and persists a new GLB.',
	},
	{
		slug: 'pipeline-gameready',
		sourceFile: 'api/x402/pipeline-gameready.js',
		path: '/api/x402/pipeline-gameready',
		method: 'POST',
		body: () => ({ glb_url: 'https://three.ws/avatars/default.glb', topology: 'quad', poly_budget: 15_000 }),
		priceAtomicDefault: 30_000,
		priceSlug: 'pipeline-gameready',
		tier: 'commerce',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Runs a game-ready retopology job (quad/tri poly budget) against the Cloud Run remesh worker and persists the output GLB.',
		note: 'autobuy:false — every call runs a real Cloud Run GPU remesh worker job and persists a new GLB.',
	},

	// ── embody — real GPU generation, the priciest single-call service ──────────
	{
		slug: 'embody',
		sourceFile: 'api/x402/embody.js',
		path: '/api/x402/embody',
		method: 'POST',
		body: () => ({ name: 'Ring Canary Body', prompt: 'a small friendly robot mascot' }),
		priceAtomicDefault: 1_000_000,
		priceSlug: 'embody',
		tier: 'commerce',
		kind: 'service',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Generates a rigged, animated GLB + a durable embeddable persona (agent_id, viewer/profile URLs, embed_html) via the free NVIDIA TRELLIS generate→auto-rig chain.',
		note: 'autobuy:false — every call is a real GPU generation ($1.00, the priciest single-call service in the catalog) and creates a durable persona row; not a cheap read-only ping.',
	},

	// ── remix — real generation + on-chain creator royalty ──────────────────────
	{
		slug: 'remix-asset',
		sourceFile: 'api/x402/remix-asset.js',
		path: '/api/x402/remix-asset',
		method: 'POST',
		body: () => ({ source_creation_id: RING_CANARY_UUID, instruction: 'make it metallic' }),
		priceAtomicDefault: 250_000,
		priceSlug: 'remix-asset',
		tier: 'commerce',
		kind: 'commerce',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Generates a real GPU-derived remix of a published creation, records parent→child provenance, and routes a real on-chain USDC royalty to the source creator.',
		note: 'autobuy:false — every call is a real GPU generation plus a possible real on-chain USDC royalty transfer to a third-party creator wallet; requires a live, published remixable source creation id (the canary UUID resolves to source_not_found). Verify once against a known published remixable source.',
	},

	// ── Robinhood Chain — market data ────────────────────────────────────────
	{
		slug: 'robinhood-portfolio',
		sourceFile: 'api/x402/robinhood-portfolio.js',
		path: '/api/x402/robinhood-portfolio',
		method: 'GET',
		query: { address: '0x0000000000000000000000000000000000000000' },
		body: NO_BODY,
		priceAtomicDefault: 2_000,
		priceSlug: 'robinhood-portfolio',
		tier: 'intel',
		kind: 'intel',
		network: null,
		autobuy: false,
		weight: 0,
		businessEffect: 'Reads a wallet\'s multiplier-correct Robinhood Chain Stock Token portfolio via on-chain multicall, priced at live Chainlink NAV (read-only, no state change).',
		note: 'autobuy:false — the canary (zero address) always succeeds but fans out one multicall of ~95 balanceOf reads against the public Robinhood Chain RPC per call; rotating it hourly adds avoidable RPC load for a brand-new, low-traffic endpoint. One-time settle proof via the coverage sweep.',
	},
];

// ── selectors ─────────────────────────────────────────────────────────────────

/** All entries the ring payer may purchase on a loop. */
export function autobuyEntries() {
	return RING_CATALOG.filter((e) => e.autobuy);
}

/** Look up a catalog entry by slug. */
export function bySlug(slug) {
	return RING_CATALOG.find((e) => e.slug === slug) || null;
}

/**
 * Build the round-robin rotation the volume loop / ring tick walks. Each autobuy
 * entry is expanded `weight` times and the copies are INTERLEAVED (round-robin
 * fill) rather than block-repeated, so a batch of N consecutive picks spreads
 * across distinct endpoints instead of clustering weighted duplicates together.
 *
 * A full pass over the returned array touches every autobuy slug at least once;
 * the cursor in the loop advances by its batch size each tick, so coverage is
 * guaranteed within ceil(rotation.length / batch) ticks. See
 * AUTONOMOUS_TICKS_PER_HOUR for the default-cadence math.
 *
 * @returns {CatalogEntry[]}
 */
export function rotationPlan() {
	const entries = autobuyEntries();
	const maxWeight = entries.reduce((m, e) => Math.max(m, e.weight || 1), 1);
	const plan = [];
	for (let pass = 0; pass < maxWeight; pass++) {
		for (const e of entries) {
			if ((e.weight || 1) > pass) plan.push(e);
		}
	}
	return plan;
}

// The x402 autonomous loop cron runs every 5 minutes (vercel.json:
// `/api/cron/x402-autonomous-loop` → `*/5 * * * *`) → 12 ticks/hour. The volume
// loop reserves VOLUME_BATCH_PER_RUN endpoints per tick, so default-cadence
// coverage = 12 * batch selections/hour. With batch 4 that is 48 selections/hour,
// comfortably above the rotation length, so every autobuy endpoint is selected
// at least once per hour. tests/x402-ring-catalog.test.js asserts this holds.
export const AUTONOMOUS_TICKS_PER_HOUR = 12;