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
// POST /api/x402/three-buy
//
// The x402 micro-buy service: one settled payment → one small, real on-chain buy
// of $THREE. It is the high-frequency, small-ticket sibling of the daily buyback
// (api/cron/run-three-buyback) — where that lane deploys revenue in a few large
// buys per day, this lane fires many tiny buys per minute so the platform shows
// continuous, verifiable buy pressure on $THREE. Driven by api/cron/three-buy-loop.
//
// HOW IT SETTLES. The caller pays the small x402 toll (X402_PRICE_THREE_BUY, default
// $0.001) in USDC to the ring treasury (X402_PAY_TO_SOLANA), exactly like every
// other ring endpoint. The toll is NOT the buy funding — on a paid call the handler
// executes a separate USDC→$THREE swap funded by the micro-buy wallet
// (api/_lib/token/microbuy.js). Two independent, auditable money streams.
//
// BUY-ONLY. The service never sells $THREE. Bought tokens accrue in the micro-buy
// wallet and are swept to the treasury by the loop; there is no sell path.
//
// FAIL-CLOSED ON THE TOLL. The endpoint takes the toll ONLY when a buy actually
// broadcasts. When the engine is disabled, unfunded, or the UTC-daily cap is
// reached, the handler re-emits the 402 challenge (X402Error 402) so settlement
// never runs and the caller keeps their funds — the platform never charges a toll
// for a buy it didn't make. This also caps the amplification a direct payer could
// force: they can trigger buys only up to the same daily ceiling the loop obeys.
//
// discoverable:false — internal buy-pressure machinery, not an organic third-party
// service, so it is not advertised on the public x402 bazaar (same stance as
// ring-settle).
import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { buildBazaarSchema } from '../_lib/x402-spec.js';
import { X402Error } from '../_lib/x402-spec.js';
import { priceFor } from '../_lib/x402-prices.js';
import { sql } from '../_lib/db.js';
import { logger } from '../_lib/usage.js';
import { TOKEN_MINT } from '../_lib/token/config.js';
import {
isEnabled,
ensureMicrobuySchema,
hasDailyBudget,
loadMicrobuySigner,
planMicrobuy,
executeMicrobuy,
usdcAtomicsToUsd,
threeAtomicsToTokens,
} from '../_lib/token/microbuy.js';
const log = logger('x402-three-buy');
const ROUTE = '/api/x402/three-buy';
// Default $0.001 — a deliberately tiny toll: this endpoint's value is the on-chain
// buy it triggers, not the toll itself. Operators tune it with X402_PRICE_THREE_BUY.
const DEFAULT_PRICE_ATOMICS = 1_000;
const DESCRIPTION =
'three.ws internal $THREE micro-buy primitive. A settled x402 payment triggers ' +
'one small, real on-chain market buy of $THREE on Jupiter (buy-only); bought ' +
'tokens are swept to the treasury. High-frequency sibling of the daily buyback. ' +
'Not a public service.';
const INPUT_EXAMPLE = { note: 'microbuy' };
const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
properties: {
note: { type: 'string', description: 'Optional label echoed into the receipt.' },
},
};
const OUTPUT_EXAMPLE = {
ok: true,
kind: 'three-buy',
status: 'confirmed',
mint: TOKEN_MINT,
buySignature: '5x8…',
spentUsd: 0.01,
boughtThree: 5.1956,
priceUsd: 0.001924,
boughtAt: '2026-07-17T18:42:09.000Z',
};
const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['ok', 'kind', 'status', 'mint', 'buySignature', 'boughtAt'],
properties: {
ok: { type: 'boolean', const: true },
kind: { type: 'string', const: 'three-buy' },
status: { type: 'string', enum: ['submitted', 'confirmed', 'pending'] },
mint: { type: 'string' },
buySignature: { type: 'string' },
spentUsd: { type: ['number', 'null'] },
boughtThree: { type: ['number', 'null'] },
priceUsd: { type: ['number', 'null'] },
boughtAt: { type: 'string', format: 'date-time' },
},
};
const BAZAAR = {
discoverable: false,
info: {
input: { type: 'http', method: 'POST', body: INPUT_EXAMPLE },
output: { type: 'json', example: OUTPUT_EXAMPLE },
},
schema: buildBazaarSchema({
method: 'POST',
bodyType: 'json',
bodySchema: INPUT_SCHEMA,
outputSchema: OUTPUT_SCHEMA,
}),
};
// Re-emit the 402 challenge so the wrapper never settles the toll — used whenever a
// buy will not happen (disabled, unfunded, cap reached). The caller keeps its funds.
function refuseToll(reason) {
return new X402Error('three_buy_unavailable', `three-buy: ${reason}`, 402);
}
// Record every buy (and skipped/failed reason) into three_microbuy_runs — never a
// silent no-op. Wrapped so a DB fault never fails a buy that already landed.
async function record(status, fields = {}) {
try {
const [row] = await sql`
INSERT INTO three_microbuy_runs
(status, reason, usdc_spent_atomics, three_bought_atomics, price_usd,
slippage_bps, buy_signature)
VALUES
(${status}, ${fields.reason ?? null}, ${fields.usdcSpentAtomics ?? 0},
${fields.threeBoughtAtomics ?? 0}, ${fields.priceUsd ?? null},
${fields.slippageBps ?? null}, ${fields.buySignature ?? null})
RETURNING id
`;
return row?.id ?? null;
} catch (err) {
log.warn('three_microbuy_record_failed', { status, message: err?.message });
return null;
}
}
export default paidEndpoint({
route: ROUTE,
method: 'POST',
priceAtomics: priceFor('three-buy', DEFAULT_PRICE_ATOMICS),
networks: ['solana'],
description: DESCRIPTION,
bazaar: BAZAAR,
async handler() {
// Self-heal the ledger table so record() + the daily-cap DB fallback always
// work, even on a fresh/behind database (best-effort — never blocks a buy).
try { await ensureMicrobuySchema(); } catch { /* migration owns it in prod */ }
// Gate: a scheduled/paid call is a recorded no-op — and the toll is refused —
// until an operator funds the wallet and opts in.
if (!isEnabled()) {
await record('skipped', { reason: 'disabled' });
throw refuseToll('engine disabled (set THREE_MICROBUY_ENABLED)');
}
const signer = await loadMicrobuySigner();
if (!signer) {
await record('skipped', { reason: 'not_configured' });
throw refuseToll('signer not configured (set THREE_MICROBUY_SECRET_KEY_B64 or THREE_BUYBACK_SECRET_KEY_B64)');
}
// Cheap pre-check: refuse the toll before quoting Jupiter once the day's
// budget is spent. The atomic reserve in executeMicrobuy is the real guard.
if (!(await hasDailyBudget())) {
await record('skipped', { reason: 'daily_cap_reached' });
throw refuseToll('daily_cap_reached');
}
let plan;
try {
plan = await planMicrobuy(signer.publicKey.toBase58());
} catch (err) {
await record('failed', { reason: err.code || 'plan_failed' });
throw refuseToll(`plan failed (${err.code || err.message})`);
}
if (!plan.ok) {
await record('skipped', { reason: plan.reason });
throw refuseToll(plan.reason);
}
let receipt;
try {
receipt = await executeMicrobuy(signer, plan);
} catch (err) {
// daily_cap_reached / swap_failed / tx_reverted all reclaim any reservation
// inside executeMicrobuy and mean no buy went out → refuse the toll.
await record('failed', {
reason: err.code || 'execute_failed',
usdcSpentAtomics: 0,
});
throw refuseToll(err.code || 'execute_failed');
}
// A buy broadcast (confirmed or in-flight) — the toll is earned; let the
// wrapper settle it.
await record(receipt.status, {
usdcSpentAtomics: receipt.spendUsdcAtomics.toString(),
threeBoughtAtomics: receipt.boughtAtomics.toString(),
priceUsd: receipt.priceUsd,
slippageBps: null,
buySignature: receipt.buySignature,
});
return {
ok: true,
kind: 'three-buy',
status: receipt.status,
mint: TOKEN_MINT,
buySignature: receipt.buySignature,
spentUsd: usdcAtomicsToUsd(receipt.spendUsdcAtomics),
boughtThree:
receipt.boughtAtomics > 0n ? threeAtomicsToTokens(receipt.boughtAtomics) : null,
priceUsd: receipt.priceUsd ?? null,
boughtAt: new Date().toISOString(),
};
},
});