# Token Unlock Calendar Vesting Cliff Tracker (`automation-lab/token-unlock-calendar`) Actor

Track Tokenomist token unlock calendar rows, vesting countdowns, release progress, supply metrics, market cap, FDV, and token prices.

- **URL**: https://apify.com/automation-lab/token-unlock-calendar.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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 Vesting Cliff Tracker

Track public Tokenomist token unlock calendar rows, vesting countdowns, release progress, supply metrics, market cap, FDV, and token prices.

Use this Actor when you need a lightweight token unlock monitor for crypto research, fund risk checks, market watchlists, or recurring dilution alerts.

### What does Token Unlock Calendar Vesting Cliff Tracker do?

This Actor extracts public web data from Tokenomist pages.

It collects upcoming token unlock rows from the public overview page.

It can also enrich tokens from public token detail pages.

The output is designed for analysts who want a repeatable export rather than manual browser checks.

Typical rows include token identity, unlock value text, countdown text, released percentage, price, market cap, FDV, and supply metrics.

### Who is it for?

Crypto funds use it to monitor near-term unlock risk.

Traders use it to screen upcoming vesting cliffs before entering positions.

Risk analysts use it to combine unlock value with FDV and circulating supply.

Data teams use it to feed watchlists, dashboards, and alerts.

Researchers use it to build recurring snapshots of tokenomics changes.

### Why use this token unlock scraper?

Manual token unlock research is slow and easy to miss.

Unlock events can create dilution pressure.

Supply progress and FDV context help estimate the scale of a release.

This Actor turns public Tokenomist pages into structured dataset rows.

You can run it daily, weekly, or before portfolio reviews.

### Data extracted

| Field | Description |
| --- | --- |
| `recordType` | `upcoming_unlock` or `token_metric` |
| `tokenName` | Public token name |
| `symbol` | Token symbol |
| `tokenSlug` | Tokenomist slug |
| `sourceUrl` | Tokenomist source page |
| `unlockDateEstimate` | Estimated unlock timestamp derived from countdown text |
| `timeLeftText` | Public countdown text |
| `unlockValueUsdText` | Public unlock value text |
| `unlockSupplyPercentText` | Public unlock percent of supply when available |
| `releasedPercentageText` | Token release progress |
| `tokenPriceUsd` | Token price from public detail page |
| `reportedMarketCapText` | Reported market cap text |
| `fullyDilutedValueText` | FDV text |
| `reportedCirculatingSupplyText` | Circulating supply text |
| `adjustedReleasedSupplyText` | Released supply text |
| `maxSupplyText` | Max supply text |
| `supplyY2035Text` | Projected supply Y2035 text |
| `scrapedAt` | Extraction timestamp |

### How much does it cost to track token unlock calendar data?

This Actor uses pay-per-event pricing.

There is a small run start charge.

Each saved dataset row is charged as an item.

The final live prices are visible on the Apify Store page before you run the Actor.

Use low `maxItems` values for quick tests.

Use higher `maxItems` values for portfolio or market-wide monitoring.

### Input options

`mode` controls the extraction mode.

Choose `upcoming_unlocks` for the public unlock table.

Choose `token_metrics` for token profile metrics.

Choose `both` to combine the two workflows.

`maxItems` caps the total number of rows saved.

`tokenSlugs` lets you focus on tokens such as `sui`, `solana`, and `hyperliquid`.

`includeTokenMetrics` controls whether token detail pages are fetched.

### Output example

```json
{
  "recordType": "upcoming_unlock",
  "tokenName": "AERO",
  "symbol": "AERO",
  "tokenSlug": "aerodrome-finance",
  "sourceUrl": "https://tokenomist.ai/aerodrome-finance",
  "timeLeftText": "0D 18H 23M 28S",
  "unlockValueUsdText": "$2.93M",
  "releasedPercentageText": "62.13%",
  "scrapedAt": "2026-07-01T05:36:31.793Z"
}
````

### How to run

Open the Actor input tab.

Select the extraction mode.

Set `maxItems`.

Optionally add Tokenomist slugs.

Run the Actor.

Download the dataset as JSON, CSV, Excel, or via API.

### Tips for best results

Start with `maxItems` set to 25.

Use `tokenSlugs` for focused monitoring.

Use `both` when you need unlock rows and market context together.

Run on a schedule for a daily unlock watchlist.

Join rows by `tokenSlug` in your warehouse.

### Integrations

Send the dataset to Google Sheets for analyst review.

Load CSV exports into BI dashboards.

Use webhooks to notify Slack when a run finishes.

Use Apify API clients to pull the dataset into Python or Node.js.

Schedule daily runs to create a token unlock history.

### API usage with Node.js

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/token-unlock-calendar').call({
  mode: 'both',
  maxItems: 50,
  tokenSlugs: ['sui', 'solana', 'hyperliquid']
});
console.log(run.defaultDatasetId);
```

### API usage with Python

```python
from apify_client import ApifyClient

client = ApifyClient('MY-APIFY-TOKEN')
run = client.actor('automation-lab/token-unlock-calendar').call(run_input={
    'mode': 'both',
    'maxItems': 50,
    'tokenSlugs': ['sui', 'solana', 'hyperliquid'],
})
print(run['defaultDatasetId'])
```

