Blockscout MCP Server REST API

July 24, 2026 · View on GitHub

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 a dedicated credential to access the MCP server itself. This may be subject to change in future releases.

Its data endpoints query Blockscout through its PRO API, so every request to those endpoints must include a Blockscout PRO API key in the Blockscout-MCP-Pro-Api-Key request header. To obtain a key, register on the Blockscout Developer Portal (the free tier does not require a credit card); keys are prefixed proapi_.

The supplied key authenticates that request's upstream PRO API calls, so each caller consumes its own PRO credit allowance.
If the key is missing, or malformed (it contains control characters or exceeds the maximum allowed length), any request that reaches a PRO-authenticated upstream call fails with HTTP 400. Endpoints that don't query the PRO API are unaffected.
The key is never written to logs, analytics, or cache keys. A raw Authorization header sent by the client is ignored and never forwarded to the PRO API; only the dedicated header above is honored.

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, a low-credits advisory emitted when the Blockscout PRO API credit balance drops below the configured threshold, or an operator-configured notice that requests should be authorized with the client's own PRO API key.
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 an account/quota state of the PRO API key supplied with the request 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 API key supplied with the request has been exhausted. This is a distinct, clearly-labeled signal — separate from generic transient upstream failures — and reflects that key's quota state, not a problem with the request itself: the caller 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 encodes the server's position within the result set, but it is not necessarily the only replay-relevant parameter: some endpoints (for example direct_api_call carrying a query_params filter) include additional parameters alongside the cursor that must be resent on every page. Always replay the complete next_call.params object verbatim — treat it, not the cursor alone, as the pagination replay contract.

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.
`auth_origin`	`string \| null`	No	Resolved authorization origin on the reporting instance: `client`, `server`, or `none`. Explicit `null` (or omitted, as from legacy reporters) is treated as `unknown` downstream.
`api_key_fingerprint`	`string \| null`	No	One-way, non-reversible SHA-256 fingerprint of the effective PRO API key available to back the request on the reporting instance — the request's authorization context, not whether the invoked tool consumed the key. Non-null values are exactly 64 lowercase hexadecimal characters; never the key itself; explicit `null` (or omitted) when no usable key was available.

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"}'