lookup_token_by_symbol
Find token addresses by symbol or name using the Blockscout MCP Server. Returns matching token results based on similarity, limited to the top results. Specify chain ID and token details to search blockchain data efficiently.
Instructions
Search for token addresses by symbol or name. Returns multiple potential
matches based on symbol or token name similarity. Only the first
``TOKEN_RESULTS_LIMIT`` matches from the Blockscout API are returned.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chain_id | Yes | The ID of the blockchain | |
| symbol | Yes | Token symbol or name to search for |
Implementation Reference
- The primary handler function for the 'lookup_token_by_symbol' tool. It queries the Blockscout search API, limits results, constructs TokenSearchResult objects, and returns a standardized ToolResponse.@log_tool_invocation async def lookup_token_by_symbol( chain_id: Annotated[str, Field(description="The ID of the blockchain")], symbol: Annotated[str, Field(description="Token symbol or name to search for")], ctx: Context, ) -> ToolResponse[list[TokenSearchResult]]: """ Search for token addresses by symbol or name. Returns multiple potential matches based on symbol or token name similarity. Only the first ``TOKEN_RESULTS_LIMIT`` matches from the Blockscout API are returned. """ api_path = "/api/v2/search" params = {"q": symbol} await report_and_log_progress( ctx, progress=0.0, total=2.0, message=f"Starting token search for '{symbol}' on chain {chain_id}...", ) base_url = await get_blockscout_base_url(chain_id) await report_and_log_progress( ctx, progress=1.0, total=2.0, message="Resolved Blockscout instance URL. Searching for tokens...", ) response_data = await make_blockscout_request(base_url=base_url, api_path=api_path, params=params) await report_and_log_progress( ctx, progress=2.0, total=2.0, message="Successfully completed token search.", ) all_items = response_data.get("items", []) notes = None if len(all_items) > TOKEN_RESULTS_LIMIT: notes = [ ( f"The number of results exceeds the limit of {TOKEN_RESULTS_LIMIT}. " f"Only the first {TOKEN_RESULTS_LIMIT} are shown." ) ] items_to_process = all_items[:TOKEN_RESULTS_LIMIT] search_results = [ TokenSearchResult( address=item.get("address_hash", ""), name=item.get("name", ""), symbol=item.get("symbol", ""), token_type=item.get("token_type", ""), total_supply=item.get("total_supply"), circulating_market_cap=item.get("circulating_market_cap"), exchange_rate=item.get("exchange_rate"), is_smart_contract_verified=item.get("is_smart_contract_verified", False), is_verified_via_admin_panel=item.get("is_verified_via_admin_panel", False), ) for item in items_to_process ] return build_tool_response(data=search_results, notes=notes)
- blockscout_mcp_server/server.py:170-173 (registration)Registration of the lookup_token_by_symbol tool with the FastMCP server instance, including annotations for title and hints.structured_output=False, annotations=create_tool_annotations("Lookup Token by Symbol"), )(lookup_token_by_symbol) mcp.tool(
- Pydantic model defining the structure of each token search result returned by the tool.class TokenSearchResult(BaseModel): """Represents a single token found by a search query.""" address: str = Field(description="The contract address of the token.") name: str = Field(description="The full name of the token (e.g., 'USD Coin').") symbol: str = Field(description="The symbol of the token (e.g., 'USDC').") token_type: str = Field(description="The token standard (e.g., 'ERC-20').") total_supply: str | None = Field(description="The total supply of the token.") circulating_market_cap: str | None = Field(description="The circulating market cap, if available.") exchange_rate: str | None = Field(description="The current exchange rate, if available.") is_smart_contract_verified: bool = Field(description="Indicates if the token's contract is verified.") is_verified_via_admin_panel: bool = Field(description="Indicates if the token is verified by the Blockscout team.")
- Generic Pydantic model used for the tool's output, wrapping the list of TokenSearchResult with additional metadata like notes 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.", )