defillama

What this skill does

# DefiLlama API

> **Script-mode skill (PoC).** This skill is NOT registered as Anthropic
> tools. To use it, read this file, then run `python` in `bash` and import
> from `exports.py`. See **Script Usage** section below.

## Script Usage

This skill ships a single `exports.py` with all functions. Call it from a
`bash` block like this:

```bash
python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/defillama")
from exports import protocols, chains, yield_pools, dex_overview, fees_overview

# Top 10 protocols by TVL
data = protocols()
top = sorted(data, key=lambda p: p.get("tvl") or 0, reverse=True)[:10]
print(json.dumps([{"name": p["name"], "tvl": p["tvl"]} for p in top], indent=2))
EOF
```

Available functions in `exports.py`: `protocols`, `chains`, `protocol_tvl`,
`yield_pools`, `dex_overview`, `fees_overview`, `revenue_overview`,
`stablecoins`, `bridges`, `treasury`. Read `exports.py` directly for
signatures.

**Trit**: -1 (MINUS - Validator/Data Source)
**Color**: #4A90D9 (Cold blue, 210°)

Comprehensive DeFi data from DefiLlama's API ecosystem.


## Function Reference (signatures)

All functions are in `exports.py`. Call from a `bash` block after
`sys.path.insert(0, "/data/workspace/skills/defillama")`.

### Protocols & TVL
| Function | Description |
|---|---|
| `protocols()` | List all protocols with current TVL, chain breakdown, category. Returns list of dicts. |
| `protocol(slug)` | Detailed history for one protocol (slug from `protocols()`). |
| `chains()` | All supported chains with current TVL. |
| `chain_tvl_history(chain)` | Daily TVL series for one chain. |
| `global_tvl_history()` | Global daily TVL series. |

### Stablecoins
| Function | Description |
|---|---|
| `stablecoins(include_prices=True)` | All stablecoins with circulating supply per chain. |
| `stablecoin_chains()` | Per-chain stablecoin totals. |

### Yields
| Function | Description |
|---|---|
| `yield_pools()` | All yield pools with APY, TVL, project, chain. |
| `yield_chart(pool_id)` | Historical APY/TVL for one pool (pool_id from `yield_pools()`). |

### Volume / Fees / Revenue
| Function | Description |
|---|---|
| `dex_overview(exclude_chart=True)` | Aggregated DEX volume across all chains. |
| `dex_overview_chain(chain, exclude_chart=True)` | DEX volume for one chain. |
| `fees_overview(exclude_chart=True)` | Aggregated fees+revenue across all protocols. |
| `fees_overview_chain(chain, exclude_chart=True)` | Per-chain fees breakdown. |

### Bridges
| Function | Description |
|---|---|
| `bridges()` | List all bridges with volume stats. |
| `bridge_chain_volume(chain)` | Bridge volume by chain. |
| `bridge_volume(bridge_id, start_timestamp=None, end_timestamp=None)` | Time series for one bridge. |

### Prices
| Function | Description |
|---|---|
| `current_prices(coins)` | Current prices. `coins` = list/string like `"ethereum:0x...,coingecko:bitcoin"`. |
| `historical_prices(coins, timestamp)` | Prices at a specific unix timestamp. |

## Matching Keywords (intent triggers)

Use this skill when users ask about any of the following:

- **TVL**: TVL ranking, protocol TVL, chain TVL, TVL changes, DeFi market share
- **Stablecoin yield**: stablecoin yield, USDC/USDT APY, low-risk yield pools, safe yield, fixed-income-like DeFi
- **Yield / Farming**: APY ranking, yield pool screening, vault yield, lending APY, borrow rates, LSD/LRT yield
- **DEX / Fees / Revenue**: DEX volume, protocol fees, protocol revenue, revenue growth, which DEX revenue is growing fastest
- **Flows / Rotation**: capital flows, chain inflow/outflow, stablecoin netflow, liquidity rotation
- **Protocol Research**: protocol fundamentals, multi-protocol comparison, sector comparison, DeFi snapshot/report

Typical user prompts this skill should match:
- “Which DEX has seen the strongest revenue growth recently?”
- “Find me some low-risk stablecoin yield options with decent returns.”
- “Create a DeFi market snapshot for today (TVL / volume / fees).”
- “Compare ETH vs SOL on-chain flow changes over the last 30 days.”

## Base URLs

