How to get token unlock data

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:

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, 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 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 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 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, 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.

# 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'

# 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'

# 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'

# 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:

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). 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; 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 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. 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 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.