DeFi Llama Python API Tutorial
This tutorial aims to be a quick guide to get you started using the DeFi Llama API integrated into messari’s python library.
[2]:
from messari.defillama import DeFiLlama
dl = DeFiLlama()
API Structure
The Messari Python client contains a number of functions that wrap all of DeFi Llama’s API endpoints. These include:
get_protocol_tvl_timeseries
get_global_tvl_timeseries
get_chain_tvl_timeseries
get_current_tvl
get_protocols
Below are a few examples to showcase the functionality and types of data each function generates.
Get protocol tvl timeseries
This function returns a timeseries of a protocol’s TVL broken down by token amounts as a pandas DataFrame. The DataFrame uses a multiindex to group relevant data together following a convenient df[protocol][chain][asset] pattern. For example, the following code returns Aave’s aggregate TVL and token amounts across all chains:
[3]:
protocols = ['aave']
protocol_tvls = dl.get_protocol_tvl_timeseries(protocols, start_date="2021-10-01", end_date="2021-10-10")
protocol_tvls['aave']['all'].head()
[3]:
| totalLiquidityUSD | ENJ | CRV | USDT | LEND | AAVE | UNI | WBTC | SUSD | LINK | ... | RENFIL_usd | UNKNOWN (0x1985365e9f78359a9B6AD760e32412f4a445E862)_usd | RAI_usd | AMPL_usd | PAX_usd | DPI_usd | USDP_usd | FRAX_usd | FEI_usd | WAVAX_usd | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2021-10-01 | 1.370234e+10 | 1.046651e+07 | 6.311565e+06 | 2.455208e+08 | 174907.299479 | 1.910542e+06 | 3.918288e+06 | 41781.707197 | 2.544456e+07 | 2.200474e+07 | ... | 4.142907e+06 | NaN | 1.369684e+07 | 1.067524e+06 | NaN | 5.856352e+07 | 2.990423e+06 | 1.601764e+06 | 4.276806e+06 | NaN |
| 2021-10-02 | 1.419310e+10 | 1.057785e+07 | 6.935109e+06 | 2.275302e+08 | 174907.299479 | 1.912798e+06 | 4.063942e+06 | 42631.168237 | 2.483117e+07 | 2.211693e+07 | ... | 4.275809e+06 | NaN | 1.513579e+07 | 1.651881e+05 | NaN | 4.688960e+07 | 2.970062e+06 | 3.600939e+06 | 4.036727e+06 | NaN |
| 2021-10-03 | 1.431644e+10 | 1.063210e+07 | 7.733310e+06 | 3.273912e+08 | 174907.299479 | 1.910459e+06 | 4.060696e+06 | 43108.704933 | 2.256727e+07 | 2.216695e+07 | ... | 4.120871e+06 | NaN | 1.513579e+07 | 2.528140e+05 | NaN | 4.588331e+07 | 2.931041e+06 | 2.859444e+06 | 5.071526e+06 | NaN |
| 2021-10-04 | 1.481314e+10 | 1.062416e+07 | 7.951371e+06 | 3.380871e+08 | 174907.299479 | 2.024898e+06 | 4.119227e+06 | 44953.703369 | 2.232785e+07 | 2.216039e+07 | ... | 4.092038e+06 | NaN | 1.536486e+07 | 3.413756e+05 | NaN | 4.441723e+07 | 2.931041e+06 | 1.647494e+06 | 5.114161e+06 | 8.102013e+07 |
| 2021-10-05 | 1.562776e+10 | 1.060164e+07 | 8.145123e+06 | 3.916334e+08 | 174296.741465 | 2.081462e+06 | 4.122575e+06 | 45576.912796 | 1.488648e+07 | 2.214311e+07 | ... | 4.184423e+06 | NaN | 1.481286e+07 | 1.000055e+06 | NaN | 4.478705e+07 | 2.931041e+06 | 1.834846e+06 | 5.018526e+06 | 8.322869e+07 |
5 rows × 77 columns
We could narrow down our search by passing other supported chains as follows:
[6]:
protocol_tvls['aave']['Ethereum'].head()
[6]:
| totalLiquidityUSD | ENJ | CRV | USDT | LEND | AAVE | UNI | WBTC | SUSD | LINK | ... | XSUSHI_usd | RENFIL_usd | UNKNOWN (0x1985365e9f78359a9B6AD760e32412f4a445E862)_usd | RAI_usd | AMPL_usd | PAX_usd | DPI_usd | USDP_usd | FRAX_usd | FEI_usd | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2021-10-01 | 1.176457e+10 | 1.046651e+07 | 6.311565e+06 | 2.097273e+08 | 174907.299479 | 1.719256e+06 | 3.918288e+06 | 33783.716382 | 2.544456e+07 | 2.200474e+07 | ... | 1.552155e+08 | 4.142907e+06 | NaN | 1.369684e+07 | 1.067524e+06 | NaN | 5.856352e+07 | 2.990423e+06 | 1.601764e+06 | 4.276806e+06 |
| 2021-10-02 | 1.220245e+10 | 1.057785e+07 | 6.935109e+06 | 1.905787e+08 | 174907.299479 | 1.721987e+06 | 4.063942e+06 | 34580.139148 | 2.483117e+07 | 2.211693e+07 | ... | 1.610315e+08 | 4.275809e+06 | NaN | 1.513579e+07 | 1.651881e+05 | NaN | 4.688960e+07 | 2.970062e+06 | 3.600939e+06 | 4.036727e+06 |
| 2021-10-03 | 1.232623e+10 | 1.063210e+07 | 7.733310e+06 | 2.923815e+08 | 174907.299479 | 1.719631e+06 | 4.060696e+06 | 35020.173599 | 2.256727e+07 | 2.216695e+07 | ... | 1.563189e+08 | 4.120871e+06 | NaN | 1.513579e+07 | 2.528140e+05 | NaN | 4.588331e+07 | 2.931041e+06 | 2.859444e+06 | 5.071526e+06 |
| 2021-10-04 | 1.220784e+10 | 1.062416e+07 | 7.951371e+06 | 2.719606e+08 | 174907.299479 | 1.699531e+06 | 4.119227e+06 | 34959.163570 | 2.232785e+07 | 2.216039e+07 | ... | 1.579955e+08 | 4.092038e+06 | NaN | 1.536486e+07 | 3.413756e+05 | NaN | 4.441723e+07 | 2.931041e+06 | 1.647494e+06 | 5.114161e+06 |
| 2021-10-05 | 1.249159e+10 | 1.060164e+07 | 8.145123e+06 | 2.402593e+08 | 174296.741465 | 1.694906e+06 | 4.122575e+06 | 34650.687732 | 1.488648e+07 | 2.214311e+07 | ... | 1.633028e+08 | 4.184423e+06 | NaN | 1.481286e+07 | 1.000055e+06 | NaN | 4.478705e+07 | 2.931041e+06 | 1.834846e+06 | 5.018526e+06 |
5 rows × 73 columns
To look at a protocol’s aggregate TVL across all tokens of one specific chain, pass ‘totalLiquidityUSD’ as the asset index. For example, if we wanted to know Aave’s total TVL in Ethereum, we would run:
[7]:
protocol_tvls['aave']['Ethereum']['totalLiquidityUSD']
[7]:
2021-10-01 1.176457e+10
2021-10-02 1.220245e+10
2021-10-03 1.232623e+10
2021-10-04 1.220784e+10
2021-10-05 1.249159e+10
2021-10-06 1.248139e+10
2021-10-07 1.249473e+10
2021-10-08 1.199861e+10
2021-10-09 1.144368e+10
2021-10-10 1.132894e+10
Name: totalLiquidityUSD, dtype: float64
Get global tvl timeseries
This function returns a timeseries of aggregate TVL across all supported protocols in DeFi Llama as a pandas DataFrame
[3]:
global_tvl = dl.get_global_tvl_timeseries(start_date="2021-10-01", end_date="2021-10-10")
global_tvl
[3]:
| totalLiquidityUSD | |
|---|---|
| 2021-10-01 | 1.931929e+11 |
| 2021-10-02 | 1.975269e+11 |
| 2021-10-03 | 2.000398e+11 |
| 2021-10-04 | 2.010004e+11 |
| 2021-10-05 | 2.052809e+11 |
| 2021-10-06 | 2.050247e+11 |
| 2021-10-07 | 2.074607e+11 |
| 2021-10-08 | 2.110497e+11 |
| 2021-10-09 | 2.116465e+11 |
| 2021-10-10 | 2.129363e+11 |
Get chain tvl timeseries
This function retrives timeseries TVL for a given chain or list of chains as a pandas DataFrame
[4]:
chains = ["Avalanche", "Harmony", "Polygon"]
chain_tvls = dl.get_chain_tvl_timeseries(chains, start_date="2021-10-01", end_date="2021-10-10")
chain_tvls
[4]:
| Avalanche | Harmony | Polygon | |
|---|---|---|---|
| 2021-10-01 | 3.880313e+09 | 1.350100e+08 | 4.504783e+09 |
| 2021-10-02 | 4.066595e+09 | 1.399944e+08 | 4.580609e+09 |
| 2021-10-03 | 4.075295e+09 | 1.500492e+08 | 4.687820e+09 |
| 2021-10-04 | 3.984976e+09 | 1.497508e+08 | 4.663548e+09 |
| 2021-10-05 | 4.470707e+09 | 1.553020e+08 | 4.762029e+09 |
| 2021-10-06 | 4.528760e+09 | 1.534946e+08 | 4.724335e+09 |
| 2021-10-07 | 4.483351e+09 | 1.577545e+08 | 4.696261e+09 |
| 2021-10-08 | 4.560892e+09 | 1.645999e+08 | 4.651345e+09 |
| 2021-10-09 | 5.069958e+09 | 1.935887e+08 | 4.486516e+09 |
| 2021-10-10 | 5.131014e+09 | 1.875108e+08 | 4.455768e+09 |
Get current tvl
The function retrives the current protocol tvl as a pandas DataFrame for an asset or list of assets
[8]:
protocols = ["uniswap", "curve", "aave"]
current_tvl = dl.get_current_tvl(protocols)
current_tvl
[8]:
| tvl | |
|---|---|
| uniswap | 1.040976e+10 |
| curve | 2.041504e+10 |
| aave | 1.541991e+10 |
Get protocols
The function returns basic information on all DeFi Llama listed protocols.
[10]:
protocols = dl.get_protocols()
protocols
[10]:
| curve | makerdao | aave | convex-finance | wbtc | instadapp | compound | uniswap | polygon-bridge-&-staking | lido | ... | oraichain | bacondao | yel-finance | smartcoin | billion-happiness | decubate | nasdex | potluck-protocol | atmossoft | zigzag | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | 3 | 118 | 111 | 319 | 2 | 120 | 114 | 1 | 240 | 182 | ... | 681 | 682 | 686 | 715 | 716 | 717 | 720 | 723 | 783 | 800 |
| name | Curve | MakerDAO | AAVE | Convex Finance | WBTC | Instadapp | Compound | Uniswap | Polygon Bridge & Staking | Lido | ... | OraiChain | BaconDAO | YEL Finance | SmartCoin | Billion Happiness | Decubate | Nasdex | Potluck Protocol | AtmosSoft | ZigZag |
| address | 0xD533a949740bb3306d119CC777fa900bA034cd52 | 0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2 | 0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9 | 0x4e3fbd56cd56c3e72c1403e103b45db9da5b9d2b | 0x2260fac5e5542a773aa44fbcfedf7c193bc2c599 | 0x6f40d4a6237c257fff2db00fa0510deeecd303eb | 0xc00e94cb662c3520282e6f5717214004a7f26888 | 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 | 0x7d1afa7b718fb893db30a3abc0cfc608aacfebb0 | 0x5a98fcbea516cf06857215779fd812ca3bef1b32 | ... | 0x4c11249814f11b9346808179cf06e71ac328c1b5 | bsc:0x0615dbba33fe61a31c7ed131bda6655ed76748b1 | 0x7815bda662050d84718b988735218cffd32f75ea | avax:0xCC2f1d827b18321254223dF4e84dE399D9Ff116c | bsc:0x6fd7c98458a943f469E1Cf4eA85B173f5Cd342F4 | bsc:0xEAc9873291dDAcA754EA5642114151f3035c67A2 | polygon:0xE8d17b127BA8b9899a160D9a07b69bCa8E08... | fantom:0x49894fcc07233957c35462cfc3418ef0cc26129f | bsc:0xC53C65C4A925039cC149fA99fD011490D40270a3 | None |
| symbol | CRV | MKR | AAVE | CVX | WBTC | INST | COMP | UNI | MATIC | LDO | ... | ORAI | BACON | YEL | SMRT | BHC | DCB | NSDX | FANG | ATMSSFT | - |
| url | https://curve.fi | https://makerdao.com/ | https://aave.com\r\n | https://www.convexfinance.com/ | https://wbtc.network/ | https://instadapp.io/ | https://compound.finance | https://info.uniswap.org/ | https://polygon.technology/ | https://lido.fi/ | ... | https://orai.io | https://app.bacondao.com/ | https://yel.finance | https://smartcoin.farm | https://billionhappiness.finance/ | https://platform.decubate.com/ | https://www.nasdex.xyz | http://fantom.potluckprotocol.com | https://www.atmossoftdefi.app | https://trade.zigzag.exchange |
| description | Curve is a decentralized exchange liquidity po... | Builders of Dai, a digital currency that can b... | Aave is an Open Source and Non-Custodial proto... | Convex simplifies your Curve-boosting experien... | Wrapped Bitcoin (WBTC) is the first ERC20 toke... | Aims to drive interoperability between protoco... | Compound is an algorithmic, autonomous interes... | A fully decentralized protocol for automated l... | Ethereum sidechain\r\n | Liquidity for staked assets. Daily rewards, no... | ... | Oraichain is a data oracle platform that aggre... | BaconDAO (BACON) is a Decentralized Autonomous... | YEL aggregates multiple projects across severa... | SmartCoin is a yield farming protocol on Avala... | Billion Happiness is a blockchain community-ba... | Decubate is a community-powered investment pla... | NASDEX is a decentralised app on polygon, that... | Defi AMM with gamified products and features. | Atmosphere Software(AtmosSoft) is a next gener... | A Layer 2 decentralized exchange (DEX) on zkSync |
| chain | Multi-Chain | Ethereum | Multi-Chain | Ethereum | Ethereum | Ethereum | Ethereum | Ethereum | Polygon | Multi-Chain | ... | Multi-Chain | Multi-Chain | Multi-Chain | Avalanche | Binance | Binance | Polygon | Fantom | Multi-Chain | zkSync |
| logo | https://icons.llama.fi/curve.png | https://icons.llama.fi/makerdao.jpg | https://icons.llama.fi/aave.png | https://icons.llama.fi/convex-finance.jpg | https://icons.llama.fi/wbtc.png | https://icons.llama.fi/instadapp.jpg | https://icons.llama.fi/compound.png | https://icons.llama.fi/uniswap.png | https://icons.llama.fi/polygon.jpg | https://icons.llama.fi/lido.png | ... | https://icons.llama.fi/oraichain.jpg | https://icons.llama.fi/bacondao.png | https://icons.llama.fi/yel-finance.png | https://icons.llama.fi/smrt.png | https://icons.llama.fi/billion-happiness.png | https://icons.llama.fi/decubate.png | https://icons.llama.fi/nasdex.png | https://icons.llama.fi/potluck-protocol.png | https://icons.llama.fi/atmossoft.jpg | https://icons.llama.fi/zigzag.jpg |
| audits | 2 | 2 | 2 | 2 | 2 | None | 2 | 2 | 0 | 2 | ... | 2 | 2 | 2 | 2 | 2 | 0 | 0 | 2 | 0 | 0 |
| audit_note | None | None | None | None | None | None | None | None | None | None | ... | None | None | None | None | None | None | None | None | None | None |
| gecko_id | curve-dao-token | maker | aave | convex-finance | wrapped-bitcoin | instadapp | compound-governance-token | uniswap | matic-network | lido-dao | ... | oraichain-token | bacondao | yel-finance | smartcoin-2 | billionhappiness | decubate | nasdex-token | fang-token | None | None |
| cmcId | 6538 | 1518 | 7278 | 9903 | 3717 | 10508 | 5692 | 7083 | 3890 | 8000 | ... | 7533 | 10501 | 11301 | 12917 | 7182 | 10563 | 12312 | 12671 | None | None |
| category | Dexes | Minting | Lending | Yield | Assets | Services | Lending | Dexes | Chain | Staking | ... | Yield | Yield | Yield | Yield | Yield | Launchpad | Dexes | Staking | Gaming | Dexes |
| chains | [Avalanche, Harmony, Ethereum, xDai, Polygon, ... | [Ethereum] | [Ethereum, Polygon, Avalanche] | [Ethereum] | [Ethereum] | [Ethereum] | [Ethereum] | [Optimism, Ethereum, Arbitrum] | [Polygon] | [Ethereum, Solana, Terra] | ... | [Ethereum] | [Binance, Ethereum] | [Ethereum] | [Avalanche] | [Binance] | [Binance] | [Polygon] | [Fantom] | [Fantom] | [zkSync] |
| module | curve.js | maker/index.js | aave/index.js | convex/index.js | wbtc.js | instadapp.js | compound-onchain/index.js | uniswap/index.js | polygon/index.js | lido/index.js | ... | oraichain.js | bacondao/index.js | yel/index.js | smartcoin/index.js | billion-happiness/index.js | decubate/index.js | nasdex/index.js | potluckprotocol/index.js | atmossoft.js | zigzag/index.js |
| CurveFinance | MakerDAO | AaveAave | ConvexFinance | WrappedBTC | Instadapp | compoundfinance | Uniswap | 0xPolygon | LidoFinance | ... | oraichain | BaconDAO_ | yel_finance | 0xSmartCoin | BHC_Happiness | decubate | nasdex_xyz | PotluckProtocol | AtmosSoft | ZigZagExchange | |
| audit_links | [https://curve.fi/audits] | [https://security.makerdao.com/] | [https://aave.com/security] | [https://github.com/convex-eth/platform/blob/m... | [https://wbtc.network/dashboard/audit] | [https://github.com/Instadapp/dsa-contracts/bl... | [https://compound.finance/docs/security] | [https://github.com/Uniswap/uniswap-v3-core/tr... | NaN | [https://github.com/lidofinance/audits] | ... | [https://github.com/oraichain/audits] | [https://drive.google.com/file/d/1AVc_YuSKoaoj... | [https://yield-enhancement-labs.gitbook.io/yie... | [https://paladinsec.co/pld/assets/20211018_Pal... | [https://www.certik.org/projects/billionhappin... | NaN | NaN | [https://dessertswap.finance/audits/Potluck%20... | NaN | NaN |
| oracles | [Chainlink] | [Maker] | [Chainlink] | NaN | [Chainlink] | NaN | [Chainlink] | [Uniswap] | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | [Internal] | NaN | NaN |
| slug | curve | makerdao | aave | convex-finance | wbtc | instadapp | compound | uniswap | polygon-bridge-&-staking | lido | ... | oraichain | bacondao | yel-finance | smartcoin | billion-happiness | decubate | nasdex | potluck-protocol | atmossoft | zigzag |
| tvl | 20415038798.327824 | 17969496759.492355 | 15419913267.352034 | 15131073490.628565 | 14449256853.309999 | 12102460033 | 11922059387.8978 | 10409755599.486263 | 9710159190.366772 | 9485282686.237036 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| chainTvls | {'Avalanche': 936811028.2676972, 'Harmony': 12... | {'Ethereum': 17969496759.492355} | {'Ethereum': 10471743116.25161, 'Polygon': 182... | {'Ethereum': 15131073490.628565} | {'Ethereum': 14449256853.31} | {'Ethereum': 12102460033} | {'Ethereum': 11922059387.897799} | {'Optimism': 40914299.193099, 'Ethereum': 1030... | {'Polygon': 9710159190.366772} | {'Ethereum': 6288679048.837508, 'Solana': 2258... | ... | {'Binance-staking': 2069241.2442397017, 'Ether... | {'pool2': 221923.15863504808, 'Binance-pool2':... | {'pool2': 6445303.662442322, 'Fantom-staking':... | {'Avalanche': 0, 'pool2': 96739.95349781934, '... | {'Binance': 0, 'Binance-staking': 4712925.0535... | {'Binance': 0, 'Binance-staking': 2304569.8020... | {'pool2': 169532.88870213774, 'staking': 92538... | {'Fantom-staking': 142474.83638762677, 'stakin... | {'pool2': 19304.101388327308, 'Fantom-pool2': ... | {'Zksync': 0, 'offers': 1636467.8193695154, 'Z... |
| change_1h | -0.44896 | -0.548806 | -0.572617 | -0.197715 | -0.743818 | 0 | 0.359498 | -0.219655 | -0.675755 | -0.964538 | ... | None | None | None | None | None | None | None | -100 | None | None |
| change_1d | -3.131439 | -5.297916 | -5.013928 | -4.886415 | -5.450934 | -5.518304 | -4.320109 | -0.608482 | -5.742343 | -8.011128 | ... | None | None | None | None | None | None | None | -100 | None | None |
| change_7d | -2.475693 | -9.598398 | -6.84128 | None | -8.440936 | -3.395067 | -7.09348 | None | -7.491259 | -11.422413 | ... | None | None | None | None | None | None | None | -100 | None | None |
| fdv | 12301661224 | 2840314296 | 4491341668 | 2485404838 | 14483125559 | NaN | 3153251980 | 21834450907 | 15778573102 | 3872965400 | ... | 297401311 | 10616405 | 44201792 | 16121682 | NaN | 57017539 | NaN | 184351117 | NaN | NaN |
| mcap | 1459791560 | 2545808395 | 3719606083 | 913173794 | 14483125559 | 73522897 | 1940052879 | 9888225317 | 10844439988 | 235584083 | ... | 33371283 | 0 | 27646000 | 0 | 10244171 | 3644403 | 0 | 0 | NaN | NaN |
| staking | NaN | NaN | 1276237472.239922 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | 4812640.377482 | 121803.487761 | 11131451.1693 | NaN | 4712925.053547 | 2304569.802009 | 925380.492968 | 142474.836388 | NaN | NaN |
| forkedFrom | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | NaN | NaN | NaN | NaN | NaN | NaN | [Pantherswap, Pancakeswap] | NaN | NaN |
| pool2 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | NaN | 221923.158635 | 6445303.662442 | 96739.953498 | 211307.874648 | NaN | 169532.888702 | NaN | 19304.101388 | NaN |
| listedAt | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | ... | 1634551713 | 1634577126 | 1634674060 | 1635279168 | 1635296377 | 1635383289 | 1635463716 | 1635465731 | 1636043958 | 1636305888 |
30 rows × 704 columns
[ ]: