# Token Unlocks & Vesting Calendar (Crypto) (`foxlabs/token-unlocks-calendar`) Actor

Calendar of upcoming crypto token unlocks from DefiLlama emissions — ~326 projects. Filter by days ahead, % of max supply, recipient (insiders/investors) and cliff/linear; sort by date or size. Flat CSV/Excel, no API key, no proxy.

- **URL**: https://apify.com/foxlabs/token-unlocks-calendar.md
- **Developed by:** [Berkan Kaplan](https://apify.com/foxlabs) (community)
- **Categories:** Developer tools
- **Stats:** 18 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

<p align="center"><a href="https://apify.com/foxlabs/token-unlocks-calendar"><img src="https://data.foxlabs.com.tr/img/token-unlocks-banner.svg" alt="Token Unlocks &amp; Vesting Calendar" width="100%" /></a></p>

## Crypto Token Unlocks & Vesting Calendar (DefiLlama)

**Which tokens unlock next — and how big is the dump?** Export a clean, schedulable calendar of **upcoming crypto token unlocks** across every project DefiLlama tracks (300+), ranked by date or by size, as flat JSON / CSV / Excel rows.

Token unlocks are one of the most-watched signals in crypto: when a large slice of supply vests to insiders or investors, it often means sell pressure. This Actor turns DefiLlama's **free, no-key emissions data** into a filterable feed so you can see **what's unlocking this week / month**, how much (as **% of max supply**), to **whom** (insiders / investors / community), and **how** (cliff vs linear).

- 📅 **Forward calendar** — every upcoming unlock event, soonest-first, with the exact ISO date and a `daysUntil` countdown
- 📊 **The signal traders watch** — each event as a **% of max supply**, so you can spot the big dilution / sell-pressure moments
- 🎯 **Filter to what matters** — time window, minimum % of supply, recipient category, cliff vs linear, or a project watchlist
- ⚡ **Free source, zero external cost** — built on DefiLlama's public emissions data; **no API key, no proxy** — a full scan runs in seconds

Deterministic and built for recurring feeds — schedule it for a live "what unlocks this week" dataset piped into a sheet, bot or alert.

### Quick start (API)

Get the 100 biggest unlocks in the next 30 days, largest first, in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/foxlabs~token-unlocks-calendar/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "daysAhead": 30, "minPctOfSupply": 0.5, "sortBy": "pctOfSupply", "maxResults": 100 }'
```

Prefer no code? Open the **Input** tab, set your filters, and click **Start** — then download the results as JSON, CSV or Excel.

### What you get

One flat row per upcoming unlock event:

| Field | Type | Description |
|---|---|---|
| `rank` | number | Position in the returned, sorted calendar (`1` = first) |
| `project` | string | Project name (e.g. *Celestia*) |
| `slug` | string | DefiLlama project slug (e.g. `celestia`) — reuse it in the `projects` filter |
| `token` | string | DefiLlama token identifier, often a CoinGecko id (e.g. `coingecko:celestia`); may be empty |
| `chain` | string | Chain label from DefiLlama; empty when not mapped to a single chain |
| `unlockDateIso` | string | Unlock timestamp, ISO 8601 (UTC) |
| `daysUntil` | number | Whole days from run time until the unlock |
| `unlockType` | string | `cliff` (one sudden release) or `linear` (gradual); may be empty |
| `category` | string | Recipient bucket from DefiLlama (e.g. `insiders`, `farming`, `ecosystem`, `publicSale`); may be empty |
| `tokensUnlocked` | number | Number of tokens released in this event |
| `pctOfMaxSupply` | number | null | Tokens as a percentage of max supply; `null` when DefiLlama has no max supply |
| `description` | string | Human-readable DefiLlama note (e.g. *"On 2026-07-05 531,250 of Team & Advisors tokens will be unlocked"*) |
| `source` | string | Always `DefiLlama` |
| `generatedAtIso` | string | When the row was produced, ISO 8601 (UTC) |

#### Sample output

```json
{
  "rank": 2,
  "project": "Stader",
  "slug": "stader",
  "token": "coingecko:stader",
  "chain": "",
  "unlockDateIso": "2026-07-05T12:45:21.000Z",
  "daysUntil": 0,
  "unlockType": "cliff",
  "category": "insiders",
  "tokensUnlocked": 531250,
  "pctOfMaxSupply": 0.443,
  "description": "On 2026-07-05 531,250 of Team & Advisors tokens will be unlocked",
  "source": "DefiLlama",
  "generatedAtIso": "2026-07-05T09:00:00.000Z"
}
```

*Illustrative — a real DefiLlama record pulled during testing. `rank`, `unlockDateIso` and `daysUntil` shift on every run as the calendar rolls forward. `chain` is `""` here because DefiLlama doesn't map this token to a single chain — that's the register, not a miss.*

### Input & filters

- **Days ahead** (`daysAhead`) — include unlocks within this many days from now. `7` = this week, `30` = this month, `90` = this quarter. Range `1`–`3650`, default `90`.
- **Min % of max supply** (`minPctOfSupply`) — keep only unlocks worth at least this % of max supply (the metric that signals real sell pressure). `0` = no filter.
- **Recipient category** (`category`) — keep one DefiLlama recipient bucket, e.g. `insiders`, `farming`, `publicSale`, `privateSale`, `ecosystem`, `noncirculating`. Empty = all.
- **Unlock type** (`unlockType`) — `cliff` (one big release), `linear` (gradual), or both.
- **Projects** (`projects`) — a watchlist of DefiLlama slugs (e.g. `aptos`, `arbitrum`, `celestia`). Empty = scan every tracked project.
- **Sort by** (`sortBy`) — `date` (soonest first, calendar order) or `pctOfSupply` (biggest unlock first).
- **Max results** (`maxResults`) — cap the number of rows, up to `100000`.

### Example inputs (copy & paste)

```jsonc
// 1) Big unlocks this month, biggest first
{ "daysAhead": 30, "minPctOfSupply": 0.5, "sortBy": "pctOfSupply", "maxResults": 500 }

