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-api): answer a mistyped cursor, SKU id or ring period with a 4xx instead of a 500

nirholasaa3fdce8a256
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c040c6eea..849d464ed 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,10 +9,12 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr
- **A mistyped id on the signal marketplace answers plainly, and the live feed links to the right chain**: The signal marketplace identifies a feed or a subscription by a number. Anything that was not one (a typo, a stray word, an empty box) went straight to the database, which threw the whole query out, so the caller got an opaque "something went wrong" and our alerting recorded a fault that was never a fault. Pausing a feed, killing or resyncing a subscription, and subscribing to a feed each now answer with a plain "that is not a valid id" instead. Separately, the paid live signal stream built its Solscan links from whichever network the request named rather than the one the feed actually publishes on, so a subscriber could be handed devnet explorer links for a mainnet call; the feed's own record now decides, and every proof link lands on the chain the trade really happened on. (`/signals`) `[fix]`
- **Avatar Studio trait library: the mirror can no longer be pointed at someone else's server**: Avatar Studio loads its hair, clothing and accessory traits through a three.ws address that mirrors the open-source trait library, so your browser never talks to an outside CDN. The list of where those traits live was being written using the address in the incoming request, and that address can be set by whoever sends the request. Because the mirror is cached at the edge for a day, one crafted request could have left every Avatar Studio visitor loading trait files from a stranger's server for the next 24 hours. That list is now written the same way for everybody, with no part of it taken from the request, so there is nothing left to steer. Three smaller repairs went in alongside it: asking the mirror how big a file is no longer answers with the compressed size (a trait manifest claimed 2 KB and delivered 20 KB), the mirror will not hand back a web page or script even if the upstream library ever served one, and a failure at the library now answers plainly as either not found or mirror is down instead of passing its raw status through as ours. (`/avatar-studio`) `[security, fix]`
- **Live stage hosts stop swallowing hyphens, and only confirmed tippers get greeted by name**: Two repairs to the Living Stages host. The cleanup pass that tidies the host's spoken line was stripping hyphens along with the invisible characters it was meant to remove, so every show heard "on chain" where the host said "on-chain" and "state of the art" for "state-of-the-art"; punctuation now survives and only invisible characters are removed. Separately, the host's memory of returning regulars counted tips whose on-chain settlement had not been confirmed yet, which meant anyone could post an unconfirmed tip under a name of their choosing and hear the host greet it aloud. That memory now reads confirmed tips only, matching the public leaderboard. Smaller repairs in the same pass: a stage that has not opened its first show is no longer cached as empty at the edge, an over-long coin address is refused instead of quietly trimmed into a different plaza, and the running tip total is written before the response returns. (`/stage`) `[fix, security]`
+- **Memory seeding reads Farcaster with no vendor key, and X now works from the app credentials we already hold**: The memory-seeding demo asks a GitHub, X or Farcaster handle what it can learn about you in public, then writes a short memory seed your agent can carry. Two of those three connectors were showing a "connector not configured" card to everyone, because each insisted on a vendor key nobody had set. Farcaster now reads through the same failover the rest of the platform uses: an indexer when a key exists, and a public Farcaster hub with no key at all otherwise, so it returns real profiles and casts on any deployment. Anything the keyless lane genuinely cannot know, such as follower counts, is now shown as unknown instead of zero. The X connector accepts the app key and secret the platform already stores, exchanging them for a read-only token itself, so it no longer needs a separate token provisioned by hand. A mistyped Farcaster name now comes back as not found rather than as an upstream outage, and all four endpoints are documented in the API reference for the first time. (`/demos/memory-seed`) `[fix, improvement, docs]`
- **Mistyped filters on the revenue, checkout and ring endpoints answer plainly instead of failing**: The public revenue feed, the checkout SKU API and the ring report all took values straight from the URL into the database. A timestamp that was not a timestamp, a checkout id that was not an id, and the query fell over: the caller got an opaque "something went wrong" with a support reference, and our own alerting logged a fault that was only ever a typo. All three now say what was wrong, in words, with the right status code. The ring report also stops treating an unrecognised period as "show me everything", which quietly answered the wrong question and ran the most expensive query it has. The revenue feed now echoes back the endpoint filter it actually applied rather than the raw text it was sent, and the paid-call lookup only accepts something shaped like a real transaction signature. (`/x402-revenue`) `[fix]`
- **Robinhood Chain worlds survive a hiccup in the live feed instead of going dark**: The in-world trading terminal inside a Robinhood Chain world polls the chain feed every five seconds, and the Worlds lobby lists those coins from the same feed. A single event that arrived without its payload, or with a timestamp the chain wrote in an unexpected format, took both requests down with a server error: the terminal showed a dead tape, and the lobby's Robinhood Chain tab quietly emptied with nothing on screen to say why. Bad events are now skipped and the rest of the tape still renders, a price that is genuinely missing stays blank rather than printing as a real $0 trade, and a launch with no readable contract address no longer produces a card that leads nowhere. Asking for trades with an address that is not a contract address now gets a clear error back instead of an empty list that read as "this coin has never traded". (`/worlds`) `[fix]`
- **Sharing an agent link posts the agent's picture again**: Pasting a link to an agent into a chat app, a social post or a group thread is supposed to unfurl into a card with the agent's name, its description and a picture of it. For every agent that actually has an avatar picture, which is nearly all of them, the page that builds that card was crashing instead, so the link unfurled as a bare URL with nothing attached. The card now renders with the agent's own thumbnail, falls back to a freshly rendered portrait when an agent has no thumbnail yet, and an unknown or malformed agent link sends the visitor to the app instead of erroring. `[fix]`
- **Skill marketplace: installs are locked to your own clicks, and edits keep their star rating**: Three fixes to the skills marketplace. Installing or removing a skill now carries the same one-time security token every other account action does, so a page you happen to have open elsewhere can no longer quietly add skills to your account behind your back. Editing one of your published skills used to answer back with its rating blanked out, which made the detail panel show 'No ratings yet' on a skill people had actually rated until you reloaded; it now reports the real average and count. And when a skill you were paging past gets deleted or made private mid-scroll, 'Load more' stops cleanly instead of looping the first page of results back into the grid over and over. (`/marketplace`) `[fix, security]`
+- **Solana agents from the outside registries get a real link preview, and a mistyped discover link stops erroring**: Two fixes to the Discover detail pages. Agents crawled from the outside Solana registries opened fine in the browser but shared as a nameless card: every one of them unfurled in Slack, Discord, X and iMessage with a generic three.ws title and the stock image, while the Ethereum-side agents in the same grid previewed properly. Those pages now carry the agent name, description and artwork, whether the link points at the mint or at its registry entry. Separately, a Discover link with a mistyped or truncated id answered with a server error and the page showed a vague "something went wrong"; it now says plainly that the item was not found and shows the Not found state, and an agent whose on-chain id is larger than the site could previously handle resolves instead of coming back empty. (`/discover`) `[fix]`
- **The $THREE economy dashboard no longer errors out on an odd date range**: Asking the public $THREE economy stats endpoint for a window it could not read (a non-numeric range, or one longer than ten years) returned a server error instead of an answer. It now replies with a clear message for a range it cannot parse, caps an oversized one at ten years of history, and treats a blank range as all-time again. The creator earnings ledger does the same for a bad page cursor. `[fix]`
- **The public profile sitemap now lists people, not the seed crons**: The sitemap Google and Bing crawl is split into one file per kind of page, and the profiles file was handing search engines every account row with a username. That was 29,600 machine accounts minted by the avatar and forge seed crons against 42 real people, growing by about one a minute, so the profiles that belong to actual members were buried under auto-generated ones whose content (the avatars and agents they own) was already listed in its own sitemap. Machine accounts are now excluded from both the profiles sitemap and the last-updated stamp the sitemap index publishes for it, so that stamp changes when a person updates their profile rather than every time a cron runs. Separately, a handful of URLs under the sitemap API answered scanners with a server error instead of a plain not-found, which also filed a false internal alert each time; those now return a normal not-found listing the sitemap types that do exist. `[fix, infra]`
- **The sniper's laddered-exit settings can finally be saved**: An armed sniper strategy has two knobs that decide how a winner is taken off the table: the multiple of your entry at which it sells enough to recover what you put in, and the minimum slice of the position it always keeps riding afterwards. Both were documented and both were read by the trading worker, but the arm API quietly threw them away on the way in, so every strategy kept the fleet default no matter what you sent. They now save, an explicit null on the multiple switches the strategy back to a single-shot exit, and reading your strategies back reports both values plus whether the treasury is allowed to refill that agent's wallet. Sending the treasury-refill consent flag now returns a clear error instead of a success that changed nothing, because that permission is granted by the platform, not by the arm call. (`/dashboard/sniper`) `[fix, improvement]`
diff --git a/api/x402-pay.js b/api/x402-pay.js
index e36587885..d05cac436 100644
--- a/api/x402-pay.js
+++ b/api/x402-pay.js
@@ -22,8 +22,7 @@
import { solanaConnection } from './_lib/solana/connection.js';
import {
- Connection, PublicKey, Keypair, TransactionMessage, VersionedTransaction,
- ComputeBudgetProgram,
+ PublicKey, TransactionMessage, VersionedTransaction, ComputeBudgetProgram,
} from '@solana/web3.js';
import {
getAssociatedTokenAddressSync, createTransferCheckedInstruction,
@@ -132,6 +131,9 @@ async function readFeed(limit = 25) {
}
// Per-tx record so /pay/calls/<tx> can show the full receipt + tool result.
+// A Solana signature is 64 bytes of base58 (86-88 chars); the bound is generous
+// enough for any real signature and tight enough that the Redis key stays bounded.
+export const TX_SIGNATURE_RE = /^[1-9A-HJ-NP-Za-km-z]{32,128}$/;
const memCalls = new Map();
const CALL_KEY = (tx) => `x402:pay:call:${tx}`;
const CALL_TTL_SECONDS = 60 * 60 * 24 * 30; // 30 days
@@ -879,14 +881,14 @@ function payErrorEnvelope(err) {
} else if (code === 'invalid_payment' || code === 'payment_required' || code === 'builder_code_tampered') {
error_description = 'The payment was rejected before settlement; no funds were transferred.';
}
- const env = {
+ const envelope = {
ok: false,
error: err?.message || 'flow_failed',
code,
mcpError: err?.mcpError || null,
};
- if (error_description) env.error_description = error_description;
- return env;
+ if (error_description) envelope.error_description = error_description;
+ return envelope;
}
// Map a flow error to its HTTP status. X402Error carries an explicit `status`
@@ -1099,11 +1101,11 @@ export default wrap(async (req, res) => {
if (err.code === 'wallet_misconfigured' || err.code === 'wallet_unconfigured') {
return json(res, 200, { configured: false, code: err.code, error: err.message, address: null, sol: 0, usdc: 0 });
}
- // A balance read failure here is a Solana RPC fault — and web3.js
- // embeds the keyed RPC URL in its error text, so the raw message
- // must never reach the client. respondError sanitizes the 5xx to a
- // support ref (and still passes a 4xx client-fault message through).
- return respondError(res, err.status || 500, err.code || 'balance_unavailable', err);
+ // A balance read failure here is a Solana RPC fault, and web3.js
+ // embeds the keyed RPC URL in its error text, so the raw message
+ // must never reach the client. respondError sanitizes the 5xx to a
+ // support ref (and still passes a 4xx client-fault message through).
+ return respondError(res, err.status || 500, err.code || 'balance_unavailable', err);
}
}
if (u.searchParams.get('feed') === '1') {
@@ -1113,6 +1115,13 @@ export default wrap(async (req, res) => {
}
const txParam = u.searchParams.get('call');
if (txParam) {
+ // The lookup key is a Solana transaction signature. Shape-check it before
+ // it becomes a Redis key: an unbounded caller-controlled suffix turns a
+ // public GET into arbitrary key reads against the Upstash request budget
+ // this feed already had to be rewritten to protect (see readFeed above).
+ if (!TX_SIGNATURE_RE.test(txParam)) {
+ return json(res, 400, { error: 'invalid_call', error_description: 'call must be a base58 transaction signature' });
+ }
const record = await readCall(txParam);
if (!record) return json(res, 404, { error: 'call_not_found' });
return json(res, 200, record);
diff --git a/api/x402-revenue.js b/api/x402-revenue.js
index f85b077b7..166fdbaac 100644
--- a/api/x402-revenue.js
+++ b/api/x402-revenue.js
@@ -52,16 +52,40 @@ function shortAddr(a) {
return a.length > 12 ? `${a.slice(0, 6)}…${a.slice(-4)}` : a;
}
-// A route → slug ('/api/x402/token-intel' → 'token-intel'); null if not one of ours.
-function routeForEndpoint(slug) {
- if (!slug) return null;
- const clean = String(slug)
+// A caller-supplied `?endpoint=` → the canonical slug we filter on, or null when
+// it sanitizes to nothing. Echoed back in `filter.endpoint` so the response names
+// the filter that was actually applied instead of the raw string that was sent.
+export function endpointSlug(raw) {
+ if (!raw) return null;
+ const clean = String(raw)
.trim()
.replace(/^\/?(api\/x402\/)?/, '')
.replace(/[^a-z0-9-]/gi, '');
+ return clean || null;
+}
+
+// A route → slug ('/api/x402/token-intel' → 'token-intel'); null if not one of ours.
+function routeForEndpoint(slug) {
+ const clean = endpointSlug(slug);
return clean ? `/api/x402/${clean}` : null;
}
+// A `?since=` / `?cursor=` value → an ISO timestamp Postgres can cast, or null
+// when the param is absent. An unparseable value used to be bound straight into
+// the ::timestamptz cast, so `?since=notadate` threw 22P02 deep in the query and
+// surfaced as a 500 on what is plainly a caller mistake. Reject it up front.
+export function timestampParam(raw, name) {
+ if (raw == null || raw === '') return null;
+ const ms = Date.parse(raw);
+ if (!Number.isFinite(ms)) {
+ throw Object.assign(new Error(`\`${name}\` must be an ISO 8601 timestamp`), {
+ status: 400,
+ code: `invalid_${name}`,
+ });
+ }
+ return new Date(ms).toISOString();
+}
+
// A `?network=` value → the raw ledger ids it selects, as a comma-joined string
// bound once and expanded in SQL. The ledger holds CAIP-2 ids ('solana:5eykt4Us…',
// 'eip155:8453') while callers filter by family ('solana', 'base'), so comparing
@@ -217,7 +241,7 @@ async function handleFeed({ since, cursor, limit, endpoint, network }) {
count: events.length,
next_cursor: events.length === limit ? nextCursor : null,
filter: {
- endpoint: route ? endpoint : null,
+ endpoint: endpointSlug(endpoint),
network: resolveNetworkFilter(network)?.family || null,
},
};
@@ -277,8 +301,8 @@ export default async function handler(req, res) {
const url = new URL(req.url, 'http://x');
const view = url.searchParams.get('view') || 'feed';
const period = url.searchParams.get('period') || '24h';
- const since = url.searchParams.get('since');
- const cursor = url.searchParams.get('cursor');
+ const sinceRaw = url.searchParams.get('since');
+ const cursorRaw = url.searchParams.get('cursor');
const endpoint = url.searchParams.get('endpoint');
const network = url.searchParams.get('network');
const limit = Math.min(
@@ -287,6 +311,9 @@ export default async function handler(req, res) {
);
try {
+ const since = timestampParam(sinceRaw, 'since');
+ const cursor = timestampParam(cursorRaw, 'cursor');
+
if (view === 'stats') {
const cacheKey = `x402rev:stats:${resolvePeriod(period).key}`;
let body = await cacheGet(cacheKey);
@@ -318,6 +345,10 @@ export default async function handler(req, res) {
res.setHeader('cache-control', 'public, max-age=8');
return json(res, 200, { data: body });
} catch (err) {
+ // A caller-fault throw (a malformed cursor/since) carries its own 4xx.
+ if (Number.isInteger(err?.status) && err.status >= 400 && err.status < 500) {
+ return error(res, err.status, err.code || 'bad_request', err.message);
+ }
if (isDbUnavailableError(err)) {
return error(res, 503, 'db_unavailable', 'revenue ledger is temporarily unavailable');
}
diff --git a/api/x402-ring.js b/api/x402-ring.js
index 003981723..78909d13a 100644
--- a/api/x402-ring.js
+++ b/api/x402-ring.js
@@ -17,7 +17,7 @@
// empty. This is internal/dogfooding volume and is labeled as such; it is NOT the
// public organic-revenue feed (see /api/x402-revenue).
-import { cors, json, method, wrap } from './_lib/http.js';
+import { cors, error, json, method, wrap } from './_lib/http.js';
import { sql, isDbUnavailableError } from './_lib/db.js';
import { env } from './_lib/env.js';
import { PublicKey } from '@solana/web3.js';
@@ -28,11 +28,16 @@ import { SELF_FACILITATOR_ENABLED, SPONSOR_SOL_FLOOR_LAMPORTS } from './_lib/x40
import { validateRingConfig, warnIfRingRoutesExternal } from './_lib/x402/ring-config.js';
const PERIOD_HOURS = { '24h': 24, '7d': 168, '30d': 720 };
+// 'all' is the documented lifetime window; every other key is a windowed report.
+// An unrecognized value is rejected rather than quietly widened to lifetime: a
+// typo (`?period=alll`) silently answering with an unbounded full-ledger scan is
+// both a wrong answer and the most expensive query this endpoint can run.
+export const PERIODS = [...Object.keys(PERIOD_HOURS), 'all'];
// Resolve ?period= to an ISO cutoff (or null for lifetime). Returned as a bound
// parameter — the Neon tagged template does NOT compose SQL fragments, so the
// window is a value, not injected SQL.
-function sinceFor(periodKey) {
+export function sinceFor(periodKey) {
const hours = PERIOD_HOURS[periodKey];
if (!hours) return null;
return new Date(Date.now() - hours * 3600 * 1000).toISOString();
@@ -97,6 +102,9 @@ export default wrap(async (req, res) => {
if (!method(req, res, ['GET'])) return;
const periodKey = String(req.query?.period || '24h').toLowerCase();
+ if (!PERIODS.includes(periodKey)) {
+ return error(res, 400, 'invalid_period', `period must be one of: ${PERIODS.join(', ')}`);
+ }
const since = sinceFor(periodKey); // ISO string, or null = lifetime
let settlements = { count: 0, gross_usdc: 0, avg_call_usdc: null };
diff --git a/api/x402-skus.js b/api/x402-skus.js
index 39838950e..b1bdecfac 100644
--- a/api/x402-skus.js
+++ b/api/x402-skus.js
@@ -57,6 +57,27 @@ const createSchema = z.object({
const updateSchema = createSchema.partial();
+// `x402_skus.id` is a uuid column. Binding a non-uuid straight into the query
+// makes Postgres throw 22P02, which surfaced as a 500 (with a support ref) on an
+// obvious caller mistake; check the shape first and answer 400.
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// Resolve the required `?id=` for the owner-only routes. Sends the 4xx and
+// returns null when the param is missing or malformed.
+function requireSkuId(req, res) {
+ const raw = req.query?.id;
+ if (!raw) {
+ error(res, 400, 'missing_id', 'query param `id` required');
+ return null;
+ }
+ const id = String(raw);
+ if (!UUID_RE.test(id)) {
+ error(res, 400, 'invalid_id', 'query param `id` must be a SKU uuid');
+ return null;
+ }
+ return id;
+}
+
// Shape the merchant's giving config into the minimal public payload the checkout
// modal needs — or null when nothing is active. Round-up routes to the same cause
// wallet, so both primitives require a charity address to mean anything.
@@ -131,13 +152,17 @@ async function handleGet(req, res) {
if (!user) return error(res, 401, 'unauthorized', 'sign in required');
if (id) {
+ const skuId = String(id);
+ if (!UUID_RE.test(skuId)) {
+ return error(res, 400, 'invalid_id', 'query param `id` must be a SKU uuid');
+ }
const [row] = await sql`
select id, slug, owner_user_id, target_endpoint, target_method, target_body,
merchant_name, action_name, description, logo_url, image_url, accent_color,
success_url, price_atomics, price_network, position, active,
created_at, updated_at, archived_at
from x402_skus
- where id = ${String(id)} limit 1
+ where id = ${skuId} limit 1
`;
if (!row) return error(res, 404, 'sku_not_found', 'no such SKU');
if (row.owner_user_id !== user.id) return error(res, 403, 'forbidden', 'not owner');
@@ -212,10 +237,10 @@ async function handleUpdate(req, res) {
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
- const id = req.query?.id;
- if (!id) return error(res, 400, 'missing_id', 'query param `id` required');
+ const id = requireSkuId(req, res);
+ if (!id) return;
- const [row] = await sql`select owner_user_id from x402_skus where id = ${String(id)} limit 1`;
+ const [row] = await sql`select owner_user_id from x402_skus where id = ${id} limit 1`;
if (!row) return error(res, 404, 'sku_not_found', 'no such SKU');
if (row.owner_user_id !== user.id) return error(res, 403, 'forbidden', 'not owner');
@@ -239,7 +264,7 @@ async function handleUpdate(req, res) {
position = coalesce(${patch.position ?? null}, position),
active = coalesce(${patch.active ?? null}, active),
updated_at = now()
- where id = ${String(id)}
+ where id = ${id}
returning id, slug, merchant_name, action_name, updated_at
`;
return json(res, 200, { sku: updated });
@@ -251,13 +276,13 @@ async function handleArchive(req, res) {
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
- const id = req.query?.id;
- if (!id) return error(res, 400, 'missing_id', 'query param `id` required');
+ const id = requireSkuId(req, res);
+ if (!id) return;
- const [row] = await sql`select owner_user_id from x402_skus where id = ${String(id)} limit 1`;
+ const [row] = await sql`select owner_user_id from x402_skus where id = ${id} limit 1`;
if (!row) return error(res, 404, 'sku_not_found', 'no such SKU');
if (row.owner_user_id !== user.id) return error(res, 403, 'forbidden', 'not owner');
- await sql`update x402_skus set archived_at = now() where id = ${String(id)}`;
+ await sql`update x402_skus set archived_at = now() where id = ${id}`;
return json(res, 200, { ok: true });
}
diff --git a/data/changelog.json b/data/changelog.json
index 8b7d17246..ac5a1fdc7 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,26 @@
{
"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.",
"entries": [
+ {
+ "date": "2026-08-16",
+ "title": "Solana agents from the outside registries get a real link preview, and a mistyped discover link stops erroring",
+ "summary": "Two fixes to the Discover detail pages. Agents crawled from the outside Solana registries opened fine in the browser but shared as a nameless card: every one of them unfurled in Slack, Discord, X and iMessage with a generic three.ws title and the stock image, while the Ethereum-side agents in the same grid previewed properly. Those pages now carry the agent name, description and artwork, whether the link points at the mint or at its registry entry. Separately, a Discover link with a mistyped or truncated id answered with a server error and the page showed a vague \"something went wrong\"; it now says plainly that the item was not found and shows the Not found state, and an agent whose on-chain id is larger than the site could previously handle resolves instead of coming back empty.",
+ "tags": [
+ "fix"
+ ],
+ "link": "/discover"
+ },
+ {
+ "date": "2026-08-16",
+ "title": "Memory seeding reads Farcaster with no vendor key, and X now works from the app credentials we already hold",
+ "summary": "The memory-seeding demo asks a GitHub, X or Farcaster handle what it can learn about you in public, then writes a short memory seed your agent can carry. Two of those three connectors were showing a \"connector not configured\" card to everyone, because each insisted on a vendor key nobody had set. Farcaster now reads through the same failover the rest of the platform uses: an indexer when a key exists, and a public Farcaster hub with no key at all otherwise, so it returns real profiles and casts on any deployment. Anything the keyless lane genuinely cannot know, such as follower counts, is now shown as unknown instead of zero. The X connector accepts the app key and secret the platform already stores, exchanging them for a read-only token itself, so it no longer needs a separate token provisioned by hand. A mistyped Farcaster name now comes back as not found rather than as an upstream outage, and all four endpoints are documented in the API reference for the first time.",
+ "tags": [
+ "fix",
+ "improvement",
+ "docs"
+ ],
+ "link": "/demos/memory-seed"
+ },
{
"date": "2026-08-16",
"title": "Avatar Studio trait library: the mirror can no longer be pointed at someone else's server",
diff --git a/docs/x402-revenue.md b/docs/x402-revenue.md
index 7a088c056..6dbd259a8 100644
--- a/docs/x402-revenue.md
+++ b/docs/x402-revenue.md
@@ -84,6 +84,21 @@ curl -s "https://three.ws/api/x402-revenue?view=feed&limit=5&network=base" | jq
CSV columns: `timestamp,endpoint,network,chain,amount_usd,asset,payer,tx_hash,tx_url`
(`network` is the raw CAIP-2 id, `chain` its readable label).
+**Malformed params answer 4xx, not 5xx.** `?since=` and `?cursor=` are bound into
+a `::timestamptz` cast, so an unparseable value is rejected before it reaches the
+query rather than surfacing as an opaque 500:
+
+```bash
+curl -s "https://three.ws/api/x402-revenue?since=notadate"
+# {"error":"invalid_since","error_description":"`since` must be an ISO 8601 timestamp"}
+```
+
+`?endpoint=` is sanitized to a slug (`../../etc/passwd` becomes `etcpasswd`), and
+the response echoes the sanitized value in `data.filter.endpoint`, so the filter
+you read back is always the filter that ran. `?period=` and `?network=` fall back
+to the default instead of erroring: an unrecognised period is `24h`, an
+unrecognised network drops the filter.
+
---
## The settlement flow
diff --git a/prompts/swarm-100/api-top-17.md b/prompts/swarm-100/api-top-17.md
deleted file mode 100644
index d0759fe90..000000000
--- a/prompts/swarm-100/api-top-17.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# API audit: api/*.js batch 17 (7 files)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. Confirm each file below still exists; deleted ones are done, skip them.
-2. For each, decide routability: grep its path in vercel.json and read how
- server/index.mjs maps filesystem handlers. Routed files get an endpoint
- audit; internal modules get a code and test audit.
-3. Start a local server for endpoint checks: node server/index.mjs with .env
- loaded, on a free PORT if 3000 is busy.
-
-## Task: audit these api files, then fix everything found
-
-Files in this batch:
-
-- api/x402-pay.js
-- api/x402-revenue.js
-- api/x402-ring.js
-- api/x402-skus.js
-- api/x402-status.js
-- api/zauth-reposcan.js
-- api/zauth-status.js
-
-For every routed handler:
-
-1. Exercise it with curl against the local server: the success path returns
- real data with the correct status; malformed input returns a 4xx JSON
- error, never a stack trace or an HTML error page; auth is enforced where
- the code intends it; CORS matches neighboring handlers.
-2. Hard-rule scan: no mock fallbacks, no fake-data arrays, no stubbed
- responses, no unfinished markers. Errors are handled at the boundary and
- internal code trusts itself.
-3. Do not spend funds or sign anything on-chain while probing. Payment and
- trading handlers get their validation and error paths exercised, never a
- live settlement.
-
-For every internal (non-routed) module:
-
-4. Something must import it; if nothing does, delete it as dead code (verify
- with a repo-wide grep first).
-5. Its main path and one failure path must be covered in tests/; add the
- missing test if not.
-
-## Definition of done
-
-- [ ] Every listed file has recorded evidence: a curl transcript for routed
- handlers, a passing test or a deletion for internal modules.
-- [ ] Zero hard-rule violations remain in these files.
-- [ ] vitest run passes; npm run check:rules -- --paths <touched files>
- exits 0.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/api-top-17.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/public/changelog.json b/public/changelog.json
index 966c66cdf..249bda50d 100644
--- a/public/changelog.json
+++ b/public/changelog.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-16T06:58:40.744Z",
+ "generated_at": "2026-08-16T07:08:36.874Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json",
"site": {
"name": "three.ws",
@@ -38,6 +38,18 @@
"security"
]
},
+ {
+ "date": "2026-08-16",
+ "type": "update",
+ "title": "Memory seeding reads Farcaster with no vendor key, and X now works from the app credentials we already hold",
+ "summary": "The memory-seeding demo asks a GitHub, X or Farcaster handle what it can learn about you in public, then writes a short memory seed your agent can carry. Two of those three connectors were showing a \"connector not configured\" card to everyone, because each insisted on a vendor key nobody had set. Farcaster now reads through the same failover the rest of the platform uses: an indexer when a key exists, and a public Farcaster hub with no key at all otherwise, so it returns real profiles and casts on any deployment. Anything the keyless lane genuinely cannot know, such as follower counts, is now shown as unknown instead of zero. The X connector accepts the app key and secret the platform already stores, exchanging them for a read-only token itself, so it no longer needs a separate token provisioned by hand. A mistyped Farcaster name now comes back as not found rather than as an upstream outage, and all four endpoints are documented in the API reference for the first time.",
+ "link": "/demos/memory-seed",
+ "tags": [
+ "fix",
+ "improvement",
+ "docs"
+ ]
+ },
{
"date": "2026-08-16",
"type": "update",
@@ -79,6 +91,16 @@
"security"
]
},
+ {
+ "date": "2026-08-16",
+ "type": "update",
+ "title": "Solana agents from the outside registries get a real link preview, and a mistyped discover link stops erroring",
+ "summary": "Two fixes to the Discover detail pages. Agents crawled from the outside Solana registries opened fine in the browser but shared as a nameless card: every one of them unfurled in Slack, Discord, X and iMessage with a generic three.ws title and the stock image, while the Ethereum-side agents in the same grid previewed properly. Those pages now carry the agent name, description and artwork, whether the link points at the mint or at its registry entry. Separately, a Discover link with a mistyped or truncated id answered with a server error and the page showed a vague \"something went wrong\"; it now says plainly that the item was not found and shows the Not found state, and an agent whose on-chain id is larger than the site could previously handle resolves instead of coming back empty.",
+ "link": "/discover",
+ "tags": [
+ "fix"
+ ]
+ },
{
"date": "2026-08-16",
"type": "update",
diff --git a/public/changelog.xml b/public/changelog.xml
index 414eb8498..fdb8e6501 100644
--- a/public/changelog.xml
+++ b/public/changelog.xml
@@ -30,6 +30,14 @@
<category>fix</category>
<description>Two repairs to the Living Stages host. The cleanup pass that tidies the host's spoken line was stripping hyphens along with the invisible characters it was meant to remove, so every show heard &quot;on chain&quot; where the host said &quot;on-chain&quot; and &quot;state of the art&quot; for &quot;state-of-the-art&quot;; punctuation now survives and only invisible characters are removed. Separately, the host's memory of returning regulars counted tips whose on-chain settlement had not been confirmed yet, which meant anyone could post an unconfirmed tip under a name of their choosing and hear the host greet it aloud. That memory now reads confirmed tips only, matching the public leaderboard. Smaller repairs in the same pass: a stage that has not opened its first show is no longer cached as empty at the edge, an over-long coin address is refused instead of quietly trimmed into a different plaza, and the running tip total is written before the response returns.</description>
</item>
+ <item>
+ <title>Memory seeding reads Farcaster with no vendor key, and X now works from the app credentials we already hold</title>
+ <link>https://three.ws/demos/memory-seed</link>
+ <guid isPermaLink="false">2026-08-16:Memory seeding reads Farcaster with no vendor key, and X now works from the app credentials we already hold</guid>
+ <pubDate>Sun, 16 Aug 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>The memory-seeding demo asks a GitHub, X or Farcaster handle what it can learn about you in public, then writes a short memory seed your agent can carry. Two of those three connectors were showing a &quot;connector not configured&quot; card to everyone, because each insisted on a vendor key nobody had set. Farcaster now reads through the same failover the rest of the platform uses: an indexer when a key exists, and a public Farcaster hub with no key at all otherwise, so it returns real profiles and casts on any deployment. Anything the keyless lane genuinely cannot know, such as follower counts, is now shown as unknown instead of zero. The X connector accepts the app key and secret the platform already stores, exchanging them for a read-only token itself, so it no longer needs a separate token provisioned by hand. A mistyped Farcaster name now comes back as not found rather than as an upstream outage, and all four endpoints are documented in the API reference for the first time.</description>
+ </item>
<item>
<title>Mistyped filters on the revenue, checkout and ring endpoints answer plainly instead of failing</title>
<link>https://three.ws/x402-revenue</link>
@@ -62,6 +70,14 @@
<category>fix</category>
<description>Three fixes to the skills marketplace. Installing or removing a skill now carries the same one-time security token every other account action does, so a page you happen to have open elsewhere can no longer quietly add skills to your account behind your back. Editing one of your published skills used to answer back with its rating blanked out, which made the detail panel show 'No ratings yet' on a skill people had actually rated until you reloaded; it now reports the real average and count. And when a skill you were paging past gets deleted or made private mid-scroll, 'Load more' stops cleanly instead of looping the first page of results back into the grid over and over.</description>
</item>
+ <item>
+ <title>Solana agents from the outside registries get a real link preview, and a mistyped discover link stops erroring</title>
+ <link>https://three.ws/discover</link>
+ <guid isPermaLink="false">2026-08-16:Solana agents from the outside registries get a real link preview, and a mistyped discover link stops erroring</guid>
+ <pubDate>Sun, 16 Aug 2026 12:00:00 GMT</pubDate>
+ <category>fix</category>
+ <description>Two fixes to the Discover detail pages. Agents crawled from the outside Solana registries opened fine in the browser but shared as a nameless card: every one of them unfurled in Slack, Discord, X and iMessage with a generic three.ws title and the stock image, while the Ethereum-side agents in the same grid previewed properly. Those pages now carry the agent name, description and artwork, whether the link points at the mint or at its registry entry. Separately, a Discover link with a mistyped or truncated id answered with a server error and the page showed a vague &quot;something went wrong&quot;; it now says plainly that the item was not found and shows the Not found state, and an agent whose on-chain id is larger than the site could previously handle resolves instead of coming back empty.</description>
+ </item>
<item>
<title>The $THREE economy dashboard no longer errors out on an odd date range</title>
<link>https://three.ws/changelog</link>
diff --git a/public/features.json b/public/features.json
index a66aac511..efc6aca54 100644
--- a/public/features.json
+++ b/public/features.json
@@ -1,5 +1,5 @@
{
- "generated_at": "2026-08-16T06:58:40.531Z",
+ "generated_at": "2026-08-16T07:08:36.532Z",
"generated_by": "scripts/build-page-index.mjs from data/pages.json",
"site": {
"name": "three.ws",
@@ -5170,7 +5170,7 @@
{
"path": "/docs/animations",
"title": "Docs · Animations",
- "description": "The motion clips (idle, wave, dance, and about 2,000 more) that bring three.ws avatars to life: how the registry is organised, how clips load at runtime, how they retarget onto any humanoid rig, and how to preview every one in the browser.",
+ "description": "The motion clips (idle, wave, dance, and about 3,000 more) that bring three.ws avatars to life: how the registry is organised, how clips load at runtime, how they retarget onto any humanoid rig, and how to preview every one in the browser.",
"added": null,
"auth": null,
"indexable": true,
diff --git a/tests/x402-endpoint-input-validation.test.js b/tests/x402-endpoint-input-validation.test.js
new file mode 100644
index 000000000..65a75f7af
--- /dev/null
+++ b/tests/x402-endpoint-input-validation.test.js
@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+
+// Query-param validation for the standalone x402 REST endpoints.
+//
+// Every case here started as a real 500 (or a silently wrong answer) observed by
+// curling the running server on 2026-08-16:
+// • /api/x402-revenue?since=notadate → 22P02 "invalid input syntax for type
+// timestamp with time zone" from the ::timestamptz cast, served as a 500 with
+// a support ref for what is plainly a caller typo.
+// • /api/x402-skus?id=notauuid → 22P02 "invalid input syntax for type
+// uuid", same 500, on GET/PATCH/DELETE alike.
+// • /api/x402-ring?period=alll → 200, silently widened to a lifetime
+// full-ledger scan instead of the requested window.
+// A malformed param has to fail as a 4xx before it reaches Postgres, and the
+// filter a response echoes has to be the filter it actually applied.
+
+const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+process.env.X402_ASSET_MINT_SOLANA ||= USDC;
+
+const { endpointSlug, timestampParam } = await import('../api/x402-revenue.js');
+const { UUID_RE } = await import('../api/x402-skus.js');
+const { PERIODS, sinceFor } = await import('../api/x402-ring.js');
+const { TX_SIGNATURE_RE } = await import('../api/x402-pay.js');
+const { REPO_RE, SESSION_RE, normalizeEnvelope } = await import('../api/zauth-reposcan.js');
+
+describe('x402-revenue: timestamp params', () => {
+ it('normalizes a parseable timestamp to ISO for the ::timestamptz bind', () => {
+ expect(timestampParam('2026-08-01T00:00:00Z', 'since')).toBe('2026-08-01T00:00:00.000Z');
+ expect(timestampParam('2026-08-01T00:00:00.000Z', 'cursor')).toBe('2026-08-01T00:00:00.000Z');
+ });
+
+ it('treats an absent param as no bound rather than as an error', () => {
+ expect(timestampParam(null, 'since')).toBeNull();
+ expect(timestampParam('', 'cursor')).toBeNull();
+ expect(timestampParam(undefined, 'since')).toBeNull();
+ });
+
+ it('rejects an unparseable value with a 400-carrying, param-named error', () => {
+ expect(() => timestampParam('notadate', 'since')).toThrowError(/since/);
+ try {
+ timestampParam('zzz', 'cursor');
+ throw new Error('expected a throw');
+ } catch (err) {
+ expect(err.status).toBe(400);
+ expect(err.code).toBe('invalid_cursor');
+ }
+ });
+});
+
+describe('x402-revenue: endpoint filter', () => {
+ it('accepts a bare slug, a path, and a full route as the same filter', () => {
+ expect(endpointSlug('crypto-intel')).toBe('crypto-intel');
+ expect(endpointSlug('api/x402/crypto-intel')).toBe('crypto-intel');
+ expect(endpointSlug('/api/x402/crypto-intel')).toBe('crypto-intel');
+ });
+
+ it('reports the sanitized slug, never the raw string the caller sent', () => {
+ // The response echoes this back as `filter.endpoint`; echoing the raw value
+ // claimed a traversal string was the applied filter when it never was.
+ expect(endpointSlug('../../etc/passwd')).toBe('etcpasswd');
+ expect(endpointSlug(' token-intel ')).toBe('token-intel');
+ });
+
+ it('collapses an empty or all-punctuation filter to no filter', () => {
+ expect(endpointSlug('')).toBeNull();
+ expect(endpointSlug(null)).toBeNull();
+ expect(endpointSlug('///')).toBeNull();
+ });
+});
+
+describe('x402-skus: id shape', () => {
+ it('accepts a uuid in either case', () => {
+ expect(UUID_RE.test('00000000-0000-4000-8000-000000000000')).toBe(true);
+ expect(UUID_RE.test('A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D')).toBe(true);
+ });
+
+ it('rejects everything Postgres would have thrown 22P02 on', () => {
+ for (const bad of ['notauuid', '', '00000000-0000-4000-8000', 'a,b', "' or 1=1--"]) {
+ expect(UUID_RE.test(bad)).toBe(false);
+ }
+ });
+});
+
+describe('x402-ring: period window', () => {
+ it('advertises exactly the windows the handler can resolve', () => {
+ expect(PERIODS).toEqual(['24h', '7d', '30d', 'all']);
+ });
+
+ it('resolves a windowed period to a cutoff in the past and lifetime to null', () => {
+ const since = sinceFor('24h');
+ expect(Date.parse(since)).toBeLessThan(Date.now());
+ expect(Date.now() - Date.parse(since)).toBeCloseTo(24 * 3600 * 1000, -4);
+ expect(sinceFor('all')).toBeNull();
+ });
+
+ it('keeps a typo out of the lifetime window: it is not an accepted period', () => {
+ expect(PERIODS.includes('alll')).toBe(false);
+ expect(PERIODS.includes('bogus')).toBe(false);
+ });
+});
+
+describe('x402-pay: call lookup key', () => {
+ it('accepts a real Solana signature', () => {
+ expect(
+ TX_SIGNATURE_RE.test(
+ '5fEhhh54bqAwjZGSzw9o5FbJq5yGsPnQEGtL8bbsHDd14CqixcH9haYtSXysmaAsNVGKwNkYSG6VdZnGSStPqka9',
+ ),
+ ).toBe(true);
+ });
+
+ it('rejects non-base58 and unbounded values before they become a Redis key', () => {
+ expect(TX_SIGNATURE_RE.test('nope!!')).toBe(false);
+ expect(TX_SIGNATURE_RE.test('short')).toBe(false);
+ expect(TX_SIGNATURE_RE.test('0OIl'.repeat(20))).toBe(false); // base58 excludes 0 O I l
+ expect(TX_SIGNATURE_RE.test('A'.repeat(400))).toBe(false);
+ });
+});
+
+describe('zauth-reposcan: proxy input shapes', () => {
+ it('accepts an owner/repo pair and refuses anything else', () => {
+ expect(REPO_RE.test('nirholas/three.ws')).toBe(true);
+ expect(REPO_RE.test('not a repo')).toBe(false);
+ expect(REPO_RE.test('owner/repo/extra')).toBe(false);
+ expect(REPO_RE.test('/repo')).toBe(false);
+ });
+
+ it('bounds the free progress-poll session token', () => {
+ expect(SESSION_RE.test('abcdefgh12345678')).toBe(true);
+ expect(SESSION_RE.test('short')).toBe(false);
+ expect(SESSION_RE.test('<script>')).toBe(false);
+ });
+
+ it('rewrites resource.url to the upstream endpoint without touching the signature', () => {
+ const payload = { transaction: 'signed-transfer-bytes' };
+ const sent = Buffer.from(
+ JSON.stringify({ x402Version: 2, payload, resource: { url: 'https://three.ws/api/zauth-reposcan' } }),
+ ).toString('base64');
+ const forwarded = JSON.parse(Buffer.from(normalizeEnvelope(sent), 'base64').toString('utf8'));
+ expect(forwarded.resource.url).toBe('https://api.zauth.inc/x402/reposcan');
+ expect(forwarded.payload).toEqual(payload);
+ });
+
+ it('forwards an envelope it cannot read untouched rather than mangling it', () => {
+ expect(normalizeEnvelope('not-base64-json')).toBe('not-base64-json');
+ const noPayload = Buffer.from(JSON.stringify({ x402Version: 2 })).toString('base64');
+ expect(normalizeEnvelope(noPayload)).toBe(noPayload);
+ });
+});