Overview

The Blockworks Token Unlocks API exposes the vesting schedules behind circulating supply. Every covered asset is modeled by hand from the project’s own disclosures: the allocation is split into recipient buckets (team, investors, foundation, community), each bucket is given a release schedule, and each tranche carries the analyst’s description, assumptions, and sources. You get the schedule as data rather than as a chart.

​

What you get

• Allocation breakdowns, with citations. Every tranche records what the recipient was allocated, how much has unlocked, and the sources the model was built from, so a number can be traced back to a filing or a disclosure.
• Cliffs and linear vesting, separated. Unlock events distinguish a discrete tranche landing on a date from a change in the daily vesting rate, so “the next big unlock” is a query rather than an eyeball estimate.
• Flow and stock, as two series. Per-interval unlock amounts for supply pressure, and daily cumulative vesting state for progress against the full allocation.
• Projected forward. Schedules run past today. Future dated windows are valid on every timeseries endpoint.
• Joins to the rest of the platform. Assets carry the same UUIDs and slugs as the Data API and Monitoring, so unlock data lines up with price, supply, and events without a mapping table.

​

Base URL and authentication

All Token Unlocks endpoints live under /token-unlocks/v1 on the shared Blockworks API host, https://api.blockworks.com, and every request requires an API key in the X-Blockworks-API-Key header. The Quickstart walks through getting a key and making a first request; Authentication covers access tiers and key handling.

​

Core concepts

Allocation. A named recipient bucket (Team, Community Reserve, Coinlist Auction Sale) with a total allocation, the amount unlocked to date, and the amount still locked, in both native units and USD. Each tranche also carries a description, the assumptions the analyst applied, and sources. The recipient name is the join key across every endpoint in this tab. Unlock event. A date on which the schedule changes. A cliff releases a discrete tranche on that date. A dailyLinearRateChange changes how much vests per day from that date forward. An event carries one or the other, and the other field is null. Filter with unlockType to get just one kind. Snapshot. A point in one of the two timeseries. Unlock snapshots are flow: each one reports what unlocked during that interval and nothing before it. Vesting schedule snapshots are stock: each one reports cumulative unlocked, remaining, and percent complete as of that day. Both come in a total series plus a per-recipient breakdown that sums to it.

​

Choosing an endpoint

The two timeseries answer different questions from the same underlying model. If you are sizing sell pressure in a window, use the unlocks timeseries. If you are tracking how far through its schedule an allocation is, use the vesting schedule.

​

Identifiers

The four per-asset endpoints take assetId and accept either a slug (solana) or the asset UUID. The assetIDs filter on List Covered Assets is the exception: it accepts UUIDs only, and slugs match nothing rather than returning an error. Resolve slugs through the list endpoint before filtering by id.

​

Response shape

Token Unlocks uses the same envelope as every Blockworks API: error is null on success and a string on failure, and data carries the payload. There is no metadata block on these endpoints.

​

Coverage and filtering

• Filters combine as AND across parameters, OR within one. category=Networks,Financial Services returns both categories; adding sector=Lending narrows that set rather than widening it.
• page and limit are accepted but not currently applied. List Covered Assets returns the full matching set on every call. Do not build paging logic against them.
• Results are unordered. Two identical calls return the same assets in a different order. Sort client-side when ordering matters.
• tags can be null on an asset rather than an empty list, and category and sector can be empty strings for assets that have not been classified.
• Read otherInfo before trusting a schedule as complete. It is null for most assets, but when it is set it records an analyst caveat, such as a project that has only published its schedule through a given year. The unlock data for those allocations is partial by construction.
• projectedEndDate equal to genesisDate means the allocation unlocked at genesis rather than meaning the data is missing.

​

Use cases

• Supply pressure models. Pull the unlocks timeseries at WEEKLY or MONTHLY for the assets you cover and rank upcoming windows by unlocked value.
• Unlock calendars. Query events with unlockType=CLIFF and a forward endTime to build a dated calendar of discrete releases.
• Holder concentration. Combine allocation breakdowns with the vesting schedule to see which recipients are still locked and for how long.
• Diligence. Surface the description, assumptions, and sources on a tranche next to the numbers, so a reader can audit where a figure came from.
• Event correlation. Join unlock dates to Monitoring developments on the same asset UUID to study what happened around a release.