Blockscout MCP Server

Instructions

Implementation Reference

• blockscout_mcp_server/tools/transaction/get_transactions_by_address.py:23-125 (handler)

  The primary handler function for the 'get_transactions_by_address' tool. It queries the Blockscout API's advanced filters endpoint, handles date/method filtering, cursor-based pagination, progress reporting, data transformation, and returns a paginated ToolResponse with AdvancedFilterItem instances.
  @log_tool_invocation async def get_transactions_by_address( chain_id: Annotated[str, Field(description="The ID of the blockchain")], address: Annotated[str, Field(description="Address which either sender or receiver of the transaction")], ctx: Context, age_from: Annotated[str | None, Field(description="Start date and time (e.g 2025-05-22T23:00:00.00Z).")] = None, age_to: Annotated[str | None, Field(description="End date and time (e.g 2025-05-22T22:30:00.00Z).")] = None, methods: Annotated[ str | None, Field(description="A method signature to filter transactions by (e.g 0x304e6ade)"), ] = None, cursor: Annotated[ str | None, Field(description="The pagination cursor from a previous response to get the next page of results."), ] = None, ) -> ToolResponse[list[AdvancedFilterItem]]: """ Retrieves native currency transfers and smart contract interactions (calls, internal txs) for an address. **EXCLUDES TOKEN TRANSFERS**: Filters out direct token balance changes (ERC-20, etc.). You'll see calls *to* token contracts, but not the `Transfer` events. For token history, use `get_token_transfers_by_address`. A single tx can have multiple records from internal calls; use `internal_transaction_index` for execution order. Use cases: - `get_transactions_by_address(address, age_from)` - get all txs to/from the address since a given date. - `get_transactions_by_address(address, age_from, age_to)` - get all txs to/from the address between given dates. - `get_transactions_by_address(address, age_from, age_to, methods)` - get all txs to/from the address between given dates, filtered by method. **SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages. """ # noqa: E501 api_path = "/api/v2/advanced-filters" query_params = { "to_address_hashes_to_include": address, "from_address_hashes_to_include": address, } if age_from: query_params["age_from"] = age_from if age_to: query_params["age_to"] = age_to if methods: query_params["methods"] = methods apply_cursor_to_params(cursor, query_params) tool_overall_total_steps = 12.0 await report_and_log_progress( ctx, progress=0.0, total=tool_overall_total_steps, message=f"Starting to fetch transactions for {address} on chain {chain_id}...", ) base_url = await get_blockscout_base_url(chain_id) await report_and_log_progress( ctx, progress=1.0, total=tool_overall_total_steps, message="Resolved Blockscout instance URL. Now fetching transactions...", ) filtered_items, has_more_pages = await _fetch_filtered_transactions_with_smart_pagination( base_url=base_url, api_path=api_path, initial_params=query_params, target_page_size=config.advanced_filters_page_size, ctx=ctx, progress_start_step=2.0, total_steps=tool_overall_total_steps, ) await report_and_log_progress( ctx, progress=tool_overall_total_steps, total=tool_overall_total_steps, message="Successfully fetched transaction data.", ) fields_to_remove = [ "total", "token", "token_transfer_batch_index", "token_transfer_index", ] final_items, pagination = create_items_pagination( items=filtered_items, page_size=config.advanced_filters_page_size, tool_name="get_transactions_by_address", next_call_base_params={ "chain_id": chain_id, "address": address, "age_from": age_from, "age_to": age_to, "methods": methods, }, cursor_extractor=extract_advanced_filters_cursor_params, force_pagination=has_more_pages and len(filtered_items) <= config.advanced_filters_page_size, ) transformed_items = [ AdvancedFilterItem.model_validate(_transform_advanced_filter_item(item, fields_to_remove)) for item in final_items ] return build_tool_response(data=transformed_items, pagination=pagination)
• blockscout_mcp_server/server.py:162-164 (registration)

  Registration of the get_transactions_by_address tool in the FastMCP server instance, with annotations and structured_output disabled.
  structured_output=False, annotations=create_tool_annotations("Get Transactions by Address"), )(get_transactions_by_address)
• blockscout_mcp_server/models.py:276-292 (schema)

  Pydantic model defining the structure of individual transaction items returned by the tool (AdvancedFilterItem), used in ToolResponse[list[AdvancedFilterItem]]. Allows extra fields for API compatibility.
  # --- Model for get_transactions_by_address and get_token_transfers_by_address Data Payload --- class AdvancedFilterItem(BaseModel): """Represents a single item from the advanced filter API response.""" model_config = ConfigDict(extra="allow") # External APIs may add new fields; allow them to avoid validation errors from_address: str | None = Field( default=None, alias="from", description="The sender address.", ) to_address: str | None = Field( default=None, alias="to", description="The recipient address.", )
• blockscout_mcp_server/models.py:384-410 (schema)

  Generic Pydantic response model (ToolResponse[T]) used by the tool for output, including data, notes, instructions, and pagination.
  class ToolResponse(BaseModel, Generic[T]): """A standardized, structured response for all MCP tools, generic over the data payload type.""" data: T = Field(description="The main data payload of the tool's response.") data_description: list[str] | None = Field( None, description="A list of notes explaining the structure, fields, or conventions of the 'data' payload.", ) notes: list[str] | None = Field( None, description=( "A list of important contextual notes, such as warnings about data truncation or data quality issues." ), ) instructions: list[str] | None = Field( None, description="A list of suggested follow-up actions or instructions for the LLM to plan its next steps.", ) pagination: PaginationInfo | None = Field( None, description="Pagination information, present only if the 'data' is a single page of a larger result set.", )