# DefiLlama API

> DefiLlama provides free, open-source DeFi analytics data. There are two separate APIs with different base URLs and authentication. Do NOT mix them.

## Important: Free API vs Pro API

The Free API and Pro API are entirely separate services.

| Feature | Free API | Pro API |
|---|---|---|
| Base URL | https://api.llama.fi | https://pro-api.llama.fi/{KEY} |
| Auth Required | No | Yes ($300/mo) |
| Rate Limit | Standard | Higher |
| Endpoints | 31 | 106 exclusive + 31 free with prefix |

## Pro API authentication

Put your API key between the base URL and the endpoint. Do NOT send it as a query parameter (`?apikey=`) or header. Do NOT put it in `api.llama.fi` URLs.

```
WRONG  https://pro-api.llama.fi/api/overview/derivatives?apikey={YOUR_API_KEY}
RIGHT  https://pro-api.llama.fi/{YOUR_API_KEY}/api/overview/derivatives
```

There are only two tiers: free (no key) and the API plan. One API plan key unlocks every Pro endpoint. There are no add-ons or separate keys for volumes, derivatives, or other data.

## Troubleshooting

A 200 from `/protocols` or `/overview/fees` on `api.llama.fi` does not validate your API key. Those endpoints require no authentication. A 402 from `api.llama.fi` does not prove your subscription expired. It means the endpoint needs the Pro API.

1. Check the host and key placement: `https://pro-api.llama.fi/{YOUR_API_KEY}/...`, not `api.llama.fi` and not `?apikey=`.
2. Call `https://pro-api.llama.fi/usage/{YOUR_API_KEY}` (key at the end, for this endpoint only). It returns your remaining credits, like `{"creditsLeft": 1000000}`.
3. Retry the keyed URL: `https://pro-api.llama.fi/{YOUR_API_KEY}/api/overview/derivatives`.

**Pro users accessing free endpoints:** Pro API key holders can also call free endpoints on `pro-api.llama.fi` for higher rate limits. Use the exact path mappings below.

## Free-to-Pro Path Mapping

Pro users: to call free endpoints with higher rate limits, use `https://pro-api.llama.fi/{YOUR_API_KEY}` with the pro path below.

| Free path (api.llama.fi) | Pro path (pro-api.llama.fi) | Description |
|---|---|---|
| `/protocols` | `/api/protocols` | List all protocols on defillama along with their tvl |
| `/protocol/{protocol}` | `/api/protocol/{protocol}` | Get historical TVL of a protocol and breakdowns by token and chain |
| `/v2/historicalChainTvl` | `/api/v2/historicalChainTvl` | Get historical TVL (excludes liquid staking and double counted tvl) of DeFi on all chains |
| `/v2/historicalChainTvl/{chain}` | `/api/v2/historicalChainTvl/{chain}` | Get historical TVL (excludes liquid staking and double counted tvl) of a chain |
| `/tvl/{protocol}` | `/api/tvl/{protocol}` | Simplified endpoint to get current TVL of a protocol |
| `/v2/chains` | `/api/v2/chains` | Get current TVL of all chains |
| `/prices/current/{coins}` | `/coins/prices/current/{coins}` | Get current prices of tokens by contract address |
| `/prices/historical/{timestamp}/{coins}` | `/coins/prices/historical/{timestamp}/{coins}` | Get historical prices of tokens by contract address |
| `/batchHistorical` | `/coins/batchHistorical` | Get historical prices for multiple tokens at multiple different timestamps |
| `/chart/{coins}` | `/coins/chart/{coins}` | Get token prices at regular time intervals |
| `/percentage/{coins}` | `/coins/percentage/{coins}` | Get percentage change in price over time |
| `/prices/first/{coins}` | `/coins/prices/first/{coins}` | Get earliest timestamp price record for coins |
| `/block/{chain}/{timestamp}` | `/coins/block/{chain}/{timestamp}` | Get the closest block to a timestamp |
| `/stablecoins` | `/stablecoins/stablecoins` | List all stablecoins along with their circulating amounts |
| `/stablecoincharts/all` | `/stablecoins/stablecoincharts/all` | Get historical mcap sum of all stablecoins |
| `/stablecoincharts/{chain}` | `/stablecoins/stablecoincharts/{chain}` | Get historical mcap sum of all stablecoins in a chain |
| `/stablecoin/{asset}` | `/stablecoins/stablecoin/{asset}` | Get historical mcap and historical chain distribution of a stablecoin |
| `/stablecoinchains` | `/stablecoins/stablecoinchains` | Get current mcap sum of all stablecoins on each chain |
| `/stablecoinprices` | `/stablecoins/stablecoinprices` | Get historical prices of all stablecoins |
| `/pools` | `/yields/v1/pools` | Retrieve the latest data for all pools, including enriched information such as predictions |
| `/chart/{pool}` | `/yields/v1/chart/{pool}` | Get historical APY and TVL of a pool |
| `/overview/dexs` | `/api/overview/dexs` | List all dexs along with summaries of their volumes and dataType history data |
| `/overview/dexs/{chain}` | `/api/overview/dexs/{chain}` | List all dexs along with summaries of their volumes and dataType history data filtering by chain |
| `/summary/dexs/{protocol}` | `/api/summary/dexs/{protocol}` | Get summary of dex volume with historical data |
| `/overview/options` | `/api/overview/options` | List all options dexs along with summaries of their volumes and dataType history data |
| `/overview/options/{chain}` | `/api/overview/options/{chain}` | List all options dexs along with summaries of their volumes and dataType history data filtering by chain |
| `/summary/options/{protocol}` | `/api/summary/options/{protocol}` | Get summary of options dex volume with historical data |
| `/overview/open-interest` | `/api/overview/open-interest` | List all open interest dex exchanges along with summaries of their open interest |
| `/overview/fees` | `/api/overview/fees` | List all protocols along with summaries of their fees and revenue and dataType history data |
| `/overview/fees/{chain}` | `/api/overview/fees/{chain}` | List all protocols along with summaries of their fees and revenue and dataType history data by chain |
| `/summary/fees/{protocol}` | `/api/summary/fees/{protocol}` | Get summary of protocol fees and revenue with historical data |

