# Token Unlock Tracker — Vesting Schedules & Cliff Alerts (`aspiring_barricade/crypto-token-unlock-tracker`) Actor

Upcoming token unlocks & vesting schedules with the numbers that move price: date, cliff vs linear, tokens released, % of circulating supply (dilution), USD value, big-unlock flag and per-beneficiary breakdown (team/investors/ecosystem). Lookahead window, watchlist & new-only alerts.

- **URL**: https://apify.com/aspiring\_barricade/crypto-token-unlock-tracker.md
- **Developed by:** [Joachim Pouchain](https://apify.com/aspiring_barricade) (community)
- **Categories:** Developer tools, Automation, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 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

## Token Unlock Tracker — Vesting Schedules & Cliff Alerts

Track **upcoming token unlocks** and **vesting schedules** with the numbers that actually move price. This **token unlock calendar** returns, for every upcoming **cliff** or **linear** unlock: the date, the amount released, the **% of circulating supply** unlocked (dilution / sell pressure), the USD value, a **big-unlock** flag, and the **per-beneficiary breakdown** (team / investors / ecosystem). Built for trading bots, AI agents and analysts who need a clean **token vesting API** instead of a screenshot of a website.

Most unlock tools give you a calendar. This one gives you **actionable supply-unlock data**: the headline figure is **% of circulating supply**, because a 5% unlock going to early investors is a very different trade than a 0.1% ecosystem drip.

### What it does

- **Upcoming unlocks per token** — date, type (`cliff` / `linear` / `mixed`), tokens released.
- **% of circulating supply unlocked** — the dilution number that matters, using real circulating supply.
- **Big-unlock flag** — flags any unlock above your threshold (default ≥ 1% of circulating supply).
- **USD value** — tokens unlocked × live price.
- **Beneficiaries** — who receives the unlock (investors, insiders, ecosystem, public sale, farming…) — they don't all sell the same way.
- **Lookahead window** — only unlocks in the next *N* days.
- **Watchlist or all** — track specific tokens, or auto-scan every protocol with the biggest upcoming unlocks.
- **New-only alert mode** — return only unlocks not seen in previous runs (dedup), ideal for scheduled alerts.

### What you get per unlock event

| Field | Meaning |
|-------|---------|
| `unlock_date`, `days_until`, `unlock_timestamp` | When the unlock happens |
| `unlock_type` | `cliff`, `linear` or `mixed` |
| `tokens_unlocked` | Number of tokens released |
| `pct_of_circulating_supply` | **Dilution** — % of circulating supply unlocked |
| `pct_of_max_supply` | % of max supply unlocked |
| `usd_value` | USD value at current price |
| `is_big_unlock` | Above your big-unlock threshold? |
| `beneficiaries[]` | Per-recipient amount, category & % of circulating |
| `beneficiary_categories` | Distinct recipient classes (insiders, privateSale, ecosystem…) |
| `circulating_supply`, `max_supply`, `price_usd` | Context for the numbers |

### Why this one

- **% of circulating supply + cliff flags**, not just a date. The differentiator: dilution and sell-pressure, computed for you.
- **Beneficiary breakdown** — distinguishes insider/investor unlocks (high dump risk) from ecosystem/staking emissions.
- **Big-unlock alerts + new-only mode** — turn the calendar into a high-signal alert stream for scheduled runs.
- **Agent- & bot-ready** — one clean JSON row per unlock event, ready for an LLM or a trading strategy.
- **Free, official-grade source** — DefiLlama emissions for the vesting schedules, CoinGecko for real circulating supply and price. No fragile scraping.

### Input

| Field | Type | Description |
|-------|------|-------------|
| `tokens` | array | Optional watchlist as DefiLlama slugs / names / CoinGecko ids (e.g. `aptos`, `arbitrum`, `optimism`). Empty = auto-scan the biggest upcoming unlocks. |
| `window_days` | integer | Only unlocks within the next N days. Default 30. |
| `big_unlock_pct` | number | Flag unlocks ≥ this % of circulating supply. Default 1. |
| `only_big_unlocks` | boolean | Return only flagged big unlocks. Default false. |
| `alert_new_only` | boolean | Only events new since the last run. Default false. |
| `alert_key` | string | Namespace for new-only history. |
| `max_items` | integer | Max events returned/charged. Default 50. |

#### Example input

```json
{
  "tokens": [],
  "window_days": 30,
  "big_unlock_pct": 1,
  "only_big_unlocks": false,
  "alert_new_only": false,
  "max_items": 50
}
```

### Output

One dataset item per unlock event. Real output for an **EIGEN** cliff unlock:

```json
{
  "token": "EigenCloud",
  "symbol": "EIGEN",
  "slug": "eigencloud",
  "gecko_id": "eigenlayer",
  "chain": null,
  "unlock_date": "2026-07-01",
  "unlock_timestamp": 1782933573,
  "days_until": 2,
  "unlock_type": "cliff",
  "tokens_unlocked": 36820227,
  "pct_of_circulating_supply": 4.97,
  "pct_of_max_supply": null,
  "usd_value": 8515893,
  "is_big_unlock": true,
  "circulating_supply": 741228567,
  "circulating_supply_source": "coingecko",
  "max_supply": null,
  "price_usd": 0.231283,
  "beneficiaries": [
    { "recipient": "Investors", "category": "privateSale", "unlock_type": "cliff", "amount": 19749031, "pct_of_circulating_supply": 2.66 },
    { "recipient": "Early Contributors", "category": "insiders", "unlock_type": "cliff", "amount": 17071196, "pct_of_circulating_supply": 2.3 }
  ],
  "beneficiary_categories": ["privateSale", "insiders"],
  "source": "DefiLlama Emissions + CoinGecko",
  "source_url": "https://defillama.com/unlocks/eigencloud",
  "timestamp": "2026-06-29T09:59:29.977Z"
}
```

This single row tells a trader: in 2 days, **EIGEN unlocks ~4.97% of circulating supply (~$8.5M)**, and it goes to **investors and early contributors** — a classic sell-pressure event.

### Use cases

- **Trading bots** — avoid or short tokens ahead of large insider unlocks; gate entries on `pct_of_circulating_supply`.
- **AI research agents** — a single tool call returns structured, ranked unlock events to reason over.
- **Unlock alerts** — schedule with `alert_new_only: true` and `only_big_unlocks: true` for a clean, high-signal feed.
- **Token & fund due diligence** — quantify forward dilution and the insider/investor share of upcoming supply.

### Pricing

Pay-per-result: charged **per unlock event returned** (target **$0.003 per result**, i.e. **$3 / 1,000**), plus Apify platform usage. `max_items` caps your spend; `only_big_unlocks` and `alert_new_only` keep scheduled runs cheap. (Final price is set on the Store listing.)

### Categories

`Developer tools`, `Automation`, `Agents`.

### Data source & method

- **Vesting schedules:** [DefiLlama](https://defillama.com/unlocks) emissions dataset (free, public) — `cliffAllocations` / `linearAllocations` per unlock event.
- **Circulating supply & price:** [CoinGecko](https://www.coingecko.com) public API. When a token isn't on CoinGecko, circulating supply is derived from cumulative past unlocks and flagged via `circulating_supply_source: "derived"`.
- **% of circulating supply** = tokens unlocked ÷ circulating supply. **% of max supply** = tokens unlocked ÷ max supply (`null` when the token has no fixed max supply).

### Notes & limits

- Coverage follows DefiLlama's tracked protocols (hundreds of major tokens with documented vesting). Tokens without a published schedule won't appear.
- In "all" mode the actor scans the protocols with the largest upcoming emissions; use the `tokens` watchlist to force specific tokens regardless of size.
- Informational data, **not financial advice**. Unlock schedules can change if a project amends its tokenomics.

### Use as an MCP tool (AI agents)

This Actor is available as an **MCP tool** for AI agents (Claude, ChatGPT, Cursor, etc.) through Apify’s hosted MCP server. Point your MCP client at:

```
https://mcp.apify.com/?actors=aspiring_barricade/crypto-token-unlock-tracker
```

The Actor’s input schema becomes the tool’s parameters automatically. An Apify API token is required.

### Use in n8n

Run this Actor inside your [n8n](https://n8n.io) workflows using the official **Apify** node (search “Apify” in the n8n nodes panel) and select the Actor `aspiring_barricade/crypto-token-unlock-tracker`. A dedicated community node (`n8n-nodes-token-unlock-tracker`) is also being published to npm for one-click installation via **n8n → Settings → Community Nodes**.

# Actor input Schema

## `tokens` (type: `array`):

Optional list of tokens to track, as DefiLlama protocol slugs / names / CoinGecko ids (e.g. "aptos", "arbitrum", "optimism", "sui"). Leave EMPTY to auto-scan all protocols with the biggest upcoming unlocks.

## `window_days` (type: `integer`):

Only return unlocks happening within the next N days.

## `big_unlock_pct` (type: `number`):

Flag an unlock as a "big unlock" when it releases at least this percentage of the circulating supply (dilution / sell-pressure). Example: 1 = 1%.

## `only_big_unlocks` (type: `boolean`):

If on, return only unlocks flagged as big (>= the threshold above). Great for high-signal alerts.

## `alert_new_only` (type: `boolean`):

Return only unlock events not seen in previous runs (persisted per alert key). Perfect for scheduled monitoring.

## `alert_key` (type: `string`):

Namespace for new-only history so different saved watchlists keep separate state.

## `max_items` (type: `integer`):

Maximum number of unlock events to return (and charge).

## Actor input object example

```json
{
  "tokens": [],
  "window_days": 30,
  "big_unlock_pct": 1,
  "only_big_unlocks": false,
  "alert_new_only": false,
  "alert_key": "default",
  "max_items": 50
}
```

# 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 = {
    "window_days": 30,
    "big_unlock_pct": 1,
    "max_items": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("aspiring_barricade/crypto-token-unlock-tracker").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 = {
    "window_days": 30,
    "big_unlock_pct": 1,
    "max_items": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("aspiring_barricade/crypto-token-unlock-tracker").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 '{
  "window_days": 30,
  "big_unlock_pct": 1,
  "max_items": 50
}' |
apify call aspiring_barricade/crypto-token-unlock-tracker --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/kEJE9PrHmm0oP1Cvp/builds/jP94NpOHxTemQBxq6/openapi.json