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
// POST /api/x402/pipeline { stages: [...], prompt?, glb_url?, options?: {...} }
//
// One x402 call, full 3D asset pipeline — text or GLB in, rigged/optimized
// game-ready GLB out. The only asset pipeline in the x402 ecosystem: an agent
// describes what it wants and gets back a game-ready asset from a single paid
// call, priced per stage and quoted EXACTLY in the 402 challenge.
//
// `stages` is an ordered subsequence of
// ['generate','rig','remesh','gameready','stylize']
// (generate must be first and needs `prompt`; without generate, `glb_url` is the
// input). Only stages whose backing lane is configured on this deployment are
// offered — the grammar is computed from env per request, and the 402 quote is
// the SUM of the requested stages' prices.
//
// Execution mirrors api/x402/forge.js: the first stage is submitted AFTER verify
// but BEFORE settle, so a dead first lane never charges. The chain then advances
// as a poll-driven state machine — the buyer polls FREE at
// GET /api/forge?job=<job_token>
// and each poll runs the next stage when the current one finishes, recording
// per-stage progress (id, status, started_at, finished_at, output_url, error).
// A stage failing mid-chain marks the job `failed` at that stage with the
// completed stages' outputs still delivered (honest partial value).
//
// Network: USDC on Solana mainnet (Base is a dev/preview failsafe when
// X402_PAY_TO_SOLANA is unset). GET (no payment) returns the live stage grammar
// and per-stage pricing so agents can discover cost + capability before paying.
import { wrap, cors, error, json, rateLimited, readBody } from '../_lib/http.js';
import {
NETWORK_BASE_MAINNET,
NETWORK_SOLANA_MAINNET,
send402,
verifyPayment,
settlePayment,
encodePaymentResponseHeader,
permit2VariantOf,
solanaSelfPayOnly,
resolveResourceUrl,
buildBazaarSchema,
} from '../_lib/x402-spec.js';
import { env } from '../_lib/env.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import {
PAYMENT_IDENTIFIER,
checkCache,
claimSlotOrRespond,
extractIdFromHeader,
hashPaymentProof,
hashRequestPayload,
paymentIdentifierExtension,
releaseSlot,
storeResponse,
writeCachedResponse,
writeConflict,
} from '../_lib/x402/payment-identifier-server.js';
import { installAccessControl } from '../_lib/x402/access-control.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { assertSafePublicUrl } from '../_lib/ssrf-guard.js';
import { encodeJobToken } from '../_lib/forge-job-token.js';
import {
CANONICAL_ORDER,
validateChain,
priceForChain,
stageGrammar,
submitStage,
availableStages,
} from '../_lib/pipeline.js';
import { createPipelineJob, savePipelineJob, publicView } from '../_lib/pipeline-store.js';
const ROUTE = '/api/x402/pipeline';
const REQUIRED_SCOPE = 'x402:bypass';
const accessControl = installAccessControl({ requiredScope: REQUIRED_SCOPE });
const routeConfig = { path: ROUTE, method: 'POST', requiredScope: REQUIRED_SCOPE };
const HTTP_URL_RE = /^https:\/\/[^\s]+$/i;
const ROUTE_DESCRIPTION =
'One call, full 3D asset pipeline — text or GLB in, rigged/optimized ' +
'game-ready GLB out; the only asset pipeline in the x402 ecosystem. Submit an ' +
'ordered chain of stages (generate → rig → remesh → gameready → stylize) and ' +
'get back a job token you poll for FREE at GET /api/forge?job=<id>, watching ' +
'per-stage progress until the final GLB is delivered. Priced per stage and ' +
'quoted EXACTLY in the 402 challenge (the sum of the requested stages). Pay ' +
'autonomously in USDC on Solana mainnet — no API key, no account.';
const INPUT_EXAMPLE = {
stages: ['generate', 'rig'],
prompt: 'a brass steampunk owl, full body',
options: { tier: 'draft', rig: { rig_type: 'biped' } },
};
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['stages'],
properties: {
stages: {
type: 'array',
minItems: 1,
maxItems: CANONICAL_ORDER.length,
items: { type: 'string', enum: [...CANONICAL_ORDER] },
description:
'Ordered subsequence of ' + JSON.stringify(CANONICAL_ORDER) +
'. generate must be first and requires prompt; without generate, glb_url is required.',
},
prompt: {
type: 'string',
minLength: 3,
maxLength: 1000,
description: 'Subject for the generate stage. Required when stages starts with generate.',
},
glb_url: {
type: 'string',
format: 'uri',
description: 'Public https GLB to feed the first stage when the chain does not start with generate.',
},
options: {
type: 'object',
description: 'Per-stage options: { tier, aspect_ratio, rig:{rig_type}, remesh:{...}, gameready:{topology,poly_budget,texture_size}, stylize:{style,resolution} }.',
},
},
};
const OUTPUT_EXAMPLE = {
job_id: 'f1.eyJwIjoicGlwZWxpbmUifQ.sig',
status: 'running',
poll_url: '/api/forge?job=f1.eyJwIjoicGlwZWxpbmUifQ.sig',
price_usdc: '0.15',
stages: [
{ id: 'generate', status: 'done', output_url: 'https://three.ws/cdn/forge/…/model.glb' },
{ id: 'rig', status: 'running', output_url: null },
],
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['job_id', 'status', 'stages'],
properties: {
job_id: { type: 'string', description: 'Poll this FREE on GET /api/forge?job=<id>.' },
status: { type: 'string', description: '"queued" | "running" | "done" | "failed".' },
poll_url: { type: 'string' },
price_usdc: { type: 'string' },
result_glb_url: { type: ['string', 'null'], description: 'Latest completed stage output; the final GLB when status is done.' },
stages: {
type: 'array',
items: {
type: 'object',
properties: {
id: { type: 'string' },
status: { type: 'string' },
started_at: { type: ['string', 'null'] },
finished_at: { type: ['string', 'null'] },
output_url: { type: ['string', 'null'] },
error: { type: ['string', 'null'] },
},
},
},
},
};
export function buildRequirements(resourceUrl, priceAtomics) {
const amount = String(priceAtomics);
// Solana mainnet USDC only in production. Base is a dev/preview failsafe when
// X402_PAY_TO_SOLANA is unset so the route never dead-ends with an empty 402.
if (env.X402_PAY_TO_SOLANA) {
return [
{
scheme: 'exact',
network: NETWORK_SOLANA_MAINNET,
amount,
payTo: env.X402_PAY_TO_SOLANA,
asset: env.X402_ASSET_MINT_SOLANA,
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USDC', decimals: 6, ...(solanaSelfPayOnly() ? {} : { feePayer: env.X402_FEE_PAYER_SOLANA }) },
},
];
}
const eip3009 = {
scheme: 'exact',
network: NETWORK_BASE_MAINNET,
amount,
payTo: env.X402_PAY_TO_BASE,
asset: env.X402_ASSET_ADDRESS_BASE,
maxTimeoutSeconds: 60,
resource: resourceUrl,
extra: { name: 'USD Coin', version: '2', decimals: 6 },
};
const out = [eip3009];
const permit2 = permit2VariantOf(eip3009);
if (permit2) out.push(permit2);
return out;
}
function bazaarFor() {
return {
discoverable: true,
info: {
input: { type: 'http', method: 'POST', bodyType: 'json', body: INPUT_EXAMPLE },
output: { type: 'json', example: OUTPUT_EXAMPLE },
},
schema: buildBazaarSchema({
method: 'POST',
bodyType: 'json',
bodySchema: INPUT_SCHEMA,
outputSchema: OUTPUT_SCHEMA,
}),
};
}
// Parse + validate the request body into a resolved plan. Throws a tagged error
// (status/code/message) on any grammar/input fault so the handler rejects it
// BEFORE payment. Pure validation + a live env-driven grammar check.
function parsePlan(body) {
body = body && typeof body === 'object' ? body : {};
const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : '';
const glbUrl = typeof body.glb_url === 'string' ? body.glb_url.trim() : '';
const hasPrompt = prompt.length >= 3 && prompt.length <= 1000;
const hasGlb = HTTP_URL_RE.test(glbUrl) && glbUrl.length <= 2048;
if (glbUrl && !hasGlb) {
throw tagged(400, 'invalid_glb_url', 'glb_url must be a public https URL under 2048 characters.');
}
const check = validateChain(body.stages, { hasPrompt, hasGlb });
if (!check.ok) throw tagged(check.status || 400, check.code, check.message);
const options = body.options && typeof body.options === 'object' ? body.options : {};
return {
stages: check.stages,
prompt: hasPrompt ? prompt : null,
glbUrl: hasGlb ? glbUrl : null,
options,
};
function tagged(status, code, message) {
return Object.assign(new Error(message), { status, code });
}
}
// GET — free discovery: the live stage grammar + per-stage pricing so agents can
// see capability and cost before paying. No payment, no work.
function handleGet(req, res) {
const url = new URL(req.url, 'http://localhost');
if (url.searchParams.get('job')) {
return json(res, 400, {
error: 'wrong_endpoint',
message: 'Poll pipeline jobs on GET /api/forge?job=<id> (free), not here.',
});
}
const grammar = stageGrammar();
return json(res, 200, {
route: ROUTE,
description: ROUTE_DESCRIPTION,
method: 'POST',
input_schema: INPUT_SCHEMA,
poll: 'GET /api/forge?job=<id>',
...grammar,
pricing_note: 'The 402 quote is the sum of the requested stages’ prices.',
});
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
if (req.method === 'GET') return handleGet(req, res);
if (req.method !== 'POST') {
res.setHeader('allow', 'GET, POST');
return error(res, 405, 'method_not_allowed', 'use POST to run a pipeline, GET for the stage grammar + pricing');
}
// Light pre-payment rate limit so the 402 challenge + validation can't be hammered.
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
// Read the raw body once (validate + hash for idempotency).
const chunks = [await readBody(req, 1_000_000)];
const rawBody = Buffer.concat(chunks).toString('utf8');
// A body that never becomes a plan must NOT short-circuit the paywall. Every
// directory that indexes a paid route registers it by probing with a bare
// POST and no body, and reads anything other than 402 as a row that sells
// nothing. Answering that probe with a 400 is why this route stayed
// unlistable while quoting a spec-valid 402 to real buyers. The probe now
// gets the challenge, priced at the catalog's example chain (the same amount
// /.well-known/x402.json and /openapi.json advertise for this route), and the
// validation error is re-raised below for any caller that crosses the paywall.
let plan = null;
let planError = null;
try {
const bodyObj = rawBody ? JSON.parse(rawBody) : {};
plan = parsePlan(bodyObj);
} catch (err) {
planError = err.status
? { status: err.status, code: err.code, message: err.message }
: { status: 400, code: 'invalid_json', message: 'Request body must be valid JSON.' };
}
// The 402 quote is the EXACT sum of the requested stages' prices; an
// unpriceable probe body quotes the catalog's example chain instead.
const price = priceForChain(plan ? plan.stages : INPUT_EXAMPLE.stages);
const resourceUrl = resolveResourceUrl(req, ROUTE);
const requirements = buildRequirements(resourceUrl, price.atomics);
const service = withService({
serviceName: 'three.ws 3D Asset Pipeline',
tags: ['3d', 'pipeline', 'rig', 'gameready', 'glb'],
});
const challenge = {
resourceUrl,
accepts: requirements,
description: ROUTE_DESCRIPTION,
bazaar: bazaarFor(),
extensions: { [PAYMENT_IDENTIFIER]: paymentIdentifierExtension(false) },
serviceName: service.serviceName,
tags: service.tags,
iconUrl: service.iconUrl,
};
// Internal / subscription / OAuth callers bypass payment.
const acResult = await accessControl(req, routeConfig);
if (acResult?.abort) {
if (acResult.headers) for (const [k, v] of Object.entries(acResult.headers)) res.setHeader(k, v);
return error(res, acResult.status || 403, acResult.code || 'access_denied', acResult.reason || 'access denied');
}
const bypass = Boolean(acResult?.grantAccess);
const paymentHeader = req.headers['x-payment'] || req.headers['payment-signature'];
if (!bypass && !paymentHeader) return send402(res, challenge);
// Past the paywall with a body we could not turn into a plan: answer the
// validation error it earned. Nothing settles, because nothing ran.
if (planError) return error(res, planError.status, planError.code, planError.message);
// Guard the input GLB against SSRF before any lane fetches it.
if (plan.glbUrl) {
try {
await assertSafePublicUrl(plan.glbUrl);
} catch {
return error(res, 400, 'invalid_glb_url', 'glb_url must resolve to a public host.');
}
}
// Idempotency: a retried payment (same id, same body) returns the SAME job
// token instead of launching a second pipeline and double-charging.
let paymentId = null;
let payloadHash = null;
let paymentHash = null;
let ownsReservation = false;
if (!bypass) {
const clientPaymentId = extractIdFromHeader(paymentHeader);
payloadHash = hashRequestPayload({ method: 'POST', url: ROUTE, body: rawBody });
paymentHash = hashPaymentProof(paymentHeader);
paymentId = clientPaymentId || (paymentHash ? `proof:${paymentHash}` : null);
if (paymentId) {
const lookup = await checkCache({ route: ROUTE, paymentId, payloadHash, paymentHash });
if (lookup.kind === 'hit') return writeCachedResponse(res, lookup.entry);
if (lookup.kind === 'conflict') {
return writeConflict(res, {
route: ROUTE,
attemptedHash: lookup.attemptedHash,
existingHash: lookup.existingHash,
reason: lookup.reason,
});
}
// Close the check-then-act window: N concurrent requests carrying the
// same payment could all miss the cache, all launch a pipeline, and
// all settle before the first response was stored. The NX claim
// admits exactly one; the rest are answered inside claimSlotOrRespond.
ownsReservation = await claimSlotOrRespond({ res, route: ROUTE, paymentId, payloadHash, paymentHash });
if (!ownsReservation) return;
}
}
let verified;
if (!bypass) {
try {
verified = await verifyPayment({ paymentHeader, requirements });
} catch (err) {
if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
if (err.status === 402) return send402(res, { ...challenge, error: err.message });
return error(res, err.status || 502, err.code || 'verify_failed', err.message);
}
}
// Submit the FIRST stage AFTER verify but BEFORE settle so a dead first lane
// never charges. A throw here means no settlement ran → the buyer isn't billed.
const firstStageInput = plan.stages[0] === 'generate' ? null : plan.glbUrl;
let firstHandle;
try {
firstHandle = await submitStage(plan.stages[0], {
prompt: plan.prompt,
glbUrl: firstStageInput,
options: plan.options,
});
} catch (err) {
if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
return respondStageError(res, err);
}
if (!bypass) {
let settled;
try {
settled = await settlePayment({ verified });
} catch (err) {
if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
return error(res, err.status || 502, err.code || 'settle_failed', err.message);
}
res.setHeader('x-payment-response', encodePaymentResponseHeader(settled));
} else {
res.setHeader('x-payment-bypass', acResult.reason || 'granted');
}
// Persist the job record with the first stage's result already applied, so the
// very first free poll shows real progress.
const job = await createPipelineJob({
stages: plan.stages,
prompt: plan.prompt,
glbUrl: plan.glbUrl,
options: plan.options,
priceUsdc: price.usdc,
priceAtomics: price.atomics,
network: env.X402_PAY_TO_SOLANA ? NETWORK_SOLANA_MAINNET : NETWORK_BASE_MAINNET,
});
if (!job) {
if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
return error(
res,
503,
'store_unavailable',
'The pipeline job store is unavailable on this deployment. Set UPSTASH_REDIS_REST_URL to enable multi-stage jobs.',
);
}
applyFirstHandle(job, firstHandle);
await savePipelineJob(job);
const token = encodeJobToken({ provider: 'pipeline', kind: null, taskId: job.id });
const view = publicView(job);
const body = JSON.stringify({
...view,
job_token: token,
poll_url: `/api/forge?job=${encodeURIComponent(token)}`,
price_usdc: price.usdc,
result_glb_url: job.result_glb_url,
});
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', 'application/json; charset=utf-8');
res.end(body);
if (!bypass && paymentId) {
await storeResponse({
route: ROUTE,
paymentId,
payloadHash,
paymentHash,
status: 200,
body,
contentType: 'application/json; charset=utf-8',
paymentResponseHeader: res.getHeader('x-payment-response') || null,
});
}
});
// Apply the pre-settlement first-stage submit result onto the fresh job record.
function applyFirstHandle(job, handle) {
const stage = job.stages[0];
stage.started_at = new Date().toISOString();
if (handle.done && handle.glbUrl) {
stage.status = 'done';
stage.finished_at = new Date().toISOString();
stage.output_url = handle.glbUrl;
job.result_glb_url = handle.glbUrl;
job.status = job.stages.length === 1 ? 'done' : 'running';
} else {
stage.status = 'running';
stage.handle = handle;
job.status = 'running';
}
}
// Map a first-stage submit failure onto an HTTP response. Because submit runs
// before settle, the payment was never taken — say so plainly. Provider detail
// (vendor billing/credit strings, task ids) is masked to neutral copy.
function respondStageError(res, err) {
if (err?.status === 429 || err?.code === 'rate_limited') {
const retryAfter = Number.isFinite(err?.retryAfter) && err.retryAfter > 0 ? Math.ceil(err.retryAfter) : 5;
res.setHeader('retry-after', String(retryAfter));
return error(res, 429, 'rate_limited', 'The first stage is briefly busy and your payment was not taken — retry in a few seconds.', { retry_after: retryAfter });
}
if (err?.status === 501 || err?.code === 'stage_unconfigured') {
return error(res, 503, 'stage_unavailable', `That stage is not available right now and your payment was not taken. Available stages: ${availableStages().join(', ') || '(none)'}.`);
}
const status = err?.status || 502;
if (status >= 500) {
console.warn(`[x402/pipeline] first stage failed (${status}): ${err?.message || err}`);
return error(res, status, err?.code || 'stage_failed', 'The pipeline could not start and your payment was not taken — please retry shortly.');
}
return error(res, status, err?.code || 'stage_failed', err?.message);
}