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/skill-call?skill=<slug>
//
// Per-call x402 gate for marketplace skills. Each priced skill in the
// marketplace_skills catalog charges `price_per_call_usd` per invocation. This
// endpoint meters that: a caller pays the skill's per-call price in USDC (Base
// or Solana) and receives the skill's executable payload — its tool schema and
// content — so the calling agent can run it. Settlement routes straight to the
// skill author's wallet, so authors earn per call.
//
// Unlike /api/x402/asset-download (buy-once, re-download free via SIWX), this
// is genuinely per-call: there is no SIWX re-access grant, so every invocation
// is a fresh payment. That matches the per-call pricing model the catalog
// advertises and the royalty semantics in api/_lib/skill-runtime.js.
//
// Built per-request like asset-download: the slug selects the row, which
// dictates price + author payout; everything else is shared. Free skills
// (price_per_call_usd = 0) are rejected with 409 — fetch those for free via
// /api/skills/:id.
import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema, paymentRequirements, send402 } from '../_lib/x402-spec.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { priceFor } from '../_lib/x402-prices.js';
import { sql } from '../_lib/db.js';
import { cors, error, respondError } from '../_lib/http.js';
import { env } from '../_lib/env.js';
import { enabledRails, railEnabled } from '../_lib/skill-rails.js';
import { accrueSkillCallRoyalty } from '../_lib/skill-royalty.js';
import skillCallListing from '../_lib/service-catalog/services/skill-call.js';
const ROUTE = '/api/x402/skill-call';
// Single source of truth: api/_lib/service-catalog/services/skill-call.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 = skillCallListing.description;
const INPUT_EXAMPLE = { skill: 'wallet-balance' };
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['skill'],
properties: {
skill: {
type: 'string',
description: 'Unique skill slug from the marketplace_skills catalog.',
minLength: 1,
maxLength: 128,
},
},
};
const OUTPUT_EXAMPLE = {
ok: true,
skill: {
id: 'fc504e4a-6667-4757-9157-2bcc35434e6c',
slug: 'wallet-balance',
name: 'Wallet Balance',
description: 'Check ETH and ERC-20 token balances for any Ethereum address.',
category: 'crypto',
},
tools: [{ type: 'function', function: { name: 'get_balance', description: 'Fetch balances.' } }],
content: '# Wallet Balance\n\nUse get_balance to fetch ...',
calledAt: '2026-05-31T18:48:09.000Z',
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['ok', 'skill', 'calledAt'],
properties: {
ok: { type: 'boolean', const: true },
skill: {
type: 'object',
required: ['id', 'slug', 'name'],
properties: {
id: { type: 'string' },
slug: { type: 'string' },
name: { type: 'string' },
description: { type: 'string' },
category: { type: 'string' },
},
},
tools: { type: 'array', items: { type: 'object' } },
content: { type: 'string' },
calledAt: { type: 'string', format: 'date-time' },
},
};
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,
}),
};
// Load the priced skill row plus the author's primary payout wallets. A skill
// with no author (system seed) or no linked wallet falls back to the platform
// receiver via env — the call still works, the platform collects.
async function loadSkill(slug) {
const rows = await sql`
SELECT ms.id, ms.slug, ms.name, ms.description, ms.category, ms.rails,
ms.schema_json, ms.content, ms.price_per_call_usd, ms.author_id,
evm.address AS author_payto_base,
sol.address AS author_payto_solana
FROM marketplace_skills ms
LEFT JOIN user_wallets evm
ON evm.user_id = ms.author_id
AND evm.chain_type = 'evm' AND evm.is_primary = true
LEFT JOIN user_wallets sol
ON sol.user_id = ms.author_id
AND sol.chain_type = 'solana' AND sol.is_primary = true
WHERE ms.slug = ${slug} AND ms.is_public = true
LIMIT 1
`;
return rows[0] || null;
}
// USD (price_per_call_usd) → USDC atomics (6 decimals). Floor at 1 atomic so a
// priced skill can never be free; the no-payment 0-price case is handled before
// we ever reach this.
function usdToAtomics(usd) {
return String(Math.max(1, Math.round(Number(usd) * 1_000_000)));
}
// Discovery probes (x402scan registration, Bazaar validators) hit the bare
// route with no ?skill= and expect a valid 402 challenge, not a 400. Without
// a slug there is no per-skill price, so this advertises the endpoint at a
// representative default (env-overridable via X402_PRICE_SKILL_CALL — the
// per-skill env slugs are `skill-call-<slug>`, so the bare slug is free for
// this) with the full bazaar schema. No money can settle against it: a paid
// retry still needs ?skill=<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('skill-call', '10000') }),
description: DESCRIPTION,
bazaar: BAZAAR,
error: errText,
serviceName: 'three.ws Skill Call',
tags: ['skill', 'agent', 'tool', 'pay-per-call'],
});
}
export default async function handler(req, res) {
// paidEndpoint answers CORS itself, but every branch below can respond BEFORE
// one is built (discovery challenge, unknown slug, free skill), and an
// X-PAYMENT header always triggers a preflight. Without this the preflight was
// answered with a bare 402 and no allow-origin, so no browser wallet could pay.
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
const slug = req.query?.skill ? String(req.query.skill).trim() : '';
const paymentPresent = Boolean(req.headers['x-payment'] || req.headers['payment-signature']);
if (!slug) {
if (paymentPresent) {
return error(res, 400, 'skill_required', 'query parameter "skill" is required');
}
return sendDiscoveryChallenge(
res,
'query parameter "skill" is required — retry with ?skill=<slug> from the marketplace catalog for that skill’s exact price',
);
}
let skill;
try {
skill = await loadSkill(slug);
} catch (err) {
// respondError, not error(): a 5xx must not echo the driver's own message
// back to a buyer (the DB outage path answered "Missing required env var:
// DATABASE_URL"). It sanitizes and hands back a support ref instead.
return respondError(res, 502, 'skill_lookup_failed', err);
}
if (!skill) {
if (paymentPresent) {
return error(res, 404, 'skill_not_found', `no public skill with slug "${slug}"`);
}
return sendDiscoveryChallenge(
res,
`no public skill with slug "${slug}" — browse /api/skills for available slugs`,
);
}
if (!(Number(skill.price_per_call_usd) > 0)) {
return error(
res,
409,
'skill_not_priced',
`skill "${slug}" is free — fetch it without payment via /api/skills/${skill.id}`,
);
}
if (!railEnabled(skill, 'x402')) {
return error(res, 404, 'rail_disabled', `the x402 rail is not enabled for skill "${slug}"`, {
enabled_rails: enabledRails(skill),
});
}
// Author payout overrides. Only set a network when the author has a wallet
// for it; missing networks fall back to the platform receiver in env so the
// endpoint still settles. Advertise only the networks we can actually route.
const payTo = {};
if (skill.author_payto_base) payTo.base = skill.author_payto_base;
if (skill.author_payto_solana) payTo.solana = skill.author_payto_solana;
// Solana-first platform default: advertise Solana ahead of Base so
// first-accept clients settle on Solana when the author supports both.
const networks = [];
if (payTo.solana) networks.push('solana');
if (payTo.base) networks.push('base');
if (!networks.length) networks.push('solana', 'base'); // platform fallback
const priceAtomics = priceFor(`skill-call-${slug}`, usdToAtomics(skill.price_per_call_usd));
const inner = paidEndpoint({
route: ROUTE,
method: 'GET',
priceAtomics,
networks,
description: `${DESCRIPTION} — currently metering: ${skill.name}.`,
mimeType: 'application/json',
bazaar: BAZAAR,
service: withService({
serviceName: 'three.ws Skill Call',
tags: ['skill', 'agent', 'tool', 'pay-per-call'],
}),
payTo: Object.keys(payTo).length ? payTo : undefined,
// Roadmap phase 3: per-call author royalties. After settlement lands,
// record the author's share (price minus the platform bps) on
// royalty_ledger with the rail's tx as provenance. Fire-and-forget by
// contract of onSettled; an accrual failure never breaks the response.
onSettled: skill.author_id
? ({ payer, network, txHash, amountAtomics }) =>
accrueSkillCallRoyalty({
skillId: skill.id,
authorId: skill.author_id,
payer,
network,
txHash,
priceAtomics: amountAtomics ?? priceAtomics,
})
: undefined,
// Per-call resource key so payment-identifier idempotency and audit logs
// attribute to the specific skill being called.
resourceUrlBuilder: () => `${env.APP_ORIGIN}${ROUTE}?skill=${encodeURIComponent(skill.slug)}`,
async handler() {
return {
ok: true,
skill: {
id: skill.id,
slug: skill.slug,
name: skill.name,
description: skill.description ?? '',
category: skill.category ?? 'general',
},
tools: Array.isArray(skill.schema_json) ? skill.schema_json : [],
content: skill.content ?? '',
calledAt: new Date().toISOString(),
};
},
});
return inner(req, res);
}