lookup_token_by_symbol
Find token addresses by searching with symbol or name. Returns multiple matches from blockchain data to help identify tokens.
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 core handler function that executes the lookup_token_by_symbol tool logic. It queries the Blockscout search API, processes results, limits to 7 items, and returns a ToolResponse with TokenSearchResult objects.@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:169-172 (registration)MCP tool registration for lookup_token_by_symbol, including annotations and structured_output=False.mcp.tool( structured_output=False, annotations=create_tool_annotations("Lookup Token by Symbol"), )(lookup_token_by_symbol)
- Pydantic model defining the structure of each TokenSearchResult in the tool's output data list.# --- Model for lookup_token_by_symbol Data Payload --- 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.")
- blockscout_mcp_server/api/routes.py:335-335 (registration)REST API route registration for the lookup_token_by_symbol tool endpoint (/v1/lookup_token_by_symbol)._add_v1_tool_route(mcp, "/lookup_token_by_symbol", lookup_token_by_symbol_rest)
- REST wrapper function that calls the main tool handler with extracted parameters from the HTTP request.@handle_rest_errors async def lookup_token_by_symbol_rest(request: Request) -> Response: """REST wrapper for the lookup_token_by_symbol tool.""" params = extract_and_validate_params(request, required=["chain_id", "symbol"], optional=[]) tool_response = await lookup_token_by_symbol(**params, ctx=get_mock_context(request)) return JSONResponse(tool_response.model_dump())