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 Examples below make a first request; Authentication covers access tiers and key handling.

Core concepts

Allocation

A recipient bucket and its share of total supply.

Unlock event

A dated cliff, or a change in the daily vesting rate.

Snapshot

One point in a series, either per interval or per day.

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 Token Unlocks endpoint. 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

You want	Endpoint
The list of assets with unlock coverage	List Covered Assets
Who holds what, and how much has unlocked	Get Allocations
The next cliff, or every dated schedule change	Get Unlock Events
Supply hitting the market per week or month	Get Unlocks Timeseries
Percent vested over time, per recipient	Get Vesting Schedule

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.

Examples

Every example reads the key from BLOCKWORKS_API_KEY. If you do not have one yet, the Data API quickstart covers creating and storing it.

Find an asset with coverage

Start with the list of covered assets, narrowed to a category. The examples sort before printing because the result set is unordered, and they fall back to an empty list because an empty result is "data": null (see Coverage and filtering).

curl "https://api.blockworks.com/token-unlocks/v1/assets?category=Networks" \
  -H "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"

import os
import requests

response = requests.get(
    "https://api.blockworks.com/token-unlocks/v1/assets",
    params={"category": "Networks"},
    headers={"X-Blockworks-API-Key": os.environ["BLOCKWORKS_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

assets = response.json()["data"] or []
for asset in sorted(assets, key=lambda a: a["symbol"]):
    print(asset["symbol"], asset["slug"], asset["projectedEndDate"])

const url = new URL("https://api.blockworks.com/token-unlocks/v1/assets");
url.searchParams.set("category", "Networks");

const response = await fetch(url, {
  headers: { "X-Blockworks-API-Key": process.env.BLOCKWORKS_API_KEY },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);

const { data } = await response.json();
for (const asset of (data ?? []).sort((a, b) => a.symbol.localeCompare(b.symbol))) {
  console.log(asset.symbol, asset.slug, asset.projectedEndDate);
}

Find the next cliff

Unlock events are the dated points where a schedule changes. Filter to CLIFF and a forward window to get the discrete releases ahead.

curl "https://api.blockworks.com/token-unlocks/v1/assets/solana/events?unlockType=CLIFF&startTime=2026-01-01T00:00:00Z&endTime=2027-01-01T00:00:00Z" \
  -H "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"

import os
import requests

response = requests.get(
    "https://api.blockworks.com/token-unlocks/v1/assets/solana/events",
    params={
        "unlockType": "CLIFF",
        "startTime": "2026-01-01T00:00:00Z",
        "endTime": "2027-01-01T00:00:00Z",
    },
    headers={"X-Blockworks-API-Key": os.environ["BLOCKWORKS_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

events = (response.json()["data"] or {}).get("unlockEvents", [])
for event in events[:5]:
    cliff = event["cliff"]
    recipients = ", ".join(a["allocationRecipient"] for a in cliff["allocations"])
    print(f"{event['timestamp']} {cliff['amountNative']:,.0f} native to {recipients}")

Each event carries either a cliff or a dailyLinearRateChange, and the other field is null. Both shapes report amountNative, amountUSD, percentOfTotalAllocation, and a per-recipient allocations breakdown. Drop unlockType to get both kinds in one call.

Chart supply pressure

The unlocks timeseries buckets released tokens by interval. interval is required and takes DAILY, WEEKLY, MONTHLY, QUARTERLY, or YEARLY.

curl "https://api.blockworks.com/token-unlocks/v1/assets/solana/unlocks?interval=MONTHLY&startTime=2026-01-01T00:00:00Z&endTime=2026-07-01T00:00:00Z" \
  -H "X-Blockworks-API-Key: $BLOCKWORKS_API_KEY"

import os
import requests

response = requests.get(
    "https://api.blockworks.com/token-unlocks/v1/assets/solana/unlocks",
    params={
        "interval": "MONTHLY",
        "startTime": "2026-01-01T00:00:00Z",
        "endTime": "2026-07-01T00:00:00Z",
    },
    headers={"X-Blockworks-API-Key": os.environ["BLOCKWORKS_API_KEY"]},
    timeout=30,
)
response.raise_for_status()

data = response.json()["data"]
for snapshot in data["totalSnapshots"]:
    print(snapshot["timestamp"], round(snapshot["unlockedInPeriodUSD"]))

# The same series, split by who receives the tokens.
for allocation in data["allocations"]:
    released = sum(s["unlockedInPeriodNative"] for s in allocation["dailySnapshots"])
    print(allocation["allocationRecipient"], round(released))

These snapshots are flow: each one covers its own interval and carries no running total. For cumulative state (how much has vested, how much remains, percent complete per day), use Get Vesting Schedule instead. The per-recipient arrays are named dailySnapshots on both endpoints, even when you requested a coarser interval.

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.

An empty result is "data": null, not an empty array, and it still comes back with a 200. A filter that matches nothing and an asset with no unlock coverage both look like this, so check for null before iterating.

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.

Getting Started

Discovery

Concepts

Market Data

Onchain Fundamentals

Institutional

Fundraising

Social & Mindshare

News

Research

Token Unlocks

Token Transparency Framework

Charts

Token Unlocks

What you get

Base URL and authentication

Core concepts

Allocation

Unlock event

Snapshot

Choosing an endpoint

Examples

Find an asset with coverage

Find the next cliff

Chart supply pressure

Identifiers

Response shape

Coverage and filtering

Use cases

​What you get

​Base URL and authentication

​Core concepts

Allocation

Unlock event

Snapshot

​Choosing an endpoint

​Examples

​Find an asset with coverage

​Find the next cliff

​Chart supply pressure

​Identifiers

​Response shape

​Coverage and filtering

​Use cases

What you get

Base URL and authentication

Core concepts

Choosing an endpoint

Examples

Find an asset with coverage

Find the next cliff

Chart supply pressure

Identifiers

Response shape

Coverage and filtering

Use cases