DefiLlama MCP Data Reference

Tool Quick Reference

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 getprotocolmetrics, aggregates all versions
• Sub-protocol (e.g., aave-v3) — individual versions, used in sub_protocol views

resolveentity returns both slug (sub-protocol) and parentprotocol. Use parentprotocol for getprotocol_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 getprotocolmetrics 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 startdate and enddate (YYYY-MM-DD format) instead of period. If startdate is set without enddate, 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): fees1d, revenue1d, volume -- CAN sum across dates

Percentage Formatting

Two different conventions in the data:

• *pctchange 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)
• tvllsonly = liquid staking portion not in tvl_base
• tvldconly = double-counted portion not in tvl_base
• tvllsand_dc = both LS and DC
• Total with LS+DC = tvlbase + tvllsonly + tvldconly + tvllsanddc

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: chainfees (gas), chainrevenue, chainmev, appfees (protocol fees on chain), app_revenue

Metric Name Patterns

Protocol metrics follow these patterns:

• TVL: tvlbase, tvlstaking, tvlborrowed, tvlpool2, tvltreasury, tvlvesting
• Flows (with suffixes 1d/7d/30d/90d/180d/365d/ytd/alltime/annualised): fees, revenue, holderrevenue, incentive
• Volume (same suffixes): volumedexs, volumeaggregators, volumederivatives, volumeaggrderivatives, volumeoptions
• Market: price, mcap, fdv, fdvoutstanding, tokenvolume, psratio, pfratio
• pctchange variants only available on current views

Chain metrics use chainfees, chainrevenue, chainmev, appfees, app_revenue instead of fees, revenue.

Daily views only have the _1d suffix for flows/volumes.

Important Gotchas

• Category column: getprotocolmetrics has NO category column. Use getcategorymetrics for category-level data.
• FDV: Never sort by FDV -- unreliable total_supply data produces junk rankings. Sort by mcap instead.
• Valuation: psratio = mcap / annualised revenue. pfratio = 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).
• sortby format: String like "tvlbase desc" or "fees_1d desc".

Examples

Example 1: User: "What is Aave's TVL?" Tool call: defillama:getprotocolmetrics(protocol: "aave", metrics: ["tvl_base"])

Example 2: User: "Top 5 chains by fees" Tool call: defillama:getchainmetrics(sortby: "chainfees_1d desc", limit: 5)

Example 3: User: "ETH price history over 90 days" Tool call: defillama:gettokenprices(token: "coingecko:ethereum", period: "90d")

Example 4: User: "Compare ETH price and Ethereum chain TVL" Tool calls in parallel:

• defillama:gettokenprices(token: "coingecko:ethereum")
• defillama:getchainmetrics(chain: "ethereum")

Example 5: User: "Biggest DeFi hacks this year" Tool call: defillama:getevents(eventtype: "hacks", sort_by: "amount desc", limit: 10, period: "365d")

Example 6: User: "Aave TVL from Jan to Mar 2025" Tool call: defillama:getprotocolmetrics(protocol: "aave", metrics: ["tvlbase"], startdate: "2025-01-01", end_date: "2025-03-31")

Error Recovery

1. 0 rows returned -> call defillama:resolve_entity(name: "...") -> retry with the correct slug
2. Wrong data -> verify you're using the right tool (protocol vs chain vs category)
3. Ambiguous entity -> call resolve_entity to see all matching slugs, then pick the right one