Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

14.6 KB
Raw Blame

x402 Distribution — getting listed and ranked everywhere

three.ws sells 90+ pay-per-call services over x402. Building them is half the job; the other half is making sure every x402 directory, crawler, and agent marketplace can find them — and ranks us at the top. This page is the operating playbook for that distribution: how each surface indexes providers, what we automate, and what needs a human.

Source: catalog api/_lib/service-catalog/, discovery doc /.well-known/x402.json (rendered live by api/wk.js), static cards regenerated by scripts/build-discovery-cards.mjs, directory registrar scripts/x402-register-directories.mjs.


Chain priority: Solana first

Solana is the home chain. $THREE and our ecosystem live there, and our x402 rail settles Solana through our OWN self-hosted facilitator, with no third-party credential required. Every paid endpoint already advertises Solana USDC (and $THREE) accepts, and x402scan attributes on-chain Solana settlements to us natively.

Base is a secondary surface. It is worth having, because the CDP Bazaar (and therefore agentic.market) indexes only endpoints that settle through the CDP facilitator on Base. But that is an additional listing, not the goal, and a Base blocker (missing CDP creds, an unfunded EVM buyer) must never stall or re-scope Solana work. Treat everything below about CDP/Base as a nice-to-have distribution channel. See the Solana-first rule in CLAUDE.md.

The one rule of ranking

Every major surface ranks the same way: settled transaction count and distinct buyers in the trailing 30 days. Metadata quality gets us found (semantic search embeds our description fields); paid traffic gets us ranked. The autonomous x402 loop already drives real settled canary purchases against every autobuy: true entry in api/_lib/x402/ring-catalog.js — that loop is also our 30-day-activity keeper: the CDP Bazaar drops resources from search results after 30 days without a settle.

Surface-by-surface

