Quickstart - Blockworks Documentation

This page gets you a key and a first Token Unlocks response, then builds the two queries most people want: the next cliff, and how much supply unlocks per month. The key is the same one that authenticates every Blockworks product, so if you already have one you can skip the first step.

Get an API key

Create a key at app.blockworks.com/account/api.Keys are shown once at creation. Store yours in a secret manager or environment variable, and never commit it or send it from a browser.

export BLOCKWORKS_API_KEY="your-api-key"

Find an asset with coverage

All Token Unlocks endpoints live under /token-unlocks/v1 on the shared Blockworks API host, and every one of them requires the X-Blockworks-API-Key header. Start with the list of covered assets, narrowed to a category.

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

Filters combine as AND across parameters and OR within one, so ?category=Networks&tags=Proof-of-Stake is proof-of-stake networks, while ?tags=EVM,Proof-of-Stake is either tag. Note the two things that differ from most list endpoints: page and limit are accepted but not applied, so you always get the full matching set, and the result is unordered, which is why the examples sort before printing.

Read the response

Token Unlocks responses use the same envelope as every Blockworks API: error is null on success and a string on failure, and data carries the payload.

{
  "error": null,
  "data": [
    {
      "id": "b3d5d66c-26a2-404c-9325-91dc714a722b",
      "serialId": 6079,
      "symbol": "SOL",
      "name": "Solana",
      "genesisDate": "2020-04-07T00:00:00Z",
      "projectedEndDate": "2029-03-01T00:00:00Z",
      "slug": "solana",
      "category": "Networks",
      "sector": "Smart Contract Platform",
      "tags": [
        "Proof-of-Stake",
        "SEC Alleged Securities",
        "Stakeable"
      ],
      "otherInfo": "Tokens allocated to inflationary categories (Validator Rewards) are not accounted for in the unlock data below. "
    }
  ]
}

An empty result is "data": null, not [], and it arrives with a 200. Both examples above fall back to an empty list for exactly this reason.

Two fields are worth reading before you trust a schedule. otherInfo is null for most assets, but when it is set it records an analyst caveat about incomplete coverage. projectedEndDate equal to genesisDate means the allocation unlocked at genesis, not that data is missing.

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.

Next steps

Allocations

Totals per recipient, with the analyst description, assumptions, and sources behind each tranche.

Vesting schedule

Daily cumulative unlocked, remaining, and percent complete, in total and per recipient.

Concepts and caveats

Flow against stock, identifier rules, and the coverage caveats worth knowing.

Errors

Status codes and the shared error envelope.

​Next steps

Allocations

Vesting schedule

Concepts and caveats

Errors

Next steps