## SDKs

**JavaScript** — `npm install @defillama/api` — [GitHub](https://github.com/DefiLlama/api-sdk)
**Python** — `pip install defillama-sdk` — [GitHub](https://github.com/DefiLlama/python-sdk)

## Free API Endpoints (api.llama.fi)

Full documentation: [llms-free.txt](/llms-free.txt)

No authentication required. Base URL: `https://api.llama.fi`

- **TVL**: `/protocols`, `/protocol/{protocol}`, `/v2/historicalChainTvl`, `/v2/historicalChainTvl/{chain}`, `/tvl/{protocol}`, `/v2/chains`
- **Coins & Prices**: `/prices/current/{coins}`, `/prices/historical/{timestamp}/{coins}`, `/batchHistorical`, `/chart/{coins}`, `/percentage/{coins}`, `/prices/first/{coins}`, `/block/{chain}/{timestamp}`
- **Stablecoins**: `/stablecoins`, `/stablecoincharts/all`, `/stablecoincharts/{chain}`, `/stablecoin/{asset}`, `/stablecoinchains`, `/stablecoinprices`
- **Yields & APY**: `/pools`, `/chart/{pool}`
- **DEX Volumes**: `/overview/dexs`, `/overview/dexs/{chain}`, `/summary/dexs/{protocol}`, `/overview/options`, `/overview/options/{chain}`, `/summary/options/{protocol}`
- **Perpetuals & Open Interest**: `/overview/open-interest`
- **Fees & Revenue**: `/overview/fees`, `/overview/fees/{chain}`, `/summary/fees/{protocol}`

## Pro-Only API Endpoints (pro-api.llama.fi)

Full documentation: [llms-pro.txt](/llms-pro.txt)

Requires API key. Base URL: `https://pro-api.llama.fi/{YOUR_API_KEY}`

- **TVL**: `/api/tokenProtocols/{symbol}`, `/api/inflows/{protocol}/{timestamp}`, `/api/chainAssets`, `/api/v2/metrics/tvl/protocol/{protocol}`, `/api/v2/chart/tvl/protocol/{protocol}`, `/api/v2/chart/tvl/protocol/{protocol}/chain-breakdown`, `/api/v2/chart/tvl/protocol/{protocol}/token-breakdown`
- **Token Unlocks**: `/api/emissions`, `/api/emission/{protocol}`
- **Protocol Analytics**: `/api/categories`, `/api/forks`, `/api/oracles`, `/api/hacks`, `/api/raises`, `/api/treasuries`, `/api/entities`
- **Token Liquidity**: `/api/historicalLiquidity/{token}`
- **Perpetuals & Open Interest**: `/api/overview/derivatives`, `/api/summary/derivatives/{protocol}`
- **Treasury**: `/api/v2/metrics/treasury/protocol/{protocol}`, `/api/v2/chart/treasury/protocol/{protocol}`, `/api/v2/chart/treasury/protocol/{protocol}/chain-breakdown`, `/api/v2/chart/treasury/protocol/{protocol}/token-breakdown`
- **Oracles**: `/api/v2/metrics/oracle`, `/api/v2/chart/oracle`, `/api/v2/chart/oracle/chain-breakdown`, `/api/v2/chart/oracle/protocol-breakdown`, `/api/v2/chart/oracle/protocol/{protocol}`, `/api/v2/chart/oracle/protocol/{protocol}/chain-breakdown`, `/api/v2/chart/oracle/chain/{chain}`, `/api/v2/chart/oracle/chain/{chain}/protocol-breakdown`
- **Forks**: `/api/v2/metrics/fork`, `/api/v2/chart/fork/protocol-breakdown`, `/api/v2/chart/fork/protocol/{protocol}`
- **Dimensions**: `/api/v2/metrics/{metric}`, `/api/v2/chart/{metric}`, `/api/v2/chart/{metric}/chain-breakdown`, `/api/v2/chart/{metric}/protocol-breakdown`, `/api/v2/metrics/{metric}/chain/{chain}`, `/api/v2/chart/{metric}/chain/{chain}`, `/api/v2/chart/{metric}/chain/{chain}/protocol-breakdown`, `/api/v2/metrics/{metric}/protocol/{protocol}`, `/api/v2/chart/{metric}/protocol/{protocol}`, `/api/v2/chart/{metric}/protocol/{protocol}/chain-breakdown`, `/api/v2/chart/{metric}/protocol/{protocol}/version-breakdown`, `/api/v2/chart/{metric}/protocol/{protocol}/label-breakdown`, `/api/v2/metrics/{metric}/category/{category}`, `/api/v2/chart/{metric}/category/{category}`, `/api/v2/chart/{metric}/category/{category}/chain-breakdown`, `/api/v2/chart/{metric}/category/{category}/protocol-breakdown`, `/api/v2/metrics/{metric}/category/{category}/chain/{chain}`, `/api/v2/chart/{metric}/category/{category}/chain/{chain}`, `/api/v2/chart/{metric}/category/{category}/chain/{chain}/protocol-breakdown`
- **Financial Statements**: `/api/v2/metrics/financial-statement/protocol/{protocol}`
- **Stablecoins**: `/stablecoins/stablecoindominance/{chain}`
- **Yields & APY**: `/yields/v1/pools`, `/yields/v1/chart/{pool}`, `/yields/v1/poolsBorrow`, `/yields/v1/chartLendBorrow/{pool}`, `/yields/v2/earn`, `/yields/v2/earn/query`, `/yields/v2/earn/{id}/history`, `/yields/v2/earn/verified`, `/yields/v2/earn/verified/{id}`, `/yields/v2/earn/verified/{id}/history`, `/yields/v2/borrow/markets`, `/yields/v2/borrow/markets/{id}/history`, `/yields/v2/borrow/routes`, `/yields/v2/loops`, `/api/perpFundingRates`, `/api/lstRates`
- **ETFs**: `/etfs/snapshot`, `/etfs/flows`
- **Narratives**: `/fdv/performance/{period}`
- **Bridges**: `/bridges/bridges`, `/bridges/bridge/{id}`, `/bridges/bridgevolume/{chain}`, `/bridges/bridgedaystats/{timestamp}/{chain}`, `/bridges/transactions/{id}`
- **API Key Management**: `/usage/{YOUR_API_KEY}`
- **Digital Asset Treasury**: `/dat/institutions`, `/dat/institutions/{symbol}`
- **Equities**: `/equities/v1/companies-list`, `/equities/v1/statements`, `/equities/v1/dimensions`, `/equities/v1/price-history`, `/equities/v1/ohlcv`, `/equities/v1/summary`, `/equities/v1/filings`, `/equities/v1/onchain`, `/equities/v1/sectors`, `/equities/v1/sectors-overview`, `/equities/v1/sector`, `/equities/v1/industries`, `/equities/v1/earnings-calendar`
- **Pre-IPO**: `/pre-ipo/v1/companies-list`, `/pre-ipo/v1/valuations`, `/pre-ipo/v1/raises`, `/pre-ipo/v1/summary`, `/pre-ipo/v1/integrations`
- **Real World Assets**: `/rwa/current`, `/rwa/stats`, `/rwa/list`, `/rwa/chain/{chain}`, `/rwa/chart/chain/{chain}`, `/rwa/chart/chain-breakdown`

## Optional

- [OpenAPI spec (free)](/defillama-openapi-free.json): Full OpenAPI 3.0 specification for free endpoints
- [OpenAPI spec (pro)](/defillama-openapi-pro.json): Full OpenAPI 3.0 specification for pro endpoints