DefiLlama MCP Data Reference
Tool Quick Reference
| Question |
Tool |
Key Params |
| Total DeFi TVL, global volumes |
defillama:get_market_totals |
metrics (tvl_base, volume_dexs_1d, etc.) |
| Protocol TVL, fees, revenue |
defillama:get_protocol_metrics |
protocol, metrics |
| Chain TVL, gas fees, REV |
defillama:get_chain_metrics |
chain, metrics |
| Token price, mcap, ATH |
defillama:get_token_prices |
token |
| Category rankings |
defillama:get_category_metrics |
category |
| Pool APY, lending rates |
defillama:get_yield_pools |
token, chain, category |
| Stablecoin supply |
defillama:get_stablecoin_supply |
stablecoin, chain |
| ETF inflows/outflows |
defillama:get_etf_flows |
token (bitcoin/ethereum) |
| Bridge volume |
defillama:get_bridge_flows |
bridge, chain |
| CEX volume |
defillama:get_cex_volumes |
cex |
| Open interest |
defillama:get_open_interest |
protocol, chain |
| Hacks/exploits |
defillama:get_events |
event_type: "hacks" |
| Fundraising |
defillama:get_events |
event_type: "raises" |
| Protocol events |
defillama:get_events |
event_type: "protocol_events" |
| Protocol treasury |
defillama:get_treasury |
treasury |
| Institutional holdings |
defillama:get_dat_holdings |
institution, token |
| Token unlocks |
defillama:get_token_unlocks |
token, query_type (chart, window, day, window_all, ratio, market_window) |
| Token TVL in protocols |
defillama:get_token_tvl |
token, protocol |
| Oracle coverage |
defillama:get_oracle_metrics |
oracle |
| User activity |
defillama:get_user_activity |
protocol, chain |
| Income statement |
defillama:get_income_statement |
protocol |
| Protocol metadata, URLs, audit |
defillama:get_protocol_info |
protocol, category, tag, has_token, chain |
| Chain metadata, type, L2 parent |
defillama:get_chain_info |
chain, chain_type |
| List valid categories |
defillama:list_categories |
type (protocol, token, chain) |
| Unknown entity slug |
defillama:resolve_entity |
name |
Entity Conventions
- Protocols: lowercase-hyphenated slugs (
aave, uniswap, compound-v3)
- Chains: lowercase (
ethereum, solana, arbitrum)
- Tokens:
coingecko: prefix (coingecko:ethereum, coingecko:bitcoin, coingecko:usd-coin)
- CEX: slug includes suffix (
binance-cex, coinbase-cex, htx, gate-io)
- Categories: Title case (
Lending, DEX, Derivatives)
Protocol vs Sub-Protocol
Many protocols have multiple versions. The database tracks both:
- Parent protocol (e.g.,
aave) — used in get_protocol_metrics, aggregates all versions
- Sub-protocol (e.g.,
aave-v3) — individual versions, used in sub_protocol views
resolve_entity returns both slug (sub-protocol) and parent_protocol. Use parent_protocol for get_protocol_metrics. Use slug when you need a specific version.
Example: resolve_entity({name: "compound"}) returns:
- slug: compound-v2, parent_protocol: compound
- slug: compound-v3, parent_protocol: compound
→ Use
protocol: "compound" in get_protocol_metrics for the aggregate.
Array Support
All entity params accept single values or arrays for comparison:
protocol: "aave" or protocol: ["aave", "lido", "compound"]
chain: "ethereum" or chain: ["ethereum", "solana"]
token: "coingecko:ethereum" or token: ["coingecko:ethereum", "coingecko:bitcoin"]
Entity Resolution
Try tools directly for well-known entities — works 80%+ of the time. Use defillama:resolve_entity only when:
- Unsure of exact slug
- Tool returns 0 rows
- Need to disambiguate (e.g., "compound" → compound-v2, compound-v3)
- Need to find the parent_protocol slug
Period Parameter
All tools accept period (NOT time_range):
current (default) -- latest snapshot
7d, 30d, 90d, 180d, 365d -- rolling windows
For custom date ranges, use start_date and end_date (YYYY-MM-DD format) instead of period. If start_date is set without end_date, it defaults to today.
Critical Conventions
Stock vs Flow
Different aggregation rules -- getting this wrong produces nonsensical results:
- Stock (point-in-time snapshots):
tvl, price, mcap -- NEVER sum across dates
- Flow (cumulative over period):
fees_1d, revenue_1d, volume -- CAN sum across dates
Percentage Formatting
Two different conventions in the data:
*_pct_change columns = decimals (e.g., -0.13 = -13%, 0.35 = +35%). Multiply by 100 for display.
apy columns = already percentages (e.g., 2.32 = 2.32%). Do NOT multiply by 100.
TVL Components
Components are mutually exclusive -- never double-add:
tvl_base = default TVL (excludes liquid staking and double-counted)
tvl_ls_only = liquid staking portion not in tvl_base
tvl_dc_only = double-counted portion not in tvl_base
tvl_ls_and_dc = both LS and DC
- Total with LS+DC =
tvl_base + tvl_ls_only + tvl_dc_only + tvl_ls_and_dc
Fee and Revenue
fees = gross payments by users
revenue = protocol's cut (fees - payments to LPs/stakers)
holder_revenue = buybacks + dividends to token holders
- Chain-level:
chain_fees (gas), chain_revenue, chain_mev, app_fees (protocol fees on chain), app_revenue
Metric Name Patterns
Protocol metrics follow these patterns:
- TVL:
tvl_base, tvl_staking, tvl_borrowed, tvl_pool2, tvl_treasury, tvl_vesting
- Flows (with suffixes
_1d/_7d/_30d/_90d/_180d/_365d/_ytd/_alltime/_annualised): fees, revenue, holder_revenue, incentive
- Volume (same suffixes):
volume_dexs, volume_aggregators, volume_derivatives, volume_aggr_derivatives, volume_options
- Market:
price, mcap, fdv, fdv_outstanding, token_volume, ps_ratio, pf_ratio
- pct_change variants only available on
_current views
Chain metrics use chain_fees, chain_revenue, chain_mev, app_fees, app_revenue instead of fees, revenue.
Daily views only have the _1d suffix for flows/volumes.
Important Gotchas
- Category column:
get_protocol_metrics has NO category column. Use get_category_metrics for category-level data.
- FDV: Never sort by FDV -- unreliable
total_supply data produces junk rankings. Sort by mcap instead.
- Valuation:
ps_ratio = mcap / annualised revenue. pf_ratio = mcap / annualised fees. Lower = potentially undervalued.
- Metric validation: Protocol/chain/category metrics are validated against actual DB columns. Invalid metrics return a suggestion for the closest match.
- NULL values: NULL means data unavailable, NOT $0. Do not report NULL as zero.
- Params accept string or array:
protocol: "aave" or protocol: ["aave", "lido"]. Param names are singular (protocol not protocols).
- sort_by format: String like
"tvl_base desc" or "fees_1d desc".
Examples
Example 1:
User: "What is Aave's TVL?"
Tool call: defillama:get_protocol_metrics(protocol: "aave", metrics: ["tvl_base"])
Example 2:
User: "Top 5 chains by fees"
Tool call: defillama:get_chain_metrics(sort_by: "chain_fees_1d desc", limit: 5)
Example 3:
User: "ETH price history over 90 days"
Tool call: defillama:get_token_prices(token: "coingecko:ethereum", period: "90d")
Example 4:
User: "Compare ETH price and Ethereum chain TVL"
Tool calls in parallel:
defillama:get_token_prices(token: "coingecko:ethereum")
defillama:get_chain_metrics(chain: "ethereum")
Example 5:
User: "Biggest DeFi hacks this year"
Tool call: defillama:get_events(event_type: "hacks", sort_by: "amount desc", limit: 10, period: "365d")
Example 6:
User: "Aave TVL from Jan to Mar 2025"
Tool call: defillama:get_protocol_metrics(protocol: "aave", metrics: ["tvl_base"], start_date: "2025-01-01", end_date: "2025-03-31")
Error Recovery
- 0 rows returned -> call
defillama:resolve_entity(name: "...") -> retry with the correct slug
- Wrong data -> verify you're using the right tool (protocol vs chain vs category)
- Ambiguous entity -> call
resolve_entity to see all matching slugs, then pick the right one
1---
2name: defi-data
3description: Core reference for DefiLlama MCP tools. Maps DeFi questions to the correct tool call with proper parameters. Covers entity conventions, metric interpretation, stock vs flow distinctions, percentage formatting, and error recovery. Use whenever querying DeFi data — protocol TVL, token prices, chain metrics, fees, revenue, yields, stablecoins, bridges, ETFs, hacks, raises, treasuries, or institutional holdings.
4metadata:
5 source: https://skillmd.com/skills/defillama/defi-data
6---
7
8# DefiLlama MCP Data Reference
9
10## Tool Quick Reference
11
12| Question | Tool | Key Params |
13|----------|------|------------|
14| Total DeFi TVL, global volumes | `defillama:get_market_totals` | `metrics` (tvl_base, volume_dexs_1d, etc.) |
15| Protocol TVL, fees, revenue | `defillama:get_protocol_metrics` | `protocol`, `metrics` |
16| Chain TVL, gas fees, REV | `defillama:get_chain_metrics` | `chain`, `metrics` |
17| Token price, mcap, ATH | `defillama:get_token_prices` | `token` |
18| Category rankings | `defillama:get_category_metrics` | `category` |
19| Pool APY, lending rates | `defillama:get_yield_pools` | `token`, `chain`, `category` |
20| Stablecoin supply | `defillama:get_stablecoin_supply` | `stablecoin`, `chain` |
21| ETF inflows/outflows | `defillama:get_etf_flows` | `token` (bitcoin/ethereum) |
22| Bridge volume | `defillama:get_bridge_flows` | `bridge`, `chain` |
23| CEX volume | `defillama:get_cex_volumes` | `cex` |
24| Open interest | `defillama:get_open_interest` | `protocol`, `chain` |
25| Hacks/exploits | `defillama:get_events` | `event_type: "hacks"` |
26| Fundraising | `defillama:get_events` | `event_type: "raises"` |
27| Protocol events | `defillama:get_events` | `event_type: "protocol_events"` |
28| Protocol treasury | `defillama:get_treasury` | `treasury` |
29| Institutional holdings | `defillama:get_dat_holdings` | `institution`, `token` |
30| Token unlocks | `defillama:get_token_unlocks` | `token`, `query_type` (chart, window, day, window_all, ratio, market_window) |
31| Token TVL in protocols | `defillama:get_token_tvl` | `token`, `protocol` |
32| Oracle coverage | `defillama:get_oracle_metrics` | `oracle` |
33| User activity | `defillama:get_user_activity` | `protocol`, `chain` |
34| Income statement | `defillama:get_income_statement` | `protocol` |
35| Protocol metadata, URLs, audit | `defillama:get_protocol_info` | `protocol`, `category`, `tag`, `has_token`, `chain` |
36| Chain metadata, type, L2 parent | `defillama:get_chain_info` | `chain`, `chain_type` |
37| List valid categories | `defillama:list_categories` | `type` (protocol, token, chain) |
38| Unknown entity slug | `defillama:resolve_entity` | `name` |
39
40## Entity Conventions
41
42- **Protocols**: lowercase-hyphenated slugs (`aave`, `uniswap`, `compound-v3`)
43- **Chains**: lowercase (`ethereum`, `solana`, `arbitrum`)
44- **Tokens**: `coingecko:` prefix (`coingecko:ethereum`, `coingecko:bitcoin`, `coingecko:usd-coin`)
45- **CEX**: slug includes suffix (`binance-cex`, `coinbase-cex`, `htx`, `gate-io`)
46- **Categories**: Title case (`Lending`, `DEX`, `Derivatives`)
47
48## Protocol vs Sub-Protocol
49
50Many protocols have multiple versions. The database tracks both:
51- **Parent protocol** (e.g., `aave`) — used in `get_protocol_metrics`, aggregates all versions
52- **Sub-protocol** (e.g., `aave-v3`) — individual versions, used in sub_protocol views
53
54`resolve_entity` returns both `slug` (sub-protocol) and `parent_protocol`. Use `parent_protocol` for `get_protocol_metrics`. Use `slug` when you need a specific version.
55
56Example: resolve_entity({name: "compound"}) returns:
57- slug: compound-v2, parent_protocol: compound
58- slug: compound-v3, parent_protocol: compound
59→ Use `protocol: "compound"` in get_protocol_metrics for the aggregate.
60
61## Array Support
62
63All entity params accept single values or arrays for comparison:
64- `protocol: "aave"` or `protocol: ["aave", "lido", "compound"]`
65- `chain: "ethereum"` or `chain: ["ethereum", "solana"]`
66- `token: "coingecko:ethereum"` or `token: ["coingecko:ethereum", "coingecko:bitcoin"]`
67
68## Entity Resolution
69
70Try tools directly for well-known entities — works 80%+ of the time. Use `defillama:resolve_entity` only when:
71
72- Unsure of exact slug
73- Tool returns 0 rows
74- Need to disambiguate (e.g., "compound" → compound-v2, compound-v3)
75- Need to find the parent_protocol slug
76
77## Period Parameter
78
79All tools accept `period` (NOT `time_range`):
80
81- `current` (default) -- latest snapshot
82- `7d`, `30d`, `90d`, `180d`, `365d` -- rolling windows
83
84For custom date ranges, use `start_date` and `end_date` (YYYY-MM-DD format) instead of `period`. If `start_date` is set without `end_date`, it defaults to today.
85
86## Critical Conventions
87
88### Stock vs Flow
89
90Different aggregation rules -- getting this wrong produces nonsensical results:
91
92- **Stock** (point-in-time snapshots): `tvl`, `price`, `mcap` -- NEVER sum across dates
93- **Flow** (cumulative over period): `fees_1d`, `revenue_1d`, `volume` -- CAN sum across dates
94
95### Percentage Formatting
96
97Two different conventions in the data:
98
99- `*_pct_change` columns = **decimals** (e.g., -0.13 = -13%, 0.35 = +35%). Multiply by 100 for display.
100- `apy` columns = **already percentages** (e.g., 2.32 = 2.32%). Do NOT multiply by 100.
101
102### TVL Components
103
104Components are mutually exclusive -- never double-add:
105
106- `tvl_base` = default TVL (excludes liquid staking and double-counted)
107- `tvl_ls_only` = liquid staking portion not in tvl_base
108- `tvl_dc_only` = double-counted portion not in tvl_base
109- `tvl_ls_and_dc` = both LS and DC
110- Total with LS+DC = `tvl_base + tvl_ls_only + tvl_dc_only + tvl_ls_and_dc`
111
112### Fee and Revenue
113
114- `fees` = gross payments by users
115- `revenue` = protocol's cut (fees - payments to LPs/stakers)
116- `holder_revenue` = buybacks + dividends to token holders
117- Chain-level: `chain_fees` (gas), `chain_revenue`, `chain_mev`, `app_fees` (protocol fees on chain), `app_revenue`
118
119### Metric Name Patterns
120
121Protocol metrics follow these patterns:
122- **TVL**: `tvl_base`, `tvl_staking`, `tvl_borrowed`, `tvl_pool2`, `tvl_treasury`, `tvl_vesting`
123- **Flows** (with suffixes `_1d/_7d/_30d/_90d/_180d/_365d/_ytd/_alltime/_annualised`): `fees`, `revenue`, `holder_revenue`, `incentive`
124- **Volume** (same suffixes): `volume_dexs`, `volume_aggregators`, `volume_derivatives`, `volume_aggr_derivatives`, `volume_options`
125- **Market**: `price`, `mcap`, `fdv`, `fdv_outstanding`, `token_volume`, `ps_ratio`, `pf_ratio`
126- **pct_change** variants only available on `_current` views
127
128Chain metrics use `chain_fees`, `chain_revenue`, `chain_mev`, `app_fees`, `app_revenue` instead of `fees`, `revenue`.
129
130Daily views only have the `_1d` suffix for flows/volumes.
131
132### Important Gotchas
133
134- **Category column**: `get_protocol_metrics` has NO category column. Use `get_category_metrics` for category-level data.
135- **FDV**: Never sort by FDV -- unreliable `total_supply` data produces junk rankings. Sort by `mcap` instead.
136- **Valuation**: `ps_ratio` = mcap / annualised revenue. `pf_ratio` = mcap / annualised fees. Lower = potentially undervalued.
137- **Metric validation**: Protocol/chain/category metrics are validated against actual DB columns. Invalid metrics return a suggestion for the closest match.
138- **NULL values**: NULL means data unavailable, NOT $0. Do not report NULL as zero.
139- **Params accept string or array**: `protocol: "aave"` or `protocol: ["aave", "lido"]`. Param names are singular (`protocol` not `protocols`).
140- **sort_by format**: String like `"tvl_base desc"` or `"fees_1d desc"`.
141
142## Examples
143
144**Example 1:**
145User: "What is Aave's TVL?"
146Tool call: `defillama:get_protocol_metrics(protocol: "aave", metrics: ["tvl_base"])`
147
148**Example 2:**
149User: "Top 5 chains by fees"
150Tool call: `defillama:get_chain_metrics(sort_by: "chain_fees_1d desc", limit: 5)`
151
152**Example 3:**
153User: "ETH price history over 90 days"
154Tool call: `defillama:get_token_prices(token: "coingecko:ethereum", period: "90d")`
155
156**Example 4:**
157User: "Compare ETH price and Ethereum chain TVL"
158Tool calls in parallel:
159- `defillama:get_token_prices(token: "coingecko:ethereum")`
160- `defillama:get_chain_metrics(chain: "ethereum")`
161
162**Example 5:**
163User: "Biggest DeFi hacks this year"
164Tool call: `defillama:get_events(event_type: "hacks", sort_by: "amount desc", limit: 10, period: "365d")`
165
166**Example 6:**
167User: "Aave TVL from Jan to Mar 2025"
168Tool call: `defillama:get_protocol_metrics(protocol: "aave", metrics: ["tvl_base"], start_date: "2025-01-01", end_date: "2025-03-31")`
169
170## Error Recovery
171
1721. **0 rows returned** -> call `defillama:resolve_entity(name: "...")` -> retry with the correct slug
1732. **Wrong data** -> verify you're using the right tool (protocol vs chain vs category)
1743. **Ambiguous entity** -> call `resolve_entity` to see all matching slugs, then pick the right one