resolve_token
Resolves a token symbol to its canonical contract address and decimals from a curated registry, surfacing native vs bridged warnings to prevent silent token substitution.
Instructions
Resolve a (chain, symbol) pair to its canonical contract address + decimals from the curated registry. Supports EVM chains (ethereum, arbitrum, polygon, base, optimism), Solana, and TRON. Surfaces native-vs-bridged ambiguity verbatim — e.g. asking for USDC on Arbitrum returns the native Circle USDC contract AND a hasBridgedVariant warning with the USDC.e legacy-bridged contract in alternatives[], so the agent can offer the user the actual choice instead of silently picking one. Asking for USDC.e directly returns the bridged contract with an isBridgedVariant warning + the native USDC alternative. Same shape on Polygon/Optimism (USDC.e) and Base (USDbC is the bridged form there). By design, this tool is canonical-registry-only — it does NOT probe on-chain to resolve unknown symbols, since an attacker can deploy a contract that returns "USDC" from symbol() and is wholly unrelated to the real Circle stablecoin. Unknown symbols throw with a list of registry hits on that chain so the agent can suggest the right one. USE THIS BEFORE prepare_token_send when the user names a token by symbol — surface any warnings to the user before passing the resolved contract through to prepare_token_send. If the desired token isn't in the registry, look up the contract on a block explorer and call prepare_token_send directly with the explicit address.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chain | Yes | Chain the symbol is on. Restricted to the chains with curated token tables. BTC + LTC have no token concept and aren't accepted. | |
| symbol | Yes | Token symbol to resolve (case-insensitive, but the canonical-registry key casing wins on output). Examples: "USDC", "USDC.e", "USDbC", "WETH", "BONK". The resolver does NOT probe on-chain — only canonical-registry hits succeed, by design (stops phishing-token symbol collisions from being resolved silently). |