Tool Catalog

The Balchemy platform exposes 106 registered tools through its MCP (Model Context Protocol) gateway. By default, the MCP endpoint surfaces 7 tools — the high-level agent interface designed for most external agent use cases. The full catalog of 106 tools becomes available when the platform flag MCP_EXPOSE_GRANULAR_TOOLS=true is enabled on the bot.

All tools are executed server-side. They communicate with the Rust trading engine over gRPC and with third-party data providers via the backend's service layer. Every tool call is scope-checked, rate-limited, and recorded in the MCP audit log.

Access model

Default (7 tools)

The 7 default tools cover the entire agent lifecycle without requiring granular access:

Tool	Description
`ask_bot`	Natural language query routed through the full AI pipeline
`trade_command`	Direct natural-language trading command (bypasses LLM)
`agent_execute`	High-level instruction executor for external agents
`agent_research`	Token research with snapshot delta tracking
`agent_portfolio`	Portfolio and position state snapshot
`agent_status`	Runtime/auth health check
`agent_config`	Get or update trading config and risk policy

Granular (106 tools, `MCP_EXPOSE_GRANULAR_TOOLS=true`)

Granular mode exposes all 106 tools across 14 categories. Contact the Balchemy team to enable this flag for your integration.

Scope model

Every tool declaration includes a requiredScope field. Your MCP key must carry at least that scope or tool calls return a 403 Forbidden error.

Scope	Grants
`read`	Read-only tools — market data, research, portfolio views, wallet info
`trade`	All read tools plus all execution and configuration tools

Pass scope during ERC-8004 onboarding to receive a key with the appropriate permissions.

Category 1 — AI tools

These are the 7 default tools. They form the primary interface for external agents.

Tool	Description	Scope	Key parameters
`ask_bot`	Send a message to the bot and receive its reply. Routes through the full message handler pipeline, including knowledge base retrieval, tool invocation, and conversation history.	`trade`	`message` (required), `chat_id` (optional), `metadata` (optional object)
`trade_command`	Execute a natural-language trading command directly against the trading bridge. Bypasses the LLM — the command string is parsed and dispatched to the execution pipeline.	`trade`	`message` (required), `chat_id`, `last_mentioned_ca`, `recent_messages` (array)
`agent_execute`	High-level instruction endpoint. Accepts a free-text instruction, routes it through the trading bridge, and returns a structured envelope with `intent`, `result`, and `metadata`.	`trade`	`instruction` (required), `chat_id`, `metadata`
`agent_research`	Comprehensive token research endpoint. Returns a raw research envelope including on-chain data, X (Twitter) sentiment, dev wallet analysis, and holder distribution. Tracks deltas between calls.	`read`	`query` (required), `chain` (`solana`/`base`/`ethereum`), `includeX`, `includeOnchain`, `includeDevWallets`, `includeHolders`, `maxPosts`
`agent_portfolio`	Returns a snapshot of the current agent state: balances, open orders, positions, and 7-day PnL. Tracks deltas between consecutive calls.	`read`	(none)
`agent_status`	Reports auth and runtime status for the current session: user ID presence, bot ID, trading enabled flag, trading service availability.	`read`	(none)
`agent_config`	Get or update trading configuration and risk policy. Supports three operations: `get`, `update_trade_defaults`, `update_risk_policy`.	`trade`	`operation` (required), `defaults` (for update_trade_defaults), `policy` (for update_risk_policy)

Structured response envelope

All AI tools return a structured envelope:

{
  "reply": "Human-readable response text",
  "structured": { ... },
  "trace_id": "uuid-v4",
  "session_cursor": "ISO-8601 timestamp",
  "capabilities_hash": "...",
  "metadata": {
    "tool": "ask_bot",
    "raw_mode": false,
    "ts": "2026-03-19T12:00:00.000Z",
    "trace_id": "...",
    "session_cursor": "...",
    "capabilities_hash": "..."
  }
}

Tools that return large unstructured datasets (agent_research, agent_portfolio) set raw_mode: true in their metadata.

