# Token Unlock Calendar — Vesting Cliff Tracker (Crypto) (`gochujang/token-unlock-calendar`) Actor

Track upcoming token vesting cliffs and unlock events across major crypto projects. Unlock date, USD value, % of circulating supply unlocked. Based on Tokenomist.ai. Avoid the dump, time entries around unlock events. PPE $0.005/unlock.

- **URL**: https://apify.com/gochujang/token-unlock-calendar.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** Developer tools, Automation, News
- **Stats:** 6 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$5.00 / 1,000 unlock trackeds

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 Calendar

> Track upcoming **token unlocks** across hundreds of crypto projects. Filter by USD value, % of circulating supply, time window, or symbol. Spot supply-overhang risks before VCs dump.

### ⚡ Run in 30 seconds

Click **Start** with default settings — returns upcoming token unlocks for the next 30 days, sorted by USD unlock value. Each row includes project, unlock date, USD value, % of circulating supply, and vesting category. No API key required.

***

### What It Does

Pulls the upcoming token unlock schedule from CryptoRank's public data and returns it as a clean dataset. Use it to:

- See when major VC/team/treasury allocations unlock in the next N days
- Filter to only "large" unlocks (e.g., >$10M or >1% of circulating supply)
- Time entries around post-unlock dips (or short rallies into unlocks)
- Build automated supply-overhang alerts before the market notices

***

### Why Unlocks Matter

When locked tokens (allocated to early investors, team, or treasury) hit the open market, they often trigger sell pressure. Large unlocks — especially those that meaningfully inflate circulating supply — have historically caused 10–30% drawdowns in the days surrounding the event.

This actor gives you the **calendar + sizing data** to know what's coming before retail does.

***

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `daysAhead` | integer | `30` | Only return unlocks within this many days |
| `minUnlockValueUsd` | integer | `1000000` | Min USD value of the unlock |
| `minPercentOfCircSupply` | number | `0.5` | Min % of current circulating supply being unlocked |
| `symbols` | string\[] | `[]` | If non-empty, only return these symbols (e.g. `APT`, `ARB`) |
| `sortBy` | string | `date_asc` | `date_asc`, `value_desc`, `percent_desc` |
| `limit` | integer | `100` | Max results (1–500) |
| `alertValueUsd` | integer | `0` | Send Telegram alert when any unlock exceeds this USD. 0 = disabled |
| `telegramBotToken` | string (secret) | — | Telegram bot token for alerts |
| `telegramChatId` | string | — | Chat ID to receive alerts |

#### Example: Major unlocks in the next 14 days

```json
{
  "daysAhead": 14,
  "minUnlockValueUsd": 5000000,
  "minPercentOfCircSupply": 1.0,
  "sortBy": "value_desc"
}
```

#### Example: Daily Telegram alert on any $10M+ unlock

```json
{
  "daysAhead": 7,
  "alertValueUsd": 10000000,
  "telegramBotToken": "<token>",
  "telegramChatId": "<chat_id>"
}
```

***

### Output

Each record represents one upcoming unlock event:

```json
{
  "symbol": "APT",
  "name": "Aptos",
  "slug": "aptos",
  "unlock_date": "2026-06-12T00:00:00+00:00",
  "days_until_unlock": 10.0,
  "price_usd": 8.42,
  "market_cap_usd": 5800000000,
  "price_change_24h_pct": -2.10,
  "circulating_supply": 819910797,
  "tokens_unlocking": 11304870,
  "unlock_value_usd": 95187006,
  "unlock_percent_of_circ_supply": 1.38,
  "locked_tokens": 383679399,
  "locked_tokens_percent": 31.88,
  "primary_allocation": "Community",
  "allocations": [
    {"name": "Community", "tokens": 7570860, "value_usd": 63746640},
    {"name": "Core Contributors", "tokens": 1867020, "value_usd": 15720508},
    {"name": "Foundation", "tokens": 1866990, "value_usd": 15720256}
  ],
  "top_investors": ["Andreessen Horowitz", "Multicoin Capital", "Jump Crypto"],
  "cryptorank_url": "https://cryptorank.io/price/aptos/vesting",
  "fetched_at": "2026-06-02T12:15:00+00:00"
}
```

| Field | Description |
|-------|-------------|
| `unlock_value_usd` | Tokens unlocked × current spot price |
| `unlock_percent_of_circ_supply` | How much current circulating supply increases on this date |
| `primary_allocation` | Largest single allocation type unlocking (Team / Investors / Treasury / Community / etc) |
| `locked_tokens_percent` | % of max supply still locked after this unlock |

