Defillama Official Token Research

---
name: token-research
description: >
  Comprehensive token analysis combining price, market cap, unlock schedule,
  DeFi deposits, and yield opportunities. Use when the user asks to analyze a
  token, research a token, check token fundamentals, or wants full token
  intelligence including vesting and DeFi usage.
---

# Token Research

Perform end-to-end token analysis by combining price data, unlock schedules,
DeFi deposit tracking, yield opportunities, and protocol fundamentals.

## Workflow

### Step 1 - Resolve the token entity

Get the canonical token identifier (coingecko:xxx format).

```
defillama:resolve_entity
  entity_type: "token"
  name: "<user-provided name>"
```

### Step 2 - Price and market data

Fetch current price, market cap, volume, and ATH.

```
defillama:get_token_prices
  token: "<coingecko:token_id>"
```

Key fields: `price`, `mcap`, `volume`, `price_ath`. Distance from ATH can be computed as `(price_ath - price) / price_ath`.

### Step 3 - Unlock schedule

Check vesting and upcoming token unlocks that may create sell pressure.

```
defillama:get_token_unlocks
  token: "<token_name>"
```

Flag any large unlocks in the next 30 days as potential sell pressure.

### Step 4 - DeFi deposits

See where the token is deposited across DeFi protocols.

```
defillama:get_token_tvl
  token: "<coingecko:token_id>"
```

Uses `dim.token_set()` for family resolution (e.g., `coingecko:ethereum`
matches ETH, wETH, stETH, etc.). The `component` param filters by TVL
type (base, borrowed, staking, pool2, treasury, vesting). Quality
filters (`is_distressed`, `has_misrepresented_tokens`) are applied.

This shows which protocols hold the most of this token, indicating
DeFi demand and utility.

### Step 5 - Yield opportunities

Find pools where users can earn yield on this token.

```
defillama:get_yield_pools
  token: "<coingecko:token_id>"
```

The `token` param expects canonical keys (e.g., `coingecko:ethereum`).
Uses `dim.pool_set()` for family matching.

### Step 6 - Protocol fundamentals (if applicable)

If the token belongs to a DeFi protocol, fetch protocol metrics.

```
defillama:get_protocol_metrics
  protocol: "<protocol_slug>"
```

## Output Format

Present the report with these sections in order:

1. **Price & Market** - Current price, market cap, 24h volume, distance
   from ATH, and recent trend.
2. **Unlock Schedule** - Upcoming unlocks with dates, amounts, and
   percentage of circulating supply. Highlight any cliff unlocks.
3. **DeFi Deposits** - Top protocols holding this token, total value
   deposited, and what this implies about utility.
4. **Yield Opportunities** - Top 3-5 pools by APY and TVL where users
   can deploy this token.
5. **Protocol Fundamentals** - If the token is a protocol governance or
   utility token, include TVL, fees, revenue, and valuation ratios.

## Tips

- Large unlocks (>2% of circulating supply) within 30 days are a
  material risk factor.
- High DeFi deposits relative to circulating supply indicate strong
  holder conviction and reduced liquid supply.
- Compare yield APY sources: base APY from fees is sustainable, reward
  APY from token emissions is not.
- If the token has no unlock data, it may be fully unlocked or the data
  may not be tracked - note this to the user.
- Use `start_date` / `end_date` for custom date ranges on price and TVL
  queries.