// 2) Insider cliff unlocks this quarter (sudden insider releases)
{ "daysAhead": 90, "category": "insiders", "unlockType": "cliff", "sortBy": "pctOfSupply" }

// 3) Watchlist calendar for specific tokens, next 12 months
{ "projects": ["aptos", "arbitrum", "celestia"], "daysAhead": 365, "sortBy": "date" }

// 4) This week's unlocks, soonest first (newsletter feed)
{ "daysAhead": 7, "sortBy": "date", "maxResults": 500 }

// 5) Gradual (linear) emissions unlocking this quarter
{ "daysAhead": 90, "unlockType": "linear", "sortBy": "date" }

// 6) Private-sale unlocks over the next six months, biggest first
{ "daysAhead": 180, "category": "privateSale", "sortBy": "pctOfSupply" }

// 7) Market-wide major dilution next year (>= 1% of supply)
{ "daysAhead": 365, "minPctOfSupply": 1, "sortBy": "pctOfSupply", "maxResults": 1000 }

// 8) Public-sale unlocks this month, soonest first
{ "daysAhead": 30, "category": "publicSale", "sortBy": "date" }
```

### Use cases

- **Trade & risk timing.** Anticipate sell pressure: filter `daysAhead: 30` + `minPctOfSupply: 0.5` + `sortBy: pctOfSupply` to see the biggest upcoming dilution events and de-risk or hedge before the cliff.
- **Research & newsletters.** Publishing a "token unlocks this week" segment? Schedule the Actor weekly with `daysAhead: 7` for a ready-made, date-ordered list of what's unlocking, to whom, and how much.
- **Portfolio & watchlist alerts.** Pass your holdings as `projects`, schedule daily, and wire a webhook into Slack / Telegram / a Sheet so you're pinged before your bags unlock.
- **Market-data dashboards.** Feed a live "upcoming unlocks" table into a BI dashboard or Google Sheet — flat rows with date, `% of supply`, tokens and recipient, no parsing required.
- **Screening & dilution ranking.** Sort every tracked project by `pctOfSupply` to surface the largest upcoming supply increases across the market in one pass.
- **Data pipelines & backtesting.** Snapshot the forward unlock calendar on a schedule to build a historical record of expected emissions for research or modelling.

### Performance & throughput

Each run fetches DefiLlama's project list, then pulls every project's vesting schedule in parallel (concurrency 8) and filters **locally in memory** — so tighter filters cost no extra time. There's **no proxy, no API key and no rate limit** to work around.

In a live test, a **full scan of all 339 tracked projects completed in ~5 seconds** (network-bound, zero fetch failures). Narrowing to a `projects` watchlist is faster still.

Large time windows produce a lot of rows — a 365-day window over just 10 projects already yields ~600 events, most of them small linear drips. Use **`minPctOfSupply`** to keep the calendar focused on the unlocks that actually move markets. Throughput is otherwise bounded only by your Apify plan.

### Integrations

**JavaScript** (`apify-client`):

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });
const run = await client.actor('foxlabs/token-unlocks-calendar').call({
  daysAhead: 30, minPctOfSupply: 0.5, sortBy: 'pctOfSupply', maxResults: 500,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

**Python** (`apify-client`):

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("foxlabs/token-unlocks-calendar").call(run_input={
    "daysAhead": 30, "minPctOfSupply": 0.5, "sortBy": "pctOfSupply", "maxResults": 500,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["project"], item["unlockDateIso"], item["pctOfMaxSupply"])
```

