# How to get token unlock data

Unlock calendars on a page, in CSV or by API — which fields each returns, how far back, at what price — and how to check one event against its source.

*https://cryptomarkets.tools/how-to/get-token-unlock-data · next to Crypto Fundamentals & Research*

**Answer:** For one token, read Tokenomist's page. For data, call an unlock API: Tokenomist Pro, at 99 dollars a month, gives 1,000 calls covering a year either side of today. DropsTab and CryptoRank sell per-token schedules from 299 and 475 dollars. DefiLlama and Blockworks Intel sell theirs inside larger plans. Every calendar models a vesting contract or a project's document, so check one large event against its source before you trust the rest.

## Approaches

*In the author’s order. Paid placement does not affect it.*

1. [Tokenomist](https://cryptomarkets.tools/tools/tokenomist.md) — The specialist. Cliffs per allocation in six standard recipient groups, a source and precision label on each, CSV on Pro, and an API from 99 dollars.
2. [DropsTab API](https://cryptomarkets.tools/tools/dropstab-api.md) — One token's full schedule, with TGE flags and shares of market cap, total supply and FDV, from the 299-dollar Pro plan. The free calendar is the website.
3. [DefiLlama](https://cryptomarkets.tools/tools/defillama.md) — Unlocks free on the website, built from vesting contracts and documented allocations. The 300-dollar API plan serves the list and a per-token schedule.
4. [CryptoRank API](https://cryptomarkets.tools/tools/cryptorank-api.md) — Per-coin events with shares of circulating and of max supply, and a market-wide upcoming list, from 475 dollars; 149 dollars stops at the next unlock.
5. [Blockworks Intel](https://cryptomarkets.tools/tools/messari.md) — Analyst-modelled schedules that cite sources per tranche and split cliffs from linear rate changes. The API is quoted by sales; a legacy route charges per call.

## The short way

Get a key and ask for one token's cliffs over a year. Tokenomist's Pro plan, at 99 dollars a
month, includes 1,000 API calls with a window of one year back and one year forward. On the
v5 endpoint the token goes in the path and the recipient groups go in a filter:

```bash
curl -s -H 'x-api-key: YOUR_API_KEY' \
  'https://api.tokenomist.ai/v5/unlock/events/arbitrum?start=2026-10-27&end=2027-10-27&standardAllocation=founderTeam,privateInvestors'
```

Each row is a date carrying a total in tokens and in dollars, plus a `valueToMarketCap` percentage.
Below that is an `allocationBreakdown`: the project's own allocation name, Tokenomist's standard
group, the reference price behind the dollar figure, and an `unlockPrecision` saying how exact the
date is. Take the `tokenId` from the token-list endpoint first. To scan across the market instead
of one token, `/v5/unlock/events/upcoming` takes the same filters plus a minimum market cap and a
minimum value-to-market-cap.

If you only want to read the calendar, the free web plan shows three past events and one future
event per token. Pro's CSV export puts the same data in a spreadsheet.

## What the options are

The order below follows the cheapest published plan that returns one token's schedule by API.

[Tokenomist](https://cryptomarkets.tools/tools/tokenomist), formerly TokenUnlocks, is the product built around this job.
Its two labels matter most. *Assumption* says where a schedule came from: a vesting contract,
public project data with or without on-chain verification, data the team gave privately, or
Tokenomist's own inference from on-chain behaviour. *Precision* says how exact the date is, from
second through to month, or "to be determined". Recipients are mapped into six standard groups:
founder and team, private investors, public investors, reserved, community, and other. The API
filters on those groups. History is capped by plan. Pro gets a year back and a year forward;
Standard API, at 749.95 dollars a month, gets two years each way; Elite gets three. The web plans
show all history. No self-serve plan carries a commercial licence.

The [DropsTab API](https://cryptomarkets.tools/tools/dropstab-api) returns a token's whole schedule in one response. Each
event carries a date, the allocation name, a flag for whether it is the token generation event
(TGE) unlock, a token amount, a dollar amount, and its share of all tokens, of market cap and of
FDV. Around the events sit the allocation totals, and locked, unlocked and *untracked* amounts.
The timeline filter takes `PAST` or `FUTURE`, and the docs state no history window. The ladder
is the catch. Basic, at 19 dollars, has no unlock data. Advanced, at 59, gets the market-wide
overview and the list of covered tokens. The per-token schedule and chart start at Pro, 299
dollars a month. A plan without the endpoint is refused with "Endpoint is not available for the
current plan".

[DefiLlama](https://cryptomarkets.tools/tools/defillama) carries an unlocks section on its free website. Its own data
definitions describe the schedules as built from vesting contracts and documented allocations.
The API side is two endpoints on the 300-dollar API plan, with the key placed in the URL path.
`/api/emissions` lists every covered token with circulating supply, total locked, max supply,
events, next event and unlocks per day. `/api/emission/{protocol}` returns one token's data, but
the docs describe its body only as `{body, lastModified}`, so the shape has to be read from a
response.

The [CryptoRank API](https://cryptomarkets.tools/tools/cryptorank-api) needs its Pro plan, at 475 dollars a month, for
anything per event. At that plan, a coin's unlock events are paged at 50 a time and filtered to
`all`, `upcoming` or `past`. Each event carries a date, allocation name, tokens, dollar value,
cumulative unlocked, percentage of the allocation, `percentOfMcap` and `percentOfSupply`. The
cross-market upcoming list defaults to 30 days ahead. Vesting allocations add a `vestingType` of
linear, nonlinear or dynamic. The 149-dollar Advanced plan gets the tokenomics summary: the next
unlock's date, amount and shares, total locked and unlocked, and an untracked amount for
allocations with no known schedule. It also gets market-wide unlock totals over time. The free
Sandbox gets none of this.

[Blockworks Intel](https://cryptomarkets.tools/tools/messari), formerly Messari, models each covered asset by hand from the
project's disclosures. Each tranche carries the analyst's description, assumptions and sources.
An event is either a `cliff` or a `dailyLinearRateChange`, never both. Each carries native and
dollar amounts, a share of the total allocation, and a per-recipient breakdown. The schedule runs
forward to the end of vesting. The web Pro plan, at 4,500 dollars a year, shows the unlock data
and exports any chart to CSV. Its API access, though, is the Assets endpoints only, and the Token
Unlocks API needs a key with token unlock access, which on the published plans is a sales item.
There is a cheaper door. The legacy Messari API, now in maintenance mode, serves
its token-unlock endpoints over x402 with no account, billed per request in USDC: 0.15 dollars for one asset's events, 0.25
for allocations, 0.75 for a timeseries.

## One request each

The same question asked of the other four APIs: one token's future events. Each header name is
the vendor's own. The identifiers are placeholders except where the vendor's docs use that
example, so look yours up first.

```bash
# DropsTab: COIN_SLUG comes from GET /api/v1/tokenUnlocks/supportedCoins
curl -s -H 'x-dropstab-api-key: YOUR_API_KEY' \
  'https://public-api.dropstab.com/api/v1/tokenUnlocks/COIN_SLUG?unlocksTimelineFilter=FUTURE&unlocksDateSortOrder=ASC'
```

```bash
# DefiLlama: the key is part of the path, never a header or a query parameter
curl -s 'https://pro-api.llama.fi/YOUR_API_KEY/api/emission/hyperliquid'
```

```bash
# CryptoRank: COIN_ID is the numeric id from GET /v3/currencies/map
curl -s -H 'X-Api-Key: YOUR_API_KEY' \
  'https://api.cryptorank.io/v3/currencies/COIN_ID/vesting/events?filter=upcoming&sortBy=time&sortOrder=asc'
```

```bash
# Blockworks: a key with token unlock access; slug or asset UUID in the path
curl -s -H 'X-Blockworks-API-Key: YOUR_API_KEY' \
  'https://api.blockworks.com/token-unlocks/v1/assets/solana/events?unlockType=CLIFF&startTime=2026-10-27T00:00:00Z&endTime=2027-10-27T00:00:00Z'
```

## Where this breaks

**Every calendar has one of two sources.** An unlock date is either read off a vesting contract
on chain, or copied from what the project published: a whitepaper, a blog post, an allocation
chart. These are different kinds of claim. A contract releases tokens at the timestamp in its
code. A document says "monthly", and Tokenomist's own example of that case is tagged month
precision, meaning the unlock can land on any day of the month. Tokenomist says which source each
schedule rests on. Blockworks cites sources per tranche, and those can be secondary: the example
in its own allocations docs cites a third-party tokenomics site, not a project filing. CryptoRank
and DropsTab return no source field per event. CryptoRank also stamps every event at the start of
the UTC day. So two vendors can disagree by weeks on one tranche, and both can be faithful to
what they read.

**Cliff and linear are a vendor's classification, not the contract's.** Tokenomist calls a
release linear if it happens daily, and a cliff if it happens at any longer interval. Since v4,
its unlock-events endpoint returns cliffs only; linear streams and mining rewards are in daily
emission. Blockworks splits an event into a cliff or a rate change. CryptoRank's upcoming list
merges all of a coin's events on the same day into one row. A contract with a cliff on a linear
schedule is a lump and a stream at once. OpenZeppelin's `VestingWalletCliff` vests nothing
before the cliff, then releases everything accrued since the start in one go, then continues
linearly:

```text
vested(t) = 0                                  before the cliff
          = total x (t - start) / duration     from the cliff until start + duration
          = total                              after start + duration

at t = cliff, total x (cliff - start) / duration becomes releasable at once
```

One vendor may record that as a cliff event plus a linear stream, another as twelve monthly
cliffs. Add up "next month's unlocks" from two vendors and you are summing different objects.

**Unlocked is not circulating, and the percentage is a ratio of two judgements.** Tokenomist's
supply definitions make the split explicit. Released supply is unlocked and claimable. Tokens
still sitting in a team, treasury or investor wallet are not circulating until they move. Its
Claimed panel notes that claims can happen before or after the scheduled unlock. The share
printed beside an event has a different denominator at each vendor. CryptoRank divides by current
circulating supply and, separately, by max supply. DropsTab divides by market cap, all tokens and
FDV. Tokenomist divides dollar value by market cap. Blockworks divides by total allocation. And
the circulating supply in the denominator is another vendor's rulebook (see
[circulating supply](https://cryptomarkets.tools/glossary/circulating-supply)). An allocation that a market-cap vendor
already counts as circulating, a foundation reserve for example, still appears as an unlock on a
schedule vendor's calendar. Divide one by the other and the tokens are counted twice. Why the
supply figures differ is
[how to reconcile a token's supply and market cap](https://cryptomarkets.tools/how-to/reconcile-supply-and-market-cap); do
not paste an unlock percentage from one source next to a market cap from another.

**Schedules change after they are published, and the calendar may hold the old one on
purpose.** Governance can extend a lock, release a treasury or burn an allocation. Teams re-lock.
Tokenomist's locked-supply figure does not yet include tokens in re-lock mechanisms. Supply
waiting on an event such as a governance vote is filed as "TBD locked", with no date. CryptoRank and DropsTab both report an
*untracked* amount; CryptoRank defines it as allocations with no known schedule, counted as
neither locked nor unlocked. Tokenomist also publishes a policy freeze. A change the team sends privately within 14
days of an unlock is applied 7 to 14 days after it. A newly public source is applied in two to
three business days. So close to an event, the date on the page can knowingly differ from what
the team has said.

**The recipient label is who was allocated, not who holds the claim now.** OpenZeppelin's
documentation says it plainly: a vesting wallet's ownership can be transferred, so "it is
possible to sell unvested tokens". A locked position sold over the counter changes no calendar,
and the row still says "investors". The groups are also each vendor's own mapping. Tokenomist
usually files an "Ecosystem Fund" under reserved, because the project controls it. A vendor that
keeps the project's own labels, as CryptoRank, DropsTab and Blockworks do, will put the same
tokens somewhere else. "Team share" compared across two vendors is partly a comparison of their
taxonomies.

**Dollar figures use today's price.** CryptoRank documents that its dollar values use the current
price, past events included. Tokenomist returns the reference price and when it was last updated.
For history, store token amounts and price them yourself on the event's date.

**How to check one event.** Pick the largest upcoming event on the calendar and trace it.

1. Find the source. Tokenomist's `dataSource` field and Assumption label, or Blockworks' tranche
   sources, tell you whether to look for a contract or a document. The project's own docs usually
   publish the contract addresses.
2. If it is a contract, pull its verified source and ABI first. The
   [Etherscan API](https://cryptomarkets.tools/tools/etherscan-api) serves both on every plan. That tells you which vesting
   implementation it is. Then read its getters at a block explorer or over any
   [RPC endpoint](https://cryptomarkets.tools/glossary/rpc-endpoint). On an OpenZeppelin wallet those are `start()`,
   `duration()`, `cliff()`, `released()`, `releasable()` and `vestedAmount()` at a timestamp.
   Compute the amount vested on the vendor's date and compare it in tokens, not dollars. Then check
   the transfers out of the contract: they show what was actually claimed, and when, which no
   calendar records.
3. If it is a document, find the allocation table and the vesting terms. Rebuild the event by
   hand: the TGE percentage, the cliff in months, then the release period and its frequency. If
   your number matches the vendor's and only the date differs, the gap is precision. If the
   amount differs, one of you is reading a different version of the document.

A vendor whose largest event survives this check has earned some trust for the rest of its
calendar. One that fails it has shown you which of its labels to read first.

## If you outgrow this

If the data is going **into a product other people use**, check the licence before the price.
Tokenomist sells no commercial licence on any self-serve plan, and the API terms grant personal or
non-commercial use. CryptoRank's pricing page, as archived on 28 August 2026, listed its free Sandbox
under a non-commercial licence. Redistribution terms are the conversation to have first.

If the question becomes **what actually moved, not what was scheduled**, stop reading calendars
and read the chain. Claims out of a vesting contract and transfers out of a beneficiary wallet are
ordinary on-chain events, and [querying a chain with SQL](https://cryptomarkets.tools/how-to/query-a-chain-with-sql) gets
you all of them for every contract you have identified. Keep the vendor's schedule beside your
own query as the expectation, and the chain as the record.

Everything else on token supply sits in
[fundamentals and research](https://cryptomarkets.tools/categories/fundamentals-research).

## FAQ

### Is there a free token unlock API?

Not one with a published allowance. Tokenomist's docs say a Free account can create and use a key but state no call allowance, and its pricing matrix greys the API out on Free. CryptoRank's free Sandbox has no unlock endpoints. DropsTab has no free plan. DefiLlama's unlock endpoints need its 300-dollar API plan. The free versions are web pages, and the one machine-readable route with a published price and no subscription is the legacy Messari pay-per-call endpoint, at 0.15 dollars a request for one asset's events.

### Do the CoinGecko or CoinMarketCap APIs have token unlock data?

Their API documentation indexes, read on 27 October 2026, list no unlock or vesting endpoint. Both publish a circulating supply, which is the other half of the question. A schedule of when locked tokens are released comes from a different kind of vendor.

### Why do two unlock calendars show different amounts for the same date?

Usually they are reading different sources, or classifying the same tranche differently. One vendor reads a vesting contract and another a whitepaper. One records a monthly release as a cliff and another as a linear stream. One dates an event to the second and another to the month. Each vendor also leaves out allocations that have no known schedule.

### What does "percent of circulating supply" mean on an unlock?

It is the unlock amount divided by somebody's circulating supply, and the denominator differs by vendor. CryptoRank divides by current circulating supply and also by maximum supply, falling back to total supply. DropsTab gives shares of market cap, of all tokens and of FDV. Tokenomist divides the unlock's dollar value by market cap. Blockworks gives a share of the total allocation.

## Sources

1. [Unlock Events API v5](https://docs.tokenomist.ai/api-documents/unlock-events/v5) — Tokenomist, read 2026-10-27
2. [Upcoming Unlock Events API v5](https://docs.tokenomist.ai/api-documents/upcoming-unlock-events/v5) — Tokenomist, read 2026-10-27
3. [Setting up your API key](https://docs.tokenomist.ai/api-documents/setting-up-your-api-key) — Tokenomist, read 2026-10-27
4. [Tokenomist pricing (Wayback Machine capture of 2 October 2026)](https://web.archive.org/web/20261002202522/https://tokenomist.ai/pricing) — Tokenomist, read 2026-10-27
5. [Emission — Cliff and Linear](https://docs.tokenomist.ai/methodology/cliff-and-linear-emission) — Tokenomist, read 2026-10-27
6. [Precision and Assumption](https://docs.tokenomist.ai/methodology/precision-and-assumption) — Tokenomist, read 2026-10-27
7. [Group Allocations](https://docs.tokenomist.ai/methodology/group-allocations) — Tokenomist, read 2026-10-27
8. [Supply Metrics](https://docs.tokenomist.ai/methodology/supply-metrics) — Tokenomist, read 2026-10-27
9. [Claimed Panel](https://docs.tokenomist.ai/claimed-pane) — Tokenomist, read 2026-10-27
10. [Data update policy](https://docs.tokenomist.ai/miscellaneous/data-update-policy) — Tokenomist, read 2026-10-27
11. [Get detailed unlock information for a specific token](https://api-docs.dropstab.com/reference/allbycoinslug) — DropsTab, 2026-06-09
12. [DropsTab Commercial API — plans](https://dropstab.com/products/commercial-api) — DropsTab, read 2026-10-27
13. [API — Token Unlocks, GET /api/emissions and GET /api/emission/{protocol}](https://api-docs.defillama.com/llms-pro.txt) — DefiLlama, read 2026-10-27
14. [Data Definitions — Unlocks / Emissions](https://docs.llama.fi/analysts/data-definitions) — DefiLlama, read 2026-10-27
15. [Unlock Events — GET /v3/currencies/{id}/vesting/events](https://docs.cryptorank.io/api-reference/vesting-%26-token-unlocks/unlock-events) — CryptoRank, read 2026-10-27
16. [Upcoming Token Unlocks](https://docs.cryptorank.io/api-reference/vesting-%26-token-unlocks/upcoming-token-unlocks) — CryptoRank, read 2026-10-27
17. [Tokenomics Summary](https://docs.cryptorank.io/api-reference/currencies/tokenomics-summary) — CryptoRank, read 2026-10-27
18. [Plans and limits](https://docs.cryptorank.io/migration/plans-and-limits) — CryptoRank, read 2026-10-27
19. [Token Unlocks API — Overview](https://docs.blockworks.com/api-reference/token-unlocks/overview) — Blockworks, read 2026-10-27
20. [Token Unlocks API — Get Allocations](https://docs.blockworks.com/api-reference/token-unlocks/get-v1-allocations) — Blockworks, read 2026-10-27
21. [Pay-Per-Request with x402 (legacy Messari docs)](https://docs.messari.io/api-reference/x402-payments) — Messari, read 2026-10-27
22. [Finance — VestingWallet and VestingWalletCliff](https://docs.openzeppelin.com/contracts/5.x/api/finance) — OpenZeppelin, read 2026-10-27
23. [CoinGecko API documentation index](https://docs.coingecko.com/llms.txt) — CoinGecko, read 2026-10-27
24. [CoinMarketCap API documentation index](https://coinmarketcap.com/api/documentation/llms.txt) — CoinMarketCap, read 2026-10-27

*Last updated 2026-10-27. Corrected in place — an endpoint that moves is a bug here, not a new post.*