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
// INTERNAL-USE ONLY; not an agent product. De-listed from the x402 discovery
// catalog (api/wk.js) in the 2026-07 overhaul: the /club stage and the Saloon Kid NPC in the /play town buy performances through it.
// The route stays live for those consumers; do not re-add it to the catalog.
// GET /api/x402/dance-tip?dancer=<id>&dance=<style>
//
// Paid endpoint cataloged by the CDP x402 Bazaar. For $0.001 USDC the caller
// books one dance performance on the three.ws club stage. The /club page
// uses this from the browser via window.X402.pay — when the payment settles,
// the named dancer steps onto the stage and performs the requested style for
// a fixed duration. Agents can also call it programmatically with @x402/fetch
// to drive scripted performances.
//
// Two style shapes are exposed:
// • single-clip styles → { clip, label, loop, durationSec, track }
// • sequence styles → { sequence: [{ clip, durationSec }, …], label, durationSec, track }
// The settled ticket includes `sequence` when applicable so the /club page
// can chain crossfades; `clip` is always populated (sequence styles surface
// the first step's clip there for legacy single-clip consumers and for the
// club_tips ledger column).
import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema } from '../_lib/x402-spec.js';
import { installAccessControl } from '../_lib/x402/access-control.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { sql } from '../_lib/db.js';
import { priceFor } from '../_lib/x402-prices.js';
import { STYLES } from '../_lib/club/styles.js';
const ROUTE = '/api/x402/dance-tip';
const DESCRIPTION =
'three.ws club stage — tip a dancer to perform one routine on the 3D ' +
'stage. Pay $0.001 USDC per performance. Pick a dancer slot (1-4) and a ' +
'dance style (free-floor: rumba, silly, thriller, capoeira, hiphop, ' +
'offabean; pole work: twerk; choreographed routines: spin, climb, combo). The settled ' +
'call returns a performance ticket the /club page consumes to spawn the ' +
'dancer and play the routine — sequence styles chain multiple clips ' +
'back-to-back, and pole styles turn her into the pole.';
export { STYLES };
const VALID_DANCERS = new Set(['1', '2', '3', '4']);
const INPUT_EXAMPLE = { dancer: '1', dance: 'rumba' };
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['dancer', 'dance'],
properties: {
dancer: {
type: 'string',
enum: ['1', '2', '3', '4'],
description: 'Stage slot 1-4 — which dancer takes the stage.',
},
dance: {
type: 'string',
enum: Object.keys(STYLES),
description:
'Performance style. Free-floor styles map to a single clip in ' +
'/animations/manifest.json. Sequence styles (spin, climb, combo) ' +
'chain multiple manifest clips back-to-back.',
},
},
};
const OUTPUT_EXAMPLE = {
ok: true,
ticketId: 'a3f3d6c2-1f1b-4f10-9b6c-1b1f5e0c9c34',
dancer: '1',
dance: 'spin',
clip: 'capoeira',
label: 'Spin',
loop: false,
durationSec: 10,
track: 'pole',
sequence: [
{ clip: 'capoeira', durationSec: 6 },
{ clip: 'dance', durationSec: 4 },
],
startsAt: '2026-05-21T18:42:09.000Z',
endsAt: '2026-05-21T18:42:19.000Z',
payer: 'wwwPqsM4N7T9J69tB82nLyzxqsH159j4orftLTQfUGV',
network: 'solana',
amountAtomics: '1000',
asset: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['ok', 'ticketId', 'dancer', 'dance', 'clip', 'durationSec', 'startsAt', 'endsAt', 'track'],
properties: {
ok: { type: 'boolean', const: true },
ticketId: { type: 'string', format: 'uuid' },
dancer: { type: 'string', enum: ['1', '2', '3', '4'] },
dance: { type: 'string', enum: Object.keys(STYLES) },
clip: { type: 'string' },
label: { type: 'string' },
loop: { type: 'boolean' },
pole: {
type: 'boolean',
description:
'Present and true for pole styles (twerk). Tells the /club stage to ' +
'turn the dancer into the pole, back to the crowd, instead of facing out.',
},
durationSec: { type: 'integer', minimum: 1, maximum: 60 },
track: {
type: 'string',
enum: ['rumba', 'silly', 'thriller', 'capoeira', 'hiphop', 'pole', 'im-in-love-wit-a-stripper-fast'],
description: 'Audio loop name — /public/club/audio/<track>.{ogg,mp3}.',
},
sequence: {
type: 'array',
description:
'Present for sequence styles (spin, climb, combo). Each step is a ' +
'clip name + duration in seconds; the /club page crossfades them in order.',
items: {
type: 'object',
required: ['clip', 'durationSec'],
properties: {
clip: { type: 'string' },
durationSec: { type: 'number', minimum: 0.1, maximum: 60 },
},
},
},
startsAt: { type: 'string', format: 'date-time' },
endsAt: { type: 'string', format: 'date-time' },
payer: { type: ['string', 'null'] },
network: { type: ['string', 'null'] },
amountAtomics: { type: ['string', 'null'] },
asset: { type: ['string', 'null'] },
},
};
const BAZAAR = {
// De-listed per the 2026-07-08 storefront cleanup (prompt 18) — the route
// stays live for /club + the Saloon Kid NPC, but the flag itself (not just
// wk.js's catalog omission) now matches the "internal-use only" header above.
discoverable: false,
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,
}),
};
/**
* Resolve a raw `dance` query value to a normalized style descriptor.
* Throws `Error` with status=400 / code='unknown_dance' when the style is
* not registered.
*
* For sequence styles, `clip` is the first step's clip (so single-clip
* consumers — and the `club_tips.clip` column — still have something
* meaningful) and `sequence` is the chain.
*/
export function pickStyle(name) {
const key = String(name || '').trim().toLowerCase();
const style = STYLES[key];
if (!style) {
const err = new Error(
`unknown dance "${name}". Pick one of: ${Object.keys(STYLES).join(', ')}.`,
);
err.status = 400;
err.code = 'unknown_dance';
throw err;
}
const firstClip = style.clip ?? style.sequence?.[0]?.clip ?? null;
return {
key,
label: style.label,
durationSec: style.durationSec,
track: style.track,
clip: firstClip,
loop: style.loop ?? false,
pole: style.pole ?? false,
sequence: style.sequence,
};
}
/**
* Validate a `dancer` query value against the stage slot allowlist.
* Throws `Error` with status=400 / code='unknown_dancer'.
*/
export function pickDancer(raw) {
const id = String(raw ?? '').trim();
if (VALID_DANCERS.has(id)) return id;
const err = new Error(`dancer must be one of 1, 2, 3, 4 — got "${raw}"`);
err.status = 400;
err.code = 'unknown_dancer';
throw err;
}
/**
* Build the ticket body returned on a settled tip. Pure — no I/O. Exported
* so tests can exercise the full ticket shape without going through the
* paidEndpoint HTTP wrapper.
*/
export function buildTicket({ dancer, style, now = new Date(), payer = null, requirement = null, ticketId = null }) {
const ends = new Date(now.getTime() + style.durationSec * 1000);
const ticket = {
ok: true,
ticketId: ticketId ?? crypto.randomUUID(),
dancer,
dance: style.key,
clip: style.clip,
label: style.label,
loop: style.loop,
durationSec: style.durationSec,
track: style.track,
startsAt: now.toISOString(),
endsAt: ends.toISOString(),
payer,
network: requirement?.network ?? null,
amountAtomics: requirement?.amount ?? null,
asset: requirement?.asset ?? null,
};
if (style.pole) ticket.pole = true;
if (style.sequence) ticket.sequence = style.sequence;
return ticket;
}
export const BAZAAR_SCHEMA = BAZAAR;
export default paidEndpoint({
route: ROUTE,
method: 'GET',
priceAtomics: priceFor('dance-tip', '1000'),
networks: ['solana'],
description: DESCRIPTION,
bazaar: BAZAAR,
service: withService({
serviceName: 'three.ws Club Stage',
tags: ['3d', 'dance', 'club', 'tip', 'entertainment'],
}),
requiredScope: 'x402:bypass',
accessControl: installAccessControl({ requiredScope: 'x402:bypass' }),
siwx: {
statement: 'Sign in to retrigger a dance you already tipped for.',
// Permanent grant — once a wallet has tipped on this endpoint, it can
// retrigger any (dancer, dance) combo for free. The ticket itself is
// still per-performance (new ticketId each call); SIWX only skips the
// payment step, the handler still issues a fresh ticket each call.
ttlSeconds: null,
expirationSeconds: 300,
},
async handler({ req, requirement, payer, bypass }) {
const dancer = pickDancer(req.query?.dancer);
const style = pickStyle(req.query?.dance);
const ticketId = crypto.randomUUID();
const now = new Date();
// Bypass callers don't carry a paid `requirement`; mark the ticket so the
// club_tips ledger + live feed can distinguish free passes from real tips.
const ticket = buildTicket({
dancer,
style,
now,
ticketId,
payer: payer ?? (bypass ? bypass.callerId : null),
requirement,
});
if (bypass) ticket.bypass = bypass.reason;
// Fire-and-forget: the caller has already paid + the payment is settled
// by the time we reach this handler. A Neon hiccup must not surface as
// a 5xx on the dance-tip response — the /api/club/tips backfill will
// recover from a missing row at worst. Sequence steps aren't persisted
// — they're deterministic from `dance` + STYLES — but `clip` holds the
// first step's clip so the live-feed UI has something to display.
sql`
insert into club_tips
(ticket_id, dancer, dance, clip, label, payer, network,
amount_atomics, asset, started_at, ends_at)
values
(${ticketId}, ${ticket.dancer}, ${ticket.dance}, ${ticket.clip}, ${ticket.label},
${ticket.payer}, ${ticket.network},
${ticket.amountAtomics}, ${ticket.asset},
${ticket.startsAt}, ${ticket.endsAt})
on conflict (ticket_id) do nothing
`.catch((err) => console.error('[club-tips] insert failed', err?.message || err));
return ticket;
},
});