Also works with **Make / n8n / Zapier** (Apify app → run this Actor, map the input), scheduled runs, webhooks, and the **Apify MCP server** so AI agents can pull the unlock calendar on demand.

### Data quality

Every value comes **straight from DefiLlama** and is passed through as-is — nothing is fabricated. Missing values are returned as `""` or `null`, never guessed.

| Field | Availability |
|---|---|
| `rank`, `project`, `slug`, `unlockDateIso`, `daysUntil`, `tokensUnlocked`, `source`, `generatedAtIso` | Always present |
| `pctOfMaxSupply` | Present when DefiLlama has the token's max supply; otherwise `null` |
| `token`, `chain`, `unlockType`, `category`, `description` | Present when DefiLlama provides it; otherwise `""` |

Only **upcoming** events are returned (anything already past is excluded), and every returned event has `tokensUnlocked > 0`. In a live full scan during testing, all tracked projects (339 on the test date) returned successfully with zero fetch failures.

### Pricing

See the **Pricing** tab on this Actor's page for the current rate. There's an Apify **free tier** to evaluate the full feature set before you scale, and because the data source is free with **no API key and no proxy**, there are no third-party costs passed on to you.

### FAQ

**Where does the data come from?** DefiLlama's public **emissions datasets** — the same open data that powers its unlocks page for anonymous browsers. No key, no login.

**How fresh is it?** Every run pulls DefiLlama's current data live, so each dataset reflects the latest schedules at run time. Schedule the Actor to keep a rolling, up-to-date calendar.

**What does `pctOfMaxSupply` mean, and why does it matter?** It's the size of the unlock as a percentage of the token's max supply. A large % entering circulation is the classic dilution / sell-pressure signal traders watch — that's why you can filter and sort by it.

**What's the difference between `cliff` and `linear`?** A `cliff` releases a chunk all at once (the sharpest price events); `linear` vests gradually over time. Filter with `unlockType`.

**Can I watch specific tokens only?** Yes — list their DefiLlama slugs in `projects` (e.g. `["aptos", "arbitrum", "celestia"]`). Leave it empty to scan everything.

**Why is `token` sometimes `coingecko:...` and not a ticker?** DefiLlama identifies tokens by their CoinGecko id; the Actor returns that identifier as-is rather than guessing a ticker symbol.

**Why is `chain` or `category` sometimes empty?** DefiLlama doesn't label every project with a single chain or every event with a recipient category. The Actor returns `""` rather than inventing one.

**Can I get past unlocks?** No — the calendar is forward-looking by design (upcoming events only). Widen `daysAhead` (up to 10 years) to see further ahead.

**What export formats are available?** JSON, CSV, Excel, or via the Apify API / integrations.

**Is there a rate limit?** No external key or limit — throughput is bounded only by your Apify plan.

### Troubleshooting

- **0 results** → your filters are too narrow. Increase `daysAhead`, lower `minPctOfSupply`, or clear `category` / `unlockType`.
- **A token I expect is missing** → DefiLlama may not track its emissions, its next unlock may be beyond your `daysAhead` window, or it may already be fully unlocked.
- **`pctOfMaxSupply` is `null`** → DefiLlama has no max-supply figure for that token. The event is still included (with `tokensUnlocked`); only the percentage is unknown.
- **Too many tiny rows** → most are small `linear` drips. Raise `minPctOfSupply` (e.g. `0.5`) and/or set `unlockType: cliff` to keep only the notable events.

