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
/**
* /receipts: the buyer-side x402 receipt vault.
*
* Every paid x402 call three.ws settles issues a signed offer-receipt artifact
* (USE-17) that is durably logged server-side. This page lets any buyer prove
* control of a wallet with one personal-sign message and pull back every
* receipt ever issued to it via GET /api/x402/my-receipts: resource, network,
* settlement tx, timestamp, plus the full signed artifact as JSON and a CSV
* export of the window.
*
* This is the buyer's side of the ledger: what YOU bought. Solana wallets sign via the injected provider (Phantom,
* Backpack, Solflare); EVM wallets via personal_sign. The signature only
* authorizes reads and is fresh for 5 minutes, matching the API window.
*/
import {
buildReceiptsMessage,
signatureStillFresh,
networkLabel,
explorerTxUrl,
shortAddress,
resourceDisplay,
receiptsToCsv,
summarizeReceipts,
formatReceiptAmount,
formatSpendEntries,
formatCount,
totalSpend,
} from './receipts-lib.js';
import { timeAgo } from './shared/pulse-format.js';
const API_URL = '/api/x402/my-receipts';
const SESSION_KEY = 'twx_receipts_session';
const FETCH_LIMIT = 200;
const $ = (id) => document.getElementById(id);
const state = {
session: null, // { address, network, signature, issuedAt }
rows: [],
// Account-wide aggregate from the API. The KPI strip reads THIS, never the
// loaded page: a wallet with 60k receipts must be told it has 60k, not the
// size of the window it happens to be holding.
summary: null,
nextCursor: null,
query: '',
loading: false,
loadingMore: false,
};
// ── wallet providers ─────────────────────────────────────────────────────────
function solanaProvider() {
const w = window;
if (w.phantom?.solana?.isPhantom) return w.phantom.solana;
if (w.solana?.isPhantom) return w.solana;
if (w.backpack?.solana) return w.backpack.solana;
if (w.solflare?.isSolflare) return w.solflare;
if (w.solana) return w.solana;
return null;
}
async function signWithSolana() {
const provider = solanaProvider();
if (!provider?.connect) {
throw Object.assign(
new Error('No Solana wallet found. Install Phantom, Backpack, or Solflare to continue.'),
{ code: 'no_wallet' },
);
}
const resp = await provider.connect();
const address = (resp?.publicKey || provider.publicKey)?.toString();
if (!address) throw new Error('Could not read your wallet address.');
const issuedAt = new Date().toISOString();
const message = buildReceiptsMessage(address, issuedAt, 'solana');
const signed = await provider.signMessage(new TextEncoder().encode(message), 'utf8');
const sigBytes = signed?.signature ?? signed;
const bs58 = (await import('bs58')).default;
return { address, network: 'solana', signature: bs58.encode(sigBytes), issuedAt };
}
async function signWithEvm() {
const eth = window.ethereum;
if (!eth?.request) {
throw Object.assign(
new Error('No EVM wallet found. Install MetaMask or another injected wallet to continue.'),
{ code: 'no_wallet' },
);
}
const accounts = await eth.request({ method: 'eth_requestAccounts' });
const address = accounts?.[0];
if (!address) throw new Error('Could not read your wallet address.');
const issuedAt = new Date().toISOString();
const message = buildReceiptsMessage(address, issuedAt, 'evm');
const hex = `0x${[...new TextEncoder().encode(message)]
.map((b) => b.toString(16).padStart(2, '0'))
.join('')}`;
const signature = await eth.request({ method: 'personal_sign', params: [hex, address] });
return { address, network: 'evm', signature, issuedAt };
}
// ── session persistence (survives reloads inside the 5-minute window) ────────
function loadSession() {
try {
const raw = sessionStorage.getItem(SESSION_KEY);
if (!raw) return null;
const s = JSON.parse(raw);
if (!s?.address || !s?.signature || !signatureStillFresh(s.issuedAt)) return null;
return s;
} catch {
return null;
}
}
function saveSession(session) {
try {
sessionStorage.setItem(SESSION_KEY, JSON.stringify(session));
} catch {
/* private mode: the session just won't survive a reload */
}
}
function clearSession() {
try {
sessionStorage.removeItem(SESSION_KEY);
} catch {
/* ignore */
}
}
// ── data ─────────────────────────────────────────────────────────────────────
async function fetchReceipts(session, cursor) {
const params = new URLSearchParams({
address: session.address,
signature: session.signature,
issuedAt: session.issuedAt,
network: session.network,
limit: String(FETCH_LIMIT),
});
if (cursor) params.set('cursor', cursor);
const res = await fetch(`${API_URL}?${params}`);
const body = await res.json().catch(() => null);
if (!res.ok) {
const code = body?.error || `http_${res.status}`;
const detail = body?.error_description || 'The receipt service returned an error.';
throw Object.assign(new Error(detail), { code });
}
return {
receipts: body?.receipts || [],
summary: body?.summary || null,
nextCursor: body?.nextCursor || null,
};
}
async function connect(kind) {
if (state.loading) return;
setConnectBusy(kind, true);
hideError();
try {
const session = kind === 'solana' ? await signWithSolana() : await signWithEvm();
state.session = session;
saveSession(session);
await refresh({ resign: false });
} catch (err) {
if (err?.code === 4001 || /reject|cancel|denied|declined/i.test(String(err?.message))) {
showError('Signature request was cancelled. Nothing was sent.');
} else if (err?.code === 'no_wallet') {
showError(err.message);
} else {
showError(err?.message || 'Could not sign in with that wallet.');
}
} finally {
setConnectBusy(kind, false);
}
}
async function refresh({ resign = true } = {}) {
const session = state.session;
if (!session || state.loading) return;
state.loading = true;
showVault();
renderSkeleton();
try {
let active = session;
if (!signatureStillFresh(active.issuedAt)) {
if (!resign) throw new Error('Signature expired. Sign in again to refresh.');
active = active.network === 'solana' ? await signWithSolana() : await signWithEvm();
state.session = active;
saveSession(active);
}
const page = await fetchReceipts(active);
state.rows = page.receipts;
state.summary = page.summary;
state.nextCursor = page.nextCursor;
renderVault();
} catch (err) {
if (err?.code === 'stale_signature' || err?.code === 'invalid_signature') {
// Server rejected the cached signature: drop it and return to sign-in.
disconnect();
showError('Your session expired. Connect your wallet again to view receipts.');
} else if (err?.code === 4001 || /reject|cancel|denied/i.test(String(err?.message))) {
renderVault();
} else {
renderLoadError(err?.message || 'Could not load receipts.');
}
} finally {
state.loading = false;
}
}
/**
* Append the next keyset page. The API caps a page at 200 rows and hands back
* a cursor whenever more exist; without following it a heavy buyer could only
* ever see their newest 200 receipts, which is not "retrievable forever".
*/
async function loadMore() {
const session = state.session;
if (!session || !state.nextCursor || state.loading || state.loadingMore) return;
if (!signatureStillFresh(session.issuedAt)) {
showMoreError('Your signature expired. Hit Refresh to sign again.');
return;
}
state.loadingMore = true;
setMoreBusy(true);
try {
const page = await fetchReceipts(session, state.nextCursor);
state.rows = state.rows.concat(page.receipts);
state.nextCursor = page.nextCursor;
renderVault();
} catch (err) {
showMoreError(err?.message || 'Could not load more receipts.');
} finally {
state.loadingMore = false;
setMoreBusy(false);
}
}
function disconnect() {
state.session = null;
state.rows = [];
state.summary = null;
state.nextCursor = null;
// A stale filter carried into the next session renders the new wallet's
// vault as "no receipts match your search", which reads as an empty vault.
state.query = '';
$('rc-search').value = '';
clearSession();
$('rc-load-error').hidden = true;
$('rc-more-wrap').hidden = true;
$('rc-vault').hidden = true;
$('rc-signin').hidden = false;
}
// ── rendering ────────────────────────────────────────────────────────────────
function esc(s) {
return String(s ?? '').replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
function showVault() {
$('rc-signin').hidden = true;
$('rc-vault').hidden = false;
const s = state.session;
$('rc-wallet-addr').textContent = shortAddress(s.address);
$('rc-wallet-addr').title = s.address;
$('rc-wallet-net').textContent = s.network === 'solana' ? 'Solana' : 'EVM';
}
function renderSkeleton() {
$('rc-list').innerHTML = Array.from({ length: 4 })
.map(() => '<div class="rc-row rc-skeleton" aria-hidden="true"></div>')
.join('');
$('rc-empty').hidden = true;
$('rc-load-error').hidden = true;
$('rc-more-wrap').hidden = true;
}
function renderLoadError(message) {
$('rc-list').innerHTML = '';
$('rc-empty').hidden = true;
$('rc-more-wrap').hidden = true;
const el = $('rc-load-error');
el.hidden = false;
$('rc-load-error-msg').textContent = message;
}
function filteredRows() {
const q = state.query.trim().toLowerCase();
if (!q) return state.rows;
return state.rows.filter(
(r) =>
resourceDisplay(r.resourceUrl).toLowerCase().includes(q) ||
String(r.transaction || '').toLowerCase().includes(q) ||
String(r.assetSymbol || '').toLowerCase().includes(q) ||
networkLabel(r.network).toLowerCase().includes(q),
);
}
/**
* KPI inputs: the API's account-wide summary when it supplied one, else the
* loaded page. Networks arrive as raw CAIP-2 ids in the summary, so they get
* the same label treatment the rows do.
*/
function vaultStats() {
const s = state.summary;
if (!s) {
return { stats: summarizeReceipts(state.rows), spend: totalSpend(state.rows), wide: false };
}
return {
stats: {
total: s.total,
endpoints: s.endpoints,
networks: (s.networks || []).map(networkLabel),
lastAt: s.lastAt,
},
spend: formatSpendEntries(s.spend, s.unpriced),
wide: true,
};
}
function renderPager(shown, total) {
const wrap = $('rc-more-wrap');
if (!state.nextCursor) {
wrap.hidden = true;
return;
}
wrap.hidden = false;
$('rc-shown').textContent = `Showing the newest ${formatCount(shown)} of ${formatCount(total)} receipts.`;
}
function renderVault() {
const { stats, spend } = vaultStats();
$('rc-k-total').textContent = formatCount(stats.total);
$('rc-k-endpoints').textContent = formatCount(stats.endpoints);
$('rc-k-networks').textContent = stats.networks.length ? stats.networks.join(' · ') : '·';
$('rc-k-last').textContent = stats.lastAt ? timeAgo(stats.lastAt) : '·';
// Receipts issued before settlement capture landed carry no amount, and
// non-dollar assets are never folded into the dollar figure. Say both,
// rather than quietly under-reporting or mislabelling the total.
$('rc-k-spend').textContent = spend.priced ? spend.label : '·';
const notes = [];
for (const other of spend.others) notes.push(`+ ${other.label}`);
if (spend.unpriced) notes.push(`${formatCount(spend.priced)} of ${formatCount(stats.total)} priced`);
$('rc-k-spend-note').textContent = notes.length ? notes.join(' · ') : 'USDC settled';
$('rc-load-error').hidden = true;
const rows = filteredRows();
const list = $('rc-list');
if (!state.rows.length) {
list.innerHTML = '';
$('rc-more-wrap').hidden = true;
$('rc-empty').hidden = false;
$('rc-empty-title').textContent = 'No receipts for this wallet yet';
$('rc-empty-body').innerHTML =
'Receipts appear here the moment this wallet pays any three.ws x402 endpoint. ' +
'Browse the <a href="/x402">paid endpoint catalog</a> or read ' +
'<a href="/docs/x402-endpoints">how x402 payments work</a> to make your first call.';
return;
}
if (!rows.length) {
list.innerHTML = '';
$('rc-more-wrap').hidden = true;
$('rc-empty').hidden = false;
$('rc-empty-title').textContent = 'No receipts match your search';
$('rc-empty-body').textContent = 'Try a different endpoint path, network, or transaction hash.';
return;
}
$('rc-empty').hidden = true;
renderPager(state.rows.length, stats.total);
list.innerHTML = rows
.map((r, i) => {
const url = explorerTxUrl(r.network, r.transaction);
const txCell = r.transaction
? url
? `<a class="rc-tx" href="${esc(url)}" target="_blank" rel="noopener noreferrer">${esc(shortAddress(r.transaction))} ↗</a>`
: `<span class="rc-tx rc-tx-raw" title="${esc(r.transaction)}">${esc(shortAddress(r.transaction))}</span>`
: '<span class="rc-tx rc-tx-none" title="This receipt was issued without an on-chain tx hash for privacy">private</span>';
const when = r.issuedAt
? `<time datetime="${esc(r.issuedAt)}" title="${esc(new Date(r.issuedAt).toLocaleString())}">${esc(timeAgo(r.issuedAt))}</time>`
: '·';
const amount = formatReceiptAmount(r.amountAtomics, r.assetDecimals, r.assetSymbol);
const amountCell = amount
? `<span class="rc-amount" title="${esc(r.amountAtomics)} atomic units of ${esc(r.asset || amount.symbol || 'the settlement asset')}">${esc(amount.label)}</span>`
: '';
return `
<div class="rc-row" data-idx="${i}">
<div class="rc-row-main">
<span class="rc-resource" title="${esc(r.resourceUrl)}">${esc(resourceDisplay(r.resourceUrl))}</span>
<span class="rc-meta">
${amountCell}
<span class="rc-net" data-net="${esc(networkLabel(r.network))}">${esc(networkLabel(r.network))}</span>
${when}
${txCell}
</span>
</div>
<div class="rc-row-actions">
<button type="button" class="rc-act" data-action="copy" data-idx="${i}" title="Copy the signed receipt JSON">copy</button>
<button type="button" class="rc-act" data-action="download" data-idx="${i}" title="Download the signed receipt JSON">json</button>
</div>
</div>`;
})
.join('');
}
// ── actions ──────────────────────────────────────────────────────────────────
function receiptArtifact(row) {
return JSON.stringify(
{
id: row.id,
payer: row.payer,
network: row.network,
resourceUrl: row.resourceUrl,
transaction: row.transaction,
issuedAt: row.issuedAt,
format: row.format,
receipt: row.receipt,
},
null,
2,
);
}
function downloadBlob(content, filename, type) {
const blob = new Blob([content], { type });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = filename;
a.click();
URL.revokeObjectURL(url);
}
async function copyText(text) {
try {
await navigator.clipboard.writeText(text);
toast('Copied to clipboard');
} catch {
toast('Copy failed. Use the JSON download instead.');
}
}
function exportCsv() {
if (!state.rows.length) {
toast('Nothing to export yet');
return;
}
const addr = shortAddress(state.session?.address || 'wallet').replace('…', '-');
downloadBlob(receiptsToCsv(filteredRows()), `x402-receipts-${addr}.csv`, 'text/csv');
toast('CSV exported');
}
let toastTimer = null;
function toast(message) {
const el = $('rc-toast');
el.textContent = message;
el.hidden = false;
el.classList.add('show');
clearTimeout(toastTimer);
toastTimer = setTimeout(() => {
el.classList.remove('show');
toastTimer = setTimeout(() => {
el.hidden = true;
}, 200);
}, 1800);
}
function showError(message) {
const el = $('rc-signin-error');
el.hidden = false;
el.textContent = message;
}
function hideError() {
$('rc-signin-error').hidden = true;
}
function setConnectBusy(kind, busy) {
const btn = kind === 'solana' ? $('rc-connect-solana') : $('rc-connect-evm');
btn.disabled = busy;
btn.classList.toggle('busy', busy);
btn.querySelector('.rc-btn-label').textContent = busy
? 'Waiting for wallet…'
: btn.dataset.label;
}
// ── boot ─────────────────────────────────────────────────────────────────────
function wire() {
$('rc-connect-solana').addEventListener('click', () => connect('solana'));
$('rc-connect-evm').addEventListener('click', () => connect('evm'));
$('rc-refresh').addEventListener('click', () => refresh());
$('rc-export').addEventListener('click', exportCsv);
$('rc-disconnect').addEventListener('click', disconnect);
$('rc-retry').addEventListener('click', () => refresh());
$('rc-search').addEventListener('input', (e) => {
state.query = e.target.value;
renderVault();
});
$('rc-list').addEventListener('click', (e) => {
const btn = e.target.closest('[data-action]');
if (!btn) return;
const row = filteredRows()[Number(btn.dataset.idx)];
if (!row) return;
if (btn.dataset.action === 'copy') copyText(receiptArtifact(row));
if (btn.dataset.action === 'download') {
downloadBlob(
receiptArtifact(row),
`x402-receipt-${row.id}.json`,
'application/json',
);
}
});
document.addEventListener('keydown', (e) => {
if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return;
if (e.key === '/' && !$('rc-vault').hidden) {
e.preventDefault();
$('rc-search').focus();
}
if (e.key === 'e' && !$('rc-vault').hidden) exportCsv();
});
}
function boot() {
wire();
const cached = loadSession();
if (cached) {
state.session = cached;
refresh({ resign: false });
}
}
boot();