Blockscout MCP Server REST API

This document provides detailed documentation for the versioned REST API of the Blockscout MCP Server. This API offers a web-friendly, stateless interface to the same powerful blockchain tools available through the Model Context Protocol (MCP).

The base URL for all Version 1 endpoints is: http://<host>:<port>/v1

Static Endpoints

These endpoints provide general information and are not part of the versioned API.

Method	Path	Description
`GET`	`/`	Serves a static HTML landing page.
`GET`	`/health`	A simple health check endpoint. Returns `{"status": "ok"}`.
`GET`	`/llms.txt`	A machine-readable guidance file for AI crawlers.
`GET`	`/skill/<path>`	Serves bundled `blockscout-analysis` skill Markdown.

Skill Resources

The bundled blockscout-analysis skill is mirrored over HTTP for non-MCP consumers. The address space is identical to the MCP resource URIs after the /skill/ prefix. This endpoint serves raw Markdown and is therefore a static endpoint, not a /v1/ tool wrapper.

GET /skill/<path>

The path tail matches the file's location relative to the skill root, such as SKILL.md or references/blockscout-api-index.md.

Behavior

Path	Result
`SKILL.md`	Returns the entry-point body with the YAML frontmatter stripped. The removed `name`, `license`, and `metadata` fields are not mirrored elsewhere over HTTP; only MCP resource consumers see the promoted `description` annotation.
`references/<file>.md`	Returns the file body byte-for-byte from the bundle.
`README.md`	Returns `404` because README is not enumerated.
Any path containing `..` or escaping the bundle	Returns `404`. Lookup is map-based, so traversal-shaped paths are never keys in the precomputed map.

Example Requests

curl "http://127.0.0.1:8000/skill/SKILL.md"
curl "http://127.0.0.1:8000/skill/references/blockscout-api-index.md"

MCP equivalent

The same artifacts are also reachable via the MCP resources channel under URIs of the form blockscout-mcp://skill/<path>. The two surfaces are equivalent in content and intended to be interchangeable.

Authentication

The REST API is currently in an alpha stage and does not require authentication. This may be subject to change in future releases.

General Concepts

Standard Response Structure

Tool endpoints under /v1/ return a consistent JSON object that wraps the tool's output. This structure, known as a ToolResponse, separates the primary data from important metadata. Discovery endpoints (/v1/tools and /v1/resources) return plain JSON arrays instead.

{
  "data": { ... },
  "data_description": [ ... ],
  "notes": [ ... ],
  "instructions": [ ... ],
  "pagination": { ... }
}

data: The main data payload of the response. Its structure is specific to each endpoint.
data_description: (Optional) A list of strings explaining the structure or fields of the data payload.
notes: (Optional) A list of important warnings or contextual notes, such as data truncation alerts.
instructions: (Optional) A list of suggested follow-up actions for an AI agent.
pagination: (Optional) An object containing information to retrieve the next page of results.

Error Handling

All error responses, regardless of the HTTP status code, return a JSON object with a consistent structure.

Error Response Structure

{
  "error": "A descriptive error message"
}

Error Categories

Client-Side Errors (4xx status codes): These errors usually indicate a problem with the request itself, though some (such as 402 Payment Required) instead reflect a server-side account/quota state rather than anything wrong with the request. Common examples include:
- Validation Errors (400 Bad Request): Occur when a required parameter is missing or a parameter value is invalid.
- Deprecated Endpoints (410 Gone): Occur when a requested endpoint is no longer supported.
- Credits Exhausted (402 Payment Required): Occurs when the Blockscout PRO API daily credit allowance for the server's API key has been exhausted. This is a distinct, clearly-labeled signal — separate from generic transient upstream failures — and reflects the server's API-key quota state, not a problem with the client's request: the client should stop and top up credits or wait for the daily reset rather than retry.
Server-Side Errors (5xx status codes): These errors indicate a problem on the server or with a downstream service. Common examples include:
- Internal Errors (500 Internal Server Error): Occur when the server encounters an unexpected condition.
- Downstream Timeouts (504 Gateway Timeout): Occur when a request to an external service (like a Blockscout API) times out.
- Other Downstream Errors: The server may also pass through other 4xx or 5xx status codes from downstream services.
The server already retries transient transport-level failures internally (up to BLOCKSCOUT_BS_REQUEST_MAX_RETRIES attempts, default 3) before surfacing 500 or 504. Client-side retries on these codes can therefore stay conservative — a single additional attempt is usually sufficient. Retrying 500/504 more aggressively multiplies the total attempt count for the same underlying transport failure.

