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
// Shared, runtime-agnostic MCP tool definitions for the pump.fun MCP server.
// Imported by both the Vercel handler (api/pump-fun-mcp.js) and the
// Cloudflare Workers mirror (workers/pump-fun-mcp/worker.js).
// No imports — pure data and pure helpers only.
//
// ── Two pricing regimes, never blur them ────────────────────────────────────
// The tool descriptions here are the contract a model reads, so the two
// pump.fun pricing regimes have to stay distinct:
//
// Pre-graduation · pump program BondingCurve account. Spot price is
// virtual_quote_reserves / virtual_token_reserves (both u64). Those
// quote-side fields were renamed from virtual_sol_reserves /
// real_sol_reserves once a non-SOL quote asset became possible: same u64s,
// same offsets, new names. The curve also gained a quote_mint, which is the
// SOL default on every coin created to date. Surfaced by get_bonding_curve
// and social_x_post_impact.
//
// Post-graduation · PumpSwap (pump_amm) Pool account. Quotes price against the
// EFFECTIVE quote reserve: pool_quote_token_account.amount +
// pool.virtual_quote_reserves, a field appended to Pool. It is an i128 and
// commonly NEGATIVE: since 2026-09-30 the PumpSwap v2 trades and
// multi_hop_swap keep the protocol and creator fee inside the quote vault
// until a sweep pays them out, and subtract that amount here so waiting
// fees never count as liquidity. Effective depth can therefore sit below
// the raw vault balance; the program guarantees it is never negative. The
// base side is unchanged: still the raw pool_base_token_account.amount.
// Surfaced by pumpfun_quote_swap.
//
// The handoff · the v3 buy (buy_v3 / buy_exact_quote_in_v3) that empties a
// curve has no max size: it completes the curve and buys the rest through a
// synthetic migration, priced on the reserves the pool will open with. Once
// complete=true every curve trade fails until migration lands, so callers
// move to the pool.
//
// The two virtual_quote_reserves are DIFFERENT fields, on DIFFERENT accounts,
// with DIFFERENT widths, that happen to share a name. A coin has one or the
// other, never both.
// See docs/pumpfun-program/UPSTREAM-pumpswap-virtual-quote-reserves.md
// ── MCP ToolAnnotations (spec: readOnlyHint/destructiveHint/idempotentHint/
// openWorldHint). Every tool on this surface is read-only — nothing signs or
// sends a transaction. destructiveHint defaults to TRUE in the spec when
// omitted, so it is set explicitly everywhere.
//
// LIVE_READ live-market / on-chain read: same call can return new
// data, talks to external systems.
// DETERMINISTIC_READ external read whose answer is stable for the same args
// (name-service lookups).
// LOCAL_DETERMINISTIC pure in-process computation, stable output (lexicon
// sentiment scoring).
// LOCAL_GENERATIVE pure in-process computation, fresh output each call
// (vanity keypair grind).
const LIVE_READ = Object.freeze({
readOnlyHint: true,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
});
const DETERMINISTIC_READ = Object.freeze({
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
});
const LOCAL_DETERMINISTIC = Object.freeze({
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
});
const LOCAL_GENERATIVE = Object.freeze({
readOnlyHint: true,
destructiveHint: false,
idempotentHint: false,
openWorldHint: false,
});
// Canonical (snake_case) tool name ← legacy (camelCase) alias. tools/list only
// ever advertises the canonical names; tools/call accepts BOTH forever. This
// map is the single source of truth for that aliasing — the Vercel handler,
// the Cloudflare Worker, and the npm bridge all resolve through it (the bridge
// ships a vendored copy in packages/pumpfun-mcp/src/tools.js).
export const TOOL_NAME_ALIASES = Object.freeze({
searchTokens: 'search_tokens',
getTokenDetails: 'get_token_details',
getBondingCurve: 'get_bonding_curve',
getTokenTrades: 'get_token_trades',
getTrendingTokens: 'get_trending_tokens',
getNewTokens: 'get_new_tokens',
getGraduatedTokens: 'get_graduated_tokens',
getKingOfTheHill: 'get_king_of_the_hill',
getCreatorProfile: 'get_creator_profile',
getTokenHolders: 'get_token_holders',
});
// Resolve a tools/call name to its canonical form. Unknown names pass through
// unchanged so the dispatcher's own unknown-tool error still fires. hasOwn
// guard: "__proto__"/"constructor" must not resolve an inherited member.
export function resolveToolName(name) {
if (typeof name === 'string' && Object.hasOwn(TOOL_NAME_ALIASES, name)) {
return TOOL_NAME_ALIASES[name];
}
return name;
}
// name → { title, ...ToolAnnotations }. Applied onto TOOLS below; exported so
// runtimes (and the npm bridge) can overlay the same map on older tool lists.
// Keys are the canonical snake_case names — overlay callers resolve legacy
// names through TOOL_NAME_ALIASES first.
export const TOOL_ANNOTATIONS = Object.freeze({
search_tokens: { title: 'Search Tokens', ...LIVE_READ },
get_token_details: { title: 'Token Details', ...LIVE_READ },
get_bonding_curve: { title: 'Bonding Curve', ...LIVE_READ },
get_token_trades: { title: 'Token Trades', ...LIVE_READ },
get_trending_tokens: { title: 'Trending Tokens', ...LIVE_READ },
get_new_tokens: { title: 'New Tokens', ...LIVE_READ },
get_graduated_tokens: { title: 'Graduated Tokens', ...LIVE_READ },
get_king_of_the_hill: { title: 'King of the Hill', ...LIVE_READ },
get_creator_profile: { title: 'Creator Profile', ...LIVE_READ },
get_token_holders: { title: 'Token Holders', ...LIVE_READ },
pumpfun_vanity_mint: { title: 'Vanity Mint Keypair', ...LOCAL_GENERATIVE },
pumpfun_watch_whales: { title: 'Watch Whale Trades', ...LIVE_READ },
pumpfun_list_claims: { title: 'List Creator Fee Claims', ...LIVE_READ },
pumpfun_watch_claims: { title: 'Watch Creator Fee Claims', ...LIVE_READ },
pumpfun_first_claims: { title: 'First Creator Fee Claims', ...LIVE_READ },
sns_resolve: { title: 'Resolve .sol Domain', ...DETERMINISTIC_READ },
sns_reverseLookup: { title: 'Reverse .sol Lookup', ...DETERMINISTIC_READ },
social_cashtag_sentiment: { title: 'Cashtag Sentiment', ...LOCAL_DETERMINISTIC },
kol_leaderboard: { title: 'KOL Leaderboard', ...LIVE_READ },
get_coin_intel: { title: 'Coin Intel', ...LIVE_READ },
get_oracle_conviction: { title: 'Oracle Conviction', ...LIVE_READ },
pumpfun_quote_swap: { title: 'Swap Quote (Read-Only)', ...LIVE_READ },
social_x_post_impact: { title: 'X Post Price Impact', ...LIVE_READ },
pumpfun_upload_metadata: {
title: 'Upload Coin Metadata',
readOnlyHint: false,
destructiveHint: false,
idempotentHint: true,
openWorldHint: true,
},
pumpfun_bot_status: { title: 'Indexer Status', ...LIVE_READ },
});
// outputSchema policy: only tools whose response shape is code-controlled and
// genuinely stable advertise one (sns_resolve, sns_reverseLookup,
// social_cashtag_sentiment, pumpfun_vanity_mint, pumpfun_quote_swap,
// get_bonding_curve). Indexer/upstream-shaped passthroughs (search_tokens,
// get_token_details, get_token_trades, get_trending_tokens, get_new_tokens,
// get_graduated_tokens, get_king_of_the_hill, get_creator_profile,
// get_token_holders, kol_*, pumpfun_*_claims, pumpfun_watch_whales,
// social_x_post_impact) deliberately ship NO outputSchema — their payloads
// mirror upstream feeds / multi-source on-chain decoders that can evolve, and
// a wrong schema is worse than none.
export const TOOLS = [
{
name: 'search_tokens',
description:
'Search pump.fun tokens by name, symbol, or mint address. ' +
'Use this to find a coin\'s mint when you only know its name or ticker, then pass the mint to get_token_details or get_coin_intel.',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string' },
limit: { type: 'integer', minimum: 1, maximum: 50, default: 10 },
},
required: ['query'],
},
},
{
name: 'get_token_details',
description:
'Full details for a specific pump.fun token by mint address. ' +
'Use this when you already have a mint and need its metadata, market cap, and curve status; for holder concentration call get_token_holders, for recent fills call get_token_trades.',
inputSchema: {
type: 'object',
properties: { mint: { type: 'string' } },
required: ['mint'],
},
},
{
name: 'get_bonding_curve',
description:
'Bonding curve analysis: real reserves, virtual reserves, and graduation progress (on-chain). ' +
'Pre-graduation only: these reserves come from the pump program bonding-curve account, not from a ' +
'PumpSwap pool. Pump renamed the quote-side fields on-chain (real_sol_reserves -> real_quote_reserves, ' +
'virtual_sol_reserves -> virtual_quote_reserves) once a non-SOL quote asset became possible; the ' +
'response keys below keep their original names and are still denominated in SOL, because the curve ' +
'quote_mint is the SOL default on every coin created to date. A v3 buy that empties the curve ' +
'completes it and buys the rest through a synthetic migration, priced on the reserves the ' +
'PumpSwap pool will open with, so a large final buy is not capped at realTokenReserves. Once ' +
'complete=true the curve is retired and pricing moves to the PumpSwap pool, so use ' +
'pumpfun_quote_swap from that point on. ' +
'Use this to read graduation progress or the curve spot price of a coin that has not graduated yet.',
inputSchema: {
type: 'object',
properties: {
mint: { type: 'string' },
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['mint'],
},
outputSchema: {
type: 'object',
properties: {
mint: { type: 'string' },
network: { type: 'string' },
complete: { type: 'boolean', description: 'true once the curve has graduated' },
graduationPercent: { type: 'number', description: '0–100 graduation progress' },
solReserves: { type: 'string', description: 'Real quote reserves in SOL (4-decimal string). On-chain field: real_quote_reserves.' },
tokenReserves: { type: 'string', description: 'Real token reserves (raw base units)' },
virtualSolReserves: { type: 'string', description: 'Virtual quote reserves (lamports). On-chain field: virtual_quote_reserves (u64). Spot price = virtual_quote_reserves / virtual_token_reserves. Distinct from the identically-named PumpSwap Pool.virtual_quote_reserves (an i128), which applies only after graduation.' },
virtualTokenReserves: { type: 'string', description: 'Virtual token reserves (raw base units)' },
},
required: [
'mint',
'network',
'complete',
'graduationPercent',
'solReserves',
'tokenReserves',
'virtualSolReserves',
'virtualTokenReserves',
],
additionalProperties: true,
},
},
{
name: 'get_token_trades',
description:
'Recent buy/sell history for a token. ' +
'Use this to read recent buy and sell flow on one coin; to see only large trades as they land, call pumpfun_watch_whales instead.',
inputSchema: {
type: 'object',
properties: {
mint: { type: 'string' },
limit: { type: 'integer', minimum: 1, maximum: 200, default: 50 },
},
required: ['mint'],
},
},
{
name: 'get_trending_tokens',
description:
'Top pump.fun tokens by market cap. ' +
'Use this to scan the largest coins on pump.fun right now; for fresh launches call get_new_tokens, for coins that left the curve call get_graduated_tokens.',
inputSchema: {
type: 'object',
properties: { limit: { type: 'integer', minimum: 1, maximum: 50, default: 10 } },
},
},
{
name: 'get_new_tokens',
description:
'Most recently launched pump.fun tokens. ' +
'Use this to catch launches in their first minutes; for the largest coins by market cap call get_trending_tokens instead.',
inputSchema: {
type: 'object',
properties: { limit: { type: 'integer', minimum: 1, maximum: 50, default: 10 } },
},
},
{
name: 'get_graduated_tokens',
description:
'Tokens that graduated from the bonding curve to their PumpSwap (pump_amm) pool. ' +
'Use this to list coins that now trade on a PumpSwap pool, where pumpfun_quote_swap applies instead of get_bonding_curve.',
inputSchema: {
type: 'object',
properties: { limit: { type: 'integer', minimum: 1, maximum: 50, default: 10 } },
},
},
{
name: 'get_king_of_the_hill',
description:
'Highest-market-cap token still on the bonding curve. ' +
'Use this to find the coin closest to graduating among those still on the curve; for the full ranking call get_trending_tokens.',
inputSchema: { type: 'object', properties: {} },
},
{
name: 'get_creator_profile',
description:
'All tokens by a creator wallet, with rug-pull risk flags. ' +
'Use this to vet a dev wallet\'s launch history before buying one of its coins; for its fee cash-outs call pumpfun_list_claims.',
inputSchema: {
type: 'object',
properties: { creator: { type: 'string' } },
required: ['creator'],
},
},
{
name: 'get_token_holders',
description:
'Top holders of a token with concentration analysis (on-chain). ' +
'Use this to check whether a few wallets control the supply before buying; for price and volume call get_token_details instead.',
inputSchema: {
type: 'object',
properties: {
mint: { type: 'string' },
limit: { type: 'integer', minimum: 1, maximum: 20, default: 10 },
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['mint'],
},
},
{
name: 'pumpfun_vanity_mint',
description:
'Generate a Solana keypair whose address ends/starts with a vanity pattern. Returns publicKey + secretKey (base58). Caller must save the secret key immediately; it is never stored. Hard timeout: 60 s. ' +
'Use this before launching a coin when its mint address should carry a recognizable prefix or suffix.',
inputSchema: {
type: 'object',
properties: {
suffix: { type: 'string', description: 'Desired address suffix (case-insensitive by default)' },
prefix: { type: 'string', description: 'Desired address prefix (case-insensitive by default)' },
caseSensitive: { type: 'boolean', default: false },
maxAttempts: { type: 'integer', default: 5000000 },
},
},
outputSchema: {
type: 'object',
properties: {
publicKey: { type: 'string', description: 'Matched Solana address (base58)' },
secretKey: { type: 'string', description: 'Secret key (base58) — caller is sole custodian' },
attempts: { type: 'integer', description: 'Keypairs ground before the match' },
ms: { type: 'number', description: 'Wall-clock grind time in milliseconds' },
},
required: ['publicKey', 'secretKey', 'attempts', 'ms'],
additionalProperties: true,
},
},
{
name: 'pumpfun_watch_whales',
description:
'Collect whale trades on a pump.fun token for a short window (max 10 s). Returns all trades whose USD value meets minUsd. ' +
'Use this to see who is moving size on a coin right now; for the full recent tape call get_token_trades.',
inputSchema: {
type: 'object',
properties: {
mint: { type: 'string', description: 'SPL mint pubkey (base58)' },
minUsd: { type: 'number', description: 'Minimum trade value in USD (default 5000)' },
durationMs: {
type: 'number',
description: 'Collection window in ms (default 5000, max 10000)',
},
},
required: ['mint'],
},
},
{
name: 'pumpfun_list_claims',
description:
'List recent pump.fun fee-claim events for a creator wallet (on-chain, no indexer needed). Returns signature, mint, lamports, and Unix timestamp for each claim. Creator fees from the v3 curve and v2 pool trades wait on the curve and pool until a sweep_creator_fee moves them to the creator vault, so a claim covers only what was swept (usually in the same transaction) and fees still waiting appear in no claim yet. ' +
'Use this to audit how much a creator has already cashed out; for only the claims inside a recent window call pumpfun_watch_claims.',
inputSchema: {
type: 'object',
properties: {
creator: { type: 'string', description: 'Creator wallet address (base58)' },
limit: { type: 'integer', minimum: 1, maximum: 50, default: 20 },
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['creator'],
},
},
{
name: 'pumpfun_watch_claims',
description:
'Return all pump.fun fee-claim events for a creator wallet within a look-back window (durationMs). Use this for batch collection after a delay; for a creator\'s full recent claim history call pumpfun_list_claims.',
inputSchema: {
type: 'object',
properties: {
creator: { type: 'string', description: 'Creator wallet address (base58)' },
durationMs: {
type: 'number',
description: 'Look-back window in ms (default 300000 = 5 min, max 1800000)',
},
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['creator'],
},
},
{
name: 'pumpfun_first_claims',
description:
'First-ever pump.fun creator fee claims in a time window: a cash-out signal. Returns creators who have never claimed before, with creator wallet, mint, lamports, and timestamp. ' +
'Use this to spot creators cashing out for the first time across all coins; for one creator\'s history call pumpfun_list_claims.',
inputSchema: {
type: 'object',
properties: {
sinceMinutes: {
type: 'integer',
minimum: 1,
maximum: 1440,
default: 60,
description: 'How far back to look for new claimers (minutes)',
},
limit: { type: 'integer', minimum: 1, maximum: 50, default: 20 },
},
},
},
{
name: 'sns_resolve',
description:
'Resolve a .sol Solana Name Service domain to its owner wallet address. ' +
'Use this when a wallet is named by its .sol domain and you need the address; for the reverse direction call sns_reverseLookup.',
inputSchema: {
type: 'object',
properties: {
name: { type: 'string', description: '.sol domain name, e.g. "bonfida.sol"' },
},
required: ['name'],
},
outputSchema: {
type: 'object',
properties: {
name: { type: 'string', description: 'The .sol domain that was resolved' },
address: { type: 'string', description: 'Owner wallet address (base58)' },
},
required: ['name', 'address'],
additionalProperties: true,
},
},
{
name: 'sns_reverseLookup',
description:
'Reverse-lookup a Solana wallet address to its primary .sol domain name. ' +
'Use this to label a raw wallet address with its human-readable .sol name; to go from name to address call sns_resolve.',
inputSchema: {
type: 'object',
properties: {
address: { type: 'string', description: 'Base58 Solana wallet address' },
},
required: ['address'],
},
outputSchema: {
type: 'object',
properties: {
address: { type: 'string', description: 'The wallet address that was looked up' },
name: { type: 'string', description: 'Primary .sol domain for the address' },
},
required: ['address', 'name'],
additionalProperties: true,
},
},
{
name: 'social_cashtag_sentiment',
description:
'Score social-post sentiment for a cashtag using a deterministic lexicon. Returns score (-1..1), positive/negative/neutral percentages, and example posts. ' +
'Use this to score posts you have already collected; it fetches nothing itself, so pass the posts in.',
inputSchema: {
type: 'object',
properties: {
posts: {
type: 'array',
description: 'Array of post objects. Each must have a text field; id, ts, and author are optional.',
items: {
type: 'object',
properties: {
id: { type: 'string' },
ts: { type: 'string' },
text: { type: 'string' },
author: { type: 'string' },
},
required: ['text'],
},
},
},
required: ['posts'],
},
outputSchema: {
type: 'object',
properties: {
score: { type: 'number', description: 'Net sentiment, -1 (bearish) to 1 (bullish)' },
posPct: { type: 'number', description: 'Percentage of positive posts (0–100)' },
negPct: { type: 'number', description: 'Percentage of negative posts (0–100)' },
neuPct: { type: 'number', description: 'Percentage of neutral posts (0–100)' },
count: { type: 'integer', description: 'Number of posts scored' },
examples: {
type: 'object',
properties: {
pos: { type: 'array', items: { type: 'string' } },
neg: { type: 'array', items: { type: 'string' } },
},
required: ['pos', 'neg'],
additionalProperties: true,
},
},
required: ['score', 'posPct', 'negPct', 'neuPct', 'count', 'examples'],
additionalProperties: true,
},
},
{
name: 'kol_leaderboard',
description:
'Top KOL traders ranked by P&L for a given time window. Returns wallet, pnlUsd, winRate, trades, rank. ' +
'Use this to find which trader wallets are worth following; to see whether they hold a given coin, call get_coin_intel or get_token_holders.',
inputSchema: {
type: 'object',
properties: {
window: { type: 'string', enum: ['24h', '7d', '30d'], default: '7d' },
limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 },
},
},
},
{
name: 'pumpfun_quote_swap',
description:
'Read-only price quote for a pump.fun AMM (PumpSwap) swap. No signing or tx sending. One of inputMint/outputMint must be wSOL (So11111111111111111111111111111111111111112). Only GRADUATED coins have an AMM pool; for a coin still on its bonding curve use get_bonding_curve instead. Pricing runs on the pool effective quote reserves (quote vault balance + pool.virtual_quote_reserves, a SIGNED i128 that is commonly negative because PumpSwap v2 trades keep waiting protocol and creator fees in the vault and subtract them there); the base side is the raw base vault balance. Returns amountOut, priceImpactBps, route, expiresAtMs, plus the reserves the quote was computed from so the number can be reproduced. ' +
'Use this to size a trade on a graduated coin, or to measure its pool depth, before executing anywhere.',
inputSchema: {
type: 'object',
properties: {
inputMint: { type: 'string', description: 'Input token mint (base58).' },
outputMint: { type: 'string', description: 'Output token mint (base58).' },
amountIn: { type: 'number', description: 'Input amount in raw base units (lamports for SOL).' },
slippageBps: { type: 'number', description: 'Slippage tolerance in basis points (default 100 = 1%).' },
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['inputMint', 'outputMint', 'amountIn'],
},
outputSchema: {
type: 'object',
properties: {
amountOut: { type: 'string', description: 'Expected output amount in raw base units' },
priceImpactBps: { type: 'number', description: 'Price impact in basis points' },
route: { type: 'string', description: 'AMM pool address the quote routes through (base58)' },
expiresAtMs: { type: 'number', description: 'Epoch ms after which the quote is stale' },
base_reserve: {
type: 'string',
description: 'Raw base vault balance. Unchanged by the virtual-reserve rollout.',
},
quote_reserve: {
type: 'string',
description: 'Raw quote vault balance, before virtual reserves are added. Includes protocol and creator fees waiting for a sweep, so it overstates liquidity on its own; price on effective_quote_reserve.',
},
virtual_quote_reserves: {
type: 'string',
description:
'Pool.virtual_quote_reserves, a SIGNED i128 serialized as a decimal string. Positive values ' +
'add depth held outside the vault; negative values remove fees that sit in the vault ' +
'waiting for a sweep (common since the PumpSwap v2 trades). Parse it as a signed ' +
'integer: never unsigned, never clamped to 0, never absolute-valued.',
},
effective_quote_reserve: {
type: 'string',
description:
'quote_reserve + virtual_quote_reserves (signed addition). This is what the quote is priced against; the program guarantees it is never negative.',
},
},
required: ['amountOut', 'priceImpactBps', 'route', 'expiresAtMs'],
additionalProperties: true,
},
},
{
name: 'social_x_post_impact',
description:
'Correlate an X (Twitter) post to a memecoin price impact. Fetches post metadata via oEmbed (no API key) and computes price delta from the pump.fun bonding curve in a ±windowMin window around the post. ' +
'Use this to measure how one X post moved a coin that is still on its bonding curve (pricing is virtual_quote_reserves / virtual_token_reserves); a graduated coin has no curve, so the call fails rather than returning a zero price.',
inputSchema: {
type: 'object',
properties: {
postUrl: { type: 'string', description: 'X post URL (e.g. https://x.com/user/status/123)' },
mint: { type: 'string', description: 'Solana token mint address (base58)' },
windowMin: {
type: 'integer',
default: 30,
description: '±window in minutes around the post time',
},
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['postUrl', 'mint'],
},
},
{
name: 'get_coin_intel',
description:
'Full Coin Intelligence snapshot for a pump.fun mint. Returns every signal the engine recorded during the observation window: bundle vs organic verdict, bubblemaps-style cluster connectivity, smart-money presence (with wallet labels and win-rates), dev behaviour, category/classification, news-meme detection with the matching headline, risk flags, and a 0-100 quality score. Also returns the outcome if the coin is old enough to be labeled (graduated/rugged/ATH multiple). This is the single highest-signal read for a trade decision. Call this before entering any position.',
inputSchema: {
type: 'object',
properties: {
mint: { type: 'string', description: 'Solana mint address (base58).' },
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['mint'],
},
outputSchema: {
type: 'object',
properties: {
found: { type: 'boolean' },
mint: { type: 'string' },
symbol: { type: 'string' },
name: { type: 'string' },
quality_score: { type: 'number', description: '0–100 composite quality.' },
verdict: {
type: 'object',
properties: {
key: { type: 'string', enum: ['strong', 'watch', 'caution', 'avoid'] },
label: { type: 'string' },
tone: { type: 'string' },
},
},
risk_flags: { type: 'array', items: { type: 'string' } },
category: { type: 'string' },
is_news_meme: { type: 'boolean' },
news_headline: { type: 'string', nullable: true },
organic_score: { type: 'number', description: '0–1, organic-demand likelihood.' },
bundle_score: { type: 'number', description: '0–1, coordinated-launch likelihood.' },
bubblemap_connectivity: { type: 'number', nullable: true, description: '0–1 wallet-cluster share. null = enrichment not yet run.' },
smart_money_count: { type: 'integer', description: 'Proven wallets (score≥65) in this coin.' },
smart_money_score: { type: 'number', nullable: true },
smart_money_notable: { type: 'array', items: { type: 'object' } },
dev_buy_sol: { type: 'number', nullable: true },
dev_sold: { type: 'boolean' },
unique_buyers: { type: 'integer' },
outcome: { type: 'object', nullable: true, description: 'Labeled outcome if available (graduated, ath_multiple, etc).' },
oracle: {
type: 'object',
nullable: true,
description: 'Fused Oracle conviction score (null if the Oracle engine has not yet scored this coin). Call get_oracle_conviction for the full read including who\'s-in roster and narrative.',
properties: {
score: { type: 'number', description: '0–100 fused Oracle score.' },
tier: { type: 'string', enum: ['prime', 'strong', 'lean', 'watch', 'avoid'] },
pillars: { type: 'object', description: 'Per-pillar scores: pedigree, structure, narrative, momentum (each 0–100).' },
badges: { type: 'array', items: { type: 'string' } },
reasons: { type: 'array', items: { type: 'string' }, description: 'Natural-language explanation of the score.' },
},
},
oracle_url: { type: 'string', description: 'Oracle deep-link for the coin — opens the Oracle war-room drawer directly.' },
},
required: ['found'],
additionalProperties: true,
},
},
{
name: 'get_oracle_conviction',
description:
'Oracle conviction score for a pump.fun mint: the fused 0-100 score the Oracle engine produces by combining four intelligence pillars: pedigree (who bought it), structure (organic vs bundle, holder concentration, bubblemaps connectivity), narrative (category, meme virality, news hook), and momentum (timing, velocity). Returns the tier (prime ≥86 / strong ≥72 / lean ≥54 / watch ≥36 / avoid), the per-pillar breakdown, the natural-language reasons that drove the score, the full "who\'s in" trader roster with reputation labels and win-rates, and the narrative read (category, virality, tags). Call this when you need the highest-confidence trade signal; it synthesises everything get_coin_intel exposes into one actionable score. Pairs with get_coin_intel for raw signals.',
inputSchema: {
type: 'object',
properties: {
mint: { type: 'string', description: 'Solana mint address (base58).' },
network: { type: 'string', enum: ['mainnet', 'devnet'], default: 'mainnet' },
},
required: ['mint'],
},
outputSchema: {
type: 'object',
properties: {
found: { type: 'boolean' },
mint: { type: 'string' },
symbol: { type: 'string' },
name: { type: 'string' },
conviction: {
type: 'object',
nullable: true,
description: 'Fused conviction verdict. null if the Oracle has not yet scored this coin.',
properties: {
score: { type: 'number', description: '0–100 fused Oracle score.' },
tier: { type: 'string', enum: ['prime', 'strong', 'lean', 'watch', 'avoid'], description: 'prime ≥86, strong ≥72, lean ≥54, watch ≥36, avoid <36.' },
pillars: {
type: 'object',
properties: {
pedigree: { type: 'number', description: 'Smart-money pedigree pillar score (0–100, weight 34%).' },
structure: { type: 'number', description: 'Structure pillar score: organic/bundle/concentration/connectivity (0–100, weight 30%).' },
narrative: { type: 'number', description: 'Narrative pillar score: category fit, meme virality, news hook (0–100, weight 18%).' },
momentum: { type: 'number', description: 'Momentum pillar score: velocity, buy/sell ratio, timing entropy (0–100, weight 18%).' },
},
},
structure_cap: { type: 'boolean', description: 'true when structural flags capped the score below raw pillar math.' },
badges: { type: 'array', items: { type: 'string' }, description: 'Short human-readable badges attached to this coin, e.g. "Smart money: 3 wallets".' },
reasons: { type: 'array', items: { type: 'string' }, description: 'Natural-language sentences explaining every signal that drove the score.' },
scored_at: { type: 'string', description: 'ISO timestamp when the conviction was last computed.' },
},
},
narrative: {
type: 'object',
nullable: true,
description: 'Narrative classification for the coin.',
properties: {
category: { type: 'string', description: 'E.g. meme, ai, tech, culture, news, defi.' },
narrative: { type: 'string', description: 'One-sentence description of the coin\'s story or hook.' },
virality: { type: 'number', nullable: true, description: '0–1 estimated virality of the narrative.' },
confidence: { type: 'number', nullable: true },
tags: { type: 'array', items: { type: 'string' } },
source: { type: 'string', description: 'Classifier that produced the narrative read.' },
},
},
whos_in: {
type: 'array',
description: 'Classified trader roster — every wallet that touched this coin, annotated with their reputation.',
items: {
type: 'object',
properties: {
wallet: { type: 'string' },
label: { type: 'string', description: 'Trader archetype: smart_money, kol, sniper, whale, early_degen, recycler, dca_buyer, dca_seller, bot, unproven.' },
score: { type: 'number', nullable: true, description: 'Brain reputation score (0–100).' },
win_rate: { type: 'number', nullable: true, description: 'Historical win-rate (0–1).' },
early_win_rate: { type: 'number', nullable: true, description: 'Win-rate on early entries specifically.' },
source: { type: 'string', nullable: true, description: '"brain" (trained) or "gmgn" (seed corpus).' },
tag: { type: 'string', nullable: true, description: 'Social handle when known (from seed corpus).' },
buy_sol: { type: 'number', description: 'Total SOL bought.' },
sell_sol: { type: 'number', description: 'Total SOL sold.' },
is_creator: { type: 'boolean' },
funder: { type: 'string', nullable: true, description: 'The wallet that funded this one (if identified).' },
},
},
},
outcome: {
type: 'object',
nullable: true,
description: 'Labeled outcome if available.',
properties: {
outcome: { type: 'string' },
graduated: { type: 'boolean' },
rugged: { type: 'boolean' },
ath_market_cap_usd: { type: 'number', nullable: true },
ath_multiple: { type: 'number', nullable: true },
},
},
url: { type: 'string', description: 'Oracle deep-link URL for this coin.' },
},
required: ['found'],
additionalProperties: true,
},
},
{
name: 'pumpfun_upload_metadata',
description:
'Upload coin metadata (name, symbol, description, image) to IPFS and get back a pump.fun-ready metadata URI. Call this before launching a coin: pass the returned uri to the launch-agent endpoint or the studio launch flow. Requires a valid bearer token (API key). Image may be a public HTTPS URL or a base64 data URI (max 10 MB). The returned uri is a permanent ipfs:// link; the call is idempotent for the same content.',
inputSchema: {
type: 'object',
properties: {
name: { type: 'string', description: 'Coin name (1–32 chars).' },
symbol: { type: 'string', description: 'Ticker symbol (1–10 chars, no $).' },
description: { type: 'string', description: 'Coin description (max 500 chars).' },
image_url: {
type: 'string',
description:
'Image for the coin icon. Public HTTPS URL or base64 data URI (data:image/png;base64,…). Square image, at least 400×400 px, under 5 MB.',
},
twitter: { type: 'string', description: 'Twitter/X handle or URL (optional).' },
telegram: { type: 'string', description: 'Telegram URL (optional).' },
website: { type: 'string', description: 'Website URL (optional).' },
},
required: ['name', 'symbol', 'description', 'image_url'],
},
outputSchema: {
type: 'object',
properties: {
uri: { type: 'string', description: 'ipfs:// URI ready for the pump.fun launch-agent `uri` field.' },
cid: { type: 'string', description: 'IPFS CID of the metadata JSON.' },
image_cid: { type: 'string', description: 'IPFS CID of the uploaded image.' },
provider: { type: 'string', description: 'IPFS provider used.' },
},
required: ['uri', 'cid'],
additionalProperties: false,
},
},
{
name: 'pumpfun_bot_status',
description:
'Returns the configuration and health status of the pump.fun indexer backend. Always available; does not require PUMPFUN_BOT_URL. ' +
'Use this first when search_tokens, get_graduated_tokens, get_king_of_the_hill, or get_creator_profile fail or are missing, to see whether the indexer is configured and healthy.',
inputSchema: { type: 'object', properties: {}, required: [] },
outputSchema: {
type: 'object',
properties: {
configured: {
type: 'boolean',
description: 'true when PUMPFUN_BOT_URL is set on the server',
},
healthy: {
type: 'boolean',
description: 'true when the indexer answered the health ping',
},
latencyMs: {
type: 'number',
description: 'Round-trip ms of the health ping (configured backends only)',
},
error: {
type: 'string',
description: 'Failure reason when healthy is false',
},
message: {
type: 'string',
description: 'Human-readable note when the indexer is unconfigured',
},
},
required: ['configured', 'healthy'],
additionalProperties: true,
},
},
];
// Stamp title + annotations onto every tool from the map above. A tool added
// to TOOLS without a TOOL_ANNOTATIONS entry would ship un-annotated — the
// parity tests assert full coverage so that can't land silently.
for (const tool of TOOLS) {
const annotations = TOOL_ANNOTATIONS[tool.name];
if (annotations) {
tool.title = annotations.title;
tool.annotations = annotations;
}
}
export function rpcError(code, message) {
const err = new Error(message);
err.rpcCode = code;
return err;
}
export function rpcEnvelope(id, result, errObj) {
if (errObj) {
return { jsonrpc: '2.0', id: id ?? null, error: errObj };
}
return { jsonrpc: '2.0', id: id ?? null, result };
}