Skip to content

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.

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.js
index 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.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.' }),
+ };
+ },
+};