> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Analyst-modeled token unlock schedules: who holds what, when it vests, and how much supply lands in any given week.

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](/api-reference/token-unlocks/quickstart) walks
through getting a key and making a first request;
[Authentication](/getting-started/authentication) covers access tiers and key handling.

## Core concepts

<CardGroup cols={3}>
  <Card title="Allocation" icon="chart-pie">
    A recipient bucket and its share of total supply.
  </Card>

  <Card title="Unlock event" icon="calendar">
    A dated cliff, or a change in the daily vesting rate.
  </Card>

  <Card title="Snapshot" icon="chart-line">
    One point in a series, either per interval or per day.
  </Card>
</CardGroup>

**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

| You want                                       | Endpoint                                                                                    |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
| The list of assets with unlock coverage        | [List Covered Assets](/api-reference/token-unlocks/get-v1-assets)                           |
| Who holds what, and how much has unlocked      | [Get Allocations](/api-reference/token-unlocks/get-v1-allocations)                          |
| The next cliff, or every dated schedule change | [Get Unlock Events](/api-reference/token-unlocks/get-v1-assets-assetId-events)              |
| Supply hitting the market per week or month    | [Get Unlocks Timeseries](/api-reference/token-unlocks/get-v1-assets-assetId-unlocks)        |
| Percent vested over time, per recipient        | [Get Vesting Schedule](/api-reference/token-unlocks/get-v1-assets-assetId-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.

## 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](/api-reference/token-unlocks/get-v1-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.

<Note>
  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.
</Note>

## 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](/api-reference/monitoring/overview) developments on the same asset UUID to study what happened around a release.