Category 2 — Solana trading tools

Direct integration with Solana DeFi protocols. All Solana tools proxy through the Rust trading engine.

Tool	Description	Scope	Key parameters
`trading_solana_jupiter_tokens_search`	Search Solana tokens via the Jupiter tokens API.	`read`	`q` (search query), `limit`
`trading_solana_jupiter_price`	Get current Solana token prices via the Jupiter price API. Accepts up to multiple mint addresses.	`read`	`mints` (required, array of mint addresses), `vsToken`
`trading_solana_jupiter_quote`	Get a Solana swap quote via Jupiter. Returns route, price impact, fees, and estimated output.	`read`	`inputMint` (required), `outputMint` (required), `amount` (required, in lamports), `slippageBps`, `platformFeeBps`
`trading_solana_jupiter_swap`	Plan or execute a Solana swap via Jupiter. Custodial-only. Defaults to plan mode (`submit=false`). Input mint must be native SOL or USDC (P3 constraint).	`trade`	`inputMint` (required), `outputMint` (required), `amount` (required), `slippageBps`, `submit` (boolean, default `false`)
`trading_solana_rugcheck_report`	Fetch a RugCheck.xyz security report for a Solana token. Returns risk score, flagged signals, and liquidity metadata.	`read`	`mint` (required, token mint address)
`trading_solana_token_insights`	Get on-chain token insights via Solana RPC: mint authority, freeze authority, supply, decimals, and top holders.	`read`	`mint` (required)
`trading_solana_pretrade_report`	Produce a pre-trade checklist combining RugCheck + token insights for a proposed swap. Returns raw risk signals before you commit.	`read`	`inputMint` (required), `outputMint` (required), `amount` (required), `slippageBps`

Category 3 — EVM trading tools

EVM trading is available on Base (chain ID 8453) via the 0x protocol.

Tool	Description	Scope	Key parameters
`trading_evm_status`	Get EVM integration status. Confirms engine health and Base chain availability.	`read`	(none)
`trading_evm_wallets_list`	List all custodial EVM wallets for the authenticated user on Base.	`read`	(none)
`trading_evm_wallets_custodial_create`	Create a new custodial EVM wallet on Base.	`trade`	`chainId`, `label`, `makeDefault`
`trading_evm_quote`	Get an EVM swap quote via 0x. Read-only; does not create an order.	`read`	`sellToken` (required), `buyToken` (required), `sellAmount` (required, in token base units), `chainId` (default 8453), `walletId`, `slippageBps`
`trading_evm_swap`	Execute an EVM swap via custodial signing. Defaults to `submit=false` (creates a pending order). Pass `submit=true` for on-chain execution.	`trade`	`sellToken` (required), `buyToken` (required), `sellAmount` (required), `chainId`, `walletId`, `slippageBps`, `submit`
`trading_evm_token_resolve`	Resolve EVM token metadata (symbol, name, decimals) by contract address on Base (chain 8453).	`read`	`tokenAddress` (required), `chainId`
`trading_evm_contract_risk_lite`	Get minimal EVM contract risk signals (proxy flag, owner address) for a token contract.	`read`	`tokenAddress` (required), `chainId`
`trading_evm_chain_block_number`	Fetch the latest block number for an EVM chain via RPC.	`read`	`chainId` (required)

Category 4 — EVM pre-trade tool

Tool	Description	Scope	Key parameters
`trading_evm_pretrade_report`	Produce a pre-trade checklist for an EVM swap. Runs security signals (Honeypot, GoPlus, contract risk) before the swap is submitted.	`read`	`sellToken` (required), `buyToken` (required), `sellAmount` (required), `chainId`

Category 5 — Security tools

On-chain token risk intelligence aggregated from Honeypot.is, GoPlus Security, and Bubblemaps.