Pagination

For endpoints that return large datasets, the response will include a pagination object. To fetch the next page, you must use the tool_name and params from the next_call object to construct your next request. The cursor is an opaque string that contains all necessary information for the server.

Example Pagination Object:

{
  "pagination": {
    "next_call": {
      "tool_name": "get_tokens_by_address",
      "params": {
        "chain_id": "1",
        "address": "0x...",
        "cursor": "eyJibG9ja19udW1iZXIiOjE4OTk5OTk5LCJpbmRleCI6NDJ9"
      }
    }
  }
}

Safety & Limits

Response Size Limits

To prevent system overload and context exhaustion, the direct_api_call endpoint enforces a maximum response size limit (default: 100,000 characters).

If you receive a 413 Payload Too Large (or similar error) indicating the response is too large, you can bypass this check by adding the following header to your request:

X-Blockscout-Allow-Large-Response: true

Note: This bypass is only available for REST API calls. MCP calls (used by AI agents) strictly enforce the limit.

API Endpoints

Discovery

List All Tools (`list_tools`)

Retrieves a list of all available tools and their MCP schemas.

GET /v1/tools

Parameters

None
Example Request
```
curl "http://127.0.0.1:8000/v1/tools"
```

List All Resources (`list_resources`)

Retrieves a list of all registered MCP resources and their metadata.

GET /v1/resources

Parameters

None
Example Request
```
curl "http://127.0.0.1:8000/v1/resources"
```
The response is a JSON array of MCP resource objects. Each object includes the resource URI, name, description, MIME type, and annotations. The individual resource content can be fetched via GET /skill/<path>, where <path> is the URI suffix after blockscout-mcp://skill/.

General Tools

Unlock Blockchain Analysis (`__unlock_blockchain_analysis__`)

Provides custom instructions and operational guidance for using the server. This is a mandatory first step.

GET /v1/unlock_blockchain_analysis GET /v1/get_instructions (legacy)

Parameters

None

Example Request

curl "http://127.0.0.1:8000/v1/unlock_blockchain_analysis"

Get Chains List (`get_chains_list`)

Returns supported blockchain chains, including whether each is a testnet, its native currency, ecosystem, and the settlement layer chain ID when applicable. Use this endpoint when you need to choose a supported chain_id for subsequent tool calls. Prefer a narrow search query to avoid returning the full registry unnecessarily.

GET /v1/get_chains_list

Parameters
- query (string, optional): Case-insensitive substring filter applied to chain name, chain ID, native currency, and ecosystem fields. Prefer narrow text terms such as chain name, ecosystem, or currency. Avoid partial numeric chain ID queries like 1, because substring matching can return many chains.

Example Requests

# Get all chains
curl "http://127.0.0.1:8000/v1/get_chains_list"

# Search for Polygon-related chains
curl "http://127.0.0.1:8000/v1/get_chains_list?query=polygon"

# Prefer descriptive terms over partial numeric IDs
curl "http://127.0.0.1:8000/v1/get_chains_list?query=superchain"

Block Tools

Get Block Number (`get_block_number`)

Retrieves the block number and timestamp for a specific date/time or the latest block.

GET /v1/get_block_number

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`datetime`	`string`	No	The date and time (ISO 8601 format, e.g. 2025-05-22T23:00:00.00Z) to find the block for. If omitted, returns the latest block.

Example Request

curl "http://127.0.0.1:8000/v1/get_block_number?chain_id=1&datetime=2023-01-01T00:00:00Z"

Get Block Info (`get_block_info`)

Returns detailed information for a specific block.

GET /v1/get_block_info

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`number_or_hash`	`string`	Yes	The block number or its hash.
`include_transactions`	`boolean`	No	If true, includes a list of transaction hashes.

Example Request

curl "http://127.0.0.1:8000/v1/get_block_info?chain_id=1&number_or_hash=19000000&include_transactions=true"

Transaction Tools

Get Transaction Info (`get_transaction_info`)

Gets comprehensive information for a single transaction, including a summary of ERC-4337 User Operations when present.

GET /v1/get_transaction_info

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`transaction_hash`	`string`	Yes	The hash of the transaction.
`include_raw_input`	`boolean`	No	If true, includes the raw transaction input data.

Example Request

curl "http://127.0.0.1:8000/v1/get_transaction_info?chain_id=1&transaction_hash=0x...&include_raw_input=true"

Get Transaction Logs (Deprecated) (`get_transaction_logs`)

This endpoint is deprecated and always returns a static notice.

GET /v1/get_transaction_logs

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`transaction_hash`	`string`	Yes	The transaction hash to fetch logs for.
`cursor`	`string`	No	The cursor for pagination from a previous response.

Example Request

curl "http://127.0.0.1:8000/v1/get_transaction_logs?chain_id=1&transaction_hash=0x..."

Example Response

{
  "data": {"status": "deprecated"},
  "notes": [
    "This endpoint is deprecated and will be removed in a future version.",
    "Please use `direct_api_call` with `endpoint_path='/api/v2/transactions/{transaction_hash}/logs'` to retrieve logs for a transaction."
  ],
  "pagination": null,
  "instructions": null
}

Get Transaction Summary (Deprecated) (`transaction_summary`)

This endpoint is deprecated and always returns a static notice.

GET /v1/transaction_summary

Parameters

Name Type Required Description

chain_id string Yes The ID of the blockchain.

transaction_hash string Yes The hash of the transaction.

Example Request

curl "http://127.0.0.1:8000/v1/transaction_summary?chain_id=1&transaction_hash=0x..."

Example Response

{
  "data": {"status": "deprecated"},
  "notes": [
    "This endpoint is deprecated and will be removed in a future version.",
    "Please use `direct_api_call` with `endpoint_path='/api/v2/transactions/{transaction_hash}/summary'` to retrieve this data."
  ],
  "pagination": null,
  "instructions": null
}

Get Transactions by Address (`get_transactions_by_address`)

Gets native currency transfers and contract interactions for an address.

GET /v1/get_transactions_by_address

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`address`	`string`	Yes	The address to query.
`age_from`	`string`	Yes	Start date and time (ISO 8601 format).
`age_to`	`string`	No	End date and time (ISO 8601 format).
`methods`	`string`	No	A method signature to filter by (e.g., `0x304e6ade`).
`cursor`	`string`	No	The cursor for pagination from a previous response.

Example Request

curl "http://127.0.0.1:8000/v1/get_transactions_by_address?chain_id=1&address=0x...&age_from=2024-01-01T00:00:00Z"

Get Token Transfers by Address (`get_token_transfers_by_address`)

Returns ERC-20 token transfers for an address.

GET /v1/get_token_transfers_by_address

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`address`	`string`	Yes	The address to query.
`age_from`	`string`	Yes	Start date and time (ISO 8601 format).
`age_to`	`string`	No	End date and time (ISO 8601 format).
`token`	`string`	No	An ERC-20 token contract address to filter by.
`cursor`	`string`	No	The cursor for pagination from a previous response.

Example Request

curl "http://127.0.0.1:8000/v1/get_token_transfers_by_address?chain_id=1&address=0x...&age_from=2024-01-01T00:00:00Z&token=0x..."

Address Tools

Get Address Info (`get_address_info`)

Gets comprehensive information about an address, including balance, contract details, and first transaction timestamp.

GET /v1/get_address_info

Parameters

Name Type Required Description

chain_id string Yes The ID of the blockchain.

address string Yes The address to get info for.

Example Request

curl "http://127.0.0.1:8000/v1/get_address_info?chain_id=1&address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Get Address Logs (Deprecated) (`get_address_logs`)

This endpoint is deprecated and always returns a static notice.

GET /v1/get_address_logs

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`address`	`string`	Yes	The address that emitted the logs.
`cursor`	`string`	No	The cursor for pagination from a previous response.

Example Request

curl "http://127.0.0.1:8000/v1/get_address_logs?chain_id=1&address=0xabc"

Example Response

{
  "data": {"status": "deprecated"},
  "notes": [
    "This endpoint is deprecated and will be removed in a future version.",
    "Please use the recommended workflow: first, call `get_transactions_by_address` (which supports time filtering), and then use `direct_api_call` with `endpoint_path='/api/v2/transactions/{transaction_hash}/logs'` for each relevant transaction hash."
  ],
  "pagination": null,
  "instructions": null
}

Token & NFT Tools

Get Tokens by Address (`get_tokens_by_address`)

Returns ERC-20 token holdings for an address.

GET /v1/get_tokens_by_address

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`address`	`string`	Yes	The wallet address to query.
`cursor`	`string`	No	The cursor for pagination from a previous response.

Example Request

curl "http://127.0.0.1:8000/v1/get_tokens_by_address?chain_id=1&address=0x..."

Get NFT Tokens by Address (`nft_tokens_by_address`)

Retrieves NFT tokens (ERC-721, etc.) owned by an address.

GET /v1/nft_tokens_by_address

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`address`	`string`	Yes	The NFT owner's address.
`cursor`	`string`	No	The cursor for pagination from a previous response.

Example Request

curl "http://127.0.0.1:8000/v1/nft_tokens_by_address?chain_id=1&address=0x..."

Search Tools

Lookup Token by Symbol (`lookup_token_by_symbol`)

Searches for tokens by their symbol or name.

GET /v1/lookup_token_by_symbol

Parameters

Name Type Required Description

chain_id string Yes The ID of the blockchain.

symbol string Yes The token symbol to search for.

Example Request

curl "http://127.0.0.1:8000/v1/lookup_token_by_symbol?chain_id=1&symbol=WETH"

Name Service Tools

Get Address by ENS Name (`get_address_by_ens_name`)

Converts an ENS (Ethereum Name Service) name to its corresponding Ethereum address.

GET /v1/get_address_by_ens_name

Parameters

Name Type Required Description

name string Yes The ENS name to resolve.

Name	Type	Required	Description
`name`	`string`	Yes	The ENS name to resolve.

Example Request

curl "http://127.0.0.1:8000/v1/get_address_by_ens_name?name=vitalik.eth"

Contract Tools

Get Contract ABI (`get_contract_abi`)

Retrieves the Application Binary Interface (ABI) for a smart contract.

GET /v1/get_contract_abi

Parameters

Name Type Required Description

chain_id string Yes The ID of the blockchain.

address string Yes The smart contract address.

Example Request

curl "http://127.0.0.1:8000/v1/get_contract_abi?chain_id=1&address=0x..."

Inspect Contract Code (`inspect_contract_code`)

Returns contract metadata or the content of a specific source file for a verified smart contract.

GET /v1/inspect_contract_code

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`address`	`string`	Yes	The smart contract address.
`file_name`	`string`	No	The name of the source file to fetch. Omit to retrieve metadata and file list.

Example Request

curl "http://127.0.0.1:8000/v1/inspect_contract_code?chain_id=1&address=0x..."

Read Contract (`read_contract`)

Executes a read-only smart contract function and returns its result.

GET /v1/read_contract

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`address`	`string`	Yes	Smart contract address.
`abi`	`string`	Yes	JSON-encoded function ABI dictionary.
`function_name`	`string`	Yes	Name of the function to call.
`args`	`string`	No	JSON-encoded array of function arguments.
`block`	`string`	No	Block identifier or number (`latest` by default).

Example Request

curl "http://127.0.0.1:8000/v1/read_contract?chain_id=1&address=0xdAC17F958D2ee523a2206206994597C13D831ec7&function_name=balanceOf&abi=%7B%22constant%22%3Atrue%2C%22inputs%22%3A%5B%7B%22name%22%3A%22_owner%22%2C%22type%22%3A%22address%22%7D%5D%2C%22name%22%3A%22balanceOf%22%2C%22outputs%22%3A%5B%7B%22name%22%3A%22balance%22%2C%22type%22%3A%22uint256%22%7D%5D%2C%22payable%22%3Afalse%2C%22stateMutability%22%3A%22view%22%2C%22type%22%3A%22function%22%7D&args=%5B%220xF977814e90dA44bFA03b6295A0616a897441aceC%22%5D"

Advanced Tools

Direct API Call (`direct_api_call`)

Allows calling a raw Blockscout API endpoint for advanced or chain-specific data. Supports both GET and POST requests.

GET requests (default):

GET /v1/direct_api_call

Parameters

Name	Type	Required	Description
`chain_id`	`string`	Yes	The ID of the blockchain.
`endpoint_path`	`string`	Yes	The Blockscout API path to call (e.g., `/api/v2/stats`).
`query_params`	`object`	No	Additional query parameters forwarded to the Blockscout API. Use bracket syntax in the query string, e.g., `query_params[page]=1`.
`cursor`	`string`	No	The cursor for pagination from a previous response.

Example Request

curl "http://127.0.0.1:8000/v1/direct_api_call?chain_id=1&endpoint_path=/api/v2/proxy/account-abstraction/operations&query_params[sender]=0x91f51371D33e4E50e838057E8045265372f8d448"

POST requests (for endpoints that require a JSON body, e.g., JSON-RPC):

POST /v1/direct_api_call

Parameters