| API | Base URL | Auth |
|-----|----------|------|
| **Free API** | `https://api.llama.fi` | None (no key needed) |
| Pro API | `https://pro-api.llama.fi/{API_KEY}` | Key in path `/API_KEY/endpoint` |
| Bridge API | `https://bridges.llama.fi` | None |

> **Key rule**: Use `https://api.llama.fi` for all **free endpoints** (TVL, chains, DEX, fees, prices).
> Use `https://pro-api.llama.fi/{API_KEY}` ONLY for **pro endpoints** (yields, derivatives, emissions).
> Env var: `DEFILLAMA_API_KEY` — used in pro URL path, NOT as HTTP header.

## Most Common Endpoints (Start Here)

For 90% of DeFi analytics tasks, use these free endpoints (`api.llama.fi`):

| Task | Endpoint | Example |
|------|----------|---------|
| TVL Top N protocols | `GET /protocols` | Sort by `.tvl` field |
| Single protocol detail | `GET /protocol/{slug}` | e.g. `/protocol/aave` |
| Chain TVL history | `GET /v2/historicalChainTvl/{chain}` | `.date` + `.tvl` fields |
| DEX volumes | `GET /overview/dexs?excludeChart=true` | `.total24h`, `.total7d` |
| Protocol fees | `GET /overview/fees?excludeChart=true` | `.total24h` |
| All chains TVL | `GET /v2/chains` | Sum `.tvl` for global total |

> ⚠️ **Pro endpoints** (`/yields/*`, `/emissions`, etc.) require `DEFILLAMA_API_KEY` in the URL path.

## Proxy Requirement (sc-proxy)

When using fake API keys (for example `fake-defillama-key-12345`), requests **must** go through sc-proxy so the key can be replaced upstream.

- Env key name: `DEFILLAMA_API_KEY`
- Auto proxy detection envs: `PROXY_HOST`, `PROXY_PORT`
- If `HTTP_PROXY` / `HTTPS_PROXY` are unset, direct requests may hit upstream and return key errors.

### Python template (recommended)

```python
import os
import requests

host = os.getenv("PROXY_HOST")
port = os.getenv("PROXY_PORT")
session = requests.Session()
if host and port:
    if ":" in host and not host.startswith("["):
        host = f"[{host}]"  # IPv6-safe
    proxy = f"http://{host}:{port}"
    session.proxies.update({"http": proxy, "https": proxy})

# Free endpoint (no key needed):
r_free = session.get("https://api.llama.fi/protocols", timeout=25)
print("Free:", r_free.status_code)

# Pro endpoint (key in URL path):
api_key = os.environ["DEFILLAMA_API_KEY"]
r_pro = session.get(f"https://pro-api.llama.fi/{api_key}/yields/pools", timeout=25)
print("Pro:", r_pro.status_code)
```

### Quick test commands

```bash
set -a && source .env && set +a
python3 - << 'PY'
import os, requests
s = requests.Session()
host, port = os.getenv('PROXY_HOST'), os.getenv('PROXY_PORT')
if host and port:
    if ':' in host and not host.startswith('['):
        host = f'[{host}]'
    p = f'http://{host}:{port}'
    s.proxies.update({'http': p, 'https': p})

# Free endpoint
r1 = s.get('https://api.llama.fi/protocols', timeout=25)
print('free /protocols:', r1.status_code)

# Pro endpoint
k = os.environ['DEFILLAMA_API_KEY']
r2 = s.get(f'https://pro-api.llama.fi/{k}/yields/pools', timeout=25)
print('pro /yields/pools:', r2.status_code)
PY
```

## Quick Reference

### TVL & Protocols
```bash
# All protocols with TVL
GET /protocols

# Single protocol detail
GET /protocol/{slug}

# Chain TVL
GET /v2/chains
GET /v2/historicalChainTvl/{chain}
```

### Prices
```bash
# Current prices (chain:address format)
GET /coins/prices/current/{coins}

# Historical
GET /coins/prices/historical/{timestamp}/{coins}

# Chart data
GET /coins/chart/{coins}?period=30d
```

### Yields (Pro)
```bash
GET /yields/pools           # All yield pools
GET /yields/chart/{pool}    # Pool history
GET /yields/poolsBorrow     # Borrow rates
GET /yields/perps           # Perp funding
GET /yields/lsdRates        # LSD rates
```

### Volume
```bash
GET /overview/dexs?excludeChart=true              # DEX volumes (recommended)
GET /overview/dexs/{chain}?excludeChart=true      # Chain DEX
GET /summary/dexs/{protocol}                       # Protocol detail
GET /overview/options?excludeChart=true