DefiLlama APIdefillama.com ↗
Access upcoming token unlock events from DefiLlama. Get unlock dates, USD values, supply percentages, and allocation categories for any tracked DeFi protocol.
What is the DefiLlama API?
The DefiLlama Token Unlocks API exposes upcoming token release schedules across tracked DeFi protocols via 2 endpoints. get_upcoming_unlocks returns a ranked list of all near-term unlock events with USD values and supply percentages, while get_protocol_unlocks returns per-protocol detail including 5+ response fields such as total locked tokens, token price, market cap, and a full breakdown of upcoming events by allocation category.
curl -X GET 'https://api.parse.bot/scraper/be6781dd-5455-4987-8956-077a42c1da35/get_upcoming_unlocks?limit=10' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace defillama-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: DefiLlama Token Unlocks SDK — upcoming unlocks and protocol detail."""
from parse_apis.defillama_com_api import DefiLlamaUnlocks, ProtocolNotFound
client = DefiLlamaUnlocks()
# List upcoming token unlock events, capped to 5 items.
for unlock in client.unlocks.list(limit=5):
print(f"{unlock.name} ({unlock.symbol}): "
f"unlocks {unlock.unlock_tokens:.0f} tokens on {unlock.next_unlock_date}, "
f"value ${unlock.unlock_value_usd or 0:,.2f}, "
f"category={unlock.category}")
# Drill into a specific protocol's full unlock schedule via the sub-resource.
first = client.unlocks.list(limit=1).first()
if first:
detail = first.detail.get()
print(f"\n{detail.name} ({detail.symbol}) — next event: {detail.event_countdown}")
print(f" Total unlock value: ${detail.total_unlock_value_usd:,.2f}")
for evt in detail.upcoming_events[:3]:
print(f" {evt.date} | {evt.category} | {evt.token_amount:.2f} tokens ({evt.unlock_type})")
# Direct protocol lookup by slug with typed error handling.
try:
arb = client.protocol_details.get(protocol_slug="arbitrum")
print(f"\nArbitrum price: ${arb.token_price_usd}, locked: {arb.total_locked:,.0f}")
except ProtocolNotFound as exc:
print(f"Protocol not found: {exc.protocol_slug}")
print("\nexercised: unlocks.list / detail.get / protocol_details.get / ProtocolNotFound")
Retrieves a list of upcoming token unlock events across all tracked protocols, sorted by next unlock date. Each entry includes the token name, symbol, unlock date, unlock value in USD, percentage of circulating and max supply being unlocked, and the allocation category. Results are auto-iterated; pass limit to cap total items returned.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of unlock events to return. |
{
"type": "object",
"fields": {
"total": "integer",
"unlocks": "array of unlock event objects"
},
"sample": {
"data": {
"total": 5,
"unlocks": [
{
"name": "Aptos",
"symbol": "APT",
"category": "noncirculating",
"market_cap": 517521602.72,
"max_supply": 2100000000,
"unlock_type": "cliff",
"protocol_slug": "aptos",
"unlock_tokens": 3210144.664725,
"pct_max_supply": 0.1529,
"token_price_usd": 0.623649,
"next_unlock_date": "2026-07-12T15:47:15Z",
"unlock_value_usd": 2002003.51,
"circulating_supply": 837812177.76,
"pct_circulating_supply": 0.3832
}
]
},
"status": "success"
}
}About the DefiLlama API
Endpoints and Response Shape
The get_upcoming_unlocks endpoint returns a paginated list of unlock events sorted by next unlock date. Each object in the unlocks array includes the token name, symbol, unlock date, unlock value in USD, the percentage of circulating supply and max supply being unlocked, and the allocation category (e.g. team, investors, ecosystem). Use the limit parameter to control how many results come back. The total field tells you the full count of tracked events.
Protocol-Level Detail
get_protocol_unlocks accepts a protocol_slug string (e.g. arbitrum, celestia, chainlink) and returns a richer data structure for that specific token. Top-level fields include name, symbol, market_cap, token_price_usd, max_supply, and total_locked. The categories array lists all allocation buckets tracked for that protocol. The upcoming_events array gives granular per-event data: date, description, token_amount, category, and unlock_type.
Coverage and Data Freshness
DefiLlama maintains unlock schedules for a wide range of protocols spanning L1s, L2s, DeFi applications, and infrastructure tokens. The event_countdown field on protocol responses gives a human-readable time-to-next-unlock string, useful for display or alerting. Coverage is limited to protocols that DefiLlama has manually modeled; not every token in the market is tracked.
Data Source
DefiLlama is a DeFi analytics platform that tracks TVL, yields, and token vesting schedules. It does not publish an official documented REST API for its unlock data. This API surfaces that data in a structured, queryable format.
The DefiLlama API is a managed, monitored endpoint for defillama.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when defillama.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official defillama.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor upcoming unlock events above a USD threshold using the
unlocksarray value field to filter high-impact releases - Build a token unlock calendar by ingesting
get_upcoming_unlocksand grouping events by date - Alert on large supply increases by comparing unlock percentage fields against circulating and max supply
- Analyze vesting structure for a specific protocol using
get_protocol_unlocksallocationcategoriesandupcoming_events - Track total locked tokens over time for a protocol using the
total_lockedandmarket_capfields - Correlate token price data from
token_price_usdwith upcoming unlock dates to model potential sell pressure - Classify unlock risk by
unlock_typeandcategoryfields to distinguish investor unlocks from ecosystem distributions
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does DefiLlama have an official developer API for token unlock data?+
What does get_protocol_unlocks return beyond basic unlock dates?+
categories lists every vesting bucket (e.g. team, investors, ecosystem), upcoming_events gives each event's token amount, category, and unlock type, and market context fields — market_cap, token_price_usd, max_supply, and total_locked — are included so you can assess the unlock relative to current market conditions.Can I filter get_upcoming_unlocks by allocation category or minimum USD value?+
limit parameter to control result count; server-side filtering by category or value is not currently supported. You can filter the returned unlocks array client-side on any field, including allocation category and USD value. You can also fork this API on Parse and revise it to add server-side filter parameters.Is historical unlock data (past events) available through these endpoints?+
get_upcoming_unlocks is sorted by next unlock date and get_protocol_unlocks surfaces upcoming events only. You can fork this API on Parse and revise it to add a historical events endpoint if past unlock records are exposed by the source.How complete is protocol coverage — are all tokens tracked?+
total field on get_upcoming_unlocks reflects only the protocols currently tracked.