Name	Location	Type	Required	Description
`chain_id`	Query string	`string`	Yes	The ID of the blockchain.
`endpoint_path`	Query string	`string`	Yes	The Blockscout API path to call (e.g., `/json-rpc`).
`query_params`	Query string	`object`	No	Additional query parameters forwarded to the Blockscout API. Use bracket syntax, e.g., `query_params[key]=value`.
`Content-Type`	Header	`string`	Yes	Must be `application/json`.
(request body)	Body	`object`	Yes	The JSON object to send to the Blockscout endpoint.

Note: Pagination (cursor) is not supported for POST requests.

Example Request

curl -X POST "http://127.0.0.1:8000/v1/direct_api_call?chain_id=1&endpoint_path=/json-rpc" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Reporting Tools

Report Tool Usage (`report_tool_usage`)

Receive an anonymous tool usage report from a community-run server.

POST /v1/report_tool_usage

Headers

Name Required Description

User-Agent Yes Identifies the reporting server version.

Content-Type Yes Must be application/json.

Name	Required	Description
`User-Agent`	Yes	Identifies the reporting server version.
`Content-Type`	Yes	Must be `application/json`.

Parameters

Name	Type	Required	Description
`tool_name`	`string`	Yes	Name of the tool being reported.
`tool_args`	`object`	Yes	Arguments provided to the tool.
`client_name`	`string`	Yes	Name of the MCP client invoking the tool.
`client_version`	`string`	Yes	Version of the MCP client.
`protocol_version`	`string`	Yes	Model Context Protocol version used.

Example Request

curl -X POST "http://127.0.0.1:8000/v1/report_tool_usage" \\
  -H "User-Agent: BlockscoutMCP/0.11.0" \\
  -H "Content-Type: application/json" \\
  -d '{"tool_name": "get_block_number", "tool_args": {"chain_id": "1"}, "client_name": "test-client", "client_version": "1.2.3", "protocol_version": "2024-11-05"}'

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Blockscout MCP Server REST API

Static Endpoints

Skill Resources

Authentication

General Concepts

Standard Response Structure

Error Handling

Error Response Structure

Error Categories

Pagination

Safety & Limits

Response Size Limits

API Endpoints

Discovery

List All Tools (list_tools)

List All Resources (list_resources)

General Tools

Unlock Blockchain Analysis (__unlock_blockchain_analysis__)

Get Chains List (get_chains_list)

Block Tools

Get Block Number (get_block_number)

Get Block Info (get_block_info)

Transaction Tools

Get Transaction Info (get_transaction_info)

Get Transaction Logs (Deprecated) (get_transaction_logs)

Get Transaction Summary (Deprecated) (transaction_summary)

Get Transactions by Address (get_transactions_by_address)

Get Token Transfers by Address (get_token_transfers_by_address)

Address Tools

Get Address Info (get_address_info)

Get Address Logs (Deprecated) (get_address_logs)

Token & NFT Tools

Get Tokens by Address (get_tokens_by_address)

Get NFT Tokens by Address (nft_tokens_by_address)

Search Tools

Lookup Token by Symbol (lookup_token_by_symbol)

Name Service Tools

Get Address by ENS Name (get_address_by_ens_name)

Contract Tools

Get Contract ABI (get_contract_abi)

Inspect Contract Code (inspect_contract_code)

Read Contract (read_contract)

Advanced Tools

Direct API Call (direct_api_call)

Reporting Tools

Report Tool Usage (report_tool_usage)

List All Tools (`list_tools`)

List All Resources (`list_resources`)

Unlock Blockchain Analysis (`__unlock_blockchain_analysis__`)

Get Chains List (`get_chains_list`)

Get Block Number (`get_block_number`)

Get Block Info (`get_block_info`)

Get Transaction Info (`get_transaction_info`)

Get Transaction Logs (Deprecated) (`get_transaction_logs`)

Get Transaction Summary (Deprecated) (`transaction_summary`)

Get Transactions by Address (`get_transactions_by_address`)

Get Token Transfers by Address (`get_token_transfers_by_address`)

Get Address Info (`get_address_info`)

Get Address Logs (Deprecated) (`get_address_logs`)

Get Tokens by Address (`get_tokens_by_address`)

Get NFT Tokens by Address (`nft_tokens_by_address`)

Lookup Token by Symbol (`lookup_token_by_symbol`)

Get Address by ENS Name (`get_address_by_ens_name`)

Get Contract ABI (`get_contract_abi`)

Inspect Contract Code (`inspect_contract_code`)

Read Contract (`read_contract`)

Direct API Call (`direct_api_call`)

Report Tool Usage (`report_tool_usage`)