# 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**

```bash
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](https://dev.blockscout.com) (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.

The official deployment at `https://mcp.blockscout.com` requires a client-supplied PRO API key for programmatic access: send the header above on every request. Integrations that do not are outside the scope of this document.

## 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.

```json
{
  "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

```json
{
  "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:**

```json
{
  "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:

```http
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**

  ```bash
  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**

  ```bash
  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__`)

Initializes a Blockscout MCP session: returns server reference data (`server_version` and, on session-gated deployments, `session_id`) in `data`, with the `blockscout-analysis` skill pointer and the URI resolution rule delivered in the response's `instructions` list. Call it once per session, before any other tool.

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

- **Parameters**

  *None*

- **Example Request**

  ```bash
  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.
  - `session_id` (`string`, optional): Opaque session identifier.

- **Example Requests**

  ```bash
  # 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. |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

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

#### Get Latest Block (legacy alias)

Legacy alias that invokes `get_block_number` with `datetime=None` (the latest block); prefer `/v1/get_block_number`.

`GET /v1/get_latest_block`

- **Parameters**

  | Name | Type | Required | Description |
  | ---- | ---- | -------- | ----------- |
  | `chain_id` | `string` | Yes | The ID of the blockchain. |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  curl "http://127.0.0.1:8000/v1/get_latest_block?chain_id=1"
  ```

#### 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.      |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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.|
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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**

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

- **Example Response**

  ```json
  {
    "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**

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

- **Example Response**

  ```json
  {
    "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.  |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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.|
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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. |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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**

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

- **Example Response**

  ```json
  {
    "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.|
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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.|
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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.   |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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.   |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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.  |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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. |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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). |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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. |
  | `session_id`         | `string`  | No       | Opaque session identifier.                       |

- **Example Request**

  ```bash
  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`. |
  | `session_id` | Query string | `string` | No | Opaque session identifier. |
  | `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**

  ```bash
  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`. |

- **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**

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