Upcoming Unlock Events API v1

Getting Started

Base URL

https://api.unlocks.app

Authentication

Provide your api key in the x-api-key header.

GET https://api.unlocks.app/v1/unlock/events/upcoming
HEADER: x-api-key: <YOUR_API_KEY>

Parameters

• minMarketCap (optional): Filter out tokens below a certain market cap

• minReleasedPercentage (optional): Filter out tokens below a certain percentage of released supply from 0-100

• minUnlockDate (optional): The start date for time filtering in the format YYYY-MM-DD. Defaults is the earliest available date.

• maxUnlockDate (optional): The end date for time filtering in the format YYYY-MM-DD. Defaults is the furthest available date.

• minTotalUnlockAmount (optional): Filter out unlocks below a certain amount

• minValueToMarketCap (optional): Filter out unlocks below a certain value market cap from 0-100

• standardAllocation (optional): Filter the receiver's allocation. Choose from these enums, can be multi-select: community, founderTeam, privateInvestors, publicInvestors, reserve, others

Example:

curl -X 'GET' \
  'https://api.unlocks.app/v1/unlock/events/upcoming
  -H 'x-api-key: $YOUR_API_KEY'

Response

{
    "metadata": {
        "queryDate": "2025-11-20T07:22:41Z"
    },
    "status": true,
    "data": [
        {
            "tokenId": "layerzero",
            "tokenName": "LayerZero",
            "tokenSymbol": "ZRO",
            "marketCap": 278811255,
            "releasedPercentage": 35.2833333550565,
            "listedMethod": "INTERNAL",
            "dataSource": "Whitepaper",
            "upcomingEvent": {
                "unlockDate": "2025-11-20T11:00:00Z",
                "referencePrice": 1.4,
                "referencePriceUpdatedTime": "2025-11-20T00:00:00Z",
                "cliffUnlocks": {
                    "totalCliffAmount": 25708332.666,
                    "totalCliffValue": 35991665.7324,
                    "valueToMarketCap": 12.908971602455575,
                    "allocationBreakdown": [
                        {
                            "allocationName": "Tokens Repurchased",
                            "standardAllocationName": "Community",
                            "cliffAmount": 1666666.666,
                            "cliffValue": 2333333.3323999997,
                            "unlockPrecision": "month"
                        },
                        {
                            "allocationName": "Core Contributors",
                            "standardAllocationName": "Founder / Team",
                            "cliffAmount": 10625000,
                            "cliffValue": 14874999.999999998,
                            "unlockPrecision": "month"
                        },
                        {
                            "allocationName": "Strategic Partners",
                            "standardAllocationName": "Private Investors",
                            "cliffAmount": 13416666,
                            "cliffValue": 18783332.4,
                            "unlockPrecision": "month"
                        }
                    ]
                },
                "latestUpdateDate": "2025-06-13T07:30:52Z"
            }
        },
        {
            "tokenId": "kaito",
            "tokenName": "KAITO",
            "tokenSymbol": "KAITO",
            "marketCap": 190707682,
            "releasedPercentage": 28.14428570833332,
            "listedMethod": "INTERNAL",
            "dataSource": "Whitepaper",
            "upcomingEvent": {
                "unlockDate": "2025-11-20T12:00:00Z",
                "referencePrice": 0.778154,
                "referencePriceUpdatedTime": "2025-11-20T00:00:00Z",
                "cliffUnlocks": {
                    "totalCliffAmount": 8347618.191,
                    "totalCliffValue": 6495732.485799414,
                    "valueToMarketCap": 3.4061199935298956,
                    "allocationBreakdown": [
                        {
                            "allocationName": "Ecosystem & Network Growth",
                            "standardAllocationName": "Community",
                            "cliffAmount": 7157142,
                            "cliffValue": 5569358.675868,
                            "unlockPrecision": "month"
                        },
                        {
                            "allocationName": "Foundation",
                            "standardAllocationName": "Reserve",
                            "cliffAmount": 1190476.191,
                            "cliffValue": 926373.8099314141,
                            "unlockPrecision": "month"
                        }
                    ]
                },
                "latestUpdateDate": "2025-02-20T12:00:23Z"
            }
        },
        ...
    ]
}

The response includes time series data with the date (in UTC timezone), with granularity at the level of day.

Return Fields Explanation

Fields	Data Type	Description
tokenId	string	Token ID
tokenName	string	Token Name
tokenSymbol	string	Token Symbol
marketCap	number	Market cap of the token provided by external source (Will be null if no data present)
releasedPercentage	number	Progress of token total released percentage
listedMethod	string	Human/AI
dataSource	string	Data Source of the Token
upcomingEvent	object array
latestUpdateDate	timestamp	Unlocks Data Latest Update time

Return Fields Explanation: Upcoming event

Fields	Data Type	Description
unlockDate	timestamp	Cliff Unlock Date
referencePrice	number	Total Unlock Amount Denominated in token
referencePriceUpdatedTime	number	Total Unlock Value Denominated in USD
cliffUnlocks	object array

Return Fields Explanation: Cliff Unlocks

Fields	Data Type	Description
cliffAmount	number	Total Unlock Amount Denominated in token
cliffValue	number	Total Unlock Value Denominated in USD
valueToMarketCap	number	Value / M.Cap in Percentage
allocationBreakdown	object array

Return Fields Explanation: Cliff Allocation Breakdown

Fields	Data Type	Description
allocationName	string	Allocation Name
standardAllocationName	string	Standard allocation of this allocation
cliffAmount	number	Unlock Amount Denominated in Token
cliffValue	number	Unlock Value Denominated in USD
unlockPrecision	string	Precision of Unlock. Example: second, hour, day, week, unknown(for AI listed token only), etc