> 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/intents/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/intents/token-safety-and-spam-detection.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://archer-bot.gitbook.io/archer.bot/intents/token-lookups.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.