Tool	Description	Scope	Key parameters
`trading_security_honeypot_check`	Run Honeypot.is signals for a token address. Returns is-honeypot flag, buy/sell tax, holder count, and liquidity analysis.	`read`	`tokenAddress` (required), `chainId` (default 8453)
`trading_security_goplus_token_security`	Run GoPlus Security analysis for a token. Returns comprehensive risk flags including ownership, proxy status, tax, and DEX liquidity.	`read`	`tokenAddress` (required), `chainId` (default 8453)
`trading_security_bubblemaps_map`	Fetch Bubblemaps token ownership cluster graph. Visualizes wallet concentration and connected address groups.	`read`	`chain` (required, e.g. `"base"`, `"solana"`), `tokenAddress` (required)

Category 6 — Wallet management tools

Full lifecycle management for connected and custodial wallets.

Tool	Description	Scope	Key parameters
`trading_wallet_list`	List all connected wallets for the authenticated user.	`read`	(none)
`trading_wallet_default`	Get the user's default wallet.	`read`	(none)
`trading_wallet_verification_message`	Generate a SIWE/SIWS verification message for a wallet connect flow.	`read`	`public_key` (required)
`trading_wallet_connect`	Connect a new wallet using a signed verification message.	`trade`	`wallet` (required object with signature + public key)
`trading_wallet_platform_delegate`	Get the platform delegate public key for delegated signing operations.	`read`	(none)
`trading_wallet_set_default`	Set the default wallet by index.	`trade`	`wallet_index` (required)
`trading_wallet_approvals`	List token approvals for a specific wallet.	`read`	`wallet_index`
`trading_wallet_has_approval`	Check whether a specific token has been approved for a wallet.	`read`	`wallet_index` (required), `token_mint` (required)
`trading_wallet_approve_token`	Record a new token approval for a wallet.	`trade`	`approval` (required object)
`trading_wallet_revoke_token`	Revoke a token approval.	`trade`	`revoke` (required object)
`trading_wallet_custodial_get`	Get custodial wallet information for the authenticated user.	`read`	(none)
`trading_wallet_custodial_ensure`	Ensure a custodial wallet exists, creating one if necessary.	`trade`	(none)
`trading_wallet_default_order_profile_get`	Get the default order profile for this bot (amount, slippage, stop-loss, take-profit, DCA config).	`read`	(none — requires botId in context)
`trading_wallet_default_order_profile_update`	Update the default order profile for this bot.	`trade`	`amount` (required), `amountUnit` (`SOL`/`USDC`/`USD`), `slippageBps`, `stopLossPercent`, `takeProfitTargets`, `dcaLegs`, `autoApprove`, `maxLossPercent`, `maxPositionSize`, `name`

Category 7 — Trading config tools

Read and write the bot-level trading configuration. Changes take effect on the next executed trade.

Tool	Description	Scope	Key parameters
`trading_config_get`	Get the full trading config for this bot including defaults, risk policy, and wallet mode.	`read`	(none)
`trading_config_trade_defaults`	Update trading defaults (slippage, amount, etc.).	`trade`	`defaults` (required object)
`trading_config_risk_policy`	Update the risk policy (max loss, max position size, circuit breaker thresholds).	`trade`	`policy` (required object)
`trading_config_wallet_mode`	Update wallet mode: `custodial`, `delegated`, or `connected`.	`trade`	`wallet_mode` (required string)
`trading_config_pool_preferences`	Update DEX pool preferences (priority pools, excluded pools).	`trade`	`prefs` (required object)
`trading_config_launchpads`	Get current launchpad configuration (enabled/disabled, priority).	`read`	(none)
`trading_config_launchpad_toggle`	Enable or disable a specific launchpad integration (`pumpfun`, `bonk`, etc.).	`trade`	`type` (required), `enabled` (required boolean)
`trading_config_launchpad_priority`	Update the priority rank for a launchpad. Lower numbers = higher priority.	`trade`	`type` (required), `priority` (required number)

Category 8 — Trading strategy tools

Create, delete, and control DCA and other automated trading strategies.

