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
/**
* three.ws on-chain brand + metadata builders
* -------------------------------------------
* Single source of truth for everything we stamp onto Solana when an agent is
* deployed (Metaplex Core asset) or tokenized (pump.fun). Two goals:
*
* 1. Make every on-chain artifact unmistakably a three.ws artifact — the
* platform name, our links, and the $THREE coin travel with the asset so a
* wallet, explorer, or marketplace surfaces the connection without us.
* 2. Maximize *correct* metadata. The off-chain JSON is a strict superset of
* the Metaplex token-metadata standard (so Phantom / Solscan / Magic Eden
* render it) AND our agent-manifest/0.1 schema. The on-chain Attributes
* plugin writes a curated subset *directly into the asset account* — real
* bytes on the blockchain, not just a pointer.
*
* Links here are the canonical ones used across the site (footer.html,
* features.json). Never invent a URL — if it isn't already real, it doesn't
* belong in on-chain metadata.
*/
import { env } from './env.js';
import { gmgnTokenUrl, axiomTokenUrl, padreTokenUrl, fomoTokenUrl, dextoolsTokenUrl } from '../../src/shared/trading-terminals.js';
import { THREE_MINT } from './stage-split.js';
import { DEXTOOLS_PAIR_URL } from '../../src/pump/dextools-social-boost.js';
// ── Canonical brand ──────────────────────────────────────────────────────────
export const THREE_WS = {
name: 'three.ws',
tagline: 'Give your AI a body.',
description:
'three.ws is the AI-agent layer for the open web: build, embed, monetize, ' +
'and trade autonomous agents with real 3D avatars, on-chain identity, ' +
'pay-per-call (x402), and pump.fun token launches.',
website: 'https://three.ws',
x: 'https://x.com/trythreews',
xHandle: '@trythreews',
telegram: 'https://t.me/three_ws',
github: 'https://github.com/nirholas/three.ws',
docs: 'https://three.ws/docs',
ogImage: 'https://three.ws/og-image.png',
};
// ── $THREE — the platform coin every artifact links back to ──────────────────
/** @returns {string} the $THREE mint (env-overridable for devnet/test). */
export function threeTokenMint() {
return env.THREE_TOKEN_MINT;
}
/** Canonical $THREE link set, derived from the active mint. */
export function threeTokenLinks(mint = threeTokenMint()) {
return {
symbol: 'THREE',
mint,
pumpfun: `https://pump.fun/coin/${mint}`,
jupiter: `https://jup.ag/tokens/${mint}`,
solscan: `https://solscan.io/token/${mint}`,
phantom: `https://phantom.com/tokens/solana/${mint}`,
dexscreener: `https://dexscreener.com/solana/${mint}`,
// The $THREE pair DEXTools tracks (and credits Social Boost visits to);
// any other mint (devnet/test override) goes through the resolver.
dextools: mint === THREE_MINT ? DEXTOOLS_PAIR_URL : dextoolsTokenUrl(mint, { from: 'three-brand' }),
coingecko: 'https://www.coingecko.com/en/coins/three-ws',
// Trading terminals. GMGN's carries our referral inline; the other three
// have no documented deep-link referral form, so they stay clean deep
// links. See src/shared/trading-terminals.js.
gmgn: gmgnTokenUrl(mint),
axiom: axiomTokenUrl(mint),
padre: padreTokenUrl(mint),
fomo: fomoTokenUrl(mint),
};
}
/** Public profile page for a deployed agent. */
export function agentHomeUrl(agentId) {
return `${env.APP_ORIGIN}/agents/${agentId}`;
}
// ── helpers ──────────────────────────────────────────────────────────────────
const _enc = new TextEncoder();
/**
* Clamp to a UTF-8 *byte* budget without splitting a codepoint. On-chain
* attributes are borsh strings measured in bytes, so a CJK/emoji name must be
* bounded by bytes — not characters — or it can overflow the 1232-byte tx.
*/
function clamp(str, maxBytes) {
const s = String(str ?? '').trim();
if (_enc.encode(s).length <= maxBytes) return s;
let out = '';
let bytes = 0;
for (const ch of s) {
const b = _enc.encode(ch).length;
if (bytes + b > maxBytes - 3) break; // reserve 3 bytes for the ellipsis
out += ch;
bytes += b;
}
return `${out.trimEnd()}…`;
}
/** A Metaplex `creators` array crediting the owner + the platform. */
function creators(ownerAddress) {
const list = [];
if (ownerAddress) list.push({ address: ownerAddress, share: 100 });
return list;
}
/** Default enforced secondary-sale royalty for agent assets: 5%, to the owner. */
export const AGENT_ROYALTY_BPS = 500;
/**
* Plain-data config for the Metaplex Core Royalties plugin. Kept SDK-free so
* this module stays dependency-light — the caller turns this into the plugin
* with `ruleSet('None')`. Returns `null` when there's no owner to credit
* (the plugin requires creator percentages to sum to 100).
*
* @param {string} ownerAddress base58 owner/creator wallet
* @param {number} [basisPoints]
*/
export function agentRoyaltyConfig(ownerAddress, basisPoints = AGENT_ROYALTY_BPS) {
if (!ownerAddress) return null;
return { basisPoints, creators: [{ address: ownerAddress, percentage: 100 }] };
}
/**
* Deterministic short symbol for an agent's skill NFT collection, derived from
* its name. Used identically on the off-chain collection JSON and by the create
* script so a wallet/explorer shows a stable ticker. Strips to uppercase
* alphanumerics, caps at 10 chars, falls back to 'SKILL'.
*
* @param {string} [agentName]
* @returns {string}
*/
export function skillCollectionSymbol(agentName) {
const cleaned = String(agentName || '')
.toUpperCase()
.replace(/[^A-Z0-9]/g, '')
.slice(0, 10);
return cleaned || 'SKILL';
}
// ── Agent identity (Metaplex Core asset) ─────────────────────────────────────
/**
* Off-chain JSON pinned for a Metaplex Core agent asset. Superset of the
* Metaplex token-metadata standard + agent-manifest/0.1, so generic NFT readers
* and our own resolvers both work from one document.
*
* @param {object} a
* @param {string} a.name
* @param {string} [a.description]
* @param {string} [a.image] resolvable avatar thumbnail (https/ipfs)
* @param {string} [a.animationUrl] avatar GLB (https/ipfs)
* @param {string} [a.externalUrl] agent profile page
* @param {string|null} [a.avatarId]
* @param {string[]} [a.skills]
* @param {string} [a.ownerAddress] for the creators array
* @param {string} [a.createdAt] ISO timestamp
*/
export function buildAgentManifest(a) {
const tok = threeTokenLinks();
const image = a.image || THREE_WS.ogImage;
const description =
a.description?.trim() || `${a.name} — an autonomous agent on ${THREE_WS.name}.`;
const attributes = [
{ trait_type: 'Platform', value: THREE_WS.name },
{ trait_type: 'Standard', value: 'Metaplex Core' },
{ trait_type: 'Schema', value: 'agent-manifest/0.1' },
...(a.skills?.length ? [{ trait_type: 'Skills', value: a.skills.join(', ') }] : []),
{ trait_type: '$THREE', value: tok.mint },
...(a.createdAt ? [{ trait_type: 'Created', value: a.createdAt }] : []),
];
const files = [{ uri: image, type: 'image/png' }];
if (a.animationUrl) files.push({ uri: a.animationUrl, type: 'model/gltf-binary' });
return {
// Metaplex token-metadata standard
name: a.name,
symbol: 'AGENT',
description,
image,
...(a.animationUrl ? { animation_url: a.animationUrl } : {}),
external_url: a.externalUrl || THREE_WS.website,
attributes,
properties: {
category: a.animationUrl ? 'vr' : 'image',
files,
creators: creators(a.ownerAddress),
},
// three.ws brand block — links travel with the asset
platform: {
name: THREE_WS.name,
url: THREE_WS.website,
tagline: THREE_WS.tagline,
x: THREE_WS.x,
github: THREE_WS.github,
},
token: { symbol: tok.symbol, mint: tok.mint, url: tok.pumpfun },
// agent-manifest/0.1 (our resolvers)
$schema: 'https://3d-agent.io/schemas/manifest/0.1.json',
spec: 'agent-manifest/0.1',
tags: ['three.ws', 'ai-agent', ...(a.skills || [])],
body: { uri: a.animationUrl || '', format: 'gltf-binary' },
_baseURI: 'ipfs://',
...(a.avatarId ? { avatarId: a.avatarId } : {}),
...(a.skills?.length ? { skills: a.skills } : {}),
};
}
/**
* Attributes written *directly on-chain* via the Metaplex Core Attributes
* plugin. This is the literal "more metadata on the blockchain" — each pair is
* stored in the asset account (and costs rent), so the set is curated: brand,
* provenance links, the off-chain JSON pointer, and the $THREE linkage.
*
* Keys are short; values are clamped so a long agent name or skill list can't
* blow up rent. Returns `[{ key, value }]` ready for the plugin's attributeList.
*/
export function buildAgentOnchainAttributes(a) {
const tok = threeTokenLinks();
// Caps (in UTF-8 bytes) keep the plugin comfortably under Solana's 1232-byte
// tx limit even with a long agent name and a full skill list. The off-chain
// JSON URI already lives on-chain in the asset's `uri` field, so it is not
// duplicated here.
const pairs = [
['platform', THREE_WS.name],
['url', THREE_WS.website],
['agent', clamp(a.name, 48)],
...(a.agentUrl ? [['agent_url', clamp(a.agentUrl, 72)]] : []),
['x', THREE_WS.x],
['github', THREE_WS.github],
['$THREE', tok.mint],
['$THREE_url', tok.pumpfun],
['standard', 'metaplex-core'],
['schema', 'agent-manifest/0.1'],
...(a.skills?.length ? [['skills', clamp(a.skills.join(','), 80)]] : []),
...(a.createdAt ? [['created', a.createdAt]] : []),
];
return pairs.map(([key, value]) => ({ key, value: String(value) }));
}
/**
* Off-chain registration document for the Metaplex Agent Registry
* (`@metaplex-foundation/mpl-agent-registry`). This is a DIFFERENT artifact from
* the Core asset manifest: minting a Core asset only creates the NFT — to make an
* agent discoverable in Metaplex's on-chain Agent Registry the asset needs an
* Agent Identity PDA whose `agentRegistrationUri` points at this JSON.
*
* Superset of the SDK's `AgentMetadata` interface — the six required fields
* (type/name/description/services/registrations/supportedTrust) are all present,
* so SDK-strict consumers read it without coercion. We additionally emit the
* EIP-8004 registration-v1 signals that Metaplex's Agent Registry indexes
* (`active`, `x402Support`, `x402Endpoints`, `agentMetadataUri`); without them the
* registry defaults the agent to "x402 Not Supported" / inactive even though every
* three.ws agent settles calls over x402. Mirrors the canonical served doc at
* /.well-known/agent-registration.json so on- and off-chain metadata agree.
*
* @param {object} a
* @param {string|number} a.agentId three.ws agent id (for the cross-registry link)
* @param {string} a.name
* @param {string} [a.description]
* @param {string} [a.agentUrl] public agent profile page
* @param {string} [a.image] resolvable avatar thumbnail (https/ipfs)
* @param {string} [a.modelUri] the agent's 3D avatar GLB (https/ipfs)
* @param {string} [a.modelFormat] defaults to 'gltf-binary'
* @param {string} [a.origin] public origin override (defaults to env.APP_ORIGIN)
* @param {boolean} [a.active] defaults true; pass false to mark inactive
* @param {{chainId:string|number,agentId:string|number,registry?:string}} [a.erc8004]
* @param {string[]} [a.skills]
*/
export function buildAgentRegistrationMetadata(a) {
const origin = (a.origin || env.APP_ORIGIN).replace(/\/$/, '');
const home = a.agentUrl || agentHomeUrl(a.agentId);
const description =
a.description?.trim() || `${a.name} — an autonomous agent on ${THREE_WS.name}.`;
const image = a.image || THREE_WS.ogImage;
const cardUrl = `${origin}/.well-known/agent-card.json`;
// Real, reachable endpoints. `endpoint` is the SDK's field; the extra `version`
// keys are ignored by strict consumers and used by richer registry indexers.
const services = [
{ name: 'web', endpoint: home },
{ name: 'A2A', endpoint: cardUrl, version: '0.3.0' },
{ name: 'MCP', endpoint: `${origin}/.well-known/openapi.yaml`, version: '2025-06-18' },
];
return {
// Metaplex's Agent Registry indexer requires `type` to be a STRING matching
// the EIP-8004 registration-v1 URL. An array here makes the indexer reject
// the registration-v1 shape and fall back to a name/description/image-only
// record — silently dropping active/x402Support/services/supportedTrust from
// the agent page. Keep `type` a string; carry the three.ws spec separately.
type: 'https://eips.ethereum.org/EIPS/eip-8004#registration-v1',
additionalTypes: ['https://three.ws/specs/3d-agent-card-v1'],
name: a.name,
description,
image,
active: a.active === false ? false : true,
// The 3D avatar is the three.ws differentiator — surface it so the registry
// can render the agent's body, not just a flat thumbnail.
...(a.modelUri ? { model: { uri: a.modelUri, format: a.modelFormat || 'gltf-binary' } } : {}),
services,
x402Support: true,
x402Endpoints: [
{
url: `${origin}/api/mcp`,
method: 'POST',
description:
'MCP tool call — 3D avatar viewer, glTF model validation/inspection/optimization, and Solana agent data',
networks: ['solana', 'base'],
scheme: 'exact',
priceUsdc: '0.001',
},
],
// Cross-link to other registries this agent lives in so identities resolve to
// each other — Metaplex's `AgentRegistration` shape: { agentId, agentRegistry }.
// Always the three.ws handle; plus an ERC-8004 entry when the agent has one.
registrations: [
{ agentId: String(a.agentId), agentRegistry: THREE_WS.website },
...(a.erc8004?.chainId && a.erc8004?.agentId
? [{
agentRegistry: `eip155:${a.erc8004.chainId}:${a.erc8004.registry || ''}`.replace(/:$/, ''),
agentId: String(a.erc8004.agentId),
}]
: []),
],
supportedTrust: ['reputation'],
agentMetadataUri: cardUrl,
};
}
/**
* ERC-8004 registration-file fields that the Agent Registry subgraph indexes
* (see api/agents/8004/agent.js `registrationFile { active x402Support mcpEndpoint
* a2aEndpoint webEndpoint supportedTrusts ... }`). The EVM registration flow
* (api/agents/register) pins an agent-manifest JSON whose base shape lacks these
* flat fields, so the indexer defaults `x402Support` to false and shows three.ws
* agents as inactive / "x402 Not Supported". Spread these in to advertise the
* truth: every three.ws agent settles calls over x402. Mirrors the Solana
* registry doc above so on- and cross-chain registries agree.
*
* @param {string} [origin] public app origin (defaults to env.APP_ORIGIN)
*/
export function erc8004RegistryFields(origin = env.APP_ORIGIN) {
const o = String(origin || env.APP_ORIGIN).replace(/\/$/, '');
return {
active: true,
x402Support: true,
webEndpoint: o,
a2aEndpoint: `${o}/.well-known/agent-card.json`,
a2aVersion: '0.3.0',
mcpEndpoint: `${o}/api/mcp`,
mcpVersion: '2025-06-18',
supportedTrusts: ['reputation'],
};
}
// ── Agent token (pump.fun) ───────────────────────────────────────────────────
/**
* Off-chain JSON for a pump.fun token. pump.fun's UI reads name/symbol/
* description/image/showName/createdOn/twitter/telegram/website — we fill those
* so the coin page links back to three.ws and our X. Extra standard fields
* (external_url, attributes, properties) are ignored by pump.fun but render in
* wallets and explorers.
*
* @param {object} t
* @param {string} t.name
* @param {string} t.symbol
* @param {string} [t.description]
* @param {string} [t.image]
* @param {string} [t.website] defaults to the agent page (falls back to three.ws)
* @param {string} [t.twitter] defaults to the three.ws X account
* @param {string} [t.telegram] defaults to the three.ws Telegram channel
* @param {string} [t.agentUrl] agent profile page
* @param {string} [t.creatorAddress]
* @param {string} [t.createdAt] ISO timestamp
*/
// Attribution suffix stamped onto every user-provided pump.fun token description.
// Keeps the attribution short so it doesn't crowd out the user's copy.
const THREE_WS_ATTRIBUTION = '\n\nLaunched on three.ws · 3D AI agents on-chain.';
export function buildTokenMetadata(t) {
const tok = threeTokenLinks();
const website = t.website || t.agentUrl || THREE_WS.website;
const twitter = t.twitter || THREE_WS.x;
const telegram = t.telegram || THREE_WS.telegram;
const userDesc = t.description?.trim() || '';
const ATTR_LEN = THREE_WS_ATTRIBUTION.length;
const description = userDesc
? `${userDesc.slice(0, 500 - ATTR_LEN)}${THREE_WS_ATTRIBUTION}`
: `${t.name} — an autonomous agent token launched on ${THREE_WS.name}. ${THREE_WS_ATTRIBUTION.trim()}`;
const attributes = [
{ trait_type: 'Platform', value: THREE_WS.name },
{ trait_type: 'Launchpad', value: 'pump.fun' },
{ trait_type: '$THREE', value: tok.mint },
...(t.agentUrl ? [{ trait_type: '3D Agent', value: t.agentUrl }] : []),
];
// The coin's 3D agent travels with it: the agent page, plus the avatar GLB as
// the standard `animation_url` (wallets and explorers that render 3D read it).
const files = [
...(t.image ? [{ uri: t.image, type: 'image/png' }] : []),
...(t.agentModelUrl ? [{ uri: t.agentModelUrl, type: 'model/gltf-binary' }] : []),
];
const json = {
name: t.name,
symbol: t.symbol,
description,
image: t.image || '',
showName: true,
createdOn: THREE_WS.website,
website,
twitter,
telegram,
// Standard + brand extras (explorers/wallets read these; pump ignores them)
external_url: website,
...(t.agentModelUrl ? { animation_url: t.agentModelUrl } : {}),
attributes,
properties: {
category: 'image',
...(files.length ? { files } : {}),
creators: creators(t.creatorAddress),
},
...(t.agentUrl ? { agent: { url: t.agentUrl, ...(t.agentModelUrl ? { model: t.agentModelUrl } : {}) } } : {}),
platform: {
name: THREE_WS.name,
url: THREE_WS.website,
x: THREE_WS.x,
telegram: THREE_WS.telegram,
github: THREE_WS.github,
},
token: { symbol: tok.symbol, mint: tok.mint, url: tok.pumpfun },
...(t.createdAt ? { createdAt: t.createdAt } : {}),
};
return json;
}