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
feat(metaplex-mcp): charge a mainnet deploy fee that $THREE holders get waived
nirholasd5ceb42e2a61
diff --git a/packages/metaplex-agent-mcp/src/config.js b/packages/metaplex-agent-mcp/src/config.jsindex 86ce863d1..1c84ffbf1 100644--- a/packages/metaplex-agent-mcp/src/config.js+++ b/packages/metaplex-agent-mcp/src/config.js@@ -84,4 +84,48 @@ export const HTTP_TIMEOUT_MS = (() => {return n;})();+// ── $THREE: the deploy fee and the holder waiver ──────────────────────────+//+// Every MAINNET deploy through this server carries a flat protocol fee, paid in+// SOL, in the SAME transaction that creates the asset (so a failed mint pays+// nothing). The fee lands in the wallet the three.ws $THREE buyback lane signs+// from, which turns platform revenue into on-chain $THREE buys+// (https://three.ws/api/three-token/stats is the public ledger).+//+// Holding $THREE is what makes it cheaper or free. The balance is read live from+// the paying wallet at build time; nothing is escrowed, staked, or spent.+// Devnet is always free, so a full rehearsal still costs nothing.++// $THREE is the only coin this server references, and the ONLY reason to+// override THREE_MINT is to track an updated canonical contract. Never point it+// at a different coin.+export const THREE_MINT = env('THREE_MINT', 'FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump');+export const THREE_DECIMALS = 6;++// Where the fee goes: the three.ws economy/buyback signer. Override only when+// self-hosting a fork whose fees should fund something else.+export const DEPLOY_FEE_WALLET = env('DEPLOY_FEE_WALLET', 'WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW');++function positiveNumber(key, fallback) {+ const raw = env(key);+ if (raw === undefined) return fallback;+ const n = Number(raw);+ if (!Number.isFinite(n) || n < 0) {+ throw Object.assign(new Error(`${key} must be a non-negative number (got "${raw}")`), { code: 'bad_config' });+ }+ return n;+}++export const DEPLOY_FEE_SOL = positiveNumber('DEPLOY_FEE_SOL', 0.02);++export const DEPLOY_FEE_ENABLED = (() => {+ const raw = env('DEPLOY_FEE_ENABLED');+ if (raw === undefined) return true;+ return !['0', 'false', 'no', 'off'].includes(String(raw).toLowerCase());+})();++// Holder thresholds, in whole $THREE tokens, read from the paying wallet.+export const THREE_HALF_PRICE_AT = positiveNumber('THREE_HALF_PRICE_AT', 50_000);+export const THREE_FREE_AT = positiveNumber('THREE_FREE_AT', 250_000);+export const USER_AGENT = '@three-ws/metaplex-agent-mcp';diff --git a/packages/metaplex-agent-mcp/src/index.js b/packages/metaplex-agent-mcp/src/index.jsindex 01b00a1fc..38c640763 100755--- a/packages/metaplex-agent-mcp/src/index.js+++ b/packages/metaplex-agent-mcp/src/index.js@@ -11,6 +11,7 @@// • agent_wallet : an agent's built-in wallet (Asset Signer PDA) + balance// • build_registration : the EIP-8004 document + data: URI, offline// • list_onchain_agents : the live registration feed+// • three_status : deploy fee, $THREE holder tier, live buyback ledger//// Self-custodial: mints are signed by YOUR key (SOLANA_SECRET_KEY) or your own// browser wallet via prepare/send. The read tools and the wallet flow need no@@ -36,6 +37,7 @@ import { def as getOnchainAgent } from './tools/get-onchain-agent.js';import { def as agentWallet } from './tools/agent-wallet.js';import { def as buildRegistration } from './tools/build-registration.js';import { def as listOnchainAgents } from './tools/list-onchain-agents.js';+import { def as threeStatus } from './tools/three-status.js';const require = createRequire(import.meta.url);const { version: PKG_VERSION } = require('../package.json');@@ -49,6 +51,7 @@ export const TOOLS = [agentWallet,buildRegistration,listOnchainAgents,+ threeStatus,];/**@@ -68,8 +71,11 @@ export function buildServer() {'(one atomic tx, signed by SOLANA_SECRET_KEY, ~0.007 SOL, gated by confirm:true). prepare_agent_mint ' +'+ send_signed_transaction are the SAME mint for a human wallet (Phantom, Solflare, anything) with ' +'no key configured. register_agent_identity enrols an existing Core asset. get_onchain_agent, ' +- 'agent_wallet, build_registration, and list_onchain_agents are read-only. Every Core plugin and ' +- 'metadata field is customizable; the defaults reproduce the three.ws Genesis mint shape exactly.',+ 'agent_wallet, build_registration, list_onchain_agents, and three_status are read-only. Every Core ' ++ 'plugin and metadata field is customizable; the defaults reproduce the three.ws Genesis mint shape ' ++ 'exactly. A mainnet deploy also carries a flat SOL deploy fee that funds $THREE buybacks, always ' ++ 'disclosed in the preview before anything is signed; holding $THREE halves it and then waives it, ' ++ 'and devnet is free. three_status prices it against any wallet.',},);diff --git a/packages/metaplex-agent-mcp/src/lib/index.js b/packages/metaplex-agent-mcp/src/lib/index.jsindex d7f61e776..10823843d 100644--- a/packages/metaplex-agent-mcp/src/lib/index.js+++ b/packages/metaplex-agent-mcp/src/lib/index.js@@ -19,6 +19,16 @@ export {isAssetPropagationError,} from './mint.js';+export {+ THREE_STATS_URL,+ feeSchedule,+ threeBalance,+ tierFor,+ nextTier,+ resolveDeployFee,+ threeStats,+} from './three.js';+export {LAMPORTS_PER_SOL,EST_MINT_LAMPORTS,diff --git a/packages/metaplex-agent-mcp/src/lib/mint.js b/packages/metaplex-agent-mcp/src/lib/mint.jsindex 6213a5822..a6bc8ec21 100644--- a/packages/metaplex-agent-mcp/src/lib/mint.js+++ b/packages/metaplex-agent-mcp/src/lib/mint.js@@ -13,7 +13,8 @@// of both JSON documents (or complete URI overrides).import { create, ruleSet } from '@metaplex-foundation/mpl-core';-import { generateSigner, publicKey as umiPublicKey } from '@metaplex-foundation/umi';+import { generateSigner, publicKey as umiPublicKey, sol } from '@metaplex-foundation/umi';+import { transferSol } from '@metaplex-foundation/mpl-toolbox';import { registerIdentityV1 } from '@metaplex-foundation/mpl-agent-registry';import {@@ -116,6 +117,8 @@ export function buildAgentMint(umi, {permanentTransfer,permanentBurn,addBlocker,+ feeLamports = 0,+ feeWallet,} = {}) {const assetSigner = generateSigner(umi);const assetAddress = assetSigner.publicKey.toString();@@ -168,7 +171,22 @@ export function buildAgentMint(umi, {const registerArgs = { asset: assetSigner.publicKey, agentRegistrationUri };if (collection) registerArgs.collection = umiPublicKey(collection);- const createBuilder = create(umi, createArgs);+ // The $THREE deploy fee rides on the CREATE transaction, never on its own.+ // One transaction means the fee moves if and only if the asset is created:+ // a mint that fails, is rejected, or expires costs the payer nothing. The+ // caller resolves the amount (lib/three.js) and always discloses it first.+ const fee = Math.max(0, Math.floor(Number(feeLamports) || 0));+ if (fee > 0 && !feeWallet) {+ throw Object.assign(new Error('feeLamports was set without a feeWallet to pay it to'), {+ code: 'validation_error',+ });+ }+ const createBuilder =+ fee > 0+ ? transferSol(umi, { destination: umiPublicKey(feeWallet), amount: sol(fee / 1_000_000_000) }).add(+ create(umi, createArgs),+ )+ : create(umi, createArgs);const registerBuilder = registerIdentityV1(umi, registerArgs);const combinedBuilder = createBuilder.add(registerBuilder);@@ -180,6 +198,8 @@ export function buildAgentMint(umi, {return {atomic,+ feeLamports: fee,+ feeWallet: fee > 0 ? String(feeWallet) : null,builders: atomic ? [combinedBuilder] : [createBuilder, registerBuilder],createBuilder,registerBuilder,diff --git a/packages/metaplex-agent-mcp/src/lib/three.js b/packages/metaplex-agent-mcp/src/lib/three.jsnew file mode 100644index 000000000..af46c137c--- /dev/null+++ b/packages/metaplex-agent-mcp/src/lib/three.js@@ -0,0 +1,185 @@+// $THREE: the deploy fee, the holder waiver, and the live protocol read.+//+// Two things live here, and they point the same way:+//+// 1. THE FEE. A mainnet deploy pays a flat SOL fee to the wallet the three.ws+// $THREE buyback lane signs from. It rides in the SAME transaction that+// creates the Core asset, so a mint that fails pays nothing, and it is+// always disclosed in the preview before anything is broadcast.+// 2. THE WAIVER. Hold $THREE in the paying wallet and the fee halves, then+// disappears. The balance is read live from the chain at build time.+// Nothing is escrowed, transferred, locked, or spent to earn it.+//+// Devnet is free, always: a full end-to-end rehearsal costs nothing but rent.+//+// Browser-safe: no node built-ins, RPC through the Umi instance you pass in.++import {+ THREE_MINT,+ THREE_DECIMALS,+ DEPLOY_FEE_WALLET,+ DEPLOY_FEE_SOL,+ DEPLOY_FEE_ENABLED,+ THREE_HALF_PRICE_AT,+ THREE_FREE_AT,+ THREE_WS_BASE,+ HTTP_TIMEOUT_MS,+ USER_AGENT,+} from '../config.js';+import { LAMPORTS_PER_SOL } from './solana.js';++export const THREE_STATS_URL = `${THREE_WS_BASE}/api/three-token/stats`;++/** The fee schedule as configured, with no chain reads. Safe to render anywhere. */+export function feeSchedule() {+ const lamports = Math.round(DEPLOY_FEE_SOL * LAMPORTS_PER_SOL);+ return {+ enabled: DEPLOY_FEE_ENABLED && lamports > 0,+ mint: THREE_MINT,+ fee_wallet: DEPLOY_FEE_WALLET,+ standard_sol: lamports / LAMPORTS_PER_SOL,+ standard_lamports: lamports,+ half_price_at_three: THREE_HALF_PRICE_AT,+ free_at_three: THREE_FREE_AT,+ devnet_sol: 0,+ funds: 'the three.ws $THREE buyback wallet',+ ledger: THREE_STATS_URL,+ };+}++/**+ * Live $THREE balance of a wallet, in whole tokens.+ * Sums every token account the owner holds for the mint, so a wallet with both+ * a legacy and a Token-2022 account reports its real total.+ * @returns {Promise<{ tokens: number, atomics: bigint, accounts: number }>}+ */+export async function threeBalance(umi, address, { mint = THREE_MINT } = {}) {+ const res = await umi.rpc.call('getTokenAccountsByOwner', [+ String(address),+ { mint: String(mint) },+ { encoding: 'jsonParsed' },+ ]);+ const accounts = res?.value || [];+ let atomics = 0n;+ for (const acct of accounts) {+ const raw = acct?.account?.data?.parsed?.info?.tokenAmount?.amount;+ if (raw !== undefined) atomics += BigInt(raw);+ }+ return {+ tokens: Number(atomics) / 10 ** THREE_DECIMALS,+ atomics,+ accounts: accounts.length,+ };+}++/** Which tier a $THREE balance earns. Pure; the discount math lives here alone. */+export function tierFor(tokens) {+ if (tokens >= THREE_FREE_AT) return { tier: 'holder_free', multiplier: 0 };+ if (tokens >= THREE_HALF_PRICE_AT) return { tier: 'holder_half', multiplier: 0.5 };+ return { tier: 'standard', multiplier: 1 };+}++/** How much $THREE the wallet still needs for the next discount, or null at the top. */+export function nextTier(tokens) {+ if (tokens >= THREE_FREE_AT) return null;+ const target = tokens >= THREE_HALF_PRICE_AT ? THREE_FREE_AT : THREE_HALF_PRICE_AT;+ const tier = tokens >= THREE_HALF_PRICE_AT ? 'holder_free' : 'holder_half';+ const need = Math.max(0, target - tokens);+ return { tier, at_three: target, need_three: Math.round(need * 10 ** THREE_DECIMALS) / 10 ** THREE_DECIMALS };+}++const fmt = (n) => Number(n).toLocaleString('en-US', { maximumFractionDigits: 2 });++/**+ * Resolve what THIS deploy pays, from live chain state.+ *+ * Never throws on an unreadable balance: an RPC that cannot answer means the+ * discount cannot be proven, so the deploy pays standard and the response says+ * exactly why, instead of silently charging full price or silently waiving it.+ *+ * @returns {Promise<{ lamports: number, sol: number, tier: string, wallet: string|null,+ * three_tokens: number|null, three_balance_error?: string, reason: string }>}+ */+export async function resolveDeployFee(umi, { network, payer } = {}) {+ const schedule = feeSchedule();+ const base = { schedule, three_tokens: null, wallet: schedule.fee_wallet };++ if (!schedule.enabled) {+ return { ...base, lamports: 0, sol: 0, tier: 'disabled', wallet: null, reason: 'DEPLOY_FEE_ENABLED is off' };+ }+ if (network !== 'mainnet') {+ return { ...base, lamports: 0, sol: 0, tier: 'devnet', wallet: null, reason: 'devnet deploys are free' };+ }+ if (!payer) {+ return {+ ...base,+ lamports: schedule.standard_lamports,+ sol: schedule.standard_sol,+ tier: 'standard',+ reason: 'no paying wallet to check for $THREE',+ };+ }++ let balance = null;+ let balanceError = null;+ try {+ balance = await threeBalance(umi, payer);+ } catch (err) {+ balanceError = err?.message || String(err);+ }++ if (balance === null) {+ return {+ ...base,+ lamports: schedule.standard_lamports,+ sol: schedule.standard_sol,+ tier: 'standard',+ three_balance_error: balanceError,+ reason: 'could not read the wallet $THREE balance, so the holder discount could not be applied',+ };+ }++ const { tier, multiplier } = tierFor(balance.tokens);+ const lamports = Math.round(schedule.standard_lamports * multiplier);+ const reason =+ tier === 'holder_free'+ ? `wallet holds ${fmt(balance.tokens)} $THREE: deploy fee waived`+ : tier === 'holder_half'+ ? `wallet holds ${fmt(balance.tokens)} $THREE: deploy fee halved`+ : `wallet holds ${fmt(balance.tokens)} $THREE, under the ${fmt(THREE_HALF_PRICE_AT)} half-price threshold`;++ return {+ ...base,+ lamports,+ sol: lamports / LAMPORTS_PER_SOL,+ tier,+ three_tokens: balance.tokens,+ next_tier: nextTier(balance.tokens),+ wallet: lamports > 0 ? schedule.fee_wallet : null,+ reason,+ };+}++/**+ * The live $THREE protocol read: market data plus the public buyback ledger.+ * Real numbers from three.ws; there is no cached or synthetic fallback.+ */+export async function threeStats() {+ const ctrl = new AbortController();+ const timer = setTimeout(() => ctrl.abort(), HTTP_TIMEOUT_MS);+ try {+ const res = await fetch(THREE_STATS_URL, {+ signal: ctrl.signal,+ headers: { accept: 'application/json', 'user-agent': USER_AGENT },+ });+ if (!res.ok) {+ throw Object.assign(new Error(`$THREE stats returned ${res.status}`), {+ code: 'three_stats_error',+ status: res.status,+ });+ }+ return await res.json();+ } finally {+ clearTimeout(timer);+ }+}diff --git a/packages/metaplex-agent-mcp/src/tools/agent-wallet.js b/packages/metaplex-agent-mcp/src/tools/agent-wallet.jsindex dbfcaf5f7..d6a83fdef 100644--- a/packages/metaplex-agent-mcp/src/tools/agent-wallet.js+++ b/packages/metaplex-agent-mcp/src/tools/agent-wallet.js@@ -7,6 +7,7 @@ import { z } from 'zod';import { NETWORK, SOLANA_DEFAULT_SECRET } from '../config.js';import { buildUmi, solBalance, assetSignerAddress } from '../lib/solana.js';+import { threeBalance, tierFor, nextTier } from '../lib/three.js';export const def = {name: 'agent_wallet',@@ -16,7 +17,8 @@ export const def = {"Show a wallet address and its live SOL balance. Pass `asset` to derive an on-chain agent's built-in wallet " +'(the Metaplex Core Asset Signer PDA, the wallet shown on metaplex.com/agents). Pass `address` to inspect ' +'any wallet. Pass neither to see the configured signing wallet, e.g. to confirm it is funded before ' +- 'mint_onchain_agent. Read-only; never moves funds.',+ 'mint_onchain_agent. On mainnet it also reports the wallet $THREE balance and the deploy-fee tier that ' ++ 'balance earns (see three_status). Read-only; never moves funds.',inputSchema: {asset: z.string().min(32).max(44).optional().describe("A Core asset address: derives that agent's built-in wallet."),address: z.string().min(32).max(44).optional().describe('A wallet address to inspect verbatim.'),@@ -50,12 +52,27 @@ export const def = {}const sol = await solBalance(umi, address);++ // The $THREE read is mainnet-only (the mint does not exist on devnet) and+ // never fatal: a wallet lookup must still answer if the token RPC hiccups.+ let three = null;+ if (network === 'mainnet') {+ three = await threeBalance(umi, address).catch(() => null);+ }+return {ok: true,network,kind,address,sol,+ ...(three+ ? {+ three: three.tokens,+ three_tier: tierFor(three.tokens).tier,+ three_next_tier: nextTier(three.tokens),+ }+ : {}),...(args.asset ? { asset: args.asset } : {}),};},diff --git a/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.js b/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.jsindex 57a4d8ccc..7496e0601 100644--- a/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.js+++ b/packages/metaplex-agent-mcp/src/tools/mint-onchain-agent.js@@ -18,9 +18,23 @@ import {EST_REGISTER_LAMPORTS,LAMPORTS_PER_SOL,} from '../lib/solana.js';+import { resolveDeployFee } from '../lib/three.js';import { mintShape, mintParams } from './mint-shape.js';-const EST_TOTAL_SOL = (EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS) / LAMPORTS_PER_SOL;+const EST_NETWORK_SOL = (EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS) / LAMPORTS_PER_SOL;++/** The fee block every preview and every receipt renders, in one shape. */+function feeBlock(fee) {+ return {+ deploy_fee_sol: fee.sol,+ deploy_fee_to: fee.wallet,+ three_tier: fee.tier,+ three_balance: fee.three_tokens,+ three_note: fee.reason,+ ...(fee.next_tier ? { three_next_tier: fee.next_tier } : {}),+ ...(fee.three_balance_error ? { three_balance_error: fee.three_balance_error } : {}),+ };+}export const def = {name: 'mint_onchain_agent',@@ -44,17 +58,26 @@ export const def = {const umi = buildUmi({ network, secret: args.secret, requireSigner: true });const wallet = umi.identity.publicKey.toString();- const mint = buildAgentMint(umi, mintParams(args, { network, creator: wallet }));+ const fee = await resolveDeployFee(umi, { network, payer: wallet });+ const total = EST_NETWORK_SOL + fee.sol;+ const mint = buildAgentMint(+ umi,+ mintParams(args, { network, creator: wallet, feeLamports: fee.lamports, feeWallet: fee.wallet }),+ );const asset = mint.assetSigner.publicKey.toString();if (REQUIRE_CONFIRM && args.confirm !== true) {return {ok: true,confirm_required: true,- message: `Preview only. Re-issue with confirm:true to mint on ${network} for ~${EST_TOTAL_SOL} SOL.`,+ message:+ `Preview only. Re-issue with confirm:true to mint on ${network} for ~${total} SOL ` ++ `(~${EST_NETWORK_SOL} rent + network fees${fee.sol > 0 ? `, ${fee.sol} SOL deploy fee to ${fee.wallet}` : ', no deploy fee'}).`,network,paying_wallet: wallet,- estimated_cost_sol: EST_TOTAL_SOL,+ estimated_cost_sol: total,+ network_cost_sol: EST_NETWORK_SOL,+ ...feeBlock(fee),asset_metadata: mint.assetMetadata,metadata_uri_bytes: mint.metadataUri.length,registration: mint.registration,@@ -62,10 +85,10 @@ export const def = {}const balance = await solBalance(umi, wallet);- if (balance * LAMPORTS_PER_SOL < EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS) {+ if (balance * LAMPORTS_PER_SOL < EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS + fee.lamports) {throw Object.assign(new Error(- `Wallet ${wallet} holds ${balance} SOL on ${network}; the mint needs ~${EST_TOTAL_SOL} SOL. Fund it and retry.`,+ `Wallet ${wallet} holds ${balance} SOL on ${network}; this deploy needs ~${total} SOL. Fund it and retry.`,),{ code: 'insufficient_sol' },);@@ -82,6 +105,7 @@ export const def = {txs: signatures.map((s) => txLink(s, network)),owner: args.owner || wallet,agent_wallet: assetSignerAddress(umi, asset),+ ...feeBlock(fee),metadata_uri: mint.metadataUri,registration: mint.registration,links: agentLinks(asset, network),diff --git a/packages/metaplex-agent-mcp/src/tools/mint-shape.js b/packages/metaplex-agent-mcp/src/tools/mint-shape.jsindex a50792d4b..361f4c94b 100644--- a/packages/metaplex-agent-mcp/src/tools/mint-shape.js+++ b/packages/metaplex-agent-mcp/src/tools/mint-shape.js@@ -45,10 +45,12 @@ export const mintShape = {};/** Map snake_case tool args onto buildAgentMint camelCase params. */-export function mintParams(args, { network, creator }) {+export function mintParams(args, { network, creator, feeLamports = 0, feeWallet }) {return {network,creator,+ feeLamports,+ feeWallet,owner: args.owner,collection: args.collection,name: args.name,diff --git a/packages/metaplex-agent-mcp/src/tools/prepare-agent-mint.js b/packages/metaplex-agent-mcp/src/tools/prepare-agent-mint.jsindex 31969d66e..3cefaac40 100644--- a/packages/metaplex-agent-mcp/src/tools/prepare-agent-mint.js+++ b/packages/metaplex-agent-mcp/src/tools/prepare-agent-mint.js@@ -16,6 +16,7 @@ import {EST_REGISTER_LAMPORTS,LAMPORTS_PER_SOL,} from '../lib/solana.js';+import { resolveDeployFee } from '../lib/three.js';import { mintShape, mintParams } from './mint-shape.js';import { createNoopSigner, publicKey as umiPublicKey, signerIdentity } from '@metaplex-foundation/umi';@@ -40,7 +41,11 @@ export const def = {const umi = buildUmi({ network });umi.use(signerIdentity(createNoopSigner(umiPublicKey(args.wallet))));- const mint = buildAgentMint(umi, mintParams(args, { network, creator: args.wallet }));+ const fee = await resolveDeployFee(umi, { network, payer: args.wallet });+ const mint = buildAgentMint(+ umi,+ mintParams(args, { network, creator: args.wallet, feeLamports: fee.lamports, feeWallet: fee.wallet }),+ );const asset = mint.assetSigner.publicKey.toString();const txsBase64 = [];@@ -57,7 +62,13 @@ export const def = {agent_wallet: assetSignerAddress(umi, asset),atomic: mint.atomic,txs_base64: txsBase64,- estimated_cost_sol: (EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS) / LAMPORTS_PER_SOL,+ estimated_cost_sol: (EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS) / LAMPORTS_PER_SOL + fee.sol,+ network_cost_sol: (EST_MINT_LAMPORTS + EST_REGISTER_LAMPORTS) / LAMPORTS_PER_SOL,+ deploy_fee_sol: fee.sol,+ deploy_fee_to: fee.wallet,+ three_tier: fee.tier,+ three_balance: fee.three_tokens,+ three_note: fee.reason,asset_metadata: mint.assetMetadata,registration: mint.registration,links: agentLinks(asset, network),diff --git a/packages/metaplex-agent-mcp/src/tools/three-status.js b/packages/metaplex-agent-mcp/src/tools/three-status.jsnew file mode 100644index 000000000..8d475fdb8--- /dev/null+++ b/packages/metaplex-agent-mcp/src/tools/three-status.js@@ -0,0 +1,83 @@+// `three_status`: what a deploy costs, why, and where the fee goes.+//+// One read that answers three questions at once:+// • what will MY next deploy cost (live $THREE balance -> tier -> SOL)+// • what is the fee schedule and which wallet receives it+// • what has the $THREE buyback lane actually done (public ledger, real numbers)+//+// Everything here is live: the balance from Solana, the market and buyback+// figures from the public three.ws endpoint. Nothing is cached or synthesized;+// if the endpoint is unreachable the tool says so rather than inventing a number.++import { z } from 'zod';++import { NETWORK, SOLANA_DEFAULT_SECRET, THREE_MINT, THREE_WS_BASE } from '../config.js';+import { buildUmi } from '../lib/solana.js';+import { feeSchedule, resolveDeployFee, threeStats, THREE_STATS_URL } from '../lib/three.js';++export const def = {+ name: 'three_status',+ title: 'Deploy fee, $THREE holder tier, and the live buyback ledger',+ annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: true },+ description:+ 'What the next on-chain deploy costs and why. Returns the deploy-fee schedule (a flat SOL fee on mainnet, ' ++ 'free on devnet), the live $THREE balance of a wallet and the tier it earns (half price, then free), the ' ++ 'wallet the fee is paid to, and the live $THREE market + buyback figures from the public three.ws ledger. ' ++ 'Pass `wallet` to price a specific payer, or omit it to price the configured signer. Read-only: it moves ' ++ 'nothing and needs no key.',+ inputSchema: {+ wallet: z.string().min(32).max(44).optional().describe('Price the deploy fee for this wallet. Defaults to the configured signer.'),+ network: z.enum(['mainnet', 'devnet']).optional().describe('Cluster. Defaults to the configured network. Devnet deploys are always free.'),+ },+ async handler(args) {+ const network = args.network || NETWORK;+ const umi = buildUmi({ network });++ let payer = args.wallet ? String(args.wallet).trim() : null;+ if (!payer && SOLANA_DEFAULT_SECRET) {+ payer = buildUmi({ network, requireSigner: true }).identity.publicKey.toString();+ }++ const [fee, stats] = await Promise.all([+ resolveDeployFee(umi, { network, payer }),+ threeStats().catch((err) => ({ error: err?.message || String(err) })),+ ]);++ const schedule = feeSchedule();+ const priced = fee.three_tokens !== null && fee.three_tokens !== undefined;++ return {+ ok: true,+ network,+ mint: THREE_MINT,+ your_deploy: {+ wallet: payer,+ fee_sol: fee.sol,+ tier: fee.tier,+ three_balance: fee.three_tokens,+ note: fee.reason,+ ...(fee.next_tier ? { next_tier: fee.next_tier } : {}),+ ...(fee.three_balance_error ? { balance_error: fee.three_balance_error } : {}),+ },+ fee_schedule: {+ mainnet_sol: schedule.standard_sol,+ devnet_sol: 0,+ half_price_at_three: schedule.half_price_at_three,+ free_at_three: schedule.free_at_three,+ paid_to: schedule.fee_wallet,+ funds: schedule.funds,+ rides_on: 'the same transaction that creates the asset, so a failed mint pays nothing',+ },+ three: stats?.error ? { error: stats.error, source: THREE_STATS_URL } : stats?.token || null,+ buyback: stats?.error ? null : stats?.buyback || null,+ links: {+ ledger: THREE_STATS_URL,+ token_page: `${THREE_WS_BASE}/three`,+ chart: `https://dexscreener.com/solana/${THREE_MINT}`,+ },+ ...(priced+ ? {}+ : { hint: 'Pass `wallet` (or set SOLANA_SECRET_KEY) to price the fee against a real $THREE balance.' }),+ };+ },+};