blockscout-mcp

name	blockscout-mcp
description	Use when querying onchain data through Blockscout MCP. Covers contract source retrieval, transaction analysis, address balance queries, event log queries, and token information.

Blockscout MCP Integration

Overview

Blockscout provides a comprehensive API for querying onchain data. Through MCP (Model Context Protocol), you can access contract sources, transaction details, address information, and event logs programmatically.

Blockscout API Endpoints

Base URLs by chain:

Chain	Blockscout URL
Ethereum	https://eth.blockscout.com/api/v2
Base	https://base.blockscout.com/api/v2
Optimism	https://optimism.blockscout.com/api/v2
Arbitrum	https://arbitrum.blockscout.com/api/v2
Gnosis	https://gnosis.blockscout.com/api/v2

Contract Source Retrieval

# Get verified contract source via API
curl "https://base.blockscout.com/api/v2/smart-contracts/0xContractAddress"

# Response includes:
# - source_code: full Solidity source
# - abi: contract ABI
# - compiler_version
# - optimization_enabled
# - constructor_args

Using cast:

# Download source from Blockscout-indexed chain
cast etherscan-source 0xContractAddress \
  --chain base \
  -d ./downloaded-source

Address Queries

# Get address info (balance, tx count, token balances)
curl "https://base.blockscout.com/api/v2/addresses/0xAddress"

# Get token balances for an address
curl "https://base.blockscout.com/api/v2/addresses/0xAddress/token-balances"

# Get address transactions
curl "https://base.blockscout.com/api/v2/addresses/0xAddress/transactions"

# Get internal transactions
curl "https://base.blockscout.com/api/v2/addresses/0xAddress/internal-transactions"

# Get token transfers
curl "https://base.blockscout.com/api/v2/addresses/0xAddress/token-transfers"

Transaction Analysis

# Get transaction details
curl "https://base.blockscout.com/api/v2/transactions/0xTxHash"

# Get transaction logs (events)
curl "https://base.blockscout.com/api/v2/transactions/0xTxHash/logs"

# Get internal transactions for a tx
curl "https://base.blockscout.com/api/v2/transactions/0xTxHash/internal-transactions"

# Get token transfers in a transaction
curl "https://base.blockscout.com/api/v2/transactions/0xTxHash/token-transfers"

# Get transaction state changes
curl "https://base.blockscout.com/api/v2/transactions/0xTxHash/state-changes"

Event Log Queries

# Get logs by contract address
curl "https://base.blockscout.com/api?module=logs&action=getLogs\
&address=0xContractAddress\
&fromBlock=0\
&toBlock=latest\
&topic0=0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
# topic0 = keccak256("Transfer(address,address,uint256)")

Token Information

# Get token details (name, symbol, decimals, total supply)
curl "https://base.blockscout.com/api/v2/tokens/0xTokenAddress"

# Get token holders
curl "https://base.blockscout.com/api/v2/tokens/0xTokenAddress/holders"

# Get token transfers
curl "https://base.blockscout.com/api/v2/tokens/0xTokenAddress/transfers"

# Get token instances (for NFTs)
curl "https://base.blockscout.com/api/v2/tokens/0xNFTAddress/instances"

MCP Usage Patterns

Query Contract State

// Through MCP, query a contract's verified source and ABI
const contractInfo = await blockscoutMcp.getContract({
  chain: 'base',
  address: '0xContractAddress',
});

// Use ABI to decode transaction data
const decodedTx = await blockscoutMcp.decodeTransaction({
  chain: 'base',
  txHash: '0xTxHash',
  abi: contractInfo.abi,
});

Monitor Contract Events

// Fetch recent events from a contract
const logs = await blockscoutMcp.getLogs({
  chain: 'base',
  address: '0xContractAddress',
  fromBlock: 'latest-1000',
  toBlock: 'latest',
  topic0: '0x...', // event signature hash
});

Investigate a Transaction

// Full transaction breakdown
const tx = await blockscoutMcp.getTransaction({ chain: 'base', hash: '0x...' });
const logs = await blockscoutMcp.getTransactionLogs({ chain: 'base', hash: '0x...' });
const internal = await blockscoutMcp.getInternalTxs({ chain: 'base', hash: '0x...' });
const stateChanges = await blockscoutMcp.getStateChanges({ chain: 'base', hash: '0x...' });

Blockscout vs Etherscan API

Feature	Blockscout	Etherscan
Open source	Yes	No
V2 API	REST, well-structured	Legacy format
Self-hostable	Yes	No
Multi-chain	Unified API	Separate domains
Rate limits	Generous	Restrictive
API key required	Usually no	Yes
State changes	Available	Limited

Useful Blockscout Queries for Debugging

# Check if contract is verified
curl -s "https://base.blockscout.com/api/v2/smart-contracts/0xAddr" | jq '.is_verified'

# Get proxy implementation address
curl -s "https://base.blockscout.com/api/v2/smart-contracts/0xProxy" | jq '.implementations'

# Get recent transactions for a contract
curl -s "https://base.blockscout.com/api/v2/addresses/0xAddr/transactions?limit=10"

# Search by text
curl -s "https://base.blockscout.com/api/v2/search?q=MyToken"

# Get block info
curl -s "https://base.blockscout.com/api/v2/blocks/18000000"

Integration Checklist

• Use correct Blockscout instance URL for target chain
• Handle pagination for large result sets (next_page_params)
• Cache contract ABI/source after first retrieval
• Use V2 API endpoints where available (better structured)
• Fall back to Etherscan API if Blockscout instance is unavailable
• Check is_verified before trusting contract source
• Use state-changes endpoint for understanding tx effects