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
// GET /api/x402/model-check?url=<glb-or-gltf>
//
// DEPRECATED: model inspection is now FREE at GET/POST /api/3d/inspect
// (api/3d/inspect.js). Prefer that endpoint. The 2026-07 overhaul (prompt 20)
// kept this route cataloged as a paid convenience alongside the free one.
//
// Paid endpoint cataloged by the CDP x402 Bazaar (agentic.market) and the
// pay-skills registry. For $0.001 USDC the server fetches the model bytes, runs
// the glTF-Transform inspector, and returns structural stats + optimization
// hints. Buyers pay programmatically with @x402/fetch — no API keys.
//
// Networks: Base mainnet (EIP-3009 + Permit2 sibling) and Solana mainnet
// (USDC). verifyPayment / settlePayment in x402-spec.js routes per-network:
// Base via X402_FACILITATOR_URL_BASE (CDP when configured, else PayAI) and
// Solana via X402_FACILITATOR_URL_SOLANA (PayAI). The Solana entry is omitted
// when X402_PAY_TO_SOLANA is unset so the 402 challenge stays valid.
//
// Stays alive even when CDP creds are absent — the 402 challenge still emits
// a proper bazaar discovery extension so the catalog can index this endpoint.
import { wrap, cors, error } from '../_lib/http.js';
import {
send402,
verifyPayment,
settlePayment,
encodePaymentResponseHeader,
buildExactRequirements,
resolveResourceUrl,
buildBazaarSchema,
} from '../_lib/x402-spec.js';
import { inspectModel, suggestOptimizations } from '../_lib/model-inspect.js';
import {
assertSafePublicUrl,
fetchSafePublicUrlPinned,
MaxBytesExceededError,
SsrfBlockedError,
} from '../_lib/ssrf-guard.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';
const REQUIRED_SCOPE = 'x402:bypass';
const accessControl = installAccessControl({ requiredScope: REQUIRED_SCOPE });
const routeConfig = { path: '/api/x402/model-check', method: 'GET', requiredScope: REQUIRED_SCOPE };
const ROUTE = '/api/x402/model-check';
const MAX_FETCH_BYTES = 16 * 1024 * 1024;
const ROUTE_DESCRIPTION =
'three.ws — agent-first 3D platform: drag-and-drop glTF/GLB preview plus model ' +
'validation, inspection, and optimization, with Solana agent data, all reachable ' +
'as MCP tools or pay-per-call x402 endpoints. This Model Check route fetches a ' +
'glTF/GLB model from a URL and returns structural stats (vertices, triangles, ' +
'materials, textures, animations, extensions) plus a prioritized list of ' +
'optimization recommendations. Pay-per-call in USDC on Solana mainnet.';
const DISCOVERY_INPUT_EXAMPLE = {
url: 'https://three.ws/avatars/mannequin.glb',
};
const DISCOVERY_INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['url'],
properties: {
url: {
type: 'string',
format: 'uri',
description:
'Public HTTPS URL of a glTF (.gltf) or binary glTF (.glb) model. Max 16 MiB.',
},
},
};
const DISCOVERY_OUTPUT_EXAMPLE = {
url: 'https://three.ws/avatars/mannequin.glb',
fetchedBytes: 1572864,
model: {
container: 'glb',
generator: 'three.ws CharacterStudio v1.5',
version: '2.0',
extensionsUsed: ['KHR_materials_unlit'],
extensionsRequired: [],
counts: {
scenes: 1,
nodes: 18,
meshes: 6,
materials: 4,
textures: 3,
animations: 1,
skins: 1,
totalVertices: 12480,
totalTriangles: 24812,
indexedPrimitives: 6,
nonIndexedPrimitives: 0,
},
},
suggestions: [
{
id: 'texture_size',
severity: 'info',
message: 'All textures are within 1024x1024 — good for mobile.',
},
],
};
const DISCOVERY_OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['url', 'fetchedBytes', 'model', 'suggestions'],
properties: {
url: { type: 'string', format: 'uri' },
fetchedBytes: { type: 'integer' },
model: {
type: 'object',
required: ['container', 'counts'],
properties: {
container: { type: 'string', enum: ['glb', 'gltf'] },
generator: { type: ['string', 'null'] },
version: { type: ['string', 'null'] },
extensionsUsed: { type: 'array', items: { type: 'string' } },
extensionsRequired: { type: 'array', items: { type: 'string' } },
counts: {
type: 'object',
properties: {
scenes: { type: 'integer' },
nodes: { type: 'integer' },
meshes: { type: 'integer' },
materials: { type: 'integer' },
textures: { type: 'integer' },
animations: { type: 'integer' },
skins: { type: 'integer' },
totalVertices: { type: 'integer' },
totalTriangles: { type: 'integer' },
indexedPrimitives: { type: 'integer' },
nonIndexedPrimitives: { type: 'integer' },
},
},
},
},
suggestions: {
type: 'array',
items: {
type: 'object',
required: ['id', 'severity', 'message'],
properties: {
id: { type: 'string' },
severity: { type: 'string', enum: ['info', 'warn', 'critical'] },
message: { type: 'string' },
estimate: { type: 'string' },
},
},
},
},
};
const ROUTE_BAZAAR = {
discoverable: true,
info: {
input: {
type: 'http',
method: 'GET',
queryParams: DISCOVERY_INPUT_EXAMPLE,
},
output: { type: 'json', example: DISCOVERY_OUTPUT_EXAMPLE },
},
schema: buildBazaarSchema({
method: 'GET',
queryParamsSchema: DISCOVERY_INPUT_SCHEMA,
outputSchema: DISCOVERY_OUTPUT_SCHEMA,
}),
};
function buildRequirements(resourceUrl) {
// Solana-first accepts, Base gated on baseSettleable() (CDP or opt-in) plus its
// gasless Permit2 sibling under CDP — see buildExactRequirements.
return buildExactRequirements(resourceUrl);
}
async function fetchAndInspect(targetUrl) {
let parsed;
try {
parsed = await assertSafePublicUrl(targetUrl, { allowHttp: true });
} catch (err) {
if (err instanceof SsrfBlockedError) {
const e = new Error(err.message);
e.code = 'invalid_url';
e.status = 400;
throw e;
}
throw err;
}
// Pinned fetch: each redirect hop is re-validated and the socket connects to
// the checked address, so a public URL that 302s (or rebinds) to an
// internal host is refused instead of followed. Bytes are capped in-stream.
let upstream;
try {
upstream = await fetchSafePublicUrlPinned(
parsed.toString(),
{
headers: { accept: 'model/gltf-binary,model/gltf+json,application/octet-stream' },
signal: AbortSignal.timeout(20_000),
},
{ allowHttp: true, maxBytes: MAX_FETCH_BYTES },
);
} catch (err) {
if (err instanceof SsrfBlockedError) {
const e = new Error(err.message);
e.code = 'invalid_url';
e.status = 400;
throw e;
}
if (err instanceof MaxBytesExceededError) {
const e = new Error(`model is ${err.observed} bytes; max is ${MAX_FETCH_BYTES}`);
e.code = 'too_large';
e.status = 413;
throw e;
}
const e = new Error(`could not fetch model: ${err.message}`);
e.code = 'fetch_failed';
e.status = 502;
throw e;
}
if (!upstream.ok) {
const err = new Error(`upstream returned ${upstream.status} ${upstream.statusText}`);
err.code = 'fetch_failed';
err.status = 502;
throw err;
}
const contentLength = Number(upstream.headers.get('content-length') || 0);
if (contentLength && contentLength > MAX_FETCH_BYTES) {
const err = new Error(`model is ${contentLength} bytes; max is ${MAX_FETCH_BYTES}`);
err.code = 'too_large';
err.status = 413;
throw err;
}
const buf = new Uint8Array(await upstream.arrayBuffer());
if (buf.byteLength > MAX_FETCH_BYTES) {
const err = new Error(`model is ${buf.byteLength} bytes; max is ${MAX_FETCH_BYTES}`);
err.code = 'too_large';
err.status = 413;
throw err;
}
let info;
try {
info = await inspectModel(buf, { fileSize: buf.byteLength });
} catch (err) {
const e = new Error(err.message || 'failed to parse model');
e.code = 'invalid_model';
e.status = 422;
throw e;
}
return {
url: parsed.toString(),
fetchedBytes: buf.byteLength,
model: info,
suggestions: suggestOptimizations(info),
};
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (req.method !== 'GET') {
res.setHeader('allow', 'GET');
return error(res, 405, 'method_not_allowed', 'use GET');
}
const resourceUrl = resolveResourceUrl(req, ROUTE);
const requirements = buildRequirements(resourceUrl);
const service = withService({
serviceName: 'three.ws Model Check',
tags: ['3d', 'gltf', 'glb', 'inspection', 'validation'],
});
const challenge = {
resourceUrl,
accepts: requirements,
description: ROUTE_DESCRIPTION,
bazaar: ROUTE_BAZAAR,
extensions: { [PAYMENT_IDENTIFIER]: paymentIdentifierExtension(false) },
serviceName: service.serviceName,
tags: service.tags,
iconUrl: service.iconUrl,
};
// USE-23: access-control hook short-circuits payment for internal /
// subscription / OAuth callers before we even read the X-PAYMENT header.
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',
);
}
if (acResult?.grantAccess) {
const target = String(req.query?.url || '').trim();
if (!target) return error(res, 400, 'missing_url', 'query param "url" is required');
let result;
try {
result = await fetchAndInspect(target);
} catch (err) {
return error(res, err.status || 500, err.code || 'internal_error', err.message);
}
if (acResult.headers) {
for (const [k, v] of Object.entries(acResult.headers)) res.setHeader(k, v);
}
res.setHeader('x-payment-bypass', acResult.reason || 'granted');
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', 'application/json; charset=utf-8');
res.end(JSON.stringify(result));
return;
}
const paymentHeader = req.headers['x-payment'] || req.headers['payment-signature'];
if (!paymentHeader) return send402(res, challenge);
// USE-15: idempotency cache lookup before paying for /verify.
const clientPaymentId = extractIdFromHeader(paymentHeader);
const payloadHash = hashRequestPayload({
method: req.method,
url: req.url,
body: null,
});
const paymentHash = hashPaymentProof(paymentHeader);
// Always-on replay guard: the payment-identifier extension is client-opt-in,
// so when the client omits it we fall back to the proof hash itself as the
// dedup key (reproducible only by the original payer), making replay
// protection unconditional. Same idiom as api/_lib/x402-paid-endpoint.js.
const paymentId = clientPaymentId || (paymentHash ? `proof:${paymentHash}` : null);
// Close the check-then-act window: N concurrent requests carrying the same
// payment could all miss the cache, all run the paid work, and all settle
// before the first response was stored. The NX claim admits exactly one;
// the rest are answered inside claimSlotOrRespond (replay/conflict/in-flight).
let ownsReservation = false;
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,
});
}
ownsReservation = await claimSlotOrRespond({ res, route: ROUTE, paymentId, payloadHash, paymentHash });
if (!ownsReservation) return;
}
let verified;
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);
}
const target = String(req.query?.url || '').trim();
if (!target) {
if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
return error(res, 400, 'missing_url', 'query param "url" is required');
}
let result;
try {
result = await fetchAndInspect(target);
} catch (err) {
if (ownsReservation) await releaseSlot({ route: ROUTE, paymentId });
return error(res, err.status || 500, err.code || 'internal_error', err.message);
}
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);
}
const paymentResponseHeader = encodePaymentResponseHeader(settled);
const contentType = 'application/json; charset=utf-8';
const body = JSON.stringify(result);
res.setHeader('x-payment-response', paymentResponseHeader);
res.setHeader('cache-control', 'no-store');
res.setHeader('content-type', contentType);
res.end(body);
if (paymentId) {
await storeResponse({
route: ROUTE,
paymentId,
payloadHash,
paymentHash,
status: 200,
body,
contentType,
paymentResponseHeader,
});
}
});