### Notes, limits & legal (honest)

- **Source & attribution.** Data comes from **DefiLlama's public emissions datasets**; each row is labelled `source: "DefiLlama"`. This Actor is a convenience wrapper that filters and flattens that data.
- **Not affiliated** with DefiLlama. This Actor is independent and simply reads DefiLlama's public data.
- **Not financial advice.** Unlock schedules are informational only, provided for research and analytics. Nothing here is trading, investment or financial advice — do your own research.
- **Estimates can change.** Vesting schedules and timestamps are DefiLlama's best available data and can be revised by projects; treat future dates as projections, not guarantees.
- **Pass-through accuracy.** Values are only as accurate as DefiLlama's source data; the Actor never fabricates missing fields (they return `""` or `null`).

### Support

Questions, a field you'd like added, or a custom build? Open the **Issues** tab on this Actor, or email **info@foxlabs.com.tr**. We reply fast.

*If this Actor saves you time, a ⭐ review really helps.*

### Changelog

#### 0.2 — 2026-07-05

- Gold-standard docs overhaul: API quick-start, full field table + real sample, input/filter guide, example recipes, use cases, integrations (JS / Python / Make / MCP), measured throughput, data-quality notes, FAQ, troubleshooting, and legal/attribution notes.

#### 0.1.1 — 2026-07-05

- Hardened output handling so an edge-case value can never trip dataset-schema validation.

#### 0.1.0 — 2026-06-04

- Initial release: upcoming token-unlock calendar across the DefiLlama emissions data — filter by days-ahead, % of max supply, recipient category and cliff/linear; sort by date or size; flat CSV/Excel rows, no API key or proxy.

***

Part of the **[foXLabs data platform](https://data.foxlabs.com.tr/)** — public-data scrapers for company, contact, procurement, financial and AI-search intelligence. Browse the full suite and free how-to guides at **[data.foxlabs.com.tr](https://data.foxlabs.com.tr/)**.

# Actor input Schema

## `daysAhead` (type: `integer`):

Include unlock events happening within this many days from now. E.g. 7 = this week, 30 = this month, 90 = this quarter.

## `minPctOfSupply` (type: `number`):

Only include unlocks worth at least this percentage of the token's max supply (the metric traders watch — big % = potential sell pressure). 0 = no filter.

## `category` (type: `string`):

Keep only unlocks to this recipient group, e.g. "insiders", "privateSale", "publicSale", "noncirculating". Leave empty for all.

## `unlockType` (type: `string`):

Filter by unlock mechanics: "cliff" (one big release) or "linear" (gradual). Leave empty for both.

## `projects` (type: `array`):

Limit to specific project slugs (e.g. "aptos", "arbitrum", "celestia"). Leave empty to scan all ~326 projects.

## `sortBy` (type: `string`):

Order the calendar by soonest date, or by biggest unlock (% of supply).

## `maxResults` (type: `integer`):

Cap the number of unlock-event rows returned.

## Actor input object example

```json
{
  "daysAhead": 90,
  "minPctOfSupply": 0.5,
  "category": "",
  "unlockType": "",
  "projects": [],
  "sortBy": "date",
  "maxResults": 1000
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "daysAhead": 90,
    "minPctOfSupply": 0.5,
    "sortBy": "date",
    "maxResults": 1000
};

// Run the Actor and wait for it to finish
const run = await client.actor("foxlabs/token-unlocks-calendar").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "daysAhead": 90,
    "minPctOfSupply": 0.5,
    "sortBy": "date",
    "maxResults": 1000,
}

# Run the Actor and wait for it to finish
run = client.actor("foxlabs/token-unlocks-calendar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "daysAhead": 90,
  "minPctOfSupply": 0.5,
  "sortBy": "date",
  "maxResults": 1000
}' |
apify call foxlabs/token-unlocks-calendar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=foxlabs/token-unlocks-calendar",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/0tzgJSF5pNcl5RmWv/builds/dpAkXocYhziYhfTxO/openapi.json