Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(x402): list three.ws 3D, market data and agent trust APIs for the Solana Foundation pay registry
nirholasbe09f5a3db6a
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex b838ac538..db58119a4 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -99,6 +99,7 @@ bottom.| Fits: the public cosmetics economy | [pages/fits.html](pages/fits.html) `→ /fits`, page module [src/fits.js](src/fits.js) + pure helpers [src/fits-lib.js](src/fits-lib.js), backends [api/cosmetics/leaderboard.js](api/cosmetics/leaderboard.js) + [api/cosmetics/earnings.js](api/cosmetics/earnings.js), engine [api/_lib/cosmetics-economy.js](api/_lib/cosmetics-economy.js) | Live | The settled-sale cosmetics ledger, promoted out of a panel inside `/play` into a public surface. Rarest premium fits ranked by how few wallets own them (owner count first, rarity as the tie-break, so a legendary never sorts under an equally-scarce rare), top collectors by rarity-weighted flex score, top creators by **actually settled** USDC, and a live sales drip; each fit deep-links to its coin world at `/play?coin=<mint>`. Plus a creator-earnings lookup any wallet can run without an account (lifetime + 30-day, paid vs pending, per-cosmetic and per-coin-world breakdowns), reachable in one click from each creator row rather than by copy-pasting an address. Coin mints are runtime ledger values, never hardcoded. Headline numbers are derived from the same rows rendered beneath them, so they cannot disagree; the volume tile is labelled as the returned sales window, not as an all-time total. Sub-cent sales keep their precision instead of collapsing to $0.00. Tests: [tests/fits-lib.test.js](tests/fits-lib.test.js) || Receipt Vault: buyer-side proof of purchase | [pages/receipts.html](pages/receipts.html) `→ /receipts`, page module [src/receipts.js](src/receipts.js) + pure helpers [src/receipts-lib.js](src/receipts-lib.js), backend [api/x402/my-receipts.js](api/x402/my-receipts.js), storage [api/_lib/x402/receipt-storage.js](api/_lib/x402/receipt-storage.js), issuer [api/_lib/x402/offer-receipt-issuer.js](api/_lib/x402/offer-receipt-issuer.js), key publication [api/x402/did.js](api/x402/did.js) `→ /.well-known/did.json` | Live | What a given wallet **spent** on the platform's paid endpoints. Every settled x402 call issues a signed Offer & Receipt artifact (USE-17) and durably logs it; a buyer connects a Solana or EVM wallet, signs one read-only message (5-minute window, no transaction, no fee) and gets every receipt ever issued to that wallet: endpoint, settled amount, network, explorer-linked tx, the full signed artifact as JSON, plus search and CSV export. The signing message is a fixed four-line string that must stay byte-identical between `buildReceiptsMessage()` (client) and `buildExpectedMessage()` (server); [tests/receipts-lib.test.js](tests/receipts-lib.test.js) pins that contract against a verbatim copy of the server's function. The signed artifact carries no amount and omits the tx hash under the spec §5.2 privacy default, so the row records both separately as our own audit trail (migration [api/_lib/migrations/2026-07-28-x402-receipt-settlement.sql](api/_lib/migrations/2026-07-28-x402-receipt-settlement.sql)); receipts predating that capture report as "N of M priced" rather than under-reporting a total. Issuance requires `OFFER_RECEIPT_JWK` (jws) or `OFFER_RECEIPT_SIGNING_PRIVATE_KEY` (eip712); unset means no receipts are issued at all. Docs: [docs/x402-endpoints.md](docs/x402-endpoints.md) || Unified service catalog (one source, two storefronts) | [api/_lib/service-catalog/index.js](api/_lib/service-catalog/index.js), descriptors [api/_lib/service-catalog/services/](api/_lib/service-catalog/services/index.js) | Live | The canonical written-once record of every service (paid x402 + free crypto/3D bundles + OKX.AI rows). `toBazaarDiscovery()` generates every static `/api/x402/*` entry in the [api/wk.js](api/wk.js) discovery doc (replacing ~1,400 lines of hand-mirrored blocks); `toOkxCatalog()` reproduces the OKX `catalogIndex()` payload exactly, with an `include:'all'` projection ready for listing expansion. New paid service = drop `services/<slug>.js` + add its barrel import row. No-drift guards: [tests/service-catalog.test.js](tests/service-catalog.test.js). Spec: [specs/SERVICE_CATALOG.md](specs/SERVICE_CATALOG.md) |+| `pay` registry listing (Solana Foundation pay-skills) | Projection [api/_lib/service-catalog/pay-skills.js](api/_lib/service-catalog/pay-skills.js), generator [scripts/build-pay-skills.mjs](scripts/build-pay-skills.mjs) (`npm run build:pay-skills` / `check:pay-skills` / `verify:pay-skills`), output [distributions/pay-skills/](distributions/pay-skills/README.md), guard [tests/pay-skills.test.js](tests/pay-skills.test.js), runbook § 8 of [docs/ops/x402-discovery-listings.md](docs/ops/x402-discovery-listings.md) | Ready to submit | Three providers (`three-ws/3d`, `three-ws/market-data`, `three-ws/agent-trust`) for the registry behind the Solana Foundation `pay` CLI and MCP server, in the upstream layout so publishing is a copy. Paths, schemas, examples and prices come from the service catalog and the live price functions; registry-grade copy (verb-first 24-64 char ASCII summaries, every parameter described) lives in the projection and is rule-checked at build. `verify:pay-skills` runs the registry's own `pay catalog check` with live, never-paying probes; all three pass the Solana gate. The upstream PR is owner-gated. || Conversational refinement + remix economy | Iterate: [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) `refine_model` (free, on `/api/mcp-studio`) + [mcp-server/src/tools/refine-model.js](mcp-server/src/tools/refine-model.js) (paid stdio, $0.25); shared lineage core [mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js). Remix (paid track): feed [api/remix-feed.js](api/remix-feed.js) `→ /api/remix-feed` (free browse/publish/lineage), settlement [api/x402/remix-asset.js](api/x402/remix-asset.js) `→ /api/x402/remix-asset` + core [api/_lib/remix-settlement.js](api/_lib/remix-settlement.js) + split math [api/_lib/remix-royalty.js](api/_lib/remix-royalty.js). Docs [docs/remix.md](docs/remix.md), [docs/mcp-studio.md](docs/mcp-studio.md). | Live | Talk to a model to iterate it ("make it metallic") — real anchored re-generation with a revertable/branchable version lineage rendered as a viewer version strip; free on both the OpenAI 3D Studio and the paid MCP server. Creators publish a finished model as remixable (provenance + license + royalty on the existing `forge_creations` rows — no parallel store); another agent pays $0.25 USDC to remix it and a creator-set royalty (≤20%, capped) routes on-chain to the original creator via the audited `transferSolanaUSDC` rail. Split/caps/payout unit-tested ([tests/remix-settlement.test.js](tests/remix-settlement.test.js), [tests/remix-royalty.test.js](tests/remix-royalty.test.js), [tests/refine-lineage.test.js](tests/refine-lineage.test.js)). Free track stays crypto-free. Prompt 09. || Terminal renderer (3D in a shell, no GPU) | Renderer core [packages/tty-3d/](packages/tty-3d) (`@three-ws/tty-3d`, CLI `three-tty`), hosted stream [api/tty.js](api/tty.js) `→ /tty`, `/tty/:id`, `/api/tty`, page [pages/tty.html](pages/tty.html) + [src/tty-page.js](src/tty-page.js) `→ /tty`. Docs: [docs/tty.md](docs/tty.md). Tests: [packages/tty-3d/tests/tty-3d.test.js](packages/tty-3d/tests/tty-3d.test.js), [tests/api-tty.test.js](tests/api-tty.test.js) | Live | `curl three.ws/tty` and a rigged agent walks in your terminal, with nothing installed on either side. A pure-CPU software rasterizer (z-buffer, per-vertex linear blend skinning off the glTF animation samplers, meshopt decode on the way in) draws into a framebuffer the size of the caller's terminal and encodes it as `▀` half-blocks, so one cell carries two independently coloured pixels and pixels come out square. The server streams paced frames as `text/plain`, so the HTTP response IS the animation. Sibling of [packages/tty-avatar/](packages/tty-avatar), which adds moods, avatar-id resolution and Claude Code hooks on top of a terminal renderer but deliberately does not do skeletal animation; this package owns the 3D. || Restyle Studio (material/PBR editor + AI restyle + variants) | [pages/restyle.html](pages/restyle.html) `→ /restyle`, [src/restyle.js](src/restyle.js). PBR preset/variant library [packages/viewer-presets/src/materials.js](packages/viewer-presets/src/materials.js) (`@three-ws/viewer-presets`). AI restyle + persistence core [api/_lib/material-studio-store.js](api/_lib/material-studio-store.js), free hosted endpoint [api/material-studio.js](api/material-studio.js) `→ /api/material-studio`; paid agent twin [mcp-server/src/tools/restyle-material.js](mcp-server/src/tools/restyle-material.js) (`restyle_material`, $0.05 stdio MCP), thin core [mcp-server/src/tools/_material-core.js](mcp-server/src/tools/_material-core.js). Shares the `refine_model` lineage core ([mcp-server/src/tools/_lineage.js](mcp-server/src/tools/_lineage.js)) so a restyle/variant is just another kind of version, feeding prompt 09 remix. Docs: [docs/restyle.md](docs/restyle.md), [docs/mcp-tools.md](docs/mcp-tools.md). | Live | Re-skin any GLB without regenerating its mesh: live PBR editing (color/metalness/roughness/emissive/texture) with a one-click preset library (18 looks: chrome, gold, copper, brushed steel, gunmetal, matte, glossy, rubber, ceramic, glass, real glass, wood, stone, fabric, skin, car paint, neon, holographic), seeded reproducible colorway variants (mulberry32 PRNG, so the same base plus seed yields the same set), and free-text AI restyle ("make it chrome", "cyberpunk neon") via IBM Granite-proposed PBR factors applied + re-exported server-side. Every AI restyle / saved checkpoint mints a real, `gltf-validator`-checked, durably-stored GLB recorded in an immutable parent to child lineage: non-destructive in the durable sense, not just an in-browser Reset. Every server failure surfaces the API's own `error_description`, and a storage outage says so and points at Export GLB, which is wholly in-browser. Roadmap prompt 06. |diff --git a/api/_lib/service-catalog/pay-skills.js b/api/_lib/service-catalog/pay-skills.jsnew file mode 100644index 000000000..cb3beded0--- /dev/null+++ b/api/_lib/service-catalog/pay-skills.js@@ -0,0 +1,792 @@+// pay-skills projection: three.ws paid services as providers in the Solana+// Foundation `pay` registry (github.com/solana-foundation/pay-skills).+//+// `pay` is the Solana Foundation's agentic-payments CLI and MCP server. Its+// public registry is what `pay skills search` and every agent running+// `pay mcp` browse, and an entry there is a PAY.md (frontmatter + prose) plus a+// committed OpenAPI document whose operations carry `x-payment-info`.+//+// What is written here and what is read from elsewhere:+// - Paths, methods, input schemas and example inputs come from the service+// catalog descriptors (./services), so a schema change there flows into the+// listing on the next `npm run build:pay-skills`.+// - Prices come from the same functions the live 402 challenges quote from:+// the descriptor's priceAtomics, forge-tiers.js for Forge's three tiers,+// and pipeline.js for the per-stage pipeline sum.+// - Summaries, descriptions and a few parameter descriptions are written+// here, because the registry enforces its own copy rules that our other+// storefront text does not meet: verb-first operation summaries of 24-64+// ASCII characters (the summary becomes the reason line on the payer's+// biometric prompt), no marketing language, and every parameter described.+//+// The registry only admits endpoints that accept USDC or USDT on Solana+// mainnet, so a service whose accepts builder cannot offer Solana is refused+// at build time rather than listed and then failed by the registry's CI probe.+//+// Built into distributions/pay-skills/ by scripts/build-pay-skills.mjs.+// Guarded by tests/pay-skills.test.js.++import { PAID_SERVICES } from './services/index.js';+import { TIERS } from '../forge-tiers.js';+import { STAGE_IDS, priceAtomicsForStage } from '../pipeline.js';+import { FREE_DAILY_LIMIT as FACT_CHECK_FREE_DAILY } from '../../x402/fact-check.js';++export const ORIGIN = 'https://three.ws';+export const OPERATOR = 'three-ws';++// The $THREE mint: the only token this platform uses as a worked example.+const THREE_MINT = 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump';+// A real public three.ws agent (GET /api/agents/public) and a real remixable+// creation (GET /api/remix-feed), so examples resolve against live records.+const EXAMPLE_AGENT_ID = '27a0f649-3b59-4552-bb0b-faf616ac448b';+const EXAMPLE_REMIX_SOURCE = '3abac32f-ced2-4189-b822-d30c96dbc87e';++// Accepts builders whose live 402 offers include Solana (mirrors+// NETWORKS_BY_BUILDER in ./index.js). 'permit2-only' is Base-only.+const SOLANA_BUILDERS = new Set(['standard', 'cdp-bazaar']);++export const PAY_CATEGORIES = Object.freeze([+ 'ai_ml', 'cloud', 'compute', 'data', 'devtools', 'finance', 'identity', 'maps',+ 'media', 'messaging', 'other', 'productivity', 'search', 'security', 'shopping',+ 'storage', 'translation',+]);++// ── Price helpers ────────────────────────────────────────────────────────────++function usd(atomics) {+ const n = Number(atomics) / 1_000_000;+ if (!Number.isFinite(n) || n <= 0) throw new Error(`pay-skills: bad price atomics ${atomics}`);+ return String(Number(n.toFixed(6)));+}++const fixedPrice = (atomics) => ({ mode: 'fixed', currency: 'USD', amount: usd(atomics) });+const dynamicPrice = (minAtomics, maxAtomics) => ({+ mode: 'dynamic',+ currency: 'USD',+ min: usd(minAtomics),+ max: usd(maxAtomics),+});++function forgePrice() {+ const atomics = Object.values(TIERS).map((t) => t.priceUsdcAtomics);+ return dynamicPrice(Math.min(...atomics), Math.max(...atomics));+}++function pipelinePrice() {+ const atomics = STAGE_IDS.map((id) => Number(priceAtomicsForStage(id)));+ return dynamicPrice(Math.min(...atomics), atomics.reduce((a, b) => a + b, 0));+}++// ── Providers ────────────────────────────────────────────────────────────────+//+// Each operation is either `slug` (a paid service in the catalog) or `free`+// (an unpaid companion route an agent needs to finish a paid flow, such as+// polling a job). `params` overrides or fills a parameter's description and+// example; `example` replaces the descriptor's example input wholesale.++export const PAY_PROVIDERS = Object.freeze([+ {+ name: '3d',+ title: 'three.ws 3D',+ category: 'media',+ description:+ 'Text-to-3D and image-to-3D generation returning GLB models, plus a 3D asset pipeline: auto-rigging, remeshing, game-ready retopology, geometric stylizing, background removal, model inspection, remixing, and talking avatar bodies.',+ useCase:+ 'Use when an agent needs a 3D model, game asset, prop, or character: generate a GLB from a prompt or photos, rig a static mesh for animation, cut a mesh to a poly budget, restyle it, check a GLB before using it, or give an AI agent a 3D avatar body.',+ body: `three.ws is a 3D platform for AI agents. This provider covers the paid 3D+endpoints: generation (text or up to six photos in, textured GLB out), the+asset pipeline that turns any public GLB into a rigged, retopologized, or+restyled one, structural inspection of a GLB before you use it, remixes of+published models with on-chain creator royalties, and \`embody\`, which returns+a rigged, talking avatar plus a one-tag web embed for an agent.++Generation and pipeline calls are asynchronous. The paid response carries a+job token; poll \`GET /api/forge?job=<token>\` (free, no payment) until+\`status\` is \`done\` and read the GLB URL from the result. Draft-tier prompts+often finish inline and return the GLB URL directly.++Every output is a durable HTTPS URL to a binary glTF (GLB) that loads in+Three.js, Babylon.js, Unity, Unreal, Blender, and \`<model-viewer>\`.++## Spend-aware usage++- Generate at the \`draft\` tier while iterating on a prompt, then rerun the+ winner at \`standard\` or \`high\`.+- Chain stages in one \`/api/x402/pipeline\` call instead of paying for each+ stage separately; the 402 quotes the exact sum of the stages requested.+- Run \`/api/x402/model-check\` on a third-party GLB before paying to rig or+ remesh it; it reports triangle counts, materials, and problems first.+- Polling a job is free. Never resubmit a paid generation to check progress.+- Browse remix sources with the free \`GET /api/remix-feed\` before paying for a+ remix, and reuse the returned creation ids.`,+ operations: [+ {+ slug: 'forge',+ summary: 'Generate a 3D model (GLB) from a text prompt or photos',+ description:+ 'Generate a textured GLB mesh from one text prompt or up to six reference photos of one object. Tiers: draft (fast, low-poly), standard (default), high (PBR textures). Returns a job token to poll for free.',+ price: forgePrice,+ },+ {+ free: {+ method: 'GET',+ path: '/api/forge',+ operationId: 'forge_job_status',+ params: {+ job: {+ required: true,+ description: 'Job token returned by a paid generation or pipeline call.',+ },+ },+ },+ summary: 'Fetch the status and GLB URL of a 3D generation job',+ description:+ 'Poll a generation or pipeline job without payment. Returns status (queued, running, done, failed), per-stage progress for pipelines, and the GLB URL once the job is done.',+ },+ {+ slug: 'pipeline',+ summary: 'Submit a chained 3D job: generate, rig, remesh, stylize',+ description:+ 'Run an ordered chain of 3D stages (generate, rig, remesh, gameready, stylize) in one paid call. The 402 quotes the sum of the requested stages. Returns a job token to poll for free.',+ price: pipelinePrice,+ params: {+ options: {+ description:+ 'Per-stage options keyed by stage: tier and aspect_ratio for generate, rig_type for rig, remesh settings, gameready topology and poly_budget, stylize style and resolution.',+ },+ },+ },+ {+ slug: 'pipeline-rig',+ summary: 'Convert a static GLB mesh into a rigged, animatable model',+ description:+ 'Infer a skeleton for a static GLB and bind it with skin weights so the model can walk, wave, and emote. Returns a durable URL to the rigged GLB.',+ params: {+ rig_type: { description: 'Skeleton to infer: biped (humanoid, the default) or quadruped.' },+ },+ },+ {+ slug: 'pipeline-remesh',+ summary: 'Convert a GLB mesh to a new topology and face count',+ description:+ 'Retopologize a GLB as triangles, quads, or low-poly, with repair and decimation to a target face count, and re-bake the texture onto the new mesh. Returns a durable GLB URL.',+ params: {+ remesh_mode: { description: 'Output topology: triangle (default), quad, or lowpoly.' },+ operation: {+ description: 'full (default) remeshes and re-bakes; simplify, repair, or convert run one step only.',+ },+ target_faces: { description: 'Target face count for the output mesh, 1,000 to 500,000.' },+ texture_size: { description: 'Edge length in pixels of the re-baked texture.' },+ },+ },+ {+ slug: 'pipeline-gameready',+ summary: 'Convert a GLB into a game-ready mesh under a poly budget',+ description:+ 'Retopologize a GLB to a fixed polygon budget (quad or silhouette-preserving triangles) with PBR textures re-baked onto the new topology, ready for a game engine. Returns a durable GLB URL.',+ params: {+ topology: { description: 'Output topology: quad (default) or tri.' },+ poly_budget: { description: 'Maximum polygon count of the output mesh, 1,000 to 500,000.' },+ texture_size: { description: 'Edge length in pixels of the re-baked PBR textures.' },+ },+ },+ {+ slug: 'pipeline-stylize',+ summary: 'Convert a GLB mesh into voxel, brick, shatter, or low-poly',+ description:+ 'Rebuild a GLB geometrically in a voxel, brick, Voronoi-shatter, or faceted low-poly style. The style lives in the mesh, not a shader, so it survives export to any engine.',+ params: {+ style: { description: 'Geometric style: voxel (default), brick, voronoi, or lowpoly.' },+ },+ },+ {+ slug: 'pipeline-rembg',+ summary: 'Remove the background from an image for image-to-3D',+ description:+ 'Strip the background from an image and return a transparent PNG, the clean reference view image-to-3D reconstruction needs. Returns a durable PNG URL.',+ params: {+ model: { description: 'Segmentation model to use; rmbg2 (default) suits most objects.' },+ },+ },+ {+ slug: 'model-check',+ summary: 'Analyze a GLB model and return stats and optimization tips',+ description:+ 'Fetch a public glTF or GLB and return structural stats (vertices, triangles, materials, textures, animations, extensions) with a prioritized list of optimization recommendations.',+ },+ {+ slug: 'remix-asset',+ summary: 'Create a remix of a published 3D model from an instruction',+ description:+ 'Generate a new 3D model from a published remixable source and a plain-language change. Records parent-to-child provenance and routes the creator royalty on-chain.',+ example: { source_creation_id: EXAMPLE_REMIX_SOURCE, instruction: 'make it matte black with gold trim' },+ },+ {+ free: {+ method: 'GET',+ path: '/api/remix-feed',+ operationId: 'remix_feed',+ params: {+ limit: {+ type: 'integer',+ example: 12,+ description: 'Number of remixable models to return.',+ },+ },+ },+ summary: 'Browse remixable 3D models and their royalty terms',+ description:+ 'List published 3D models that accept remixes, with their GLB and preview URLs, royalty percentage, and remix count. Use a returned id as source_creation_id for a paid remix.',+ },+ {+ slug: 'embody',+ summary: 'Create a rigged, talking 3D avatar body for an AI agent',+ description:+ 'Create a rigged, animated, voiced 3D avatar from a prompt or a photo. Returns the agent id, GLB URL, viewer and profile URLs, and an HTML embed. Failed generations are not charged.',+ params: {+ name: { description: 'Display name for the avatar and its agent profile.' },+ prompt: { description: 'Appearance of the avatar in plain language. Give this or image_url.' },+ image_url: { description: 'Public photo of the subject to build the avatar from. Give this or prompt.' },+ personality: { description: 'Optional persona text the avatar speaks and behaves from.' },+ voice: { description: 'Optional voice id for the avatar\'s speech.' },+ },+ },+ {+ slug: 'mint-to-mesh',+ summary: 'Render a Solana token mint as a themed GLB 3D object',+ description:+ 'Turn any Solana SPL token mint into a GLB object themed from its on-chain metadata, with the token image as a texture when one exists and the metadata attached to the model.',+ },+ {+ slug: 'mint-to-mesh-batch',+ summary: 'Render up to 10 Solana token mints as themed GLB objects',+ description:+ 'Resolve one to ten Solana SPL mints to themed GLB objects in one call. Each mint succeeds or fails on its own; GLB bytes come back base64-encoded in JSON.',+ example: { mints: [THREE_MINT] },+ params: {+ mints: { description: 'One to ten base58 SPL mint addresses on Solana mainnet.' },+ },+ },+ ],+ },+ {+ name: 'market-data',+ title: 'three.ws Market Data',+ category: 'finance',+ description:+ 'Crypto and DeFi market data: coin tables, coin profiles, price history, sectors, exchanges, derivatives, TVL by protocol and chain, yield pools, stablecoin pegs, fees, DEX volume, exploit history, news pulse, and token signals.',+ useCase:+ 'Use for crypto prices, market caps, price charts, trending coins, DeFi TVL, yield farming research, stablecoin depeg checks, protocol exploit due diligence, perp funding rates, token market signals, or a one-call market overview.',+ body: `Pay-per-call crypto and DeFi market data from three.ws. Each endpoint is a+single GET that returns agent-ready JSON, priced in fractions of a cent. Data is+live from multiple upstream sources with failover; when an upstream is down the+call is refused before settlement, so you are never charged for an empty or+partial answer.++Start with \`/api/x402/market-pulse\` for broad context (global market, sentiment,+top coins, trending, TVL, stablecoin supply, DEX volume, and fees in one call),+then drill down with the narrow endpoints.++## Spend-aware usage++- Use \`market-pulse\` once instead of calling global, trending, defi, and+ stablecoin endpoints separately.+- Resolve a coin name to its id once with \`market-coins?q=<name>\` and reuse+ the id for \`market-coin\` and \`market-chart\`.+- Prefer the smallest \`limit\` that answers the question; most endpoints+ default to the full board.+- \`token-intel\` takes a contract address directly, so you can skip the id+ lookup for Solana tokens.+- Responses refresh every 1 to 10 minutes. Cache them instead of re-buying the+ same snapshot inside that window.`,+ operations: [+ {+ slug: 'market-pulse',+ summary: 'Fetch a one-call crypto market overview of eight feeds',+ description:+ 'Return global market cap and dominance, the fear and greed index, top 10 coins, trending searches, gas, DeFi TVL with top protocols, stablecoin supply, DEX volume, and protocol fees in one response.',+ },+ {+ slug: 'token-intel',+ summary: 'Analyze a token by contract address with a market signal',+ description:+ 'Return price, 24h change, market cap, liquidity, 24h volume, and a bullish, bearish, or neutral signal with a two-sentence rationale for any token by contract address.',+ params: {+ mint: { description: 'Token contract address: a Solana base58 mint or an EVM 0x address.' },+ },+ },+ {+ slug: 'market-coins',+ summary: 'Fetch a ranked crypto market table with 7-day sparklines',+ description:+ 'Return coins ranked by market cap with price, market cap, 24h volume, 24h and 7d change, logo, and a 7-day sparkline, up to 250 per page. Pass q to resolve a name or ticker to coin ids.',+ params: {+ category: {+ description: 'Optional sector id from the market-categories endpoint to scope the table to one sector.',+ },+ q: { description: 'Search mode: resolve a name or ticker to coin ids and return the top 10 matches.' },+ },+ },+ {+ slug: 'market-coin',+ summary: 'Fetch a full profile for one coin by id or Solana mint',+ description:+ 'Return live market stats (price, market cap, FDV, volume, change windows, all-time high and low, supply), official links, per-chain contract addresses, and developer and community stats for one coin.',+ example: { contract: THREE_MINT },+ params: {+ id: { description: 'Coin id: the lowercase slug from market-coins. Required unless contract is set.' },+ contract: { description: 'Solana token mint (base58), an alternative lookup key to id.' },+ },+ },+ {+ slug: 'market-chart',+ summary: 'Fetch the historical price series for one coin',+ description:+ 'Return [timestamp_ms, price_usd] pairs for one coin over 1, 7, 30, 90, or 365 days, 5-minutely for one day, hourly up to 90 days, and daily beyond.',+ example: { id: 'solana', days: '30' },+ params: {+ id: { description: 'Coin id: the lowercase slug from market-coins, for example solana.' },+ },+ },+ {+ slug: 'market-categories',+ summary: 'Fetch crypto market sectors ranked by market cap',+ description:+ 'Return every crypto sector ranked by market cap with 24h market-cap change, 24h volume, and its top three coins. Pass a sector id to market-coins to drill in.',+ },+ {+ slug: 'market-exchanges',+ summary: 'Fetch spot crypto exchanges ranked by trust and volume',+ description:+ 'Return the top 100 spot exchanges ranked by trust score, each with 24h volume, trust rank, country, year established, and homepage.',+ },+ {+ slug: 'market-derivatives',+ summary: 'Fetch perpetual futures tickers, funding, and open interest',+ description:+ 'Return the top 100 perpetual futures contracts by 24h volume with price, 24h change, funding rate, and open interest, or pass view=exchanges for the derivatives venue leaderboard.',+ },+ {+ slug: 'market-global',+ summary: 'Fetch the global crypto market cap, volume, and sentiment',+ description:+ 'Return total crypto market cap, 24h volume, dominance shares, active coin count, and the fear and greed index with its label. A one-call market-regime check.',+ },+ {+ slug: 'market-trending',+ summary: 'Fetch the most-searched coins and trending categories',+ description:+ 'Return the most-searched coins over the last 24 hours with price, 24h change, market cap, and trending rank, plus trending categories and NFT collections.',+ },+ {+ slug: 'market-defi',+ summary: 'Fetch DeFi protocols ranked by total value locked',+ description:+ 'Return the top 100 DeFi protocols by TVL with 1d and 7d change, chains, category, token, and market cap, plus total DeFi TVL with exchange reserves excluded.',+ },+ {+ slug: 'market-chains',+ summary: 'Fetch blockchains ranked by DeFi total value locked',+ description:+ 'Return the top 100 blockchains ranked by DeFi TVL, each with its native token symbol and share of total value locked, plus whole-market TVL.',+ },+ {+ slug: 'market-yields',+ summary: 'Search DeFi yield pools by chain, protocol, and TVL',+ description:+ 'Query about 15,000 DeFi yield pools filtered by chain, protocol, stablecoin exposure, or text, sorted by TVL or APY, with pagination. Pass pool for one pool\'s APY and TVL history.',+ params: {+ project: { description: 'Filter to one protocol slug, as listed by market-defi.' },+ pool: {+ description: 'Chart mode: a pool id from a previous market-yields row. Returns that pool\'s APY and TVL history.',+ },+ },+ },+ {+ slug: 'market-stablecoins',+ summary: 'Fetch stablecoins ranked by supply with live peg prices',+ description:+ 'Return the top 100 stablecoins by circulating supply with live price for a peg check, peg type and mechanism, and chains, plus total stablecoin market cap.',+ },+ {+ slug: 'market-fees',+ summary: 'Fetch DeFi protocols ranked by fees or revenue',+ description:+ 'Return the top 100 protocols by 24h fees with 24h, 7d, and 30d totals and momentum. type=revenue ranks by what the protocol keeps instead of what users pay.',+ },+ {+ slug: 'market-dex-volumes',+ summary: 'Fetch decentralized exchanges ranked by 24h volume',+ description:+ 'Return the top 100 DEXes by 24h volume with 7d volume, week-over-week change, chains, and share of total DEX volume, plus market totals and a daily chart.',+ },+ {+ slug: 'market-hacks',+ summary: 'Search the DeFi exploit history by name or technique',+ description:+ 'Return historical DeFi exploits newest first with amount stolen, attack technique, classification, chains, bridge flag, post-mortem link, and funds returned. Search by name or technique.',+ },+ {+ slug: 'defi-radar',+ summary: 'Fetch DeFi TVL movers, top fee earners, and top DEXes',+ description:+ 'Return total DeFi TVL, the largest 24h TVL gainers and losers, the top fee-earning protocols over 24h, 7d, and 30d, and the top DEXes by 24h volume in one snapshot.',+ },+ {+ slug: 'yield-scan',+ summary: 'Search DeFi yield pools with risk flags by APY or TVL',+ description:+ 'Screen 15,000+ yield pools by chain, minimum TVL, and stablecoin-only exposure. Each pool carries base and reward APY, 30-day mean, TVL, and impermanent-loss, volatility, and spike flags.',+ params: {+ chain: { description: 'Filter to one chain by name, for example Solana (case-insensitive).' },+ stable: { description: 'true returns stablecoin-denominated pools only.' },+ },+ },+ {+ slug: 'stablecoin-health',+ summary: 'Monitor stablecoin peg deviation and supply flows',+ description:+ 'Score every USD stablecoin on peg deviation in basis points (on-peg, drifting, or depegged), circulating supply, and 24h, 7d, and 30d supply change, with a depeg alert list.',+ },+ {+ slug: 'hack-check',+ summary: 'Check a DeFi protocol for past exploits before using it',+ description:+ 'Return a clean or incident-history verdict for a protocol with every matching exploit (date, amount lost, technique, chains, recovered funds) and market-wide loss stats. Omit protocol for the latest incidents.',+ },+ {+ slug: 'market-heatmap',+ summary: 'Fetch top coins with momentum and market-breadth stats',+ description:+ 'Return the top coins by market cap with rank, price, 1h, 24h, and 7d momentum, market cap, and volume, plus breadth stats (advancers versus decliners, average and median move).',+ },+ {+ slug: 'market-mood',+ summary: 'Calculate a 0-100 crypto market mood score',+ description:+ 'Blend the fear and greed index with live headline sentiment from 192 crypto news feeds into one 0-100 mood score, returning both components, the driving headlines, and implied volatility.',+ },+ {+ slug: 'news-pulse',+ summary: 'Monitor news coverage and sentiment for one token ticker',+ description:+ 'Count mentions of a ticker across 192 crypto news feeds in a 1-72 hour window and return unique outlets, sentiment split, coverage velocity versus the prior window, and top headlines.',+ params: {+ ticker: { description: 'Ticker symbol to scan for, for example THREE. A leading $ is optional.' },+ },+ },+ ],+ },+ {+ name: 'agent-trust',+ title: 'three.ws Agent Trust',+ category: 'identity',+ description:+ 'Counterparty checks for AI agents: 0-100 reputation scores for wallets, mints, and agents from on-chain evidence, admit or refuse verdicts against a trust policy, on-chain identity claim verification, and sourced fact checks.',+ useCase:+ 'Use when an agent is about to pay, hire, trade with, or delegate to an unknown wallet, token, or agent: score its reputation, gate it with a trust policy, verify an address it claims, or fact-check a claim it made.',+ body: `Trust primitives for agent-to-agent commerce on three.ws. An agent about to+pay, hire, or delegate to a counterparty it has never met can buy evidence+first: a deterministic reputation score from on-chain history and settled+agent payments, a door verdict against its own trust policy, proof that an+identity really controls the address it claims, and a sourced verdict on a+factual claim.++Unknown subjects return a null score rather than an invented one, and every+verdict carries the evidence behind it.++## Spend-aware usage++- Check a counterparty once per session and cache the verdict; scores move+ slowly.+- Use \`agent-bouncer\` when you already hold a three.ws agent id and a policy;+ it is the cheapest yes-or-no gate.+- Use \`agent-reputation\` for wallets and mints outside three.ws.+- Keep fact-check claims to one checkable statement each. The first+ ${FACT_CHECK_FREE_DAILY} checks per day per IP are served free (marked \`lane: "free"\`);+ after that each check returns a 402.`,+ operations: [+ {+ slug: 'agent-reputation',+ summary: 'Score a wallet, token, or AI agent for trust from 0 to 100',+ description:+ 'Return a deterministic 0-100 trust score for a wallet, token mint, ERC-8004 agent id, or three.ws agent id from transaction history, age, counterparties, holdings, and settled agent payments.',+ params: {+ subject: {+ description: 'Counterparty to score: a Solana or EVM wallet, a token mint, an ERC-8004 agent id, or a three.ws agent id.',+ },+ chain: { description: 'Optional EVM chain id or CAIP-2 chain to resolve an EVM subject on.' },+ },+ },+ {+ slug: 'agent-bouncer',+ summary: 'Check whether to admit an AI agent by its payment record',+ description:+ 'Read a three.ws agent\'s Solana track record (payments, distinct payers, failure rate, attestations) and return an admit or refuse verdict with a tier: newcomer, regular, trusted, or vip.',+ example: { agent_id: EXAMPLE_AGENT_ID, min_payments: 10, min_distinct_payers: 3, max_failure_rate: 0.2 },+ params: {+ agent_id: { description: 'three.ws agent id (UUID) of the counterparty to check.' },+ min_payments: { description: 'Minimum confirmed on-chain payments the agent must have received.' },+ min_distinct_payers: { description: 'Minimum number of distinct wallets that have paid the agent.' },+ max_failure_rate: { description: 'Highest acceptable payment failure rate, from 0 to 1.' },+ min_attestations: { description: 'Minimum signed Solana attestations the agent must hold.' },+ allow_newcomers: { description: 'Admit agents with no history yet instead of refusing them.' },+ },+ },+ {+ slug: 'onchain-identity-verify',+ summary: 'Verify that an identity controls a wallet, mint, or contract',+ description:+ 'Check a claim that an identity controls an address and return on-chain evidence (deployer, mint and update authority, name resolution, agent registration) with verified true, false, or unverifiable.',+ example: { identity: EXAMPLE_AGENT_ID, address: THREE_MINT },+ params: {+ identity: {+ description: 'Claimed identity: a wallet, a name-service name, an ERC-8004 agent id, or a three.ws agent id.',+ },+ address: { description: 'Contract, mint, or wallet the identity claims to control.' },+ chain: { description: 'Optional CAIP-2 chain hint for the address.' },+ },+ },+ {+ slug: 'fact-check',+ summary: 'Verify a factual claim and return a sourced verdict',+ description: `Check a claim against live web sources and return supported, contradicted, mixed, or insufficient with cited sources, a confidence score, and a SHA-256 attestation. The first ${FACT_CHECK_FREE_DAILY} checks per day per IP are free.`,+ params: {+ claim: { description: 'One factual statement to check, 5 to 1,000 characters.' },+ strictness: { description: 'How hard low-authority sources are downweighted: high, medium, or low.' },+ imageUrl: { description: 'Optional public image URL to check alongside the claim.' },+ },+ },+ ],+ },+]);++// ── ASCII projection ─────────────────────────────────────────────────────────++// The registry rejects non-ASCII in listing text (it renders on OS biometric+// prompts). Descriptor schema text uses typographic characters, so map the+// ones it uses and let assertListing fail on anything else.+const ASCII_MAP = new Map([+ ['\u2192', '->'], ['\u2190', '<-'], ['\u2014', ', '], ['\u2013', '-'], ['\u2026', '...'],+ ['\u2265', '>='], ['\u2264', '<='], ['\u00d7', 'x'], ['\u2018', "'"], ['\u2019', "'"],+ ['\u201c', '"'], ['\u201d', '"'], ['\u00b7', '-'], ['\u00a0', ' '],+]);++export function toAscii(text) {+ let out = '';+ for (const ch of String(text)) out += ASCII_MAP.get(ch) ?? ch;+ return out.replace(/ ,/g, ',').replace(/ {2,}/g, ' ');+}++function asciiDeep(value) {+ if (typeof value === 'string') return toAscii(value);+ if (Array.isArray(value)) return value.map(asciiDeep);+ if (value && typeof value === 'object') {+ return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, asciiDeep(v)]));+ }+ return value;+}++// ── Listing rules (mirrors `pay catalog check`) ──────────────────────────────++const SUMMARY_MIN = 24;+const SUMMARY_MAX = 64;+const isAscii = (s) => /^[\x20-\x7e\n]*$/.test(s);++export function listingProblems(provider, openapi) {+ const problems = [];+ const where = `${OPERATOR}/${provider.name}`;+ const len = (s) => String(s || '').length;+ if (len(provider.description) < 64 || len(provider.description) > 255) {+ problems.push(`${where}: description must be 64-255 chars (got ${len(provider.description)})`);+ }+ if (len(provider.useCase) < 32 || len(provider.useCase) > 255) {+ problems.push(`${where}: use_case must be 32-255 chars (got ${len(provider.useCase)})`);+ }+ if (!/^Use (for|when) /.test(provider.useCase)) problems.push(`${where}: use_case must start with "Use for" or "Use when"`);+ if (!PAY_CATEGORIES.includes(provider.category)) problems.push(`${where}: unknown category ${provider.category}`);+ for (const field of ['title', 'description', 'useCase', 'body']) {+ if (!isAscii(provider[field])) problems.push(`${where}: ${field} has non-ASCII characters`);+ }+ for (const [path, item] of Object.entries(openapi.paths)) {+ for (const [method, op] of Object.entries(item)) {+ const at = `${where}: ${method.toUpperCase()} ${path}`;+ if (len(op.summary) < SUMMARY_MIN || len(op.summary) > SUMMARY_MAX) {+ problems.push(`${at}: summary must be ${SUMMARY_MIN}-${SUMMARY_MAX} chars (got ${len(op.summary)})`);+ }+ if (len(op.description) < 32 || len(op.description) > 255) {+ problems.push(`${at}: description must be 32-255 chars (got ${len(op.description)})`);+ }+ const text = JSON.stringify(op);+ if (!isAscii(text.replace(/\\n/g, ''))) problems.push(`${at}: operation has non-ASCII characters`);+ for (const p of op.parameters || []) {+ if (!p.description) problems.push(`${at}: parameter ${p.name} has no description`);+ }+ const schema = op.requestBody?.content?.['application/json']?.schema;+ for (const [name, prop] of Object.entries(schema?.properties || {})) {+ if (!prop.description) problems.push(`${at}: body field ${name} has no description`);+ }+ }+ }+ return problems;+}++// ── OpenAPI assembly ─────────────────────────────────────────────────────────++function serviceBySlug(slug) {+ const s = PAID_SERVICES.find((svc) => svc.slug === slug);+ if (!s) throw new Error(`pay-skills: no service-catalog descriptor for "${slug}"`);+ if (s.status !== 'live') throw new Error(`pay-skills: "${slug}" is ${s.status}, only live services are listed`);+ if (!SOLANA_BUILDERS.has(s.acceptsBuilder)) {+ throw new Error(`pay-skills: "${slug}" (${s.acceptsBuilder}) cannot be paid on Solana`);+ }+ return s;+}++function mergeProp(prop, override) {+ if (!override) return { ...prop };+ const { required: _required, ...rest } = override;+ return { ...prop, ...rest };+}++function queryParameters(schema, example, overrides = {}) {+ const required = new Set(schema?.required || []);+ const props = { ...(schema?.properties || {}) };+ for (const [name, o] of Object.entries(overrides)) {+ if (!props[name]) props[name] = { type: o.type || 'string' };+ if (o.required) required.add(name);+ }+ return Object.entries(props).map(([name, prop]) => {+ const merged = mergeProp(prop, overrides[name]);+ const { description, example: propExample, ...rest } = merged;+ const value = example && example[name] !== undefined ? example[name] : propExample;+ return {+ name,+ in: 'query',+ required: required.has(name),+ description,+ schema: { type: rest.type || 'string', ...rest },+ ...(value !== undefined && value !== '' ? { example: value } : {}),+ };+ });+}++function requestBody(schema, example, overrides = {}) {+ const { $schema: _s, ...rest } = schema || { type: 'object', properties: {} };+ const properties = {};+ for (const [name, prop] of Object.entries(rest.properties || {})) {+ properties[name] = mergeProp(prop, overrides[name]);+ }+ return {+ required: true,+ content: {+ 'application/json': {+ schema: { ...rest, properties },+ ...(example ? { example } : {}),+ },+ },+ };+}++function paidOperation(op) {+ const s = serviceBySlug(op.slug);+ const example = op.example ?? s.input;+ const price = op.price ? op.price() : fixedPrice(s.priceAtomics);+ const isGet = s.method === 'GET';+ return [+ s.path,+ s.method.toLowerCase(),+ {+ operationId: s.slug.replace(/-/g, '_'),+ summary: op.summary,+ description: op.description,+ security: [],+ ...(isGet+ ? { parameters: queryParameters(s.inputSchema, example, op.params) }+ : { requestBody: requestBody(s.inputSchema, example, op.params) }),+ 'x-payment-info': { price, protocols: [{ x402: {} }] },+ responses: {+ 200: { description: 'Paid result as JSON.' },+ 400: { description: 'Missing or invalid input. Refused before any payment settles.' },+ 402: { description: 'Payment Required: an x402 challenge payable in USDC on Solana mainnet.' },+ },+ },+ ];+}++function freeOperation(op) {+ const f = op.free;+ return [+ f.path,+ f.method.toLowerCase(),+ {+ operationId: f.operationId,+ summary: op.summary,+ description: op.description,+ security: [],+ parameters: queryParameters({ properties: {} }, null, f.params),+ responses: { 200: { description: 'Result as JSON. No payment required.' } },+ },+ ];+}++export function buildOpenApi(provider) {+ const paths = {};+ for (const op of provider.operations) {+ const [path, method, operation] = op.free ? freeOperation(op) : paidOperation(op);+ paths[path] = { ...(paths[path] || {}), [method]: operation };+ }+ return asciiDeep({+ openapi: '3.1.0',+ info: {+ title: provider.title,+ version: '1.0.0',+ description: provider.description,+ 'x-logo': { url: `${ORIGIN}/favicon.svg`, altText: 'three.ws' },+ 'x-guidance':+ 'Call an endpoint without payment to receive an x402 challenge, pay it in USDC on Solana mainnet, and retry with the payment header. Asynchronous 3D jobs return a token to poll for free at GET /api/forge?job=<token>.',+ },+ servers: [{ url: ORIGIN }],+ paths,+ });+}++function yamlString(s) {+ return JSON.stringify(s);+}++export function buildPayMd(provider) {+ return [+ '---',+ `name: ${provider.name}`,+ `title: ${yamlString(provider.title)}`,+ `description: ${yamlString(provider.description)}`,+ `use_case: ${yamlString(provider.useCase)}`,+ `category: ${provider.category}`,+ `service_url: ${ORIGIN}`,+ 'openapi:',+ ' path: openapi.json',+ '---',+ '',+ provider.body.trim(),+ '',+ ].join('\n');+}++// Every provider as the files its registry directory holds, keyed by path+// relative to the registry root. Throws with every rule violation at once.+export function buildPaySkills() {+ const files = {};+ const problems = [];+ for (const provider of PAY_PROVIDERS) {+ const openapi = buildOpenApi(provider);+ problems.push(...listingProblems(provider, openapi));+ const dir = `providers/${OPERATOR}/${provider.name}`;+ files[`${dir}/PAY.md`] = buildPayMd(provider);+ files[`${dir}/openapi.json`] = `${JSON.stringify(openapi, null, 2)}\n`;+ }+ if (problems.length) {+ throw new Error(`pay-skills listing rules failed:\n ${problems.join('\n ')}`);+ }+ return files;+}diff --git a/api/_lib/x402/fresh-workers/chain.js b/api/_lib/x402/fresh-workers/chain.jsindex f1f69fc02..332b27432 100644--- a/api/_lib/x402/fresh-workers/chain.js+++ b/api/_lib/x402/fresh-workers/chain.js@@ -74,22 +74,18 @@ async function sendIxs(conn, feePayer, signers, instructions, { confirmMs = 30_0}/** SOL balance in lamports (0 for a never-seen account), or null when unreadable. */-// readAccountInfoOrNull({ withCause: true }) always resolves to { info, cause }:-// info === null with no cause is an account that does not exist, a cause is an-// RPC transport failure. Reading the wrapper itself as the account reported 0-// lamports for every wallet and kept the lane on funder_headroom forever.export async function readSolLamports(conn, pubkey) {- const { info, cause } = await readAccountInfoOrNull(conn, pubkey, { commitment: 'confirmed', withCause: true });- if (cause) return null;- if (!info) return 0;+ const info = await readAccountInfoOrNull(conn, pubkey, { commitment: 'confirmed', withCause: true });+ if (info === null) return 0;+ if (info === undefined) return null;return Number(info.lamports || 0);}/** USDC held by an owner's ATA: { exists, atomic } or null when unreadable. */export async function readUsdc(conn, ata) {- const { info, cause } = await readAccountInfoOrNull(conn, ata, { commitment: 'confirmed', withCause: true });- if (cause) return null;- if (!info) return { exists: false, atomic: 0n };+ const info = await readAccountInfoOrNull(conn, ata, { commitment: 'confirmed', withCause: true });+ if (info === null) return { exists: false, atomic: 0n };+ if (info === undefined) return null;return { exists: true, atomic: tokenAmountFromAccountData(info.data) };}diff --git a/distributions/pay-skills/README.md b/distributions/pay-skills/README.mdnew file mode 100644index 000000000..96b38d1fd--- /dev/null+++ b/distributions/pay-skills/README.md@@ -0,0 +1,70 @@+# three.ws in the `pay` registry++This directory holds the three.ws providers for+[`pay-skills`](https://github.com/solana-foundation/pay-skills), the public+registry of stablecoin-gated APIs behind the Solana Foundation's+[`pay`](https://github.com/solana-foundation/pay) CLI and MCP server. Every+agent that runs `pay skills search`, or browses the catalog through+`pay mcp`, finds providers from this registry, and `pay curl` pays their 402+challenges in USDC on Solana.++The layout mirrors the upstream repository exactly, so publishing is a copy:++| Provider (FQN) | Category | What it lists |+|---|---|---|+| [`three-ws/3d`](providers/three-ws/3d/PAY.md) | media | Text and image to 3D, the asset pipeline (rig, remesh, game-ready, stylize, background removal), model inspection, remixes, avatar bodies, token-to-mesh, and the free job-status and remix-feed routes |+| [`three-ws/market-data`](providers/three-ws/market-data/PAY.md) | finance | The paid market data API: coin tables and profiles, price history, sectors, exchanges, derivatives, TVL, yields, stablecoins, fees, DEX volume, exploits, mood, news pulse, token signals |+| [`three-ws/agent-trust`](providers/three-ws/agent-trust/PAY.md) | identity | Agent reputation scores, the agent bouncer, on-chain identity verification, fact checks |++## Do not edit these files by hand++They are generated from the service catalog by+[`api/_lib/service-catalog/pay-skills.js`](../../api/_lib/service-catalog/pay-skills.js).+Paths, input schemas, examples, and prices come from the catalog descriptors and+the same price functions the live 402 challenges use. The listing copy (summaries,+descriptions) lives in that module because the registry has its own rules:+verb-first operation summaries of 24 to 64 ASCII characters, no marketing+language, and a description on every parameter.++```bash+npm run build:pay-skills # regenerate after a catalog change+npm run check:pay-skills # fail when the committed files are stale+npm run verify:pay-skills # regenerate, then run the registry's own validator+ # with live probes against https://three.ws+```++`verify:pay-skills` runs `pay catalog check` from the pinned `@solana/pay` npm+package, which is the same check the registry runs on every pull request. It+calls each paid endpoint once without payment and requires a 402 that is payable+in USDC on Solana mainnet. It never pays anything. `tests/pay-skills.test.js`+fails the test suite when the committed files drift from the generator.++## Adding a service++1. Make sure the service has a live descriptor in+ `api/_lib/service-catalog/services/` whose accepts builder offers Solana.+2. Add an operation to the right provider in `PAY_PROVIDERS` with a+ verb-first `summary` and a plain `description`. Fill any parameter that has no+ description through `params`.+3. Run `npm run verify:pay-skills` and commit the regenerated files.++## Publishing upstream++Copy `providers/three-ws/` into a fork of `solana-foundation/pay-skills`, run+`pay catalog check providers/three-ws/<name>/PAY.md` there, and open a pull+request. The registry's CI re-probes every listed endpoint before merge. The+runbook and submission log live in `docs/ops/x402-discovery-listings.md`.++## Calling three.ws with `pay`++Once `pay setup` has a funded Solana wallet, any listed endpoint is one command.+`pay` reads the 402, asks you to approve the payment, signs a USDC transfer on+Solana, and retries:++```bash+pay curl 'https://three.ws/api/x402/market-global'+pay curl 'https://three.ws/api/x402/token-intel?mint=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump'+pay curl -X POST https://three.ws/api/x402/forge \+ -H 'content-type: application/json' \+ -d '{"prompt":"a brass steampunk owl, full body","tier":"draft"}'+```diff --git a/distributions/pay-skills/providers/three-ws/3d/PAY.md b/distributions/pay-skills/providers/three-ws/3d/PAY.mdnew file mode 100644index 000000000..717420927--- /dev/null+++ b/distributions/pay-skills/providers/three-ws/3d/PAY.md@@ -0,0 +1,37 @@+---+name: 3d+title: "three.ws 3D"+description: "Text-to-3D and image-to-3D generation returning GLB models, plus a 3D asset pipeline: auto-rigging, remeshing, game-ready retopology, geometric stylizing, background removal, model inspection, remixing, and talking avatar bodies."+use_case: "Use when an agent needs a 3D model, game asset, prop, or character: generate a GLB from a prompt or photos, rig a static mesh for animation, cut a mesh to a poly budget, restyle it, check a GLB before using it, or give an AI agent a 3D avatar body."+category: media+service_url: https://three.ws+openapi:+ path: openapi.json+---++three.ws is a 3D platform for AI agents. This provider covers the paid 3D+endpoints: generation (text or up to six photos in, textured GLB out), the+asset pipeline that turns any public GLB into a rigged, retopologized, or+restyled one, structural inspection of a GLB before you use it, remixes of+published models with on-chain creator royalties, and `embody`, which returns+a rigged, talking avatar plus a one-tag web embed for an agent.++Generation and pipeline calls are asynchronous. The paid response carries a+job token; poll `GET /api/forge?job=<token>` (free, no payment) until+`status` is `done` and read the GLB URL from the result. Draft-tier prompts+often finish inline and return the GLB URL directly.++Every output is a durable HTTPS URL to a binary glTF (GLB) that loads in+Three.js, Babylon.js, Unity, Unreal, Blender, and `<model-viewer>`.++## Spend-aware usage++- Generate at the `draft` tier while iterating on a prompt, then rerun the+ winner at `standard` or `high`.+- Chain stages in one `/api/x402/pipeline` call instead of paying for each+ stage separately; the 402 quotes the exact sum of the stages requested.+- Run `/api/x402/model-check` on a third-party GLB before paying to rig or+ remesh it; it reports triangle counts, materials, and problems first.+- Polling a job is free. Never resubmit a paid generation to check progress.+- Browse remix sources with the free `GET /api/remix-feed` before paying for a+ remix, and reuse the returned creation ids.diff --git a/distributions/pay-skills/providers/three-ws/3d/openapi.json b/distributions/pay-skills/providers/three-ws/3d/openapi.jsonnew file mode 100644index 000000000..d0711efef--- /dev/null+++ b/distributions/pay-skills/providers/three-ws/3d/openapi.json@@ -0,0 +1,929 @@+{+ "openapi": "3.1.0",+ "info": {+ "title": "three.ws 3D",+ "version": "1.0.0",+ "description": "Text-to-3D and image-to-3D generation returning GLB models, plus a 3D asset pipeline: auto-rigging, remeshing, game-ready retopology, geometric stylizing, background removal, model inspection, remixing, and talking avatar bodies.",+ "x-logo": {+ "url": "https://three.ws/favicon.svg",+ "altText": "three.ws"+ },+ "x-guidance": "Call an endpoint without payment to receive an x402 challenge, pay it in USDC on Solana mainnet, and retry with the payment header. Asynchronous 3D jobs return a token to poll for free at GET /api/forge?job=<token>."+ },+ "servers": [+ {+ "url": "https://three.ws"+ }+ ],+ "paths": {+ "/api/x402/forge": {+ "post": {+ "operationId": "forge",+ "summary": "Generate a 3D model (GLB) from a text prompt or photos",+ "description": "Generate a textured GLB mesh from one text prompt or up to six reference photos of one object. Tiers: draft (fast, low-poly), standard (default), high (PBR textures). Returns a job token to poll for free.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "description": "Provide exactly one of prompt (text->3D) or image_urls (image->3D). tier and aspect_ratio are optional; tier defaults to \"standard\".",+ "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 6 public https reference views of one object for image->3D. Omit when supplying a prompt."+ },+ "tier": {+ "type": "string",+ "enum": [+ "draft",+ "standard",+ "high"+ ],+ "default": "standard",+ "description": "Quality/price tier: draft $0.05 (low-poly), standard $0.15 (default), high $0.50 (PBR textures). The 402 quotes the price for the requested tier."+ },+ "aspect_ratio": {+ "type": "string",+ "enum": [+ "1:1",+ "4:3",+ "3:4",+ "16:9",+ "9:16"+ ],+ "default": "1:1",+ "description": "Aspect ratio of the synthesized reference view for text->3D."+ }+ }+ },+ "example": {+ "prompt": "a brass steampunk owl, full body",+ "tier": "standard",+ "aspect_ratio": "1:1"+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "dynamic",+ "currency": "USD",+ "min": "0.05",+ "max": "0.5"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/forge": {+ "get": {+ "operationId": "forge_job_status",+ "summary": "Fetch the status and GLB URL of a 3D generation job",+ "description": "Poll a generation or pipeline job without payment. Returns status (queued, running, done, failed), per-stage progress for pipelines, and the GLB URL once the job is done.",+ "security": [],+ "parameters": [+ {+ "name": "job",+ "in": "query",+ "required": true,+ "description": "Job token returned by a paid generation or pipeline call.",+ "schema": {+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Result as JSON. No payment required."+ }+ }+ }+ },+ "/api/x402/pipeline": {+ "post": {+ "operationId": "pipeline",+ "summary": "Submit a chained 3D job: generate, rig, remesh, stylize",+ "description": "Run an ordered chain of 3D stages (generate, rig, remesh, gameready, stylize) in one paid call. The 402 quotes the sum of the requested stages. Returns a job token to poll for free.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "stages"+ ],+ "properties": {+ "stages": {+ "type": "array",+ "minItems": 1,+ "maxItems": 5,+ "items": {+ "type": "string",+ "enum": [+ "generate",+ "rig",+ "remesh",+ "gameready",+ "stylize"+ ]+ },+ "description": "Ordered subsequence of [\"generate\",\"rig\",\"remesh\",\"gameready\",\"stylize\"]. generate must be first and requires prompt; without generate, glb_url is required."+ },+ "prompt": {+ "type": "string",+ "minLength": 3,+ "maxLength": 1000,+ "description": "Subject for the generate stage. Required when stages starts with generate."+ },+ "glb_url": {+ "type": "string",+ "format": "uri",+ "description": "Public https GLB to feed the first stage when the chain does not start with generate."+ },+ "options": {+ "type": "object",+ "description": "Per-stage options keyed by stage: tier and aspect_ratio for generate, rig_type for rig, remesh settings, gameready topology and poly_budget, stylize style and resolution."+ }+ }+ },+ "example": {+ "stages": [+ "generate",+ "rig"+ ],+ "prompt": "a brass steampunk owl, full body",+ "options": {+ "tier": "draft",+ "rig": {+ "rig_type": "biped"+ }+ }+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "dynamic",+ "currency": "USD",+ "min": "0.05",+ "max": "0.41"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/pipeline-rig": {+ "post": {+ "operationId": "pipeline_rig",+ "summary": "Convert a static GLB mesh into a rigged, animatable model",+ "description": "Infer a skeleton for a static GLB and bind it with skin weights so the model can walk, wave, and emote. Returns a durable URL to the rigged GLB.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "glb_url"+ ],+ "properties": {+ "glb_url": {+ "type": "string",+ "format": "uri",+ "description": "Public HTTPS URL of the static .glb mesh to rig."+ },+ "rig_type": {+ "type": "string",+ "enum": [+ "biped",+ "quadruped"+ ],+ "default": "biped",+ "description": "Skeleton to infer: biped (humanoid, the default) or quadruped."+ }+ }+ },+ "example": {+ "glb_url": "https://three.ws/avatars/mannequin.glb",+ "rig_type": "biped"+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.05"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/pipeline-remesh": {+ "post": {+ "operationId": "pipeline_remesh",+ "summary": "Convert a GLB mesh to a new topology and face count",+ "description": "Retopologize a GLB as triangles, quads, or low-poly, with repair and decimation to a target face count, and re-bake the texture onto the new mesh. Returns a durable GLB URL.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "glb_url"+ ],+ "properties": {+ "glb_url": {+ "type": "string",+ "format": "uri",+ "description": "Public HTTPS URL of the source .glb mesh."+ },+ "remesh_mode": {+ "type": "string",+ "enum": [+ "triangle",+ "quad",+ "lowpoly"+ ],+ "default": "triangle",+ "description": "Output topology: triangle (default), quad, or lowpoly."+ },+ "operation": {+ "type": "string",+ "enum": [+ "full",+ "simplify",+ "repair",+ "convert"+ ],+ "default": "full",+ "description": "full (default) remeshes and re-bakes; simplify, repair, or convert run one step only."+ },+ "target_faces": {+ "type": "integer",+ "minimum": 1000,+ "maximum": 500000,+ "default": 50000,+ "description": "Target face count for the output mesh, 1,000 to 500,000."+ },+ "texture_size": {+ "type": "integer",+ "enum": [+ 512,+ 1024,+ 2048+ ],+ "default": 1024,+ "description": "Edge length in pixels of the re-baked texture."+ }+ }+ },+ "example": {+ "glb_url": "https://three.ws/avatars/mannequin.glb",+ "remesh_mode": "quad",+ "target_faces": 20000+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.03"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/pipeline-gameready": {+ "post": {+ "operationId": "pipeline_gameready",+ "summary": "Convert a GLB into a game-ready mesh under a poly budget",+ "description": "Retopologize a GLB to a fixed polygon budget (quad or silhouette-preserving triangles) with PBR textures re-baked onto the new topology, ready for a game engine. Returns a durable GLB URL.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "glb_url"+ ],+ "properties": {+ "glb_url": {+ "type": "string",+ "format": "uri",+ "description": "Public HTTPS URL of the source .glb mesh."+ },+ "topology": {+ "type": "string",+ "enum": [+ "quad",+ "tri"+ ],+ "default": "quad",+ "description": "Output topology: quad (default) or tri."+ },+ "poly_budget": {+ "type": "integer",+ "minimum": 1000,+ "maximum": 500000,+ "default": 15000,+ "description": "Maximum polygon count of the output mesh, 1,000 to 500,000."+ },+ "texture_size": {+ "type": "integer",+ "enum": [+ 1024,+ 2048+ ],+ "default": 1024,+ "description": "Edge length in pixels of the re-baked PBR textures."+ }+ }+ },+ "example": {+ "glb_url": "https://three.ws/avatars/mannequin.glb",+ "topology": "quad",+ "poly_budget": 12000+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.03"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/pipeline-stylize": {+ "post": {+ "operationId": "pipeline_stylize",+ "summary": "Convert a GLB mesh into voxel, brick, shatter, or low-poly",+ "description": "Rebuild a GLB geometrically in a voxel, brick, Voronoi-shatter, or faceted low-poly style. The style lives in the mesh, not a shader, so it survives export to any engine.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "glb_url"+ ],+ "properties": {+ "glb_url": {+ "type": "string",+ "format": "uri",+ "description": "Public HTTPS URL of the source .glb mesh."+ },+ "style": {+ "type": "string",+ "enum": [+ "voxel",+ "brick",+ "voronoi",+ "lowpoly"+ ],+ "default": "voxel",+ "description": "Geometric style: voxel (default), brick, voronoi, or lowpoly."+ },+ "resolution": {+ "type": "integer",+ "description": "Style density, clamped per filter."+ }+ }+ },+ "example": {+ "glb_url": "https://three.ws/avatars/mannequin.glb",+ "style": "voxel",+ "resolution": 48+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.03"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/pipeline-rembg": {+ "post": {+ "operationId": "pipeline_rembg",+ "summary": "Remove the background from an image for image-to-3D",+ "description": "Strip the background from an image and return a transparent PNG, the clean reference view image-to-3D reconstruction needs. Returns a durable PNG URL.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "image_url"+ ],+ "properties": {+ "image_url": {+ "type": "string",+ "format": "uri",+ "description": "Public HTTPS URL of the source image (PNG, JPEG, WEBP, or GIF)."+ },+ "model": {+ "type": "string",+ "enum": [+ "rmbg2",+ "birefnet",+ "u2net",+ "isnet",+ "u2net_human_seg",+ "silueta"+ ],+ "default": "rmbg2",+ "description": "Segmentation model to use; rmbg2 (default) suits most objects."+ }+ }+ },+ "example": {+ "image_url": "https://three.ws/avatars/thumbs/default.png",+ "model": "rmbg2"+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.01"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/model-check": {+ "get": {+ "operationId": "model_check",+ "summary": "Analyze a GLB model and return stats and optimization tips",+ "description": "Fetch a public glTF or GLB and return structural stats (vertices, triangles, materials, textures, animations, extensions) with a prioritized list of optimization recommendations.",+ "security": [],+ "parameters": [+ {+ "name": "url",+ "in": "query",+ "required": true,+ "description": "Public HTTPS URL of a glTF/GLB model.",+ "schema": {+ "type": "string",+ "format": "uri"+ },+ "example": "https://three.ws/avatars/mannequin.glb"+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/remix-asset": {+ "post": {+ "operationId": "remix_asset",+ "summary": "Create a remix of a published 3D model from an instruction",+ "description": "Generate a new 3D model from a published remixable source and a plain-language change. Records parent-to-child provenance and routes the creator royalty on-chain.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "source_creation_id",+ "instruction"+ ],+ "properties": {+ "source_creation_id": {+ "type": "string",+ "minLength": 1,+ "maxLength": 64,+ "description": "The id of a remixable creation (from GET /api/remix-feed)."+ },+ "instruction": {+ "type": "string",+ "minLength": 1,+ "maxLength": 500,+ "description": "The change to make, in plain language: \"make it metallic\", \"bigger helmet\", \"add a cape\"."+ }+ }+ },+ "example": {+ "source_creation_id": "3abac32f-ced2-4189-b822-d30c96dbc87e",+ "instruction": "make it matte black with gold trim"+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.25"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/remix-feed": {+ "get": {+ "operationId": "remix_feed",+ "summary": "Browse remixable 3D models and their royalty terms",+ "description": "List published 3D models that accept remixes, with their GLB and preview URLs, royalty percentage, and remix count. Use a returned id as source_creation_id for a paid remix.",+ "security": [],+ "parameters": [+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Number of remixable models to return.",+ "schema": {+ "type": "integer"+ },+ "example": 12+ }+ ],+ "responses": {+ "200": {+ "description": "Result as JSON. No payment required."+ }+ }+ }+ },+ "/api/x402/embody": {+ "post": {+ "operationId": "embody",+ "summary": "Create a rigged, talking 3D avatar body for an AI agent",+ "description": "Create a rigged, animated, voiced 3D avatar from a prompt or a photo. Returns the agent id, GLB URL, viewer and profile URLs, and an HTML embed. Failed generations are not charged.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "name"+ ],+ "oneOf": [+ {+ "required": [+ "prompt"+ ]+ },+ {+ "required": [+ "image_url"+ ]+ }+ ],+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 64,+ "description": "Display name for the avatar and its agent profile."+ },+ "prompt": {+ "type": "string",+ "minLength": 1,+ "maxLength": 600,+ "description": "Appearance of the avatar in plain language. Give this or image_url."+ },+ "image_url": {+ "type": "string",+ "format": "uri",+ "description": "Public photo of the subject to build the avatar from. Give this or prompt."+ },+ "personality": {+ "type": "string",+ "maxLength": 600,+ "description": "Optional persona text the avatar speaks and behaves from."+ },+ "voice": {+ "type": "string",+ "description": "Optional voice id for the avatar's speech."+ }+ }+ },+ "example": {+ "name": "Nova Scout",+ "prompt": "a friendly explorer in a teal jumpsuit",+ "voice": "nova"+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "1"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/mint-to-mesh": {+ "get": {+ "operationId": "mint_to_mesh",+ "summary": "Render a Solana token mint as a themed GLB 3D object",+ "description": "Turn any Solana SPL token mint into a GLB object themed from its on-chain metadata, with the token image as a texture when one exists and the metadata attached to the model.",+ "security": [],+ "parameters": [+ {+ "name": "mint",+ "in": "query",+ "required": true,+ "description": "Base58 SPL mint address on Solana mainnet.",+ "schema": {+ "type": "string",+ "minLength": 32,+ "maxLength": 44+ },+ "example": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/mint-to-mesh-batch": {+ "post": {+ "operationId": "mint_to_mesh_batch",+ "summary": "Render up to 10 Solana token mints as themed GLB objects",+ "description": "Resolve one to ten Solana SPL mints to themed GLB objects in one call. Each mint succeeds or fails on its own; GLB bytes come back base64-encoded in JSON.",+ "security": [],+ "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+ },+ "description": "One to ten base58 SPL mint addresses on Solana mainnet."+ }+ }+ },+ "example": {+ "mints": [+ "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"+ ]+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.05"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ }+ }+}diff --git a/distributions/pay-skills/providers/three-ws/agent-trust/PAY.md b/distributions/pay-skills/providers/three-ws/agent-trust/PAY.mdnew file mode 100644index 000000000..5d6f92947--- /dev/null+++ b/distributions/pay-skills/providers/three-ws/agent-trust/PAY.md@@ -0,0 +1,31 @@+---+name: agent-trust+title: "three.ws Agent Trust"+description: "Counterparty checks for AI agents: 0-100 reputation scores for wallets, mints, and agents from on-chain evidence, admit or refuse verdicts against a trust policy, on-chain identity claim verification, and sourced fact checks."+use_case: "Use when an agent is about to pay, hire, trade with, or delegate to an unknown wallet, token, or agent: score its reputation, gate it with a trust policy, verify an address it claims, or fact-check a claim it made."+category: identity+service_url: https://three.ws+openapi:+ path: openapi.json+---++Trust primitives for agent-to-agent commerce on three.ws. An agent about to+pay, hire, or delegate to a counterparty it has never met can buy evidence+first: a deterministic reputation score from on-chain history and settled+agent payments, a door verdict against its own trust policy, proof that an+identity really controls the address it claims, and a sourced verdict on a+factual claim.++Unknown subjects return a null score rather than an invented one, and every+verdict carries the evidence behind it.++## Spend-aware usage++- Check a counterparty once per session and cache the verdict; scores move+ slowly.+- Use `agent-bouncer` when you already hold a three.ws agent id and a policy;+ it is the cheapest yes-or-no gate.+- Use `agent-reputation` for wallets and mints outside three.ws.+- Keep fact-check claims to one checkable statement each. The first+ 3 checks per day per IP are served free (marked `lane: "free"`);+ after that each check returns a 402.diff --git a/distributions/pay-skills/providers/three-ws/agent-trust/openapi.json b/distributions/pay-skills/providers/three-ws/agent-trust/openapi.jsonnew file mode 100644index 000000000..1ddda67c3--- /dev/null+++ b/distributions/pay-skills/providers/three-ws/agent-trust/openapi.json@@ -0,0 +1,300 @@+{+ "openapi": "3.1.0",+ "info": {+ "title": "three.ws Agent Trust",+ "version": "1.0.0",+ "description": "Counterparty checks for AI agents: 0-100 reputation scores for wallets, mints, and agents from on-chain evidence, admit or refuse verdicts against a trust policy, on-chain identity claim verification, and sourced fact checks.",+ "x-logo": {+ "url": "https://three.ws/favicon.svg",+ "altText": "three.ws"+ },+ "x-guidance": "Call an endpoint without payment to receive an x402 challenge, pay it in USDC on Solana mainnet, and retry with the payment header. Asynchronous 3D jobs return a token to poll for free at GET /api/forge?job=<token>."+ },+ "servers": [+ {+ "url": "https://three.ws"+ }+ ],+ "paths": {+ "/api/x402/agent-reputation": {+ "get": {+ "operationId": "agent_reputation",+ "summary": "Score a wallet, token, or AI agent for trust from 0 to 100",+ "description": "Return a deterministic 0-100 trust score for a wallet, token mint, ERC-8004 agent id, or three.ws agent id from transaction history, age, counterparties, holdings, and settled agent payments.",+ "security": [],+ "parameters": [+ {+ "name": "subject",+ "in": "query",+ "required": true,+ "description": "Counterparty to score: a Solana or EVM wallet, a token mint, an ERC-8004 agent id, or a three.ws agent id.",+ "schema": {+ "type": "string"+ },+ "example": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"+ },+ {+ "name": "chain",+ "in": "query",+ "required": false,+ "description": "Optional EVM chain id or CAIP-2 chain to resolve an EVM subject on.",+ "schema": {+ "type": [+ "integer",+ "string"+ ]+ }+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.01"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/agent-bouncer": {+ "get": {+ "operationId": "agent_bouncer",+ "summary": "Check whether to admit an AI agent by its payment record",+ "description": "Read a three.ws agent's Solana track record (payments, distinct payers, failure rate, attestations) and return an admit or refuse verdict with a tier: newcomer, regular, trusted, or vip.",+ "security": [],+ "parameters": [+ {+ "name": "agent_id",+ "in": "query",+ "required": true,+ "description": "three.ws agent id (UUID) of the counterparty to check.",+ "schema": {+ "type": "string",+ "format": "uuid"+ },+ "example": "27a0f649-3b59-4552-bb0b-faf616ac448b"+ },+ {+ "name": "min_payments",+ "in": "query",+ "required": false,+ "description": "Minimum confirmed on-chain payments the agent must have received.",+ "schema": {+ "type": "integer"+ },+ "example": 10+ },+ {+ "name": "min_distinct_payers",+ "in": "query",+ "required": false,+ "description": "Minimum number of distinct wallets that have paid the agent.",+ "schema": {+ "type": "integer"+ },+ "example": 3+ },+ {+ "name": "max_failure_rate",+ "in": "query",+ "required": false,+ "description": "Highest acceptable payment failure rate, from 0 to 1.",+ "schema": {+ "type": "number"+ },+ "example": 0.2+ },+ {+ "name": "min_attestations",+ "in": "query",+ "required": false,+ "description": "Minimum signed Solana attestations the agent must hold.",+ "schema": {+ "type": "integer"+ }+ },+ {+ "name": "allow_newcomers",+ "in": "query",+ "required": false,+ "description": "Admit agents with no history yet instead of refusing them.",+ "schema": {+ "type": "boolean"+ }+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.01"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/onchain-identity-verify": {+ "get": {+ "operationId": "onchain_identity_verify",+ "summary": "Verify that an identity controls a wallet, mint, or contract",+ "description": "Check a claim that an identity controls an address and return on-chain evidence (deployer, mint and update authority, name resolution, agent registration) with verified true, false, or unverifiable.",+ "security": [],+ "parameters": [+ {+ "name": "identity",+ "in": "query",+ "required": true,+ "description": "Claimed identity: a wallet, a name-service name, an ERC-8004 agent id, or a three.ws agent id.",+ "schema": {+ "type": "string"+ },+ "example": "27a0f649-3b59-4552-bb0b-faf616ac448b"+ },+ {+ "name": "address",+ "in": "query",+ "required": true,+ "description": "Contract, mint, or wallet the identity claims to control.",+ "schema": {+ "type": "string"+ },+ "example": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"+ },+ {+ "name": "chain",+ "in": "query",+ "required": false,+ "description": "Optional CAIP-2 chain hint for the address.",+ "schema": {+ "type": "string"+ }+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.005"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/fact-check": {+ "post": {+ "operationId": "fact_check",+ "summary": "Verify a factual claim and return a sourced verdict",+ "description": "Check a claim against live web sources and return supported, contradicted, mixed, or insufficient with cited sources, a confidence score, and a SHA-256 attestation. The first 3 checks per day per IP are free.",+ "security": [],+ "requestBody": {+ "required": true,+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "required": [+ "claim"+ ],+ "properties": {+ "claim": {+ "type": "string",+ "minLength": 5,+ "maxLength": 1000,+ "description": "One factual statement to check, 5 to 1,000 characters."+ },+ "strictness": {+ "type": "string",+ "enum": [+ "high",+ "medium",+ "low"+ ],+ "description": "How hard low-authority sources are downweighted: high, medium, or low."+ },+ "imageUrl": {+ "type": "string",+ "format": "uri",+ "maxLength": 2048,+ "description": "Optional public image URL to check alongside the claim."+ }+ }+ },+ "example": {+ "claim": "The Eiffel Tower is 330 meters tall.",+ "strictness": "high"+ }+ }+ }+ },+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.1"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ }+ }+}diff --git a/distributions/pay-skills/providers/three-ws/market-data/PAY.md b/distributions/pay-skills/providers/three-ws/market-data/PAY.mdnew file mode 100644index 000000000..8de6b958c--- /dev/null+++ b/distributions/pay-skills/providers/three-ws/market-data/PAY.md@@ -0,0 +1,33 @@+---+name: market-data+title: "three.ws Market Data"+description: "Crypto and DeFi market data: coin tables, coin profiles, price history, sectors, exchanges, derivatives, TVL by protocol and chain, yield pools, stablecoin pegs, fees, DEX volume, exploit history, news pulse, and token signals."+use_case: "Use for crypto prices, market caps, price charts, trending coins, DeFi TVL, yield farming research, stablecoin depeg checks, protocol exploit due diligence, perp funding rates, token market signals, or a one-call market overview."+category: finance+service_url: https://three.ws+openapi:+ path: openapi.json+---++Pay-per-call crypto and DeFi market data from three.ws. Each endpoint is a+single GET that returns agent-ready JSON, priced in fractions of a cent. Data is+live from multiple upstream sources with failover; when an upstream is down the+call is refused before settlement, so you are never charged for an empty or+partial answer.++Start with `/api/x402/market-pulse` for broad context (global market, sentiment,+top coins, trending, TVL, stablecoin supply, DEX volume, and fees in one call),+then drill down with the narrow endpoints.++## Spend-aware usage++- Use `market-pulse` once instead of calling global, trending, defi, and+ stablecoin endpoints separately.+- Resolve a coin name to its id once with `market-coins?q=<name>` and reuse+ the id for `market-coin` and `market-chart`.+- Prefer the smallest `limit` that answers the question; most endpoints+ default to the full board.+- `token-intel` takes a contract address directly, so you can skip the id+ lookup for Solana tokens.+- Responses refresh every 1 to 10 minutes. Cache them instead of re-buying the+ same snapshot inside that window.diff --git a/distributions/pay-skills/providers/three-ws/market-data/openapi.json b/distributions/pay-skills/providers/three-ws/market-data/openapi.jsonnew file mode 100644index 000000000..9f94a0d50--- /dev/null+++ b/distributions/pay-skills/providers/three-ws/market-data/openapi.json@@ -0,0 +1,1173 @@+{+ "openapi": "3.1.0",+ "info": {+ "title": "three.ws Market Data",+ "version": "1.0.0",+ "description": "Crypto and DeFi market data: coin tables, coin profiles, price history, sectors, exchanges, derivatives, TVL by protocol and chain, yield pools, stablecoin pegs, fees, DEX volume, exploit history, news pulse, and token signals.",+ "x-logo": {+ "url": "https://three.ws/favicon.svg",+ "altText": "three.ws"+ },+ "x-guidance": "Call an endpoint without payment to receive an x402 challenge, pay it in USDC on Solana mainnet, and retry with the payment header. Asynchronous 3D jobs return a token to poll for free at GET /api/forge?job=<token>."+ },+ "servers": [+ {+ "url": "https://three.ws"+ }+ ],+ "paths": {+ "/api/x402/market-pulse": {+ "get": {+ "operationId": "market_pulse",+ "summary": "Fetch a one-call crypto market overview of eight feeds",+ "description": "Return global market cap and dominance, the fear and greed index, top 10 coins, trending searches, gas, DeFi TVL with top protocols, stablecoin supply, DEX volume, and protocol fees in one response.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.005"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/token-intel": {+ "get": {+ "operationId": "token_intel",+ "summary": "Analyze a token by contract address with a market signal",+ "description": "Return price, 24h change, market cap, liquidity, 24h volume, and a bullish, bearish, or neutral signal with a two-sentence rationale for any token by contract address.",+ "security": [],+ "parameters": [+ {+ "name": "mint",+ "in": "query",+ "required": true,+ "description": "Token contract address: a Solana base58 mint or an EVM 0x address.",+ "schema": {+ "type": "string"+ },+ "example": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.01"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-coins": {+ "get": {+ "operationId": "market_coins",+ "summary": "Fetch a ranked crypto market table with 7-day sparklines",+ "description": "Return coins ranked by market cap with price, market cap, 24h volume, 24h and 7d change, logo, and a 7-day sparkline, up to 250 per page. Pass q to resolve a name or ticker to coin ids.",+ "security": [],+ "parameters": [+ {+ "name": "page",+ "in": "query",+ "required": false,+ "description": "Page number, 1-20. Default 1.",+ "schema": {+ "type": "string"+ },+ "example": "1"+ },+ {+ "name": "per_page",+ "in": "query",+ "required": false,+ "description": "Rows per page, 10-250. Default 100.",+ "schema": {+ "type": "string"+ },+ "example": "100"+ },+ {+ "name": "category",+ "in": "query",+ "required": false,+ "description": "Optional sector id from the market-categories endpoint to scope the table to one sector.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "q",+ "in": "query",+ "required": false,+ "description": "Search mode: resolve a name or ticker to coin ids and return the top 10 matches.",+ "schema": {+ "type": "string"+ }+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-coin": {+ "get": {+ "operationId": "market_coin",+ "summary": "Fetch a full profile for one coin by id or Solana mint",+ "description": "Return live market stats (price, market cap, FDV, volume, change windows, all-time high and low, supply), official links, per-chain contract addresses, and developer and community stats for one coin.",+ "security": [],+ "parameters": [+ {+ "name": "id",+ "in": "query",+ "required": false,+ "description": "Coin id: the lowercase slug from market-coins. Required unless contract is set.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "contract",+ "in": "query",+ "required": false,+ "description": "Solana token mint (base58), an alternative lookup key to id.",+ "schema": {+ "type": "string"+ },+ "example": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump"+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-chart": {+ "get": {+ "operationId": "market_chart",+ "summary": "Fetch the historical price series for one coin",+ "description": "Return [timestamp_ms, price_usd] pairs for one coin over 1, 7, 30, 90, or 365 days, 5-minutely for one day, hourly up to 90 days, and daily beyond.",+ "security": [],+ "parameters": [+ {+ "name": "id",+ "in": "query",+ "required": true,+ "description": "Coin id: the lowercase slug from market-coins, for example solana.",+ "schema": {+ "type": "string"+ },+ "example": "solana"+ },+ {+ "name": "days",+ "in": "query",+ "required": false,+ "description": "Window: 1, 7, 30, 90, or 365. Default 30.",+ "schema": {+ "type": "string"+ },+ "example": "30"+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-categories": {+ "get": {+ "operationId": "market_categories",+ "summary": "Fetch crypto market sectors ranked by market cap",+ "description": "Return every crypto sector ranked by market cap with 24h market-cap change, 24h volume, and its top three coins. Pass a sector id to market-coins to drill in.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-exchanges": {+ "get": {+ "operationId": "market_exchanges",+ "summary": "Fetch spot crypto exchanges ranked by trust and volume",+ "description": "Return the top 100 spot exchanges ranked by trust score, each with 24h volume, trust rank, country, year established, and homepage.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-derivatives": {+ "get": {+ "operationId": "market_derivatives",+ "summary": "Fetch perpetual futures tickers, funding, and open interest",+ "description": "Return the top 100 perpetual futures contracts by 24h volume with price, 24h change, funding rate, and open interest, or pass view=exchanges for the derivatives venue leaderboard.",+ "security": [],+ "parameters": [+ {+ "name": "view",+ "in": "query",+ "required": false,+ "description": "Set to 'exchanges' for the derivatives-venue leaderboard; omit for perp tickers.",+ "schema": {+ "type": "string"+ }+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-global": {+ "get": {+ "operationId": "market_global",+ "summary": "Fetch the global crypto market cap, volume, and sentiment",+ "description": "Return total crypto market cap, 24h volume, dominance shares, active coin count, and the fear and greed index with its label. A one-call market-regime check.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-trending": {+ "get": {+ "operationId": "market_trending",+ "summary": "Fetch the most-searched coins and trending categories",+ "description": "Return the most-searched coins over the last 24 hours with price, 24h change, market cap, and trending rank, plus trending categories and NFT collections.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-defi": {+ "get": {+ "operationId": "market_defi",+ "summary": "Fetch DeFi protocols ranked by total value locked",+ "description": "Return the top 100 DeFi protocols by TVL with 1d and 7d change, chains, category, token, and market cap, plus total DeFi TVL with exchange reserves excluded.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-chains": {+ "get": {+ "operationId": "market_chains",+ "summary": "Fetch blockchains ranked by DeFi total value locked",+ "description": "Return the top 100 blockchains ranked by DeFi TVL, each with its native token symbol and share of total value locked, plus whole-market TVL.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-yields": {+ "get": {+ "operationId": "market_yields",+ "summary": "Search DeFi yield pools by chain, protocol, and TVL",+ "description": "Query about 15,000 DeFi yield pools filtered by chain, protocol, stablecoin exposure, or text, sorted by TVL or APY, with pagination. Pass pool for one pool's APY and TVL history.",+ "security": [],+ "parameters": [+ {+ "name": "chain",+ "in": "query",+ "required": false,+ "description": "Filter to one chain (case-insensitive, e.g. solana).",+ "schema": {+ "type": "string"+ },+ "example": "solana"+ },+ {+ "name": "project",+ "in": "query",+ "required": false,+ "description": "Filter to one protocol slug, as listed by market-defi.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "stablecoin",+ "in": "query",+ "required": false,+ "description": "'true' for stablecoin pools only, 'false' to exclude them.",+ "schema": {+ "type": "string"+ },+ "example": "true"+ },+ {+ "name": "search",+ "in": "query",+ "required": false,+ "description": "Substring match over symbol, project, and chain.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "minTvl",+ "in": "query",+ "required": false,+ "description": "Minimum pool TVL in USD.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "sort",+ "in": "query",+ "required": false,+ "description": "'tvl' (default) or 'apy' (dust-guarded to pools >= $10k TVL).",+ "schema": {+ "type": "string"+ },+ "example": "apy"+ },+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Rows per page, 1-200. Default 100.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "offset",+ "in": "query",+ "required": false,+ "description": "Pagination offset. Default 0.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "pool",+ "in": "query",+ "required": false,+ "description": "Chart mode: a pool id from a previous market-yields row. Returns that pool's APY and TVL history.",+ "schema": {+ "type": "string"+ }+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-stablecoins": {+ "get": {+ "operationId": "market_stablecoins",+ "summary": "Fetch stablecoins ranked by supply with live peg prices",+ "description": "Return the top 100 stablecoins by circulating supply with live price for a peg check, peg type and mechanism, and chains, plus total stablecoin market cap.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-fees": {+ "get": {+ "operationId": "market_fees",+ "summary": "Fetch DeFi protocols ranked by fees or revenue",+ "description": "Return the top 100 protocols by 24h fees with 24h, 7d, and 30d totals and momentum. type=revenue ranks by what the protocol keeps instead of what users pay.",+ "security": [],+ "parameters": [+ {+ "name": "type",+ "in": "query",+ "required": false,+ "description": "'fees' (default, what users pay) or 'revenue' (what the protocol keeps).",+ "schema": {+ "type": "string"+ },+ "example": "fees"+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-dex-volumes": {+ "get": {+ "operationId": "market_dex_volumes",+ "summary": "Fetch decentralized exchanges ranked by 24h volume",+ "description": "Return the top 100 DEXes by 24h volume with 7d volume, week-over-week change, chains, and share of total DEX volume, plus market totals and a daily chart.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-hacks": {+ "get": {+ "operationId": "market_hacks",+ "summary": "Search the DeFi exploit history by name or technique",+ "description": "Return historical DeFi exploits newest first with amount stolen, attack technique, classification, chains, bridge flag, post-mortem link, and funds returned. Search by name or technique.",+ "security": [],+ "parameters": [+ {+ "name": "search",+ "in": "query",+ "required": false,+ "description": "Case-insensitive match over incident name, technique, and classification.",+ "schema": {+ "type": "string"+ },+ "example": "bridge"+ },+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Rows per page, 1-200. Default 100.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "offset",+ "in": "query",+ "required": false,+ "description": "Pagination offset. Default 0.",+ "schema": {+ "type": "string"+ }+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.001"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/defi-radar": {+ "get": {+ "operationId": "defi_radar",+ "summary": "Fetch DeFi TVL movers, top fee earners, and top DEXes",+ "description": "Return total DeFi TVL, the largest 24h TVL gainers and losers, the top fee-earning protocols over 24h, 7d, and 30d, and the top DEXes by 24h volume in one snapshot.",+ "security": [],+ "parameters": [+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Rows per leaderboard (TVL top, gainers, losers, fees, DEX volume).",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 25,+ "default": 10+ },+ "example": 10+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.005"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/yield-scan": {+ "get": {+ "operationId": "yield_scan",+ "summary": "Search DeFi yield pools with risk flags by APY or TVL",+ "description": "Screen 15,000+ yield pools by chain, minimum TVL, and stablecoin-only exposure. Each pool carries base and reward APY, 30-day mean, TVL, and impermanent-loss, volatility, and spike flags.",+ "security": [],+ "parameters": [+ {+ "name": "chain",+ "in": "query",+ "required": false,+ "description": "Filter to one chain by name, for example Solana (case-insensitive).",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "stable",+ "in": "query",+ "required": false,+ "description": "true returns stablecoin-denominated pools only.",+ "schema": {+ "type": "boolean"+ },+ "example": true+ },+ {+ "name": "minTvlUsd",+ "in": "query",+ "required": false,+ "description": "Minimum pool TVL in USD.",+ "schema": {+ "type": "number",+ "minimum": 0,+ "default": 100000+ },+ "example": 1000000+ },+ {+ "name": "sort",+ "in": "query",+ "required": false,+ "description": "Ranking dimension.",+ "schema": {+ "type": "string",+ "enum": [+ "apy",+ "tvl"+ ],+ "default": "apy"+ }+ },+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Pools to return.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 50,+ "default": 20+ },+ "example": 10+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.005"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/stablecoin-health": {+ "get": {+ "operationId": "stablecoin_health",+ "summary": "Monitor stablecoin peg deviation and supply flows",+ "description": "Score every USD stablecoin on peg deviation in basis points (on-peg, drifting, or depegged), circulating supply, and 24h, 7d, and 30d supply change, with a depeg alert list.",+ "security": [],+ "parameters": [+ {+ "name": "symbol",+ "in": "query",+ "required": false,+ "description": "Return only this stablecoin symbol, e.g. USDC (case-insensitive).",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Coins to return, largest supply first.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 25+ },+ "example": 10+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.005"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/hack-check": {+ "get": {+ "operationId": "hack_check",+ "summary": "Check a DeFi protocol for past exploits before using it",+ "description": "Return a clean or incident-history verdict for a protocol with every matching exploit (date, amount lost, technique, chains, recovered funds) and market-wide loss stats. Omit protocol for the latest incidents.",+ "security": [],+ "parameters": [+ {+ "name": "protocol",+ "in": "query",+ "required": false,+ "description": "Protocol name to search (case-insensitive substring match). Omit for the latest incidents market-wide.",+ "schema": {+ "type": "string"+ }+ },+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Incidents to return, newest first.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 50,+ "default": 10+ },+ "example": 5+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.002"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-heatmap": {+ "get": {+ "operationId": "market_heatmap",+ "summary": "Fetch top coins with momentum and market-breadth stats",+ "description": "Return the top coins by market cap with rank, price, 1h, 24h, and 7d momentum, market cap, and volume, plus breadth stats (advancers versus decliners, average and median move).",+ "security": [],+ "parameters": [+ {+ "name": "limit",+ "in": "query",+ "required": false,+ "description": "Coins to return, largest market cap first.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 100,+ "default": 50+ },+ "example": 50+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.002"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/market-mood": {+ "get": {+ "operationId": "market_mood",+ "summary": "Calculate a 0-100 crypto market mood score",+ "description": "Blend the fear and greed index with live headline sentiment from 192 crypto news feeds into one 0-100 mood score, returning both components, the driving headlines, and implied volatility.",+ "security": [],+ "parameters": [],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.002"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ },+ "/api/x402/news-pulse": {+ "get": {+ "operationId": "news_pulse",+ "summary": "Monitor news coverage and sentiment for one token ticker",+ "description": "Count mentions of a ticker across 192 crypto news feeds in a 1-72 hour window and return unique outlets, sentiment split, coverage velocity versus the prior window, and top headlines.",+ "security": [],+ "parameters": [+ {+ "name": "ticker",+ "in": "query",+ "required": true,+ "description": "Ticker symbol to scan for, for example THREE. A leading $ is optional.",+ "schema": {+ "type": "string",+ "minLength": 2,+ "maxLength": 10+ },+ "example": "THREE"+ },+ {+ "name": "hours",+ "in": "query",+ "required": false,+ "description": "Look-back window in hours.",+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 72,+ "default": 24+ },+ "example": 24+ }+ ],+ "x-payment-info": {+ "price": {+ "mode": "fixed",+ "currency": "USD",+ "amount": "0.002"+ },+ "protocols": [+ {+ "x402": {}+ }+ ]+ },+ "responses": {+ "200": {+ "description": "Paid result as JSON."+ },+ "400": {+ "description": "Missing or invalid input. Refused before any payment settles."+ },+ "402": {+ "description": "Payment Required: an x402 challenge payable in USDC on Solana mainnet."+ }+ }+ }+ }+ }+}diff --git a/docs/ops/x402-discovery-listings.md b/docs/ops/x402-discovery-listings.mdindex 7d67419ea..e292cc5be 100644--- a/docs/ops/x402-discovery-listings.md+++ b/docs/ops/x402-discovery-listings.md@@ -316,6 +316,52 @@ The path to being counted, all Solana, no Base required:third-party buyer using the stock client could settle here, and none oftheir volume would exist to be counted.+## 8. `pay` registry (solana-foundation/pay-skills)++The Solana Foundation's `pay` CLI (`npm install -g @solana/pay`, binary+`pay`) and its MCP server read one public registry,+<https://github.com/solana-foundation/pay-skills>. Agents find providers with+`pay skills search` and pay them with `pay curl`. It is Solana-only, which makes+it the highest-fit directory for our self-hosted Solana rail. On 2026-10-09 the+registry held 26 operators and no 3D provider of any kind.++**What we submit:** `distributions/pay-skills/providers/three-ws/` (three+providers: `3d`, `market-data`, `agent-trust`), generated by+`npm run build:pay-skills` from `api/_lib/service-catalog/pay-skills.js`.++**Verified 2026-10-09** with the registry's own validator (`pay` 0.26.0 from+`@solana/[email protected]`, `pay catalog check -v`, live probes against production):+`3d` PASS 12/12 Solana gates (plus the free job-status and remix-feed routes,+classified free and indeterminate as expected), `market-data` PASS 24/24,+`agent-trust` PASS 3/3. `POST /api/x402/fact-check` probes as free because a+valid body is served from its 3-per-day free lane first; the listing says so.++**Registry rules that shaped the listing** (all enforced by+`listingProblems()` so a violation fails our build, not their CI):++- the OpenAPI spec must be committed beside `PAY.md` (`openapi.url` is+ rejected), so the generator writes it;+- operation summaries are verb-first, 24 to 64 ASCII characters, because the+ summary is the reason line on the payer's biometric prompt;+- every parameter and required body field needs a description;+- no marketing language or cost claims in summaries.++**To publish** (an outward-facing PR, so owner-approved per CLAUDE.md gate 2):++1. `npm run verify:pay-skills` (must be all PASS).+2. Fork `solana-foundation/pay-skills`, copy `providers/three-ws/` in, and run+ `pay catalog check . --changed-from origin/main` in the fork.+3. Open the PR. Their CI re-probes every endpoint; nothing else is required.++Excluded on purpose: Base-only `permit2-paid-demo`; the internal-only+`three-intel` (de-listed from discovery in the 2026-07 overhaul); internal+health probes (`auth-health`, `api-key-health`, `telegram-health` and siblings);+`symbol-availability` and the paid token-launch endpoint, which are scoped to a+third-party launchpad and so need owner approval under the other-coin commit+gate; and the+vanity grinders, whose length-tiered prices live in private route constants that+would need exporting before a listing can quote them without a second copy.+## Registration log**2026-09-09: the deploy landed; registration is the only step left.** Thediff --git a/docs/x402-distribution.md b/docs/x402-distribution.mdindex 7afa2b4b8..a20eae0cc 100644--- a/docs/x402-distribution.md+++ b/docs/x402-distribution.md@@ -43,6 +43,29 @@ search results after 30 days without a settle**.## Surface-by-surface+### `pay` registry (Solana Foundation)++[`pay`](https://github.com/solana-foundation/pay) is the Solana Foundation's+agentic-payments CLI and MCP server: `pay curl <url>` answers a 402 by signing a+USDC transfer on Solana and retrying, and `pay skills search` / `pay mcp` let+agents browse a public registry of paid APIs,+[`pay-skills`](https://github.com/solana-foundation/pay-skills). It is+Solana-only by design, so it is the most direct agent-discovery surface for our+home-chain rail.++- **What gets listed:** a `PAY.md` plus a committed OpenAPI document per+ provider. We publish three providers, `three-ws/3d`, `three-ws/market-data`,+ and `three-ws/agent-trust`, generated from the service catalog into+ [`distributions/pay-skills/`](../distributions/pay-skills/README.md) by+ `npm run build:pay-skills`.+- **Admission:** the registry's CI probes every paid endpoint and merges only+ ones whose 402 is payable in USDC or USDT on Solana mainnet. Our self-hosted+ Solana facilitator passes as-is; `npm run verify:pay-skills` runs the same+ validator locally against production.+- **Ranking:** the catalog is searched by description and use case, so the+ listing copy is written to the registry's rules rather than reused from other+ storefronts.+### CDP Bazaar (feeds agentic.market)- **Mechanism:** settlement-triggered. The CDP facilitator catalogs an endpoint@@ -203,6 +226,7 @@ search results after 30 days without a settle**.| ai-plugin manifest | `/.well-known/ai-plugin.json` | same generator || Human catalog | `/discover`, `/x402/studio`, `/pricing` | live || LLM-readable index | `/llms.txt` | build-time |+| `pay` registry providers | `distributions/pay-skills/` | `npm run build:pay-skills`; `tests/pay-skills.test.js` fails on drift |**Adding a paid endpoint?** Drop the service-catalog descriptor + barrel row +ring-catalog entry (tests enforce all three), deploy, then run the registrardiff --git a/package.json b/package.jsonindex 0ab764557..fff716d40 100644--- a/package.json+++ b/package.json@@ -262,6 +262,9 @@"audit:mcp-surfaces": "node scripts/build-mcp-surfaces.mjs --check","build:mcp-surfaces": "node scripts/build-mcp-surfaces.mjs","build:mcp-catalog": "node scripts/build-mcp-catalog.mjs",+ "build:pay-skills": "node scripts/build-pay-skills.mjs",+ "check:pay-skills": "node scripts/build-pay-skills.mjs --check",+ "verify:pay-skills": "node scripts/build-pay-skills.mjs --verify","audit:inline-handlers": "node scripts/audit-inline-handlers.mjs","audit:csp": "node scripts/audit-csp.mjs","audit:hidden-guard": "node scripts/audit-hidden-guard.mjs",diff --git a/scripts/build-pay-skills.mjs b/scripts/build-pay-skills.mjsnew file mode 100644index 000000000..3d4696a8d--- /dev/null+++ b/scripts/build-pay-skills.mjs@@ -0,0 +1,85 @@+#!/usr/bin/env node+/**+ * Build the three.ws providers for the Solana Foundation `pay` registry+ * (github.com/solana-foundation/pay-skills) into distributions/pay-skills/.+ *+ * node scripts/build-pay-skills.mjs write the provider files+ * node scripts/build-pay-skills.mjs --check fail when the committed files are stale+ * node scripts/build-pay-skills.mjs --verify write, then run the real `pay catalog check`+ * against production (live 402 probes)+ *+ * The listings are projected from the service catalog by+ * api/_lib/service-catalog/pay-skills.js, which also enforces the registry's+ * copy rules. --verify runs the registry's own validator, the same check its+ * pull-request CI runs, so a green run here means the PR will pass. Probing is+ * read-only: each paid endpoint is called once without payment and must answer+ * with a Solana-payable 402. Nothing is ever paid.+ */+import { spawnSync } from 'node:child_process';+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import { buildPaySkills, OPERATOR } from '../api/_lib/service-catalog/pay-skills.js';++// The npm package that ships the `pay` binary, pinned so a validator change+// upstream cannot silently change what --verify means.+const PAY_CLI = '@solana/[email protected]';++const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const outRoot = join(root, 'distributions/pay-skills');+const operatorDir = join(outRoot, 'providers', OPERATOR);++const check = process.argv.includes('--check');+const verify = process.argv.includes('--verify');++function listFiles(dir, base = dir) {+ if (!existsSync(dir)) return [];+ return readdirSync(dir, { withFileTypes: true }).flatMap((e) => {+ const p = join(dir, e.name);+ return e.isDirectory() ? listFiles(p, base) : [p.slice(base.length + 1)];+ });+}++const files = buildPaySkills();+const expected = new Set(Object.keys(files));+const onDisk = listFiles(operatorDir).map((f) => `providers/${OPERATOR}/${f}`);++if (check) {+ const stale = Object.entries(files)+ .filter(([rel, body]) => {+ const p = join(outRoot, rel);+ return !existsSync(p) || readFileSync(p, 'utf8') !== body;+ })+ .map(([rel]) => rel);+ const orphans = onDisk.filter((rel) => !expected.has(rel));+ if (stale.length || orphans.length) {+ for (const rel of stale) console.error(`stale: distributions/pay-skills/${rel}`);+ for (const rel of orphans) console.error(`orphan: distributions/pay-skills/${rel}`);+ console.error('Run `npm run build:pay-skills` and commit the result.');+ process.exit(1);+ }+ console.log(`pay-skills: ${expected.size} files up to date.`);+ process.exit(0);+}++for (const rel of onDisk) if (!expected.has(rel)) rmSync(join(outRoot, rel));+for (const [rel, body] of Object.entries(files)) {+ const p = join(outRoot, rel);+ mkdirSync(dirname(p), { recursive: true });+ writeFileSync(p, body);+}+console.log(`pay-skills: wrote ${expected.size} files to distributions/pay-skills/providers/${OPERATOR}/`);++if (verify) {+ let failed = false;+ for (const rel of Object.keys(files).filter((f) => f.endsWith('/PAY.md'))) {+ console.log(`\n== pay catalog check ${rel}`);+ const r = spawnSync('npx', ['-y', PAY_CLI, 'catalog', 'check', rel, '-v'], {+ cwd: outRoot,+ stdio: 'inherit',+ env: { ...process.env, NO_COLOR: '1' },+ });+ if (r.status !== 0) failed = true;+ }+ process.exit(failed ? 1 : 0);+}diff --git a/tests/pay-skills.test.js b/tests/pay-skills.test.jsnew file mode 100644index 000000000..17b4b340a--- /dev/null+++ b/tests/pay-skills.test.js@@ -0,0 +1,90 @@+// pay-skills projection (api/_lib/service-catalog/pay-skills.js): the three.ws+// providers for the Solana Foundation `pay` registry. These guards keep the+// committed listing in distributions/pay-skills/ honest:+// - the committed files are exactly what the generator emits today, so a+// service-catalog schema or price change cannot leave a stale listing,+// - every listed paid service is live and payable on Solana,+// - every listing passes the registry's copy rules (no violations thrown),+// - prices match the functions the live 402 challenges quote from.++import { describe, it, expect } from 'vitest';+import { existsSync, readFileSync } from 'node:fs';+import { join } from 'node:path';+import {+ PAY_PROVIDERS,+ buildPaySkills,+ buildOpenApi,+ listingProblems,+ toAscii,+} from '../api/_lib/service-catalog/pay-skills.js';+import { PAID_SERVICES } from '../api/_lib/service-catalog/services/index.js';+import { TIERS } from '../api/_lib/forge-tiers.js';++const ROOT = join(import.meta.dirname, '..', 'distributions', 'pay-skills');++describe('pay-skills projection', () => {+ const files = buildPaySkills();++ it('emits a PAY.md and an openapi.json for every provider', () => {+ for (const p of PAY_PROVIDERS) {+ expect(files[`providers/three-ws/${p.name}/PAY.md`]).toMatch(new RegExp(`^---\\nname: ${p.name}\\n`));+ expect(JSON.parse(files[`providers/three-ws/${p.name}/openapi.json`]).openapi).toBe('3.1.0');+ }+ });++ it('matches the committed files byte for byte (run npm run build:pay-skills)', () => {+ for (const [rel, body] of Object.entries(files)) {+ const p = join(ROOT, rel);+ expect(existsSync(p), rel).toBe(true);+ expect(readFileSync(p, 'utf8'), rel).toBe(body);+ }+ });++ it('lists only live, Solana-payable catalog services, each once', () => {+ const slugs = PAY_PROVIDERS.flatMap((p) => p.operations.filter((o) => o.slug).map((o) => o.slug));+ expect(new Set(slugs).size).toBe(slugs.length);+ for (const slug of slugs) {+ const s = PAID_SERVICES.find((x) => x.slug === slug);+ expect(s, slug).toBeDefined();+ expect(s.status).toBe('live');+ expect(['standard', 'cdp-bazaar']).toContain(s.acceptsBuilder);+ }+ });++ it('passes the registry copy rules for every provider', () => {+ for (const p of PAY_PROVIDERS) expect(listingProblems(p, buildOpenApi(p))).toEqual([]);+ });++ it('reports a too-short summary and an undescribed parameter as problems', () => {+ const p = PAY_PROVIDERS[0];+ const openapi = buildOpenApi(p);+ const [path, item] = Object.entries(openapi.paths).find(([, v]) => v.get?.parameters?.length);+ item.get.summary = 'Too short';+ item.get.parameters[0].description = '';+ const problems = listingProblems(p, openapi);+ expect(problems.some((m) => m.includes(path) && m.includes('summary'))).toBe(true);+ expect(problems.some((m) => m.includes('has no description'))).toBe(true);+ });++ it('quotes fixed prices from the catalog and Forge from its tier table', () => {+ const md = JSON.parse(files['providers/three-ws/market-data/openapi.json']);+ const global = PAID_SERVICES.find((s) => s.slug === 'market-global');+ expect(md.paths['/api/x402/market-global'].get['x-payment-info'].price).toEqual({+ mode: 'fixed',+ currency: 'USD',+ amount: String(Number(global.priceAtomics) / 1e6),+ });+ const forge = JSON.parse(files['providers/three-ws/3d/openapi.json']).paths['/api/x402/forge'].post;+ const tierPrices = Object.values(TIERS).map((t) => t.priceUsdcAtomics / 1e6);+ expect(forge['x-payment-info'].price).toEqual({+ mode: 'dynamic',+ currency: 'USD',+ min: String(Math.min(...tierPrices)),+ max: String(Math.max(...tierPrices)),+ });+ });++ it('maps typographic characters to ASCII', () => {+ expect(toAscii('text\u21923D \u2014 fast\u2026 \u22651')).toBe('text->3D, fast... >=1');+ });+});diff --git a/tests/x402-fresh-workers-chain.test.js b/tests/x402-fresh-workers-chain.test.jsdeleted file mode 100644index df1c55aff..000000000--- a/tests/x402-fresh-workers-chain.test.js+++ /dev/null@@ -1,57 +0,0 @@-// Balance readers of the fresh-wallet workers lane-// (api/_lib/x402/fresh-workers/chain.js). These two reads gate every tick: the-// SOL funder's headroom over the sponsor floor and the treasury's USDC. Both-// once read the { info, cause } wrapper returned by readAccountInfoOrNull as if-// it were the account, so every balance came back 0 and the lane skipped with-// funder_headroom on every tick from launch, never minting a single wallet.-//-// What these lock down, for both readers:-// • a funded account reports its real balance.-// • an account that does not exist reads as empty (0 / exists:false).-// • an RPC transport failure reads as unknown (null), never as zero.--import { describe, it, expect, vi } from 'vitest';--import { readSolLamports, readUsdc } from '../api/_lib/x402/fresh-workers/chain.js';--const PUBKEY = 'WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW';--const connReturning = (value) => ({ getAccountInfo: vi.fn(async () => value) });-const connFailing = () => ({- getAccountInfo: vi.fn(async () => { throw Object.assign(new Error('fetch failed'), { name: 'TypeError' }); }),-});--function tokenAccountData(amount) {- const data = Buffer.alloc(165);- data.writeBigUInt64LE(BigInt(amount), 64);- return data;-}--describe('readSolLamports', () => {- it('returns the live lamports of a funded account', async () => {- expect(await readSolLamports(connReturning({ lamports: 651_828, data: Buffer.alloc(0) }), PUBKEY)).toBe(651_828);- });-- it('returns 0 for an account that does not exist', async () => {- expect(await readSolLamports(connReturning(null), PUBKEY)).toBe(0);- });-- it('returns null, not 0, when the RPC is unreachable', async () => {- expect(await readSolLamports(connFailing(), PUBKEY)).toBeNull();- });-});--describe('readUsdc', () => {- it('returns the atomic amount held by an existing token account', async () => {- expect(await readUsdc(connReturning({ lamports: 2_039_280, data: tokenAccountData(2_587_000) }), PUBKEY))- .toEqual({ exists: true, atomic: 2_587_000n });- });-- it('reports a missing token account as not existing', async () => {- expect(await readUsdc(connReturning(null), PUBKEY)).toEqual({ exists: false, atomic: 0n });- });-- it('returns null when the RPC is unreachable', async () => {- expect(await readUsdc(connFailing(), PUBKEY)).toBeNull();- });-});