pay registry (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. 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/ 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 the first time it settles (not just verifies) a payment for it. There is no registration form.
  • Metadata: the Bazaar discovery extension in the 402 challenge — description (< 500 chars, embedded for semantic search), input + inputSchema (the example must validate against the schema or indexing is rejected), and an output example. Our shared handler emits all of this from each service-catalog descriptor.
  • Ranking: relevance × quality = distinct buyers (30 d), settled volume (30 d), recency, metadata completeness. Recomputed every 6 hours.
  • Ops required (secondary priority — see Chain priority above): CDP_API_KEY_ID/CDP_API_KEY_SECRET on the Cloud Run service so Base settles through the CDP facilitator, then ≥1 settled payment per endpoint. The ring payer (api/_lib/x402/pay.js) is still Solana-only, but the Base settle leg exists as a one-shot buyer sweep: scripts/x402-bazaar-settle-sweep.mjs pays one real Base USDC settle against every live endpoint that advertises a Base accept, cheapest-first under a spend cap (default $3), sending each endpoint's own runnable bazaar.input example so the settle indexes a 200. It needs a funded Base buyer wallet (X402_BUYER_PRIVATE_KEY); all Base accepts pay to the owner's wallet, so the sweep is an internal transfer. Do not let any of this block Solana work. Verify presence via GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources — do not trust the EXTENSION-RESPONSES header alone (known upstream bug: x402-foundation/x402#2112 — it is sometimes never emitted).
  • agentic.market (Coinbase's public directory, ~1,700 services) has no submission form — it auto-indexes from Bazaar + payment activity. Getting Bazaar-listed IS getting agentic.market-listed. Its ~70-service "curated" tier is editorial: the lever is volume + clean metadata + BD outreach.

x402scan (x402scan.com)

  • Mechanism: three ingestion paths — (1) crawls known facilitators' resource lists (incl. the CDP Bazaar), (2) attributes on-chain USDC settlements on Base + Solana to sellers, (3) manual registration at https://www.x402scan.com/resources/register (probes the URL; a valid x402 challenge auto-lists it; one-time SIWX wallet signature, no funds move).
  • Ranking: activity — tx count, volume, recency per origin/seller. No pay-to-rank.
  • Ops required: a human with a wallet registers each top resource once (start with the flagship services, not health canaries). Our origin metadata (og-tags, favicon) renders on the resource page — already good.

AgentCash (agentcash.dev)

  • Mechanism: AgentCash is an aggregating discovery interface for agent-payable APIs. It does not have its own registration form — it discovers us three ways: (1) crawling x402scan / the CDP Bazaar (register there and AgentCash picks us up), (2) reading GET /openapi.json for the AgentCash discovery fields (info.x-guidance, info.contact.email, per-operation x-payment-info + responses.402 + request/response schemas — all emitted by api/openapi-json.js), and (3) probing each paid route's live 402 challenge. Validate any time with npx -y @agentcash/discovery@latest discover https://three.ws, and a single route with npx -y @agentcash/discovery@latest check https://three.ws/api/x402/crypto-intel. check reads the OpenAPI spec, so pass a route the spec actually carries. Since 2026-09-02 that is every live, non-free service in the catalog: the spec projects each one into a paid operation (catalogPaidPaths()), so a new paid endpoint is listable the moment its descriptor lands, and hand-authored operations still win where they are richer. Routes outside the spec (anything not in the catalog, the /api/v1/x/* proxy lane and /api/mcp aside) still answer L3_NOT_FOUND even though their live 402 challenge is perfectly valid.
  • Critical invariant — the PAYMENT-REQUIRED header carries the bazaar block. AgentCash's probe reads the 402 challenge from the PAYMENT-REQUIRED response header in preference to the JSON body, and checks extensions.bazaar.schema.properties.input / .output for each endpoint's input/output schema. Our header mirror is size-capped (8 KB; oversized headers were dropped by the LB / flagged HEADERS_OVERFLOW), so paymentRequiredHeaderValue() in api/_lib/x402-spec.js keeps the bazaar extension while shedding the heavy payment-execution extensions, degrading it in tiers (full bazaar → drop info examples → compact {type:'object'} field schemas) so input/output presence survives. Do not reintroduce an extension-less header mirror for paid routes — it makes every endpoint look schema-less to AgentCash and x402scan's Bazaar probe. Covered by tests/api/x402-spec.test.js (paymentRequiredHeaderValue cap).
  • Ops required: none beyond keeping x402scan current and /openapi.json valid. We advertise x402 only (no MPP / Tempo rail), so mppscan does not apply — AgentCash lists us under x402.

402index.io — automated ✅

  • Mechanism: open API, POST https://402index.io/api/v1/register with { url, name, protocol: 'x402', description }. No auth. The service probes the URL for a valid 402 challenge; some listings go live instantly, others are "pending review — verify your domain for instant approval". Rate limit: 10 registrations/hour/IP.
  • Automation: node scripts/x402-register-directories.mjs submits a batch of 8 per run, pre-probes production for a real 402 first (registering a not-yet-deployed route burns a slot), and records results in data/x402-directory-registrations.json. Re-run hourly until it reports 0 remaining, and after every deploy that adds endpoints. --dry-run previews. The hourly cron api/cron/x402-directory-registrar.js supersedes manual runs: it re-upserts a rotating window of 8 catalog entries per tick (registration is an upsert by URL), so new endpoints auto-register and description drift self-heals.
  • Domain verification (ranks ALL our listings first): three.ws is claimed — the challenge hash is served at /.well-known/402index-verify.txt (in public/.well-known/). After a deploy makes it live, complete with curl -X POST https://402index.io/api/v1/claim/verify -H 'Content-Type: application/json' -d '{"domain": "three.ws"}'. The claim's verification_token (the ongoing credential for editing listings) is in the gitignored .x402-directory-credentials.json at the repo root — never commit it. Claims expire 72 h after issuance if unverified (re-claim with POST /api/v1/claim {"domain":"three.ws"} and update the hash file).

x402-list.com

  • Mechanism: web form at https://x402-list.com/submit — first submission free, endpoint auto-probed for a live 402 handshake, human-reviewed, then monitored (5–15 min uptime checks, "verified" badges). Updates via one-time domain proof.
  • Submitted 2026-09-30 as "three.ws 3D Studio" (category AI, origin https://three.ws, website /docs/x402-endpoints, contact [email protected]). The form is a plain POST https://x402-list.com/api/v1/submit with no sign-in, and it answered 303 /submit?success=1&found=14: every one of the 14 endpoints sent was probed and returned a live 402. They are embody, the five pipeline-* stages, model-check, asset-download, animation-download, remix-asset, print-order, knock, fact-check and llm-proxy. forge and pipeline were left out because a bare GET answers 200 with usage, not 402. The listing is human-reviewed. Before submission the full catalog (GET /api/v1/services, 857 services) had no three.ws entry. Updates to the listing need the one-time domain proof.

PR-based directories

  • x402.org ecosystem page — partner metadata PR to the x402 repo (typescript/site/app/ecosystem/): logo + description JSON.
  • awesome-x402 — PRs to xpaysh/awesome-x402 and Merit-Systems/awesome-x402.

A2A / AP2 (Google agentic commerce)

  • No central registry. Discovery is our A2A agent card at /.well-known/agent-card.json declaring the a2a-x402 extension URI under capabilities.extensions — already present, and the card now carries the generated x402-service-catalog skill. Featuring in Google's AI Agent Marketplace is BD, not crawl.

B402 (Binance BNB-chain Bazaar)

  • Same extension-declaration + settle-through-their-facilitator model as CDP, on BSC. We already have a BSC direct-settlement rail (api/_lib/x402-bsc-direct.js); listing there means routing BSC settles through Binance's facilitator. Evaluate after the CDP lane is proven.

What we publish (kept fresh automatically)

Surface Where Freshness
x402 discovery doc /.well-known/x402.json rendered live from the service catalog on every request
ERC-8004 registration card /.well-known/agent-registration.json regenerated by npm run build:discovery (runs in prebuild) — full x402Endpoints list
A2A agent card /.well-known/agent-card.json same generator — description + x402-service-catalog skill
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 registrar script. Everything else above updates itself.

Known listing blockers

  • Zero-amount auth-hint accepts break external validators. Endpoints that declare authHints (currently agent-reputation, agent-bouncer) append USE-21 zero-amount placeholder entries to accepts[]. 402index's validator rejects the whole challenge ("no valid x402 challenge detected"), and other crawlers likely apply the same amount-must-be-positive rule. Resolution: set X402_AUTH_HINT_ACCEPTS=false on the deployment to suppress the advertisement (both the zero-amount entries and the auth-hints extension — the extension schema requires them together). Auth bypass itself keeps working either way; the access-control hook honors Bearer/SIWX headers before the payment dance. Default stays true until the owner flips it.
  • Bazaar indexing needs the CDP facilitator. Solana-only settles through the self-hosted facilitator never reach the Bazaar catalog. The Base rail must settle via CDP at least once per endpoint; that is exactly what scripts/x402-bazaar-settle-sweep.mjs does once CDP credentials and a funded Base buyer wallet are in place.

Related