***

### Pricing

Pay-Per-Event (PPE):

- **$0.005 per unlock event returned**

Examples:

- Top 50 unlocks next 30 days: **$0.25**
- Full 300-unlock sweep: **$1.50**

***

### Use Cases

**Pre-unlock short scout** — Find tokens with major dilution in the next 7 days:

```bash
curl -X POST "https://api.apify.com/v2/acts/gochujang~token-unlock-calendar/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"daysAhead": 7, "minPercentOfCircSupply": 2, "sortBy": "percent_desc"}'
```

**Auto-alert on whale unlocks** — Get pinged when any unlock exceeds $20M:

```json
{
  "daysAhead": 30,
  "alertValueUsd": 20000000,
  "telegramBotToken": "<token>",
  "telegramChatId": "<chat>"
}
```

***

### Data Source

All unlock data comes from [CryptoRank](https://cryptorank.io/) — the most comprehensive vesting-schedule source for crypto. Each scrape returns ~400 upcoming unlock events across the broader market.

***

### Related Actors

Build a complete crypto edge with these actors from the same author:

- **[Airdrop & Quest Tracker (Galxe)](https://apify.com/gochujang/airdrop-quest-tracker)** — Spot the next farming campaigns; those tokens later show up here.
- **[Smart Money Wallet Tracker](https://apify.com/gochujang/smart-money-tracker)** — Track 238 smart wallets to see early VC moves before unlocks.
- **[Hyperliquid Whale Tracker](https://apify.com/gochujang/hyperliquid-whale-tracker)** — Whale perp positions around unlock events.
- **[CEX Funding Rate Aggregator](https://apify.com/gochujang/cex-funding-aggregator)** — Over-leveraged positioning context before unlock dumps.

***

***

### 🎬 Live Sample Run

A real run of this actor with default-ish inputs, executed on 2026-06-10:

| Field | Value |
|---|---|
| Items in dataset | 30 |
| Dataset (JSON) | `https://api.apify.com/v2/datasets/xm926RWjt9PVfn7gF/items?clean=1&format=json` |
| Dataset (CSV) | `https://api.apify.com/v2/datasets/xm926RWjt9PVfn7gF/items?clean=1&format=csv` |
| Run summary (KVS) | `https://api.apify.com/v2/key-value-stores/IY7FmBL36MNW57aGj/records/SUMMARY` |
| Run details | `https://api.apify.com/v2/actor-runs/Jse2STAVBA7l8gYcg` |

**Try it now**: pop any of the dataset URLs in your browser to see live output, or hit the API endpoints from your code.

> Want to reproduce? Click **Try Actor** on the Apify Store page and use the input defaults shown above.

### Feedback

If this Actor saves you time, a quick review helps others find it: [Leave a review on Apify Store](https://apify.com/gochujang/token-unlock-calendar#reviews)

# Actor input Schema

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

Only return unlocks scheduled within this many days from now.

## `minUnlockValueUsd` (type: `integer`):

Only return unlocks where the unlocked tokens are worth at least this much. 0 = no filter.

## `minPercentOfCircSupply` (type: `number`):

Only return unlocks releasing at least this % of current circulating supply. 0 = no filter.

## `symbols` (type: `array`):

If non-empty, only return unlocks for these symbols (e.g. APT, ARB, SUI).

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

Sort order for results.

## `limit` (type: `integer`):

Maximum unlocks to return.

## `alertValueUsd` (type: `integer`):

Send Telegram alert when an upcoming unlock exceeds this USD value. 0 = disabled. Requires telegramBotToken + telegramChatId.

## `telegramBotToken` (type: `string`):

Telegram bot token for unlock alerts. Leave empty to disable.

## `telegramChatId` (type: `string`):

Chat ID (user or group) to receive unlock alerts.

## Actor input object example

```json
{
  "daysAhead": 30,
  "minUnlockValueUsd": 1000000,
  "minPercentOfCircSupply": 0.5,
  "symbols": [],
  "sortBy": "date_asc",
  "limit": 100,
  "alertValueUsd": 0,
  "telegramChatId": ""
}
```

# Actor output Schema

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

No description

## `summary` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/token-unlock-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("gochujang/token-unlock-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 '{}' |
apify call gochujang/token-unlock-calendar --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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