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/asset-download?slug=<slug>
//
// Canonical "buy once, re-download forever" 3D-asset bazaar. A creator uploads
// a GLB / avatar / accessory to R2, prices it, and lists it in the paid_assets
// table. The first download is paid via x402 USDC (Base or Solana); every
// subsequent download from the same wallet is free via Sign-In-With-X (CAIP-122).
//
// The response is JSON with a short-lived presigned R2 URL — proxying the
// bytes through Vercel would blow past the function response-size limit on
// real GLBs. The client fetches the file directly from R2 with the URL.
import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema, paymentRequirements, send402 } from '../_lib/x402-spec.js';
import { priceFor } from '../_lib/x402-prices.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { sql } from '../_lib/db.js';
import { presignGet, getObjectBuffer } from '../_lib/r2.js';
import { cors, error } from '../_lib/http.js';
import { env } from '../_lib/env.js';
import assetDownloadListing from '../_lib/service-catalog/services/asset-download.js';
import { autoCredentialForBytes } from '../_lib/auto-provenance.js';
import { sha256Hex } from '../_lib/provenance-3d.js';
const ROUTE = '/api/x402/asset-download';
// Single source of truth: api/_lib/service-catalog/services/asset-download.js
// is the storefront listing copy — importing it here keeps the live 402
// challenge from drifting from what /.well-known/x402.json and the OKX
// projection advertise (same pattern as forge.js → forge-listing.js).
const DESCRIPTION = assetDownloadListing.description;
const INPUT_EXAMPLE = { slug: 'pole-dancer-rumba' };
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['slug'],
properties: {
slug: {
type: 'string',
description: 'Unique asset slug from the paid_assets catalog.',
minLength: 1,
maxLength: 128,
},
},
};
const OUTPUT_EXAMPLE = {
ok: true,
slug: 'pole-dancer-rumba',
title: 'Pole Dancer (Rumba)',
description: 'The default three.ws dancer rigged for the /club Rumba routine.',
mimeType: 'model/gltf-binary',
sizeBytes: 6_492_840,
expiresAt: '2026-05-21T18:48:09.000Z',
downloadUrl:
'https://three-ws-public.r2.dev/assets/pole-dancer-rumba.glb?X-Amz-Algorithm=...',
glbSha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b85',
verifyUrl: 'https://three.ws/api/provenance?hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b85',
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['ok', 'slug', 'title', 'mimeType', 'sizeBytes', 'downloadUrl', 'expiresAt'],
properties: {
ok: { type: 'boolean', const: true },
slug: { type: 'string' },
title: { type: 'string' },
description: { type: 'string' },
mimeType: { type: 'string' },
sizeBytes: { type: 'integer', minimum: 0 },
expiresAt: { type: 'string', format: 'date-time' },
downloadUrl: { type: 'string', format: 'uri' },
// Present for GLB assets once their free, signed content credential
// exists (work order 079): glbSha256 is the content hash the
// credential is signed over; verifyUrl checks it for free, with no
// account, wallet, or payment, against GET /api/provenance.
glbSha256: { type: 'string', pattern: '^[0-9a-f]{64}$' },
verifyUrl: { type: 'string', format: 'uri' },
},
};
const BAZAAR = {
discoverable: true,
info: {
input: { type: 'http', method: 'GET', queryParams: INPUT_EXAMPLE },
output: { type: 'json', example: OUTPUT_EXAMPLE },
},
schema: buildBazaarSchema({
method: 'GET',
queryParamsSchema: INPUT_SCHEMA,
outputSchema: OUTPUT_SCHEMA,
}),
};
// Presigned URL lifetime. Keep this short — once the buyer has the URL, R2
// will serve the file to anyone who holds it for the next N seconds. 60s is
// enough for any reasonable client to start the download; the URL becomes
// useless once the file finishes streaming.
const PRESIGN_TTL_SECONDS = 60;
async function loadAsset(slug) {
const rows = await sql`
SELECT id, slug, title, description, mime_type, size_bytes, r2_key,
price_atomics, creator_payto_base, creator_payto_solana,
creator_payto_bsc, glb_sha256
FROM paid_assets
WHERE slug = ${slug}
LIMIT 1
`;
return rows[0] || null;
}
// Every paid download carries a free, signed content credential by default
// (work order 079). The hash is cached on the row after the first download so
// a repeat buyer's re-download never re-fetches and re-hashes the full GLB
// just to answer "is this credentialed", only the first ever download pays
// that cost. Issuing the credential itself stays fire-and-forget (never
// delays the response the buyer is waiting on); the hash is awaited because
// it is needed for the verifyUrl in THIS response.
async function ensureAssetCredential(asset) {
if (asset.glb_sha256) return asset.glb_sha256;
if (asset.mime_type !== 'model/gltf-binary') return null; // credentials are GLB-specific
try {
const buffer = await getObjectBuffer(asset.r2_key);
if (!buffer?.length) return null;
const glbSha256 = sha256Hex(buffer);
autoCredentialForBytes({
buffer,
assetId: asset.id,
creator: null,
prompt: null,
model: asset.title,
provider: 'paid_assets',
}).catch(() => {});
sql`UPDATE paid_assets SET glb_sha256 = ${glbSha256} WHERE id = ${asset.id}`.catch(() => {});
return glbSha256;
} catch (err) {
console.warn('[asset-download] could not hash asset for a credential:', err?.message);
return null;
}
}
// Build the SIWX statement. EIP-4361 restricts the statement to a single line
// of RFC 3986 reserved/unreserved characters + space — double quotes, braces,
// backticks, etc. are illegal and make the official SIWX client (browser
// wallets and @x402/extensions alike) refuse to render a signable message. The
// asset title is catalog-controlled, so we strip anything outside that set and
// collapse whitespace rather than wrapping the title in quotes.
const SIWE_STATEMENT_DISALLOWED = /[^A-Za-z0-9\-._~:/?#[\]@!$&'()*+,;= ]+/g;
function buildSiwxStatement(title) {
const clean = String(title || '')
.replace(SIWE_STATEMENT_DISALLOWED, '')
.replace(/\s+/g, ' ')
.trim();
return clean
? `Sign in to re-download ${clean} without re-paying.`
: 'Sign in to re-download this asset without re-paying.';
}
function buildPayToOverride(asset) {
const out = {};
if (asset.creator_payto_base) out.base = asset.creator_payto_base;
if (asset.creator_payto_solana) out.solana = asset.creator_payto_solana;
if (asset.creator_payto_bsc) out.bsc = asset.creator_payto_bsc;
return Object.keys(out).length ? out : undefined;
}
// Discovery probes (x402scan registration, Bazaar validators) hit the bare
// route with no ?slug= and expect a valid 402 challenge, not a 400. Without a
// slug there is no per-asset price, so this advertises the endpoint at a
// representative default (env-overridable via X402_PRICE_ASSET_DOWNLOAD) with
// the full bazaar schema. No money can settle against it: a paid retry still
// needs ?slug=<slug> (the paymentPresent branches below keep their 400/404),
// and an X-PAYMENT envelope is only an authorization — USDC moves at settle,
// which this path never reaches.
function sendDiscoveryChallenge(res, errText) {
const resourceUrl = `${env.APP_ORIGIN}${ROUTE}`;
return send402(res, {
resourceUrl,
accepts: paymentRequirements(resourceUrl, { amount: priceFor('asset-download', '1000000') }),
description: DESCRIPTION,
bazaar: BAZAAR,
error: errText,
serviceName: 'three.ws Asset Bazaar',
tags: ['3d', 'asset', 'glb', 'avatar', 'download'],
});
}
// Per-asset paidEndpoint built on the fly. The slug picks the row, which
// dictates price + payout overrides + R2 key — everything else is shared.
export default async function handler(req, res) {
// Install CORS before anything else. Every other x402 handler gets this from
// paidEndpoint's own first step, but this file answers the discovery probe,
// the 400/404/502 errors and the free-listing 200 itself, long before it
// delegates. Without it the OPTIONS preflight fell through to the discovery
// challenge and returned a 402 with no Access-Control-Allow-Origin, so a
// browser x402 client (the drop-in modal, x402-fetch) could never read the
// challenge it is supposed to pay. Same options paidEndpoint uses for a GET
// route, so the delegated path below stays byte-identical.
if (cors(req, res, { methods: 'GET,HEAD,OPTIONS', origins: '*' })) return;
const slug = req.query?.slug ? String(req.query.slug).trim() : '';
const paymentPresent = Boolean(req.headers['x-payment'] || req.headers['payment-signature']);
if (!slug) {
if (paymentPresent) {
return error(res, 400, 'slug_required', 'query parameter "slug" is required');
}
return sendDiscoveryChallenge(
res,
'query parameter "slug" is required — retry with ?slug=<slug> from the paid_assets catalog for that asset’s exact price',
);
}
let asset;
try {
asset = await loadAsset(slug);
} catch (err) {
return error(res, 502, 'paid_assets_lookup_failed', err.message);
}
if (!asset) {
if (paymentPresent) {
return error(res, 404, 'asset_not_found', `no paid_assets row with slug "${slug}"`);
}
return sendDiscoveryChallenge(
res,
// Do not point callers at /api/assets: that is the free accessory,
// animation, and environment catalog and carries no paid_assets slug.
`no paid_assets row with slug "${slug}"`,
);
}
const inner = paidEndpoint({
route: ROUTE,
method: 'GET',
priceAtomics: String(asset.price_atomics),
description: `${DESCRIPTION} — currently delivering: ${asset.title}.`,
mimeType: 'application/json',
bazaar: BAZAAR,
service: withService({
serviceName: 'three.ws Asset Bazaar',
tags: ['3d', 'asset', 'glb', 'avatar', 'download'],
}),
payTo: buildPayToOverride(asset),
// Make the SIWX grant key per-asset by baking the slug into the
// resource URL. Without this, paying for any one asset would unlock
// every other asset via signature — the SIWX storage row is keyed on
// (resource, address) only. The 402 challenge advertises the same URL
// the client signs against, so verification stays consistent.
resourceUrlBuilder: () =>
`${env.APP_ORIGIN}${ROUTE}?slug=${encodeURIComponent(asset.slug)}`,
siwx: {
statement: buildSiwxStatement(asset.title),
// Permanent grant per (asset, wallet) — once a wallet has paid for
// this asset it can re-download forever by signing.
ttlSeconds: null,
expirationSeconds: 300,
},
async handler() {
const [url, glbSha256] = await Promise.all([
presignGet({ key: asset.r2_key, expiresIn: PRESIGN_TTL_SECONDS }),
ensureAssetCredential(asset),
]);
return {
ok: true,
slug: asset.slug,
title: asset.title,
description: asset.description,
mimeType: asset.mime_type,
sizeBytes: Number(asset.size_bytes),
expiresAt: new Date(Date.now() + PRESIGN_TTL_SECONDS * 1000).toISOString(),
downloadUrl: url,
...(glbSha256
? { glbSha256, verifyUrl: `${env.APP_ORIGIN}/api/provenance?hash=${glbSha256}` }
: {}),
};
},
});
return inner(req, res);
}