Tool	Description	Scope	Key parameters
`trading_strategies_list`	List all trading strategies for this bot. Optionally filter by strategy type.	`read`	`type` (optional filter)
`trading_strategies_create`	Create a new trading strategy. Supports DCA, limit, trailing stop, partial sell, and take-profit configuration objects.	`trade`	`name` (required), `type` (required), `dca_config`, `limit_config`, `trailing_stop_config`, `partial_sell_config`, `take_profit_config`
`trading_strategies_delete`	Delete a trading strategy by name or index.	`trade`	`strategy_name` or `strategy_index` (at least one required)
`trading_dca_stats`	Get DCA execution statistics for this bot: intervals hit, total invested, average entry price.	`read`	(none)
`trading_dca_pause`	Pause a running DCA strategy by name. The strategy is preserved and can be resumed.	`trade`	`strategy_name` (required)
`trading_dca_resume`	Resume a paused DCA strategy by name.	`trade`	`strategy_name` (required)

Category 9 — Trading core tools

Position tracking, order management, and token research.

Tool	Description	Scope	Key parameters
`trading_positions`	List all open trading positions for this bot.	`read`	(none)
`trading_positions_pnl`	Get PnL breakdown for open and closed positions. Returns unrealized and realized profit/loss.	`read`	(none)
`trading_agentic_state_snapshot`	Get a full agentic state snapshot: balances, orders, positions, and 7-day PnL in a single call.	`read`	(none)
`trading_orders_list`	List orders for this bot. Optionally filter by status and limit result count.	`read`	`status` (optional), `limit` (optional)
`trading_orders_approve`	Approve a pending order by ID. Required when `autoApprove=false` in the order profile.	`trade`	`order_id` (required)
`trading_orders_cancel`	Cancel an order by ID.	`trade`	`order_id` (required)
`trading_token_research`	Run a comprehensive token research report. Aggregates on-chain data, social signals, dev wallets, and holder distribution. Returns a structured envelope with a snapshot delta tracker.	`read`	`query` (token name or address), `chain`, `includeX`, `includeOnchain`, `includeDevWallets`, `includeHolders`, `maxPosts`

Category 10 — DEX pool tools

Low-level EVM DEX log and state inspection via UniswapV2/V3 ABI.

Tool	Description	Scope	Key parameters
`trading_evm_dex_uniswap_v2_pairs_created`	Fetch UniswapV2-compatible `PairCreated` factory logs for a block range.	`read`	`chainId` (required), `fromBlock` (required), `toBlock` (required)
`trading_evm_dex_uniswap_v3_pools_created`	Fetch UniswapV3 `PoolCreated` factory logs for a block range.	`read`	`chainId` (required), `fromBlock` (required), `toBlock` (required)
`trading_evm_dex_pool_swaps`	Fetch swap logs for a DEX pool (V2 or V3) by pool address and block range.	`read`	`chainId` (required), `poolAddress` (required), `poolType` (`uniswap_v2`/`uniswap_v3`, required), `fromBlock` (required), `toBlock` (required)
`trading_evm_dex_pool_mints`	Fetch liquidity mint logs for a DEX pool by pool address and block range.	`read`	`chainId`, `poolAddress`, `poolType`, `fromBlock`, `toBlock` (all required)
`trading_evm_dex_pool_burns`	Fetch liquidity burn logs for a DEX pool by pool address and block range.	`read`	`chainId`, `poolAddress`, `poolType`, `fromBlock`, `toBlock` (all required)
`trading_evm_dex_pool_syncs`	Fetch UniswapV2 `Sync` logs (reserve0/reserve1 updates) for a pool.	`read`	`chainId`, `poolAddress`, `poolType` (`uniswap_v2`), `fromBlock`, `toBlock` (all required)
`trading_evm_dex_pool_lookup`	Lookup pool address via factory `eth_call`. Supports `getPair` (V2) and `getPool` (V3).	`read`	`chainId` (required), `poolType` (required), `tokenA` (required), `tokenB` (required), `fee` (required for V3)
`trading_evm_dex_pool_state`	Fetch a DEX pool state snapshot via `eth_call`. Returns reserves (V2) or slot0 + liquidity (V3).	`read`	`chainId` (required), `poolAddress` (required), `poolType` (required)

