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
// Agent Payment Session API: create, inspect, and cancel payment sessions.
//
// A PaymentSession is a platform-managed spend envelope: developer funds a
// budget from their credits, receives a bearer token, and hands it to an agent.
// The agent spends against the session budget by calling /api/pay/execute, with
// no private key required. The platform's wallet signs the x402 transactions.
//
// POST /api/pay/session create a new session
// GET /api/pay/session/:id inspect a session (owner only)
// PATCH /api/pay/session/:id update label / allowlist / per-tx cap
// DELETE /api/pay/session/:id cancel + refund un-spent budget
// GET /api/pay/session/:id/executions list payments made in a session
// GET /api/pay/session list all sessions for the caller
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import { cors, error, json, method, readJson, wrap, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import {
createPaymentSession,
getPaymentSession,
listPaymentSessions,
cancelPaymentSession,
updatePaymentSession,
listSessionExecutions,
getPaymentStats,
} from '../_lib/pay/payment-session.js';
import { isSessionId } from '../_lib/pay/spend-governor.js';
async function resolveUser(req, res) {
const session = await getSessionUser(req, res);
if (session) return session;
// Creating or widening a session moves credits into a spend envelope that
// pays arbitrary x402 hosts, so a bearer needs wallet:write to write here.
const bearer = assertBearerMaySpend(await authenticateBearer(extractBearer(req)), req);
if (bearer) return { id: bearer.userId };
return null;
}
// Extract :id and :sub from URL path
function parsePath(req) {
const path = new URL(req.url, 'http://x').pathname;
// /api/pay/session/:id or /api/pay/session/:id/executions
const m = path.match(/\/api\/pay\/session\/([^/]+)(?:\/([^/]+))?/);
return m ? { id: m[1], sub: m[2] ?? null } : { id: null, sub: null };
}
/**
* Read a JSON object body, answering the caller when it is not one.
*
* readJson's second parameter is a byte limit, not the response: passing `res`
* there turned every `length > [object]` comparison into false and silently
* disabled the 1 MB cap. Returning `null` on a non-object body (rather than
* letting the caller return without writing a response) also closes the path
* where a request would hang instead of getting an answer.
*/
async function readJsonObject(req, res) {
const body = await readJson(req);
if (!body || typeof body !== 'object') {
error(res, 400, 'invalid_body', 'a JSON object body is required');
return null;
}
return body;
}
/**
* Read `limit` and `cursor` off the query string, clamped to values the SQL can
* actually take. Both reach Postgres verbatim otherwise: a negative limit
* becomes `LIMIT -4` and a non-date cursor becomes a timestamptz cast error, and
* either one turns a caller's typo into a 500.
*/
function parsePagination(req) {
const url = new URL(req.url, 'http://x');
const rawLimit = Number(url.searchParams.get('limit'));
const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(Math.floor(rawLimit), 100) : 20;
const rawCursor = url.searchParams.get('cursor');
const cursor = rawCursor && Number.isFinite(Date.parse(rawCursor)) ? rawCursor : null;
return { limit, cursor, cursorRejected: Boolean(rawCursor) && cursor === null };
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,PATCH,DELETE,OPTIONS', credentials: true })) return;
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const user = await resolveUser(req, res);
if (!user) return error(res, 401, 'unauthorized', 'authentication required');
const { id, sub } = parsePath(req);
const httpMethod = req.method?.toUpperCase();
// POST /api/pay/session: create
if (!id && httpMethod === 'POST') {
if (!method(req, res, ['POST'])) return;
const body = await readJsonObject(req, res);
if (!body) return;
let result;
try {
result = await createPaymentSession({
userId: user.id,
agentId: body.agent_id ?? null,
label: body.label,
budgetUsd: body.budget_usd,
maxPerTxUsd: body.max_per_tx_usd ?? null,
allowedHosts: body.allowed_hosts ?? [],
blockedHosts: body.blocked_hosts ?? [],
approvalThresholdUsd: body.approval_threshold_usd ?? null,
perRailDailyUsd: body.per_rail_daily_usd ?? null,
network: body.network ?? 'solana',
expirySeconds: body.expiry_seconds ?? 3600,
metadata: body.metadata ?? {},
});
} catch (err) {
if (err.code === 'insufficient_credits') {
return error(res, 402, 'insufficient_credits',
`Insufficient credits: need $${err.required_usd?.toFixed(4)}, have $${err.available_usd?.toFixed(4)}`
);
}
if (err.status === 400 || err.code?.startsWith('invalid_')) {
return error(res, 400, err.code ?? 'bad_request', err.message);
}
throw err;
}
return json(res, 201, {
session: result.session,
token: result.token,
note: 'Store this token securely. It is shown once and cannot be recovered.',
});
}
// GET /api/pay/session: list all sessions
if (!id && httpMethod === 'GET') {
const url = new URL(req.url, 'http://x');
const status = url.searchParams.get('status') || null;
const { limit, cursor, cursorRejected } = parsePagination(req);
if (cursorRejected) {
return error(res, 400, 'invalid_cursor', 'cursor must be an ISO 8601 timestamp');
}
const [sessions, stats] = await Promise.all([
listPaymentSessions(user.id, { status, limit, cursor }),
getPaymentStats(user.id),
]);
return json(res, 200, { ...sessions, stats });
}
// The collection route only answers POST (create) and GET (list). Anything
// else is a method problem, not a missing-id problem, so say which.
if (!id) {
return error(
res,
405,
'method_not_allowed',
`${httpMethod} on the session collection is not supported. Use POST to create or GET to list.`,
);
}
// Every id lands in a `uuid` column comparison, where Postgres answers a
// malformed value with a cast error rather than "no rows". Rejecting the
// shape here is what keeps /api/pay/session/not-a-uuid a 404 and not a 500.
if (!isSessionId(id)) {
return error(res, 404, 'not_found', 'session not found');
}
// GET /api/pay/session/:id/executions
if (sub === 'executions' && httpMethod === 'GET') {
const session = await getPaymentSession(id, user.id);
if (!session) return error(res, 404, 'not_found', 'session not found');
const { limit, cursor, cursorRejected } = parsePagination(req);
if (cursorRejected) {
return error(res, 400, 'invalid_cursor', 'cursor must be an ISO 8601 timestamp');
}
const result = await listSessionExecutions(id, user.id, { limit, cursor });
return json(res, 200, result);
}
// GET /api/pay/session/:id
if (httpMethod === 'GET') {
const session = await getPaymentSession(id, user.id);
if (!session) return error(res, 404, 'not_found', 'session not found');
return json(res, 200, { session });
}
// PATCH /api/pay/session/:id: update mutable fields on an active session
if (httpMethod === 'PATCH') {
const body = await readJsonObject(req, res);
if (!body) return;
const updates = {};
if (typeof body.label === 'string') updates.label = body.label.trim();
if (Array.isArray(body.allowed_hosts)) updates.allowedHosts = body.allowed_hosts;
if (body.max_per_tx_usd !== undefined) updates.maxPerTxUsd = body.max_per_tx_usd;
if (Array.isArray(body.blocked_hosts)) updates.blockedHosts = body.blocked_hosts;
if (body.approval_threshold_usd !== undefined) updates.approvalThresholdUsd = body.approval_threshold_usd;
if (body.per_rail_daily_usd !== undefined) updates.perRailDailyUsd = body.per_rail_daily_usd;
if (Object.keys(updates).length === 0) {
return error(
res,
400,
'nothing_to_update',
'Provide at least one of: label, allowed_hosts, max_per_tx_usd, blocked_hosts, approval_threshold_usd, per_rail_daily_usd',
);
}
const result = await updatePaymentSession(id, user.id, updates);
if (!result) return error(res, 404, 'not_found', 'session not found, not active, or not owned by you');
return json(res, 200, { session: result });
}
// DELETE /api/pay/session/:id
if (httpMethod === 'DELETE') {
const result = await cancelPaymentSession(id, user.id);
if (!result) return error(res, 404, 'not_found', 'session not found or already closed');
return json(res, 200, {
cancelled: true,
session_id: id,
refunded_usd: result.refunded_usd,
});
}
return error(res, 405, 'method_not_allowed', `${httpMethod} not supported`);
});