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.

fix(x402): catalog the sell-an-agent dispatcher, keep the facilitator mock whole, and restate the cron count as 125

nirholase03e571fe182
diff --git a/CLAUDE.md b/CLAUDE.md
index 7029b9e06..113b73104 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -311,7 +311,7 @@ The whole build + submit + purge in one command: `npm run deploy:gcp:full`.
- Frontend: vanilla JS modules + Vite (`npm run dev`, port 3000).
- 3D: Three.js with glTF/GLB.
- Backend touchpoints: serverless-style handlers in `api/`, workers in `workers/`.
-- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (123 as of 2026-09-29, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.
+- **Production runs on Google Cloud Run, NOT Vercel** (migrated 2026-07-07 after Vercel disabled the deployment). One container ([server/index.mjs](server/index.mjs)) serves the static frontend, the vercel.json route table, and all `api/**` handlers; the crons (125 as of 2026-09-30, see vercel.json) run on Cloud Scheduler. `vercel.json` is a LIVE config file: `server/index.mjs` reads its `routes` array on boot (split at the `{handle:"filesystem"}` marker into pre- and post-filesystem phases), and `scripts/create-gcp-scheduler.mjs` reads its `crons` array to sync Cloud Scheduler jobs. The server itself never reads `crons`. Never delete `vercel.json` as a leftover. GCP builds/deploys must pin the `three-ws-build@` (build) and `three-ws@` (runtime) service accounts; the project's default compute SA was deleted. Deploys: see the "Deploy runbook" section above.
- **Env-var trap:** `vercel env pull` returns EMPTY for secret-type vars. Never trust a Vercel env export as complete. Production env lives on the Cloud Run service (`gcloud run services describe/update three-ws-api --region us-central1`).
- Solana/agent SDKs in `sdk/`, `solana-agent-sdk/`, `agent-payments-sdk/`.
- Real APIs in use: Pump.fun feed, Solana RPC, OpenAI/Anthropic via worker proxies. Never mock these.
diff --git a/README.md b/README.md
index cdec05ce3..0ba250bb6 100644
--- a/README.md
+++ b/README.md
@@ -9996,7 +9996,7 @@ The full OpenAPI 3.1 spec is available at `/openapi.json`. The key API surface i
Cron schedules are declared in `vercel.json` (still the live cron/route config the server reads) and executed in production by **Google Cloud Scheduler**, which calls each endpoint on its schedule. All cron endpoints are fail-closed — a missing auth token aborts with an error rather than silently skipping (see [Security Hardening](#security-hardening)).
-The crons in `vercel.json` (123 entries on 2026-09-29) are routed through a single dynamic handler at [`api/cron/[name].js`](api/cron/[name].js); the `name` segment selects the handler function. Scheduler jobs are provisioned from the `vercel.json` cron list via [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs). The table below is a selection of the notable jobs, each schedule quoted verbatim from `vercel.json`; that file is the complete list.
+The crons in `vercel.json` (125 entries on 2026-09-30) are routed through a single dynamic handler at [`api/cron/[name].js`](api/cron/[name].js); the `name` segment selects the handler function. Scheduler jobs are provisioned from the `vercel.json` cron list via [scripts/create-gcp-scheduler.mjs](scripts/create-gcp-scheduler.mjs). The table below is a selection of the notable jobs, each schedule quoted verbatim from `vercel.json`; that file is the complete list.
| Schedule | Endpoint | Purpose |
| -------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
diff --git a/api/_lib/x402/ring-catalog.js b/api/_lib/x402/ring-catalog.js
index 39cd07587..522b15098 100644
--- a/api/_lib/x402/ring-catalog.js
+++ b/api/_lib/x402/ring-catalog.js
@@ -1011,6 +1011,25 @@ export const RING_CATALOG = [
businessEffect: 'Proxies a paid agent service; settles USDC to the agent wallet and returns the upstream result.',
note: 'autobuy:false — price/payee/upstream are agent-controlled per agent_paid_services row; not a fixed known endpoint.',
},
+ {
+ slug: 'agents',
+ sourceFile: 'api/x402/agents.js',
+ path: '/api/x402/agents',
+ method: 'POST',
+ body: () => ({ message: 'hello' }),
+ priceAtomicDefault: 0,
+ priceSlug: 'agents',
+ tier: 'service',
+ kind: 'service',
+ network: 'solana',
+ autobuy: false,
+ weight: 0,
+ // Whole-agent dispatcher: /api/x402/agents/<agentId>. Price and payee are
+ // owner-controlled per agent (meta.api_service), so it can't be swept
+ // generically. Path is the base; the real route carries an agent id.
+ businessEffect: 'Buys one conversational turn with an agent; settles USDC to the agent owner\'s payout wallet and returns the reply.',
+ note: 'autobuy:false: price and payee are owner-set per agent and the payment lands in a third-party owner wallet; not a fixed known endpoint.',
+ },
{
slug: 'animation-download',
sourceFile: 'api/x402/animation-download.js',
diff --git a/docs/build.md b/docs/build.md
index fc62f6d54..fdad1646e 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -47,7 +47,7 @@ front-end, the `vercel.json` route table, and every `api/**` handler from source
provisioned from the `crons` array in `vercel.json` by
[scripts/create-gcp-scheduler.mjs](../scripts/create-gcp-scheduler.mjs); that
array is the count, so read it there rather than trusting a number quoted here
-(123 entries on 2026-09-29). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](./ops/gcp-production.md).
+(125 entries on 2026-09-30). There is **no GitHub Actions CI**. Full runbook: [docs/ops/gcp-production.md](./ops/gcp-production.md).
`.npmrc` sets `legacy-peer-deps=true` (npm never auto-installs peers — the
reason `audit:deploy` checks the peer tree), and `engines.node` pins Node
diff --git a/tests/api/x402-discovery-parity.test.js b/tests/api/x402-discovery-parity.test.js
index 43a438064..3c6d14ed8 100644
--- a/tests/api/x402-discovery-parity.test.js
+++ b/tests/api/x402-discovery-parity.test.js
@@ -34,6 +34,13 @@ const EXCLUSIONS = new Map([
'concrete listing is cataloged dynamically from agent_paid_services by ' +
"handleX402Discovery's buildAgentServiceItems(), not as a static entry.",
],
+ [
+ '/api/x402/agents',
+ 'Dynamic dispatcher, not a single fixed-price route: it serves the paywall ' +
+ 'for every agent its owner sells as an API at /api/x402/agents/<agentId>. ' +
+ 'Each agent on sale is cataloged dynamically from agent meta.api_service by ' +
+ "handleX402Discovery's buildSellableAgentItems(), not as a static entry.",
+ ],
[
'/api/x402/ring-settle',
'Internal closed-loop settlement primitive (discoverable:false in the ' +
diff --git a/tests/api/x402-facilitator-log-durable.test.js b/tests/api/x402-facilitator-log-durable.test.js
index be454930d..b2a6312d3 100644
--- a/tests/api/x402-facilitator-log-durable.test.js
+++ b/tests/api/x402-facilitator-log-durable.test.js
@@ -38,7 +38,8 @@ vi.mock('../../api/_lib/db.js', () => ({
}));
// Keep verify deterministic and side-effect free — we only care about log timing.
-vi.mock('../../api/_lib/x402/self-facilitator.js', () => ({
+vi.mock('../../api/_lib/x402/self-facilitator.js', async (importOriginal) => ({
+ ...(await importOriginal()),
SELF_FACILITATOR_ENABLED: true,
verifyRingPayment: () => ({ isValid: true, network: 'solana:x', asset: 'MINT', payer: 'BUYER' }),
settleRingPayment: async () => ({ success: true, transaction: 'SIG', network: 'solana:x', payer: 'BUYER' }),