> For the complete documentation index, see [llms.txt](https://archer-bot.gitbook.io/archer.bot/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://archer-bot.gitbook.io/archer.bot/what-you-can-do/token-lookups.md).

# Token Lookups

Token lookups are the **read-only** primitives that underpin every transaction Archer runs. They cover three things: resolving a token's identity, fetching its current price, and reading your balances. None of these require approval. Call them as freely as you want.

***

## Token Resolution

Look up a token's metadata (contract address, decimals, chain availability) by ticker or contract address.

### Sample Input Queries

* *"What's the contract address for USDC on Arbitrum?"*
* *"Resolve PEPE on Ethereum"*
* *"Find the token address for WBTC on Base"*
* *"What is 0x8e5c04f82d6464b420e2018362e7e7ab813cf190?"*

### What It Does

Under the hood this is the `resolve_token` tool. Archer searches its token database by ticker or contract address and returns the canonical metadata. Resolution happens automatically before any swap, bridge, or send. You don't usually need to call it explicitly unless you want the raw info.

### Sample Output Structure

```json
{
  "status": "OK",
  "tokens": [
    {
      "ticker": "USDC",
      "name": "USD Coin",
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "chain": "arbitrum",
      "chainId": 42161,
      "decimals": 6,
      "coingeckoId": "usd-coin",
      "isSpam": false
    }
  ]
}
```

When a ticker is ambiguous (e.g., "USDC" exists on every chain), Archer returns multiple matches and the agent disambiguates from context. When a ticker is recognized as spam, `isSpam: true` short-circuits any downstream swap or bridge.

***

## Price Lookups

Check the current USD price of any supported token.

### Sample Input Queries

* *"What's the price of ETH?"*
* *"How much is SOL right now?"*
* *"Price of ARB"*
* *"What's MATIC trading at?"*

### What It Does

Prices are fetched live from Moralis, CoinGecko, and Jupiter (for Solana tokens). Archer never guesses. If every price provider is unavailable for a token, Archer tells you it can't quote rather than returning a stale or fabricated number.

### Sample Output Structure

```json
{
  "status": "OK",
  "ticker": "ETH",
  "priceUsd": "3354.21",
  "source": "coingecko",
  "fetchedAt": "2026-04-28T14:32:18Z"
}
```

***

## Portfolio & Balance Queries

View your holdings across all connected wallets and chains.

### Sample Input Queries

* *"What's my balance?"*
* *"Show my portfolio"*
* *"How much USDC do I have?"*
* *"What's my ETH balance on Arbitrum?"*
* *"Show all my balances"*

### What It Does

Archer aggregates balances across all 7 supported EVM chains (Ethereum, Arbitrum, Base, Polygon, Optimism, Avalanche, BSC) and Solana, with USD values. Each balance row identifies which wallet it belongs to (`primary` or `connected`). See [Manage Your Wallet](/archer.bot/getting-started/manage-your-wallet.md) for why per-wallet attribution matters.

### Sample Output Structure

```json
{
  "status": "OK",
  "balances": [
    {
      "ticker": "ETH",
      "chain": "base",
      "amount": "0.049",
      "amountUsd": "115.06",
      "wallet": "0xPrimary...",
      "walletType": "primary"
    },
    {
      "ticker": "USDC",
      "chain": "polygon",
      "amount": "3.00",
      "amountUsd": "3.00",
      "wallet": "0xConnected...",
      "walletType": "connected"
    }
  ],
  "totalUsd": "118.06"
}
```

Spam-flagged tokens are filtered out automatically. See [Token Safety & Spam Detection](/archer.bot/what-you-can-do/token-safety-and-spam-detection.md).