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
/**
* Single source of truth for the agent "$coin" affordance.
*
* Every agent on three.ws can have exactly one pump.fun coin. This module
* surfaces that one fact consistently wherever an agent is drawn — a card, a
* profile, a dashboard row — so the launchpad stops living only inside /studio
* and becomes a first-class, one-tap action next to the agent itself.
*
* Two states, one chip:
* - has a coin → a gold "$SYMBOL" pill linking straight to pump.fun (anyone).
* - no coin yet → an understated "Launch coin" pill, shown only to the owner,
* that opens the existing launch flow (src/pump/launch-token-modal.js).
*
* The launch pill is deliberately low-emphasis (muted until hover): present
* everywhere, but never shouting — visible enough to discover, quiet enough not
* to clutter a wall of agents. The coin detail/launch logic lives here once;
* callers just drop in `coinChipHTML(agent)` (string sites) or `coinChipEl(agent)`
* (element sites), exactly like the on-chain badge.
*
* Detection piggybacks on getOnchainStatus() (the on-chain badge normalizer) and
* additionally accepts the dashboard's `meta.pumpfun.mint` shape.
*/
import { getOnchainStatus } from './onchain-badge.js';
const STYLE_ID = 'tws-agent-coin-styles';
function esc(s) {
return String(s == null ? '' : s).replace(
/[&<>"']/g,
(c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c],
);
}
function pumpfunUrl(mint, cluster) {
if (!mint) return null;
if (cluster === 'devnet') return `https://explorer.solana.com/address/${mint}?cluster=devnet`;
return `https://pump.fun/coin/${mint}`;
}
/**
* Normalize any agent record into a coin descriptor, or null when it has no coin.
* @returns {null | { mint: string, symbol: string|null, cluster: 'mainnet'|'devnet', url: string|null }}
*/
export function getCoinStatus(agent) {
if (!agent || typeof agent !== 'object') return null;
// Prefer the canonical on-chain normalizer — it already resolves the pump.fun
// token across every surfaced shape (onchain block, token block, meta.token).
const status = getOnchainStatus(agent);
if (status && status.isToken && status.address) {
const cluster = status.cluster === 'devnet' ? 'devnet' : 'mainnet';
return {
mint: status.address,
symbol: status.tokenSymbol || null,
cluster,
// The canonical rich coin page (conviction + live market + trades) on
// mainnet; devnet has no such page.
pageUrl: cluster === 'mainnet' ? oraclePageUrl(status.address) : null,
// Prefer the pump.fun coin page on mainnet — this is a launchpad, not a
// block explorer. Fall back to the explorer only when there's no better link.
url: status.pumpfunUrl || pumpfunUrl(status.address, cluster) || status.explorerUrl,
};
}
// Dashboard / older shapes the badge normalizer doesn't reach: meta.pumpfun.
const token = agent.token || agent.meta?.token || agent.meta?.pumpfun || null;
const mint = token?.mint || token?.contract_address || token?.ca || null;
if (mint) {
const cluster = token.cluster === 'devnet' ? 'devnet' : 'mainnet';
return {
mint,
symbol: token.symbol || token.name || null,
cluster,
pageUrl: cluster === 'mainnet' ? oraclePageUrl(mint) : null,
url: token.pumpfun_url || pumpfunUrl(mint, cluster),
};
}
return null;
}
// The canonical three.ws rich coin page for a mint.
function oraclePageUrl(mint) {
return mint ? `/oracle/coin/${mint}` : null;
}
/** True when the agent already has a coin. */
export function hasCoin(agent) {
return getCoinStatus(agent) != null;
}
/**
* True when the viewer can launch this agent's coin: it has no coin yet and the
* viewer owns it. Ownership is read from the record (`is_owner`/`isOwner`) or
* forced by the caller via `opts.owner` on surfaces that only ever render the
* owner's own agents (e.g. the dashboard).
*/
export function canLaunchCoin(agent, opts = {}) {
if (!agent || getCoinStatus(agent)) return false;
if (opts.owner === true) return true;
return agent.is_owner === true || agent.isOwner === true;
}
// ── Single launch entry point ───────────────────────────────────────────────
// One place builds the launch context (image, needsDeploy, deploy fields) and
// opens the existing modal. Card chips and the agent-detail panel both call it,
// so the launchpad behaves identically no matter where it's triggered from.
/**
* Open the pump.fun launch flow for an agent record (any surfaced shape).
* @param {object} agent
*/
export async function openCoinLaunch(agent) {
if (!agent) return;
const rec = agent.rawMetadata || agent;
const id = agent.id || rec.id || agent.agent_id || rec.agent_id;
if (!id) return;
// First-timers crossing the on-chain threshold get the plain-language
// explainer + wallet setup before the launch modal. Returning/ready users
// pass straight through (the primer resolves instantly). Loaded lazily so a
// wall of coin chips never pays for the wizard's deps until one is clicked.
const { ensureOnchainPrimer } = await import('./onchain-primer.js');
if (!(await ensureOnchainPrimer({ action: 'launch-token' }))) return;
const onchain = rec.onchain || rec.meta?.onchain || agent.onchain || null;
const needsDeploy = !onchain || onchain.family !== 'solana';
const name = rec.name || agent.name || 'Agent';
const imageUrl =
rec.avatar_thumbnail_url ||
rec.meta?.thumbnail_url ||
agent.thumbnail_url ||
agent.avatar ||
agent.image ||
'';
const { openLaunchTokenModal } = await import('/src/pump/launch-token-modal.js');
openLaunchTokenModal({
agentId: id,
agentName: name,
imageUrl,
needsDeploy,
agentForDeploy: needsDeploy
? {
id,
name,
description: rec.description || agent.description || '',
avatar_id: rec.avatar_id || agent.avatar_id || null,
skills: rec.skills || agent.skills || undefined,
}
: null,
});
}
// ── Delegated launch handler ────────────────────────────────────────────────
// String-render sites (innerHTML) can't attach listeners, so the launch pill is
// a plain `[data-tws-coin-launch]` button and one capture-phase document listener
// drives it. Capture phase + stopPropagation means clicking the pill never
// triggers the surrounding card's navigation.
const _launchCtx = new Map();
let _delegated = false;
function _ensureDelegate() {
if (_delegated || typeof document === 'undefined') return;
_delegated = true;
document.addEventListener(
'click',
(e) => {
const btn = e.target?.closest?.('[data-tws-coin-launch]');
if (!btn) return;
e.preventDefault();
e.stopPropagation();
if (btn.disabled) return;
const id = btn.getAttribute('data-tws-coin-launch');
const agent = _launchCtx.get(String(id)) || { id };
btn.disabled = true;
Promise.resolve(openCoinLaunch(agent)).finally(() => {
btn.disabled = false;
});
},
true,
);
}
function _registerLaunchCtx(id, agent) {
if (!id) return;
_launchCtx.set(String(id), agent);
_ensureDelegate();
}
/** Inject the shared coin stylesheet once. Idempotent and SSR-safe. */
export function ensureCoinStyles() {
if (typeof document === 'undefined') return;
if (document.getElementById(STYLE_ID)) return;
const style = document.createElement('style');
style.id = STYLE_ID;
style.textContent = `
.tws-coin{display:inline-flex;align-items:center;gap:6px;padding:3px 9px;border-radius:999px;
font:600 11px/1 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;letter-spacing:.01em;
white-space:nowrap;vertical-align:middle;text-decoration:none;cursor:pointer;
border:1px solid transparent;background:transparent;font-family:inherit;
transition:background .15s ease,border-color .15s ease,transform .15s ease,color .15s ease;}
.tws-coin-glyph{flex:none;font-size:12px;line-height:1;}
.tws-coin-label{overflow:hidden;text-overflow:ellipsis;}
.tws-coin--md{padding:4px 11px;font-size:12px;gap:7px;}
.tws-coin--md .tws-coin-glyph{font-size:13px;}
/* Live coin — a real, tradable thing: gold, confident, links to pump.fun. */
.tws-coin--live{color:#eab308;background:rgba(234,179,8,.12);border-color:rgba(234,179,8,.34);}
a.tws-coin--live:hover{background:rgba(234,179,8,.2);border-color:rgba(234,179,8,.6);transform:translateY(-1px);}
a.tws-coin--live:active{transform:translateY(0);}
.tws-coin--live:focus-visible{outline:2px solid rgba(234,179,8,.7);outline-offset:2px;}
/* Launch action — understated by default so a wall of agents never reads as a
wall of buttons. Reveals its gold identity only on hover/focus. */
.tws-coin--launch{color:rgba(235,236,240,.5);background:rgba(255,255,255,.035);border-color:rgba(255,255,255,.13);}
.tws-coin--launch .tws-coin-glyph{font-weight:700;}
.tws-coin--launch:hover{color:#eab308;background:rgba(234,179,8,.12);border-color:rgba(234,179,8,.42);transform:translateY(-1px);}
.tws-coin--launch:active{transform:translateY(0);}
.tws-coin--launch:focus-visible{outline:2px solid rgba(234,179,8,.6);outline-offset:2px;}
.tws-coin--launch:disabled{opacity:.55;cursor:progress;transform:none;}
@media (prefers-reduced-motion: reduce){.tws-coin{transition:none;}}
`;
(document.head || document.documentElement).appendChild(style);
}
/**
* Render the coin chip as an HTML string. Returns '' when there's nothing to show
* (no coin and the viewer can't launch one).
*
* @param {object} agent
* @param {object} [opts]
* @param {'sm'|'md'} [opts.size='sm']
* @param {boolean} [opts.owner=false] Force owner context (owner-only surfaces).
* @param {boolean} [opts.link=true] Link the live coin to pump.fun. Pass false
* inside a fully-clickable card so the chip is a plain (non-anchor) indicator.
* @param {boolean} [opts.launchable=true] Render the owner "Launch coin" pill.
* Pass false on a surface that already has its own launch control, so the chip
* stays a pure coin indicator and never duplicates the launch entry point.
* @param {string} [opts.launchLabel='Launch coin']
*/
export function coinChipHTML(agent, opts = {}) {
const { size = 'sm', owner = false, link = true, launchable = true, launchLabel = 'Launch coin' } = opts;
const sz = size === 'md' ? ' tws-coin--md' : '';
const coin = getCoinStatus(agent);
if (coin) {
ensureCoinStyles();
const sym = coin.symbol ? `$${esc(coin.symbol)}` : 'Coin';
const inner = `<span class="tws-coin-glyph" aria-hidden="true">◎</span><span class="tws-coin-label">${sym}</span>`;
// Prefer the internal rich coin page (conviction + market + live trades) —
// it links out to pump.fun to trade. Fall back to the external link (devnet).
const href = coin.pageUrl || coin.url;
const internal = Boolean(coin.pageUrl);
const aria = internal
? `View ${coin.symbol ? coin.symbol + ' ' : ''}coin — conviction, market & live trades`
: `Trade ${coin.symbol ? coin.symbol + ' ' : ''}coin on pump.fun`;
if (link && href) {
const tgt = internal ? '' : ' target="_blank" rel="noopener noreferrer"';
return `<a class="tws-coin tws-coin--live${sz}" href="${esc(href)}"${tgt} title="${esc(aria)}" aria-label="${esc(aria)}">${inner}</a>`;
}
return `<span class="tws-coin tws-coin--live${sz}" role="img" aria-label="${esc(aria)}">${inner}</span>`;
}
if (!launchable || !canLaunchCoin(agent, { owner })) return '';
ensureCoinStyles();
const id = agent?.id || agent?.rawMetadata?.id || '';
if (!id) return '';
_registerLaunchCtx(id, agent);
return `<button type="button" class="tws-coin tws-coin--launch${sz}" data-tws-coin-launch="${esc(id)}" title="Launch this agent's coin on pump.fun" aria-label="Launch this agent's coin on pump.fun"><span class="tws-coin-glyph" aria-hidden="true">+</span><span class="tws-coin-label">${esc(launchLabel)}</span></button>`;
}
/**
* Render the coin chip as a DOM node, or null when there's nothing to show.
* Launch buttons are driven by the shared delegated listener; coin links get a
* local stopPropagation so they don't trigger an enclosing clickable card.
*/
export function coinChipEl(agent, opts = {}) {
const html = coinChipHTML(agent, opts);
if (!html) return null;
const tpl = document.createElement('template');
tpl.innerHTML = html.trim();
const node = tpl.content.firstElementChild;
if (node && node.tagName === 'A') {
node.addEventListener('click', (e) => e.stopPropagation());
}
return node;
}
if (typeof window !== 'undefined') {
window.twsAgentCoin = {
getCoinStatus,
hasCoin,
canLaunchCoin,
openCoinLaunch,
coinChipHTML,
coinChipEl,
ensureCoinStyles,
};
}