# Upcoming Unlock Events API v1

## Getting Started

#### **Base URL** <a href="#base-url" id="base-url"></a>

```
https://api.unlocks.app
```

#### **Authentication** <a href="#authentication" id="authentication"></a>

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'
```

<figure><img src="https://695257229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAiV8rQPRMYfCyYrQgX5Q%2Fuploads%2FlgFHu12dmJY6tguPtWAL%2FScreenshot%202568-11-20%20at%2014.23.32.png?alt=media&#x26;token=e32336d1-2064-45d2-96bc-7648fe39c980" alt=""><figcaption></figcaption></figure>

**Response**

<pre class="language-json"><code class="lang-json">{
    "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": [
                        {
<strong>                            "allocationName": "Tokens Repurchased",
</strong>                            "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 &#x26; 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"
            }
        },
        ...
    ]
}
</code></pre>

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**

<table><thead><tr><th width="249">Fields</th><th>Data Type</th><th>Description</th></tr></thead><tbody><tr><td>unlockDate</td><td>timestamp</td><td>Cliff Unlock Date</td></tr><tr><td>referencePrice</td><td>number</td><td>Total Unlock Amount Denominated in token</td></tr><tr><td>referencePriceUpdatedTime</td><td>number</td><td>Total Unlock Value Denominated in USD</td></tr><tr><td>cliffUnlocks</td><td>object array</td><td></td></tr></tbody></table>

**Return Fields Explanation:&#x20;**<mark style="background-color:red;">**Cliff Unlocks**</mark>

<table><thead><tr><th width="249">Fields</th><th>Data Type</th><th>Description</th></tr></thead><tbody><tr><td>cliffAmount</td><td>number</td><td>Total Unlock Amount Denominated in token</td></tr><tr><td>cliffValue</td><td>number</td><td>Total Unlock Value Denominated in USD</td></tr><tr><td>valueToMarketCap</td><td>number</td><td>Value / M.Cap in Percentage</td></tr><tr><td>allocationBreakdown</td><td>object array</td><td></td></tr></tbody></table>

**Return Fields Explanation:&#x20;**<mark style="background-color:red;">**Cliff Allocation Breakdown**</mark>

<table><thead><tr><th width="249">Fields</th><th>Data Type</th><th>Description</th></tr></thead><tbody><tr><td>allocationName</td><td>string</td><td>Allocation Name</td></tr><tr><td>standardAllocationName</td><td>string</td><td>Standard allocation of this allocation</td></tr><tr><td>cliffAmount</td><td>number</td><td>Unlock Amount Denominated in Token</td></tr><tr><td>cliffValue</td><td>number</td><td>Unlock Value Denominated in USD</td></tr><tr><td>unlockPrecision</td><td>string</td><td>Precision of Unlock. Example: second, hour, day, week, unknown(for AI listed token only), etc</td></tr></tbody></table>