Category 11 — Launchpad tools

Discovery and metadata for tokens deployed via crypto launchpads.

Pump.fun

Tool	Description	Scope	Key parameters
`trading_launchpad_pumpfun_search_coins`	Search the Pump.fun coin feed by free-text query.	`read`	`query` (required), `offset`, `limit`, `sort`, `order`, `includeNsfw`
`trading_launchpad_pumpfun_trending_coins`	Get the Pump.fun trending coins feed.	`read`	`offset`, `limit`, `sort`, `order`, `includeNsfw`

Clanker

Tool	Description	Scope	Key parameters
`trading_launchpad_clanker_tokens`	Browse and search Clanker-deployed tokens. Filter by query, FID, pair address, chain, and sort order.	`read`	`q`, `fid`, `pairAddress`, `sort` (`asc`/`desc`), `sortBy`, `limit`, `cursor`, `chainId`, `includeMarket`
`trading_launchpad_clanker_creator_search`	Search Clanker token creators by query string.	`read`	`q` (required), `limit`, `offset`, `sort`, `trustedOnly`
`trading_launchpad_clanker_token_by_address`	Get Clanker token details by contract address.	`read`	`address` (required)
`trading_launchpad_clanker_tokens_by_creator`	List all Clanker tokens deployed by a given creator address.	`read`	`address` (required), `cursor`

Zora

Tool	Description	Scope	Key parameters
`trading_launchpad_zora_coin`	Get Zora coin or token details by contract address.	`read`	`address` (required), `chain`
`trading_launchpad_zora_explore`	Explore Zora coins by list type: `trending`, `new`, `top`, or other valid types.	`read`	`listType` (required), `count`, `after` (cursor)

BaseMeme

Tool	Description	Scope	Key parameters
`trading_launchpad_basememe_factory_logs`	Fetch BaseMeme factory contract logs for a block range. Useful for discovering newly deployed meme tokens on Base.	`read`	`chainId` (required), `fromBlock` (required), `toBlock` (required), `deployment` (`current_v4`/`legacy_v3`)

Category 12 — Market data tools

Aggregated market data from DexScreener, GeckoTerminal, CoinGecko, and DefiLlama.

DexScreener

Tool	Description	Scope	Key parameters
`trading_market_dexscreener_search_pairs`	Search DexScreener trading pairs by free-text query.	`read`	`q` (required), `chainId` (optional filter)
`trading_market_dexscreener_token_pairs`	Get all DexScreener pairs for a specific token address.	`read`	`chainId` (required), `tokenAddress` (required)
`trading_market_dexscreener_pair_details`	Get DexScreener pair details for a specific pair address.	`read`	`chainId` (required), `pairAddress` (required)
`trading_market_dexscreener_tokens`	Bulk-fetch DexScreener token details for a list of token addresses.	`read`	`chainId` (required), `tokenAddresses` (required, array)
`trading_market_dexscreener_token_boosts_top`	Get the top boosted tokens list from DexScreener.	`read`	(none)
`trading_market_dexscreener_token_boosts_latest`	Get the latest boosted tokens list from DexScreener.	`read`	(none)

GeckoTerminal

Tool	Description	Scope	Key parameters
`trading_market_geckoterminal_search_pools`	Search GeckoTerminal liquidity pools by query string.	`read`	`query` (required), `network`, `page`
`trading_market_geckoterminal_trending_pools`	Get trending liquidity pools for a network on GeckoTerminal.	`read`	`network` (required, e.g. `"solana"`, `"base"`)
`trading_market_geckoterminal_pool_details`	Get full details for a GeckoTerminal pool by address.	`read`	`network` (required), `poolAddress` (required)
`trading_market_geckoterminal_pool_ohlcv`	Get OHLCV candlestick data for a GeckoTerminal pool.	`read`	`network` (required), `poolAddress` (required), `timeframe` (required), `limit`, `beforeTimestamp`
`trading_market_geckoterminal_pool_trades`	Get recent trades for a GeckoTerminal pool.	`read`	`network` (required), `poolAddress` (required), `limit`

CoinGecko

Tool	Description	Scope	Key parameters
`trading_market_coingecko_onchain_trending_pools`	Get CoinGecko on-chain trending pools for a specific network.	`read`	`network` (required)

DefiLlama

Tool	Description	Scope	Key parameters
`trading_market_defillama_prices_current`	Get current coin prices via DefiLlama. Accepts a list of coin IDs (e.g. `"coingecko:solana"`).	`read`	`coinIds` (required, array)

On-chain social signal data from Farcaster via Neynar.

Tool	Description	Scope	Key parameters
`trading_social_neynar_search_casts`	Search Farcaster casts via the Neynar API. Useful for sentiment analysis and community signal detection.	`read`	`q` (required, search query), `limit`, `cursor`

Category 14 — Indexer tools

EVM on-chain data via Blockscout (supports Base by default, chain ID 8453).

Tool	Description	Scope	Key parameters
`trading_indexer_blockscout_token_details`	Get Blockscout token metadata for a contract address: name, symbol, type, total supply, holder count.	`read`	`tokenAddress` (required), `chainId` (default 8453)
`trading_indexer_blockscout_token_holders`	Get paginated token holder list for a contract address.	`read`	`tokenAddress` (required), `chainId`, `itemsCount`, `value`, `addressHash`
`trading_indexer_blockscout_token_transfers`	Get paginated token transfer history for a contract address.	`read`	`tokenAddress` (required), `chainId`, `blockNumber`, `index`
`trading_indexer_blockscout_contract_details`	Get smart contract details including verification status, proxy information, and source code metadata.	`read`	`address` (required), `chainId` (default 8453)
`trading_indexer_blockscout_address_transactions`	Get paginated transaction history for any address.	`read`	`address` (required), `chainId`, `itemsCount`, `blockNumber`, `index`

Category 15 — Simulation tools

Transaction simulation via Tenderly before on-chain submission.

Tool	Description	Scope	Key parameters
`trading_simulation_tenderly_simulate_tx`	Simulate an EVM transaction via the Tenderly Simulation API. Returns execution trace, state changes, and revert reason if failed.	`read`	`from` (required), `to` (required), `data` (required, hex-encoded calldata), `chainId` (default 8453), `value` (in wei)
`trading_simulation_evm_gas_estimate`	Estimate gas for an EVM transaction using Tenderly simulation. Returns `gasUsed`, `gasLimit`, and `success` flag.	`read`	`from` (required), `to` (required), `data` (required), `chainId`, `value`

Category 16 — Verification tools

Smart contract source verification via Sourcify.

Tool	Description	Scope	Key parameters
`trading_verification_sourcify_contract_lookup`	Look up contract source verification metadata via Sourcify. Returns verification status, compiler version, and ABI hash.	`read`	`address` (required), `chainId` (default 8453), `fields` (optional field selector)

Tool response format

All tool responses follow the MCP tools/call JSON-RPC response format:

{
  "jsonrpc": "2.0",
  "id": "req-uuid",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...json string...}"
      }
    ],
    "isError": false
  }
}

When a tool fails, isError is true and the text field contains a JSON error object with code and message fields.

Use the SDK helpers to work with responses:

import { getToolText, parseToolJson, isToolError } from "@balchemy/agent-sdk";
 
const response = await mcp.callTool("trading_positions", {});
 
if (isToolError(response)) {
  console.error("Tool error:", getToolText(response));
} else {
  const data = parseToolJson(response);
  console.log(data);
}

Safety profiles

Each tool carries an internal safety profile that controls execution guards:

Profile	Behavior
`read_only`	No side effects. Can run even when trading is disabled.
`trade_guarded`	Requires `tradingEnabled=true` and `tradingServiceAvailable=true` on the bot context. Returns a soft error message rather than throwing if conditions are not met.

SDK Getting Started

Error Codes

Edit this page on GitHub