Server Instructions

Blockscout MCP server version: 0.15.0 <error_handling_rules> If you receive an error "500 Internal Server Error" for any tool, retry calling this tool up to 3 times until successful. </error_handling_rules> <chain_id_guidance> <rules> All Blockscout API tools require a chain_id parameter: - If the chain ID to be used in the tools is not clear, use the tool `get_chains_list` to get chain IDs of all known chains. - If no chain is specified in the user's prompt, assume "Ethereum Mainnet" (chain_id: 1) as the default. </rules> <recommended_chains> Here is the list of IDs of most popular chains: * Ethereum: 1 * Polygon PoS: 137 * Base: 8453 * Arbitrum One Nitro: 42161 * OP Mainnet: 10 * ZkSync Era: 324 * Gnosis: 100 * Celo: 42220 * Scroll: 534352 </recommended_chains> </chain_id_guidance> <pagination_rules> PAGINATION HANDLING: When any tool response includes a 'pagination' field, this means there are additional pages of data available. You MUST use the exact tool call provided in 'pagination.next_call' to fetch the next page. The 'pagination.next_call' contains the complete tool name and all required parameters (including the cursor) for the next page request. If the user asks for comprehensive data or 'all' results, and you receive a paginated response, continue calling the pagination tool calls until you have gathered all available data or reached a reasonable limit. </pagination_rules> <time_based_query_rules> TIME-BASED QUERIES: When users ask for blockchain data with time constraints (before/after/between specific dates), start with transaction-level tools that support time filtering (`get_transactions_by_address`, `get_token_transfers_by_address`) rather than trying to filter other data types directly. Use `age_from` and `age_to` parameters to filter transactions by time, then retrieve associated data (logs, token transfers, etc.) from those specific transactions. </time_based_query_rules> <binary_search_rules> BINARY SEARCH FOR HISTORICAL BLOCKCHAIN DATA: Never paginate for temporal boundaries. Use binary search with `age_from`/`age_to` parameters to efficiently locate specific time periods or events in blockchain history. ## Pattern: ``` get_transactions_by_address(age_from: START, age_to: MID) ├── Results found → search earlier half: [START, MID] └── No results → search later half: [MID, END] ``` ## Example: First transaction for vitalik.eth ``` 1. get_transactions_by_address(age_from: "2015-07-30", age_to: "2015-12-31") → ✓ 2. get_transactions_by_address(age_from: "2015-07-30", age_to: "2015-09-12") → ✗ 3. get_transactions_by_address(age_from: "2015-09-12", age_to: "2015-10-03") → ✓ 4. get_transactions_by_address(age_from: "2015-09-27", age_to: "2015-09-30") → ✓ Found: 2015-09-28T08:24:43Z 5. get_transactions_by_address(age_from: "2015-07-30", age_to: "2015-09-28T08:24:42") → ✗ Confirmed: This is the first transaction. ``` **Result: 5 API calls instead of potentially hundreds of pagination calls.** </binary_search_rules> <portfolio_analysis_rules> PORTFOLIO BALANCE ANALYSIS: When asked to analyze a portfolio, net worth, or total assets for any address, you MUST check BOTH native-coin data AND ERC-20 token data. Call `get_address_info` (native coin) AND `get_tokens_by_address` (ERC-20 holdings) before answering. When ranking or selecting top tokens by USD value, you MUST include the native coin balance (from `get_address_info`) as a candidate alongside ERC-20 holdings. Checking only one results in an incomplete and incorrect analysis. </portfolio_analysis_rules> <funds_movement_rules> FUNDS MOVEMENT ANALYSIS: When asked about funds movement, recent transfers, or transaction activity for any address, you MUST check BOTH native-coin transfers AND ERC-20 token transfers. Call `get_transactions_by_address` (native coin transfers) AND `get_token_transfers_by_address` (ERC-20 transfers) before answering. Do not assume that "transactions" implies native coin only. Checking only one results in an incomplete and incorrect analysis. </funds_movement_rules> <data_ordering_and_resumption_rules> DATA ORDERING AND ANCHOR RESUMPTION: Time-ordered tools (transactions, token transfers, logs) return items in DESCENDING order (newest first). When resuming from an anchor item, use the anchor's block as the time boundary and client-side filter. Never skip the anchor's block. Ordering Keys (DESC): - get_transactions_by_address: (block_number, transaction_index, internal_transaction_index) - get_token_transfers_by_address: (block_number, transaction_index, token_transfer_batch_index, token_transfer_index) - direct_api_call (logs): (block_number, index) # index is global within block Resume Pattern: • For EARLIER items: age_to=anchor_block_timestamp, keep where ordering_key < anchor_key • For LATER items: age_from=anchor_block_timestamp, keep where ordering_key > anchor_key Example: Found transfer at (block=1000, tx_idx=5, transfer_idx=3). To find earlier transfers: Query: age_to=timestamp_of_block_1000 Filter: keep only (block<1000) OR (block=1000 AND tx_idx<5) OR (block=1000 AND tx_idx=5 AND transfer_idx<3) Critical Notes: - Always compare the COMPLETE ordering key, not just block_number. - If the anchor is in the boundary block, filter within that block to avoid duplicates or gaps. </data_ordering_and_resumption_rules> <direct_call_endpoint_list> ADVANCED API USAGE: For specialized or chain-specific data not covered by other tools, you can use `direct_api_call`. This tool can call a curated list of raw Blockscout API endpoints. <common> <group name="Stats"> "/stats-service/api/v1/counters" - "Get consolidated historical and recent-window counters—totals and 24h/30m rollups for blockchain activity (transactions, accounts, contracts, verified contracts, ERC-4337 user ops), plus average block time and fee aggregates" "/api/v2/stats" - "Get real-time network status and market context—current gas price tiers with last-update and next-update timing, network utilization, today's transactions, average block time 'now', and coin price/market cap." </group> <group name="User Operations"> "/api/v2/proxy/account-abstraction/operations/{user_operation_hash}" - "Get details for a specific User Operation by its hash." </group> <group name="Transactions"> "/api/v2/transactions/{transaction_hash}/logs" - "Get event logs for a specific transaction by its hash." </group> <group name="Tokens & NFTs"> "/api/v2/tokens/{token_contract_address}/instances" - "Get all NFT instances for a given token contract address." "/api/v2/tokens/{token_contract_address}/holders" - "Get a list of holders for a given token." "/api/v2/tokens/{token_contract_address}/instances/{instance_id}" - "Get details for a specific NFT instance." "/api/v2/tokens/{token_contract_address}/instances/{instance_id}/transfers" - "Get transfer history for a specific NFT instance." </group> </common> <specific> <chain_family name="Ethereum Mainnet and Gnosis"> "/api/v2/addresses/{account_address}/beacon/deposits" - "Get Beacon Chain deposits for a specific address." "/api/v2/blocks/{block_number}/beacon/deposits" - "Get Beacon Chain deposits for a specific block." "/api/v2/addresses/{account_address}/withdrawals" - "Get Beacon Chain withdrawals for a specific address." "/api/v2/blocks/{block_number}/withdrawals" - "Get Beacon Chain withdrawals for a specific block." </chain_family> <chain_family name="Arbitrum"> "/api/v2/main-page/arbitrum/batches/latest-number" - "Get the latest committed batch number for Arbitrum." "/api/v2/arbitrum/batches/{batch_number}" - "Get information for a specific Arbitrum batch." "/api/v2/arbitrum/messages/to-rollup" - "Get L1 to L2 messages for Arbitrum." "/api/v2/arbitrum/messages/from-rollup" - "Get L2 to L1 messages for Arbitrum." "/api/v2/arbitrum/messages/withdrawals/{transaction_hash}" - "Get L2 to L1 messages for a specific transaction hash on Arbitrum." </chain_family> <chain_family name="Optimism"> "/api/v2/optimism/batches" - "Get the latest committed batches for Optimism." "/api/v2/optimism/batches/{batch_number}" - "Get information for a specific Optimism batch." "/api/v2/optimism/games" - "Get dispute games for Optimism." "/api/v2/optimism/deposits" - "Get L1 to L2 messages (deposits) for Optimism." "/api/v2/optimism/withdrawals" - "Get L2 to L1 messages (withdrawals) for Optimism." </chain_family> <chain_family name="Celo"> "/api/v2/celo/epochs" - "Get the latest finalized epochs for Celo." "/api/v2/celo/epochs/{epoch_number}" - "Get information for a specific Celo epoch." "/api/v2/celo/epochs/{epoch_number}/election-rewards/group" - "Get validator group rewards for a specific Celo epoch." "/api/v2/celo/epochs/{epoch_number}/election-rewards/validator" - "Get validator rewards for a specific Celo epoch." "/api/v2/celo/epochs/{epoch_number}/election-rewards/voter" - "Get voter rewards for a specific Celo epoch." </chain_family> <chain_family name="zkSync"> "/api/v2/main-page/zksync/batches/latest-number" - "Get the latest committed batch number for zkSync." "/api/v2/zksync/batches/{batch_number}" - "Get information for a specific zkSync batch." </chain_family> <chain_family name="zkEVM"> "/api/v2/zkevm/batches/confirmed" - "Get the latest confirmed batches for zkEVM." "/api/v2/zkevm/batches/{batch_number}" - "Get information for a specific zkEVM batch." "/api/v2/zkevm/deposits" - "Get deposits for zkEVM." "/api/v2/zkevm/withdrawals" - "Get withdrawals for zkEVM." </chain_family> <chain_family name="Scroll"> "/api/v2/scroll/batches" - "Get the latest committed batches for Scroll." "/api/v2/scroll/batches/{batch_number}" - "Get information for a specific Scroll batch." "/api/v2/blocks/scroll-batch/{batch_number}" - "Get blocks for a specific Scroll batch." "/api/v2/scroll/deposits" - "Get L1 to L2 messages (deposits) for Scroll." "/api/v2/scroll/withdrawals" - "Get L2 to L1 messages (withdrawals) for Scroll." </chain_family> <chain_family name="Shibarium"> "/api/v2/shibarium/deposits" - "Get L1 to L2 messages (deposits) for Shibarium." "/api/v2/shibarium/withdrawals" - "Get L2 to L1 messages (withdrawals) for Shibarium." </chain_family> <chain_family name="Stability"> "/api/v2/validators/stability" - "Get the list of validators for Stability." </chain_family> <chain_family name="Zilliqa"> "/api/v2/validators/zilliqa" - "Get the list of validators for Zilliqa." "/api/v2/validators/zilliqa/{validator_public_key}" - "Get information for a specific Zilliqa validator." </chain_family> <chain_family name="Redstone"> "/api/v2/mud/worlds" - "Get a list of MUD worlds for Redstone." "/api/v2/mud/worlds/{contract_address}/tables" - "Get tables for a specific MUD world on Redstone." "/api/v2/mud/worlds/{contract_address}/tables/{table_id}/records" - "Get records for a specific MUD world table on Redstone." "/api/v2/mud/worlds/{contract_address}/tables/{table_id}/records/{record_id}" - "Get a specific record from a MUD world table on Redstone." </chain_family> </specific> </direct_call_endpoint_list>