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
// Public AgenC bridge endpoints — free reads of the AgenC coordination
// protocol (agenc.tech, by Tetsuo Corp) so three.ws frontends and external
// agents can browse the on-chain task marketplace without standing up an
// Anchor + IDL pipeline of their own.
//
// Routes (all GET unless noted):
//
// /api/agenc/list-tasks?creator=<base58>&cluster=devnet
// Returns every task PDA created by `creator`, with state + reward.
//
// /api/agenc/get-task?taskPda=<base58>&cluster=devnet[&lifecycle=1]
// /api/agenc/get-task?creator=<base58>&taskId=<hex|label>&cluster=devnet
// Single task status + (optionally) lifecycle timeline.
//
// /api/agenc/recent-tasks?cluster=devnet[&limit=6]
// The newest task PDAs three.ws itself wrote on-chain through the Agora
// rail, read from the platform's own journal (no RPC round trip), so a
// client with no address in hand has something real to watch.
//
// /api/agenc/get-agent?agentPda=<base58>&cluster=devnet
// /api/agenc/get-agent?agentId=<hex|label>&cluster=devnet
// Agent registration state.
//
// /api/agenc/link (POST)
// body: { erc8004AgentId?, mplCoreAsset?, handle?, cluster? }
// → { agenCAgentId, agentPda, metadataUri, source, label,
// registered, agent? }
// Computes the canonical three.ws → AgenC agentId via the identity
// bridge and checks whether that PDA is already registered on-chain.
//
// Cluster defaults to `mainnet`; set `?cluster=devnet` for the devnet
// deployment. Every response carries the `programId` the read actually ran
// against, because `createAgenCClient` derives it from the bundled IDL rather
// than from a constant: quoting a program address from anywhere else (docs, UI
// copy, an older SDK export) is how a page ends up naming a program no read of
// ours has touched in months. Reads rotate across the platform's canonical
// Solana RPC chain (see withAgenC below); `AGENC_RPC_URL` pins a preferred
// endpoint at the head of that chain.
import { PublicKey } from '@solana/web3.js';
import { createHash } from 'node:crypto';
import { getTask, getTaskLifecycleSummary, getTasksByCreator, getAgent, deriveTaskPda, deriveAgentPda } from '@tetsuo-ai/sdk';
import { cors, json, method, readJson, wrap, error, rateLimited, serverError } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { sql } from '../_lib/db.js';
import {
solanaRpcEndpoints,
isEndpointCooling,
markEndpointCooldown,
hydrateEndpointCooldowns,
shouldRotate,
isTransientRpcError,
} from '../_lib/solana/connection.js';
import { Bazaar, filterByExtension, filterByMaxPrice, filterByNetwork, parseAtomicAmount } from '../_lib/x402/bazaar-client.js';
// @three-ws/solana-agent (the symlinked `file:solana-agent-sdk` SDK) is loaded
// LAZILY at the point of use — every other importer (api/agora/act.js,
// api/agora/[action].js, api/_lib/agora-human.js) does the same so the module
// evaluates even where the SDK's dist/ isn't built yet, and so the Vitest
// resolver doesn't have to externalize a static entry it can't load.
function pickCluster(req) {
const c = (req.query?.cluster || '').toString().trim().toLowerCase();
return c === 'devnet' ? 'devnet' : 'mainnet';
}
function parsePubkey(s, label) {
if (!s) throw new Error(`${label} is required`);
try {
return new PublicKey(String(s).trim());
} catch {
throw new Error(`${label} is not a valid base58 pubkey`);
}
}
function resolveIdInput(s) {
const t = String(s).trim();
if (t.startsWith('0x') || t.startsWith('0X')) {
const hex = t.slice(2);
if (hex.length !== 64) throw new Error('hex id must be 32 bytes');
return Uint8Array.from(Buffer.from(hex, 'hex'));
}
if (/^[0-9a-fA-F]{64}$/.test(t)) return Uint8Array.from(Buffer.from(t, 'hex'));
return Uint8Array.from(createHash('sha256').update(t, 'utf8').digest());
}
function serialize(value) {
if (value === null || value === undefined) return value;
if (typeof value === 'bigint') return value.toString();
if (value instanceof Uint8Array) return Buffer.from(value).toString('hex');
if (value instanceof PublicKey) return value.toBase58();
if (Array.isArray(value)) return value.map(serialize);
if (typeof value === 'object') {
const out = {};
for (const [k, v] of Object.entries(value)) out[k] = serialize(v);
return out;
}
return value;
}
// AgenC's on-chain TaskState enum, verbatim (@tetsuo-ai/sdk `TaskState` /
// `formatTaskState`). This map was previously shifted by one past `Open`, which
// reported a Completed task as "Cancelled" and a Cancelled one as "Disputed": the
// worst kind of wrong, because it reads as a definite (and alarming) status rather
// than an error. There is no 'Expired' state on-chain; a lapsed deadline leaves the
// task Open until its creator cancels it.
export function taskStateLabel(state) {
const map = { 0: 'Open', 1: 'In Progress', 2: 'Pending Validation', 3: 'Completed', 4: 'Cancelled', 5: 'Disputed' };
if (typeof state === 'number') return map[state] ?? `Unknown(${state})`;
if (state && typeof state === 'object') {
const key = Object.keys(state)[0];
return key ? key[0].toUpperCase() + key.slice(1) : 'Unknown';
}
return String(state);
}
// A base58 address a visitor can legitimately paste but that is not an AgenC
// account of the expected type fails INSIDE the Anchor decoder ("Invalid account
// discriminator", "Account does not exist"), not by returning null. That error is
// deterministic, so `rotateRpc` correctly re-throws it on the first endpoint, and
// the wrapper then answered an opaque 500 for what is really "no such task on
// this cluster": the single most likely thing a visitor gets wrong, reported as
// though the platform were broken. Classify it and reuse the handler's own 404.
function isWrongAccount(err) {
return /invalid account discriminator|account does not exist|could not find account|failed to deserialize/i.test(
String(err?.message || err),
);
}
// Read an AgenC account, turning "that address holds no such account" into null
// so callers render the honest 404 instead of a server error.
async function readAccount(read) {
try {
return await read();
} catch (err) {
if (isWrongAccount(err)) return null;
throw err;
}
}
function agentStatusLabel(status) {
const map = { 0: 'Inactive', 1: 'Active', 2: 'Busy', 3: 'Suspended' };
if (typeof status === 'number') return map[status] ?? `Unknown(${status})`;
if (status && typeof status === 'object') {
const key = Object.keys(status)[0];
return key ? key[0].toUpperCase() + key.slice(1) : 'Unknown';
}
return String(status);
}
// `createAgenCClient` builds its own Connection from ONE url, so a client made
// here is bound to a single endpoint with no failover of its own. Pointing it at
// `SOLANA_RPC_URL` alone is what took every chain-backed AgenC route down: the
// configured primary began answering this egress with a hard 403, and each read
// became an opaque 500 while eight healthy lanes sat unused. So we walk the
// platform's canonical, priority-ordered endpoint chain instead and share its
// process-wide cooldown map, which means a lane another surface just parked is
// skipped here too, and a lane we park is skipped there. `AGENC_RPC_URL` still
// wins: it is pinned to the head of the chain rather than being the whole of it.
async function agenCEndpoints(cluster) {
// Inherit the fleet's view of dead lanes first. Without it a cold Cloud Run
// instance re-discovers a quota-dead provider the expensive way: web3.js runs
// its own 429 backoff (500/1000/2000/4000ms) inside the Connection before the
// error ever reaches us, so each already-known-dead lane costs ~7.5s.
await hydrateEndpointCooldowns();
const pinned = (process.env.AGENC_RPC_URL || '').trim() || null;
const urls = solanaRpcEndpoints(cluster, pinned);
const live = urls.filter((u) => !isEndpointCooling(u));
// Every lane cooling at once is upstream weather, not a reason to answer with
// nothing: re-probe the full chain rather than skipping straight to a 503.
return live.length ? live : urls;
}
// Recover the upstream HTTP status from a web3.js error, which reports it as the
// head of the message ("403 Forbidden: {…}"). 0 means "no status in there".
function rpcStatus(err) {
const m = String(err?.message || err).match(/\b(401|403|404|408|410|429|5\d\d)\b/);
return m ? Number(m[1]) : 0;
}
// Thrown once every endpoint has refused the same read. Distinct from a normal
// failure so the wrapper can answer 503 + Retry-After (upstream weather the
// caller should retry) instead of a 500 (a defect the caller cannot act on).
export class RpcChainExhausted extends Error {
constructor(cluster, tried, cause) {
super(`all ${tried} Solana RPC endpoints refused this ${cluster} read: ${cause?.message || 'unknown error'}`);
this.name = 'RpcChainExhausted';
this.cluster = cluster;
this.tried = tried;
this.cause = cause;
}
}
// A lane that ACCEPTS the connection and then never answers is the one failure
// this rotation could not see. `createAgenCClient` builds a plain
// `new Connection(rpcUrl)`, so it never gets the rotating fetch's own
// ATTEMPT_TIMEOUT_MS bound (that only wraps multi-endpoint Connections); undici's
// defaults then run to minutes with nothing thrown, so `rotateRpc` sat on a dead
// provider instead of moving to the next one. `getTasksByCreator` is the read
// that exposed it: it is a getProgramAccounts memcmp scan, the heaviest call
// shape here and the first any provider stalls or silently drops. Bounding each
// attempt turns that silence back into a rotate-worthy failure.
const AGENC_ATTEMPT_TIMEOUT_MS = 10_000;
// Reject with a transient, rotate-worthy error once an attempt outruns its
// budget. The message is deliberately shaped to match `isTransientRpcError`, so
// a stall cools the lane exactly like a timeout reported by the provider itself.
function attemptTimeout(rpcUrl) {
let timer;
const promise = new Promise((_, reject) => {
timer = setTimeout(() => {
reject(new Error(`Solana RPC lane timed out after ${AGENC_ATTEMPT_TIMEOUT_MS}ms: ${rpcUrl}`));
}, AGENC_ATTEMPT_TIMEOUT_MS);
});
// Never hold the process open on the loser of the race.
timer?.unref?.();
return { promise, cancel: () => clearTimeout(timer) };
}
// Run `run` against an AgenC client, rotating to the next endpoint whenever one
// fails in a way the next provider may not share (401/403/404/408/410/429/5xx,
// timeouts, network blips) or simply stops answering. A real request error, e.g.
// a malformed account the chain decodes the same way everywhere, is re-thrown on
// the first endpoint rather than replayed nine times.
export async function rotateRpc({ cluster, endpoints, createClient, run }) {
let last = null;
for (const rpcUrl of endpoints) {
let client;
try {
client = createClient(rpcUrl);
} catch (err) {
// A URL this build of web3.js refuses to construct a Connection from is a
// dead lane, not a dead chain: skip it and let the next endpoint answer.
last = err;
continue;
}
const bound = attemptTimeout(rpcUrl);
try {
return await Promise.race([run(client), bound.promise]);
} catch (err) {
const status = rpcStatus(err);
if (!shouldRotate(status) && !isTransientRpcError(err)) throw err;
const ms = markEndpointCooldown(rpcUrl, status || 429, String(err?.message || ''));
console.info(`[agenc] rpc lane failed (${status || 'transient'}), cooling ${Math.round(ms / 1000)}s, rotating`);
last = err;
} finally {
// Runs on success, rotation, and the re-thrown non-rotatable error alike,
// so a won race never leaves a timer pending behind the response.
bound.cancel();
}
}
throw new RpcChainExhausted(cluster, endpoints.length, last);
}
async function withAgenC(cluster, run) {
const { createAgenCClient } = await import('@three-ws/solana-agent');
const endpoints = await agenCEndpoints(cluster);
return rotateRpc({
cluster,
endpoints,
createClient: (rpcUrl) => createAgenCClient({ cluster, rpcUrl }),
run,
});
}
async function handleListTasks(req, res) {
let creator;
try {
creator = parsePubkey(req.query?.creator, 'creator');
} catch (err) {
return error(res, 400, 'validation_error', err.message);
}
const { client, tasks } = await withAgenC(pickCluster(req), async (c) => ({
client: c,
tasks: await getTasksByCreator(c.program, creator),
}));
return json(res, 200, serialize({
ok: true,
cluster: client.cluster,
programId: client.programId,
creator,
count: tasks.length,
tasks: tasks.map((t) => ({
taskId: Buffer.from(t.taskId).toString('hex'),
taskPda: deriveTaskPda(creator, t.taskId, client.programId),
state: taskStateLabel(t.state),
stateRaw: typeof t.state === 'number' ? t.state : null,
rewardAmount: t.rewardAmount,
rewardMint: t.rewardMint,
deadline: t.deadline,
currentWorkers: t.currentWorkers,
maxWorkers: t.maxWorkers,
completedAt: t.completedAt,
private: !!t.constraintHash,
})),
fetchedAt: new Date().toISOString(),
}));
}
// Task discovery without an address in hand. `list-tasks` can only answer once
// the caller already knows a creator wallet, which leaves every first-time
// visitor of /agenc/embodied staring at an input box with nothing to put in it
// and no way to find one: the surface renders live on-chain state and offered no
// path to any. The platform does know real task PDAs, because every task the
// Agora rail posts, claims, and completes is journalled with the PDA it wrote.
// So this reads our own ledger (one DB round trip, no getProgramAccounts scan)
// and hands back the newest PDAs for the requested cluster. It is a pointer
// list, not a source of truth: whatever the caller then acts on is verified
// against the chain by `get-task`.
async function handleRecentTasks(req, res) {
const cluster = pickCluster(req);
const requested = parseInt(String(req.query?.limit ?? '6'), 10);
const limit = Math.min(Math.max(Number.isFinite(requested) ? requested : 6, 1), 25);
let rows;
try {
rows = await sql`
select a.task_pda,
max(a.created_at) as last_activity_at,
max(a.reward_label) as reward_label,
array_agg(distinct a.kind) as kinds
from agora_activity a
join agora_citizens c on c.id = a.citizen_id
where a.task_pda is not null
and c.agenc_cluster = ${cluster}
group by a.task_pda
order by last_activity_at desc
limit ${limit}`;
} catch (err) {
// The journal is a convenience index over work the chain already holds, so
// a DB blip degrades discovery rather than failing the request: the caller
// still has the manual taskPda path, and `degraded` tells it to say so.
console.warn('[agenc] recent-tasks journal unavailable:', err?.message);
return json(res, 200, { ok: true, cluster, count: 0, degraded: true, tasks: [], fetchedAt: new Date().toISOString() });
}
return json(res, 200, {
ok: true,
cluster,
count: rows.length,
degraded: false,
tasks: rows.map((r) => ({
taskPda: r.task_pda,
lastActivityAt: r.last_activity_at instanceof Date ? r.last_activity_at.toISOString() : r.last_activity_at,
rewardLabel: r.reward_label ?? null,
kinds: Array.isArray(r.kinds) ? r.kinds : [],
})),
fetchedAt: new Date().toISOString(),
});
}
async function handleGetTask(req, res) {
const q = req.query || {};
// Resolve the caller's identifiers BEFORE touching the chain: a malformed pubkey
// or task id is a 400 that must not cost an RPC round trip (or nine of them).
let explicitPda = null;
let creator = null;
let taskIdSeed = null;
try {
if (q.taskPda) {
explicitPda = parsePubkey(q.taskPda, 'taskPda');
} else if (q.creator && q.taskId) {
creator = parsePubkey(q.creator, 'creator');
taskIdSeed = resolveIdInput(q.taskId);
} else {
return error(res, 400, 'validation_error', 'provide taskPda OR (creator + taskId)');
}
} catch (err) {
return error(res, 400, 'validation_error', err.message);
}
const wantLifecycle = q.lifecycle === '1' || q.lifecycle === 'true';
const { client, pda, task, lifecycle } = await withAgenC(pickCluster(req), async (c) => {
const taskPda = explicitPda || deriveTaskPda(creator, taskIdSeed, c.programId);
const found = await readAccount(() => getTask(c.program, taskPda));
if (!found || !wantLifecycle) return { client: c, pda: taskPda, task: found, lifecycle: null };
const s = await readAccount(() => getTaskLifecycleSummary(c.program, taskPda));
if (!s) return { client: c, pda: taskPda, task: found, lifecycle: null };
return {
client: c,
pda: taskPda,
task: found,
lifecycle: {
currentState: taskStateLabel(s.currentState),
createdAt: s.createdAt,
currentWorkers: s.currentWorkers,
maxWorkers: s.maxWorkers,
timeline: s.timeline.map((e) => ({
eventName: e.eventName,
timestamp: e.timestamp,
txSignature: e.txSignature ?? null,
actor: e.actor ? e.actor.toBase58() : null,
})),
},
};
});
if (!task) {
return json(res, 404, {
ok: false,
error: 'not_found',
cluster: client.cluster,
programId: client.programId.toBase58(),
taskPda: pda.toBase58(),
});
}
// Journal enrichment reads our own DB, not the chain, so it stays outside the
// RPC rotation: a DB blip must never cost a second pass over every endpoint.
if (lifecycle) await enrichLifecycleFromProjection(lifecycle, pda.toBase58());
return json(res, 200, serialize({
ok: true,
cluster: client.cluster,
programId: client.programId,
taskPda: pda,
task: {
taskId: Buffer.from(task.taskId).toString('hex'),
state: taskStateLabel(task.state),
stateRaw: typeof task.state === 'number' ? task.state : null,
creator: task.creator,
rewardAmount: task.rewardAmount,
rewardMint: task.rewardMint,
deadline: task.deadline,
currentWorkers: task.currentWorkers,
maxWorkers: task.maxWorkers,
completedAt: task.completedAt,
constraintHash: task.constraintHash ? Buffer.from(task.constraintHash).toString('hex') : null,
private: !!task.constraintHash,
},
lifecycle,
fetchedAt: new Date().toISOString(),
}));
}
// A task account records WHAT happened but not the signature of the transaction
// that did it: Solana account state can't recover the signatures that wrote it,
// so every on-chain timeline event arrives with `txSignature: null` and a client
// can only render "no tx recorded". three.ws does know them: each write through
// the Agora rail is journalled into `agora_activity` with its real signature (and,
// for a completion, the deliverable URL + proofHash that the completion bound).
//
// So we fill the chain's blanks from our own journal, keyed by task PDA. Rules:
// • The chain stays authoritative: an event that already carries a signature is
// never overwritten, and no event is invented that the chain didn't report.
// • Enrichment is best-effort: if the DB is unreachable the timeline is returned
// exactly as the chain gave it. A missing signature renders as an honest "no tx
// recorded", never a broken Explorer link.
// • Surfacing `proofHash` + `deliverableUrl` on the completion event is what lets
// a deep-linked task (/agora?task=<pda>) verify itself: without it a visitor
// arriving by URL has bytes to fetch but nothing to check them against.
const LIFECYCLE_EVENT_KINDS = [
{ match: /^(task)?created/i, kinds: ['posted_task', 'hired'] },
{ match: /^(task)?claim/i, kinds: ['claimed_task'] },
{ match: /^(task)?(complete|prove|submit)/i, kinds: ['completed_task', 'settled'] },
];
export async function enrichLifecycleFromProjection(lifecycle, taskPda) {
if (!lifecycle?.timeline?.length) return;
let rows;
try {
rows = await sql`
select kind, tx_signature, proof_hash, deliverable_url, created_at
from agora_activity
where task_pda = ${taskPda} and tx_signature is not null
order by created_at asc
limit 200
`;
} catch (err) {
// No DB (or it's down): the chain's own timeline is still correct and honest.
console.warn('[agenc] lifecycle tx enrichment unavailable:', err?.message);
return;
}
if (!rows?.length) return;
// Consume each journal row at most once so a multi-worker task's second claim
// can't inherit the first claim's signature.
const used = new Set();
for (const ev of lifecycle.timeline) {
const spec = LIFECYCLE_EVENT_KINDS.find((s) => s.match.test(ev.eventName || ''));
if (!spec) continue;
let row = null;
for (let i = 0; i < rows.length; i++) {
if (used.has(i) || !spec.kinds.includes(rows[i].kind)) continue;
used.add(i);
row = rows[i];
break;
}
if (!row) continue;
if (!ev.txSignature) ev.txSignature = row.tx_signature;
if (row.proof_hash && !ev.proofHash) ev.proofHash = row.proof_hash;
if (row.deliverable_url && !ev.deliverableUrl) ev.deliverableUrl = row.deliverable_url;
}
// Hoist the deliverable proof to the top level too, so a client that only has a
// PDA (a deep link) can run the verifier without walking the timeline.
const done = lifecycle.timeline.find((e) => e.proofHash || e.deliverableUrl);
if (done) {
lifecycle.proofHash = done.proofHash || null;
lifecycle.deliverableUrl = done.deliverableUrl || null;
}
}
async function handleGetAgent(req, res) {
const q = req.query || {};
let explicitPda = null;
let agentIdSeed = null;
try {
if (q.agentPda) {
explicitPda = parsePubkey(q.agentPda, 'agentPda');
} else if (q.agentId) {
agentIdSeed = resolveIdInput(q.agentId);
} else {
return error(res, 400, 'validation_error', 'provide agentPda or agentId');
}
} catch (err) {
return error(res, 400, 'validation_error', err.message);
}
const { client, pda, agent } = await withAgenC(pickCluster(req), async (c) => {
const agentPda = explicitPda || deriveAgentPda(agentIdSeed, c.programId);
return { client: c, pda: agentPda, agent: await readAccount(() => getAgent(c.program, agentPda)) };
});
if (!agent) {
return json(res, 404, {
ok: false,
error: 'not_found',
cluster: client.cluster,
programId: client.programId.toBase58(),
agentPda: pda.toBase58(),
});
}
return json(res, 200, serialize({
ok: true,
cluster: client.cluster,
programId: client.programId,
agentPda: pda,
agent: {
agentId: Buffer.from(agent.agentId).toString('hex'),
authority: agent.authority,
capabilities: agent.capabilities,
status: agentStatusLabel(agent.status),
statusRaw: typeof agent.status === 'number' ? agent.status : null,
endpoint: agent.endpoint,
metadataUri: agent.metadataUri,
stakeAmount: agent.stakeAmount,
activeTasks: agent.activeTasks,
reputation: agent.reputation,
registeredAt: agent.registeredAt,
},
fetchedAt: new Date().toISOString(),
}));
}
async function handleLink(req, res) {
let body;
try {
body = await readJson(req);
} catch {
return error(res, 400, 'validation_error', 'invalid json');
}
const { erc8004AgentId, mplCoreAsset, handle, cluster, baseUrl } = body || {};
const { getCanonicalThreewsAgenCId, buildThreewsMetadataUri, agenCAgentIdToHex } =
await import('@three-ws/solana-agent');
let canonical;
try {
canonical = getCanonicalThreewsAgenCId({
erc8004AgentId: erc8004AgentId ?? null,
mplCoreAsset: mplCoreAsset ?? null,
handle: handle ?? null,
});
} catch (err) {
return error(res, 400, 'validation_error', err.message);
}
const cl = cluster === 'devnet' ? 'devnet' : 'mainnet';
const { client, pda, agent } = await withAgenC(cl, async (c) => {
const agentPda = deriveAgentPda(canonical.agenCAgentId, c.programId);
return { client: c, pda: agentPda, agent: await readAccount(() => getAgent(c.program, agentPda)) };
});
const metadataUri = buildThreewsMetadataUri(
{ erc8004AgentId: erc8004AgentId ?? null, mplCoreAsset: mplCoreAsset ?? null, handle: handle ?? null },
typeof baseUrl === 'string' && baseUrl ? baseUrl : 'https://three.ws',
);
return json(res, 200, serialize({
ok: true,
cluster: client.cluster,
programId: client.programId,
source: canonical.source,
label: canonical.label,
agenCAgentId: agenCAgentIdToHex(canonical.agenCAgentId),
agentPda: pda,
metadataUri,
registered: !!agent,
agent: agent
? {
authority: agent.authority,
status: agentStatusLabel(agent.status),
endpoint: agent.endpoint,
metadataUri: agent.metadataUri,
reputation: agent.reputation,
activeTasks: agent.activeTasks,
stakeAmount: agent.stakeAmount,
}
: null,
fetchedAt: new Date().toISOString(),
}));
}
// Stable 32-byte taskId seed derived from an x402 resource URL — lets the
// same x402 service map to a deterministic AgenC task PDA so re-postings
// idempotently update the same on-chain account.
function x402TaskIdSeed(resource) {
return createHash('sha256')
.update('AgenC/three.ws/x402/v1\0', 'utf8')
.update(String(resource), 'utf8')
.digest();
}
async function handleX402Services(req, res) {
const q = req.query || {};
const type = (q.type || 'http').toString().toLowerCase();
if (type !== 'http' && type !== 'mcp') {
return error(res, 400, 'validation_error', 'type must be "http" or "mcp"');
}
const network = q.network ? String(q.network) : null;
const maxPrice = q.maxPrice ? String(q.maxPrice) : null;
// Atomic units, not decimals (see /api/bazaar/list): a malformed cap is a 400.
if (maxPrice != null && parseAtomicAmount(maxPrice) === null) {
return error(res, 400, 'validation_error', 'maxPrice must be an atomic integer amount (e.g. 10000 = 0.01 USDC)');
}
const asset = q.asset ? String(q.asset) : null;
const extension = q.extension ? String(q.extension) : null;
const maxItems = Math.max(1, Math.min(parseInt(q.maxItems, 10) || 200, 1000));
const baz = new Bazaar();
let result;
try {
result = await baz.list({ type, limit: 200, maxItems });
} catch (err) {
console.error('[agenc] bazaar fetch failed', err?.message);
return serverError(res, 502, 'facilitator_error', err);
}
let items = result.items;
if (network) items = filterByNetwork(items, network);
if (maxPrice) items = filterByMaxPrice(items, maxPrice, asset);
if (extension) items = filterByExtension(items, extension);
const tasks = items.map((it) => {
const minAccept = it.accepts?.[0] || null;
const seed = x402TaskIdSeed(it.uniqueKey || it.resource);
return {
source: 'three.ws/x402',
type: it.type,
resource: it.resource,
toolName: it.toolName || null,
serviceName: it.serviceName,
description: it.description,
tags: it.tags || [],
method: it.method || null,
capabilities: 1, // bit 0: HTTP fetch / x402 settle
price: minAccept
? {
amountAtomic: minAccept.amountAtomic,
amountLabel: minAccept.priceLabel,
currency: minAccept.asset,
network: minAccept.network,
family: minAccept.family,
}
: null,
input: it.input || null,
output: it.output || null,
taskIdSeed: '0x' + Buffer.from(seed).toString('hex'),
rewardKind: 'x402_pay_to_endpoint',
facilitator: it.facilitator,
lastUpdated: it.lastUpdated,
};
});
res.setHeader('cache-control', 'public, max-age=15, stale-while-revalidate=60');
return json(res, 200, {
ok: true,
count: tasks.length,
tasks,
sources: result.sources,
errors: result.errors,
fetchedAt: new Date().toISOString(),
});
}
const HANDLERS = {
'list-tasks': { methods: ['GET'], fn: handleListTasks },
'recent-tasks': { methods: ['GET'], fn: handleRecentTasks },
'get-task': { methods: ['GET'], fn: handleGetTask },
'get-agent': { methods: ['GET'], fn: handleGetAgent },
'x402-services': { methods: ['GET'], fn: handleX402Services },
link: { methods: ['POST'], fn: handleLink },
};
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: false })) return;
const action = String(req.query?.action || '').toLowerCase();
const route = HANDLERS[action];
if (!route) return error(res, 404, 'not_found', `unknown action "${action}"`);
if (!method(req, res, route.methods)) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
try {
return await route.fn(req, res);
} catch (err) {
// Every RPC lane refusing the same read is upstream weather with a real
// remedy (retry once a cooldown lapses), so it gets an honest 503 + a
// Retry-After the caller can act on. A 500 here told clients "we are
// broken, do not retry" for a condition that clears itself in seconds.
if (err instanceof RpcChainExhausted) {
console.error('[agenc] rpc chain exhausted', err.message);
// A handler that already wrote a response before throwing would make this
// setHeader throw ERR_HTTP_HEADERS_SENT, turning a clean 503 into a crash.
if (!res.headersSent) res.setHeader('retry-after', '30');
return error(res, 503, 'rpc_unavailable', `Solana ${err.cluster} RPC is unavailable right now; retry in ~30s`, {
cluster: err.cluster,
endpointsTried: err.tried,
});
}
console.error('[agenc] unexpected error', err?.message);
return serverError(res, 500, 'agenc_error', err);
}
});