### API usage with cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/automation-lab~token-unlock-calendar/runs?token=MY-APIFY-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"both","maxItems":50,"tokenSlugs":["sui","solana"]}'
```

### MCP usage

Use this Actor through Apify MCP in Claude Desktop or Claude Code.

MCP URL:

```text
https://mcp.apify.com/?tools=automation-lab/token-unlock-calendar
```

Claude Code setup:

```bash
claude mcp add apify-token-unlocks https://mcp.apify.com/?tools=automation-lab/token-unlock-calendar
```

Claude Desktop JSON config:

```json
{
  "mcpServers": {
    "apify-token-unlocks": {
      "url": "https://mcp.apify.com/?tools=automation-lab/token-unlock-calendar"
    }
  }
}
```

Example prompts:

- "Run the token unlock calendar scraper for SUI, SOL, and HYPE."
- "Get the next public unlock rows and summarize large unlock values."
- "Export token release progress metrics for my crypto watchlist."

### Scheduling workflows

Create a daily Apify schedule.

Set `mode` to `both`.

Set a stable token slug watchlist.

Send the dataset to your alerting workflow.

Compare each run with the previous run to detect changed countdowns or values.

### Accuracy notes

The Actor uses public Tokenomist web pages.

Some fields are public display text rather than raw numeric API fields.

`unlockDateEstimate` is derived from countdown text when exact timestamps are not exposed.

Enterprise/API-only fields are intentionally excluded.

Rows with missing public values are skipped or returned with `null` fields.

### Legality

This Actor extracts publicly available web data.

Respect Tokenomist terms and applicable laws.

Do not use the output as financial advice.

Verify critical investment decisions with primary project disclosures.

### Troubleshooting

If you get fewer rows than expected, increase `maxItems`.

If a token is missing, pass its exact Tokenomist slug in `tokenSlugs`.

If a field is `null`, the public page did not expose that value at extraction time.

If a run is too broad, use a focused token slug list.

### Related scrapers

Explore more Automation Lab actors at https://apify.com/automation-lab/.

Relevant portfolio categories include finance, crypto, market intelligence, and monitoring actors.

### Changelog

Initial version extracts Tokenomist upcoming unlock rows and token detail metrics.

### Support

If you need a field that is visible on public Tokenomist pages but missing from the dataset, open an Apify issue with an example source URL.

### FAQ

#### Does this use the Tokenomist enterprise API?

No. It uses public web pages only.

#### Can I monitor only my portfolio?

Yes. Pass your Tokenomist slugs in `tokenSlugs`.

#### Can I run it every day?

Yes. Use an Apify schedule.

#### Is this financial advice?

No. It is a data extraction tool for public tokenomics information.

# Actor input Schema

## `mode` (type: `string`):

Choose upcoming unlock rows, token metric pages, or both.

## `maxItems` (type: `integer`):

Maximum dataset rows to save. Keep this low for first tests; increase for portfolio-wide token monitoring.

## `tokenSlugs` (type: `array`):

Optional Tokenomist token slugs to enrich, such as sui, solana, hyperliquid. Leave empty to use public sitemap token pages.

## `includeTokenMetrics` (type: `boolean`):

When enabled, fetch token detail pages for price, supply, market cap, FDV, and release progress fields.

## Actor input object example

```json
{
  "mode": "both",
  "maxItems": 20,
  "tokenSlugs": [
    "sui",
    "solana",
    "hyperliquid"
  ],
  "includeTokenMetrics": true
}
```

# Actor output Schema

## `overview` (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 = {
    "mode": "both",
    "maxItems": 20,
    "tokenSlugs": [
        "sui",
        "solana",
        "hyperliquid"
    ],
    "includeTokenMetrics": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/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 = {
    "mode": "both",
    "maxItems": 20,
    "tokenSlugs": [
        "sui",
        "solana",
        "hyperliquid",
    ],
    "includeTokenMetrics": True,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/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 '{
  "mode": "both",
  "maxItems": 20,
  "tokenSlugs": [
    "sui",
    "solana",
    "hyperliquid"
  ],
  "includeTokenMetrics": true
}' |
apify call automation-lab/token-unlock-calendar --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Token Unlock Calendar Vesting Cliff Tracker",
        "description": "Track Tokenomist token unlock calendar rows, vesting countdowns, release progress, supply metrics, market cap, FDV, and token prices.",
        "version": "0.1",
        "x-build-id": "vjkKipzGy5Elr4b3Z"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/automation-lab~token-unlock-calendar/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-automation-lab-token-unlock-calendar",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/automation-lab~token-unlock-calendar/runs": {
            "post": {
                "operationId": "runs-sync-automation-lab-token-unlock-calendar",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/automation-lab~token-unlock-calendar/run-sync": {
            "post": {
                "operationId": "run-sync-automation-lab-token-unlock-calendar",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "mode": {
                        "title": "📅 Extraction mode",
                        "enum": [
                            "upcoming_unlocks",
                            "token_metrics",
                            "both"
                        ],
                        "type": "string",
                        "description": "Choose upcoming unlock rows, token metric pages, or both.",
                        "default": "both"
                    },
                    "maxItems": {
                        "title": "Maximum records",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum dataset rows to save. Keep this low for first tests; increase for portfolio-wide token monitoring.",
                        "default": 20
                    },
                    "tokenSlugs": {
                        "title": "Token slugs",
                        "type": "array",
                        "description": "Optional Tokenomist token slugs to enrich, such as sui, solana, hyperliquid. Leave empty to use public sitemap token pages.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "includeTokenMetrics": {
                        "title": "Include token metric pages",
                        "type": "boolean",
                        "description": "When enabled, fetch token detail pages for price, supply, market cap, FDV, and release progress fields.",
                        "default": true
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```