# Unlock Events API v2

⬆️ v2 update: Remove Linear change rate events -> reflect to updated frontend

## 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/v2/unlock/events
HEADER: x-api-key: <YOUR_API_KEY>
```

**Parameters**

Note: `tokenID` needs to be specified.

* tokenId (required): Get `tokenId` from [Token List API](https://docs.unlocks.app/api-documents/api-endpoints/token-list-api)
* start (optional): The start date for time filtering in the format YYYY-MM-DD. Defaults to the earliest available date.
* end (optional):   The end date for time filtering in the format YYYY-MM-DD. Defaults is the furthest available date.

**Example:**

```
curl -X 'GET' \
  'https://api.unlocks.app/v2/unlock/events?tokenId=arbitrum' \
  -H 'x-api-key: $YOUR_API_KEY'
```

**Response**

```json
{
    "metadata": {
        "queryDate": "2024-08-20T08:19:20Z"
    },
    "status": true,
    "data": [
        {
            "unlockDate": "2024-09-16T13:00:00Z",
            "tokenName": "Arbitrum",
            "tokenSymbol": "ARB",
            "listedMethod": "INTERNAL",
            "dataSource": "Whitepaper",
            "linearUnlocks": null,
            "cliffUnlocks": {
                "cliffAmount": 92645833.29999995,
                "cliffValue": 49929711.58620228,
                "referencePrice": 0.538931,
                "referencePriceUpdatedTime": "2024-08-19T07:30:24Z",
                "valueToMarketCap": 2.7744266354166256,
                "allocationBreakdown": [
                    {
                        "unlockDate": "2024-09-16T13:00:00Z",
                        "allocationName": "Investors",
                        "standardAllocationName": "Private Investors",
                        "cliffAmount": 36520833.29999995,
                        "cliffValue": 19682209.211202275,
                        "referencePrice": 0.538931,
                        "referencePriceUpdatedTime": "2024-08-19T07:30:24Z",
                        "unlockPrecision": "month"
                    },
                    {
                        "unlockDate": "2024-09-16T13:00:00Z",
                        "allocationName": "Team, Future Team + Advisors",
                        "standardAllocationName": "Founder / Team",
                        "cliffAmount": 56125000,
                        "cliffValue": 30247502.375000004,
                        "referencePrice": 0.538931,
                        "referencePriceUpdatedTime": "2024-08-19T07:30:24Z",
                        "unlockPrecision": "month"
                    }
                ]
            },
            "latestUpdateDate": "2024-06-11T08:49:27Z"
        },
        ...
    ]
}
```

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                         |
| ---------------- | ------------ | ----------------------------------- |
| unlockDate       | timestamp    | Date of the Unlock Event            |
| tokenName        | string       | Token Name                          |
| tokenSymbol      | string       | Token Symbol                        |
| listedMethod     | string       | Human/Ai                            |
| dataSource       | string       | Data Source of the Token            |
| linearUnlocks    | object array | Linear Unlocks in this unlock event |
| cliffUnlocks     | object array | Cliff Unlocks in this unlock event  |
| latestUpdateDate | timestamp    | Unlocks Data Latest Update time     |

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

| Fields                    | Data Type    | Description                                               |
| ------------------------- | ------------ | --------------------------------------------------------- |
| linearAmount              | number       | Linear Unlocks Amount Denominated in Token                |
| linearValue               | number       | Linear Unlocks Amount Denominated in USD                  |
| dailyAmount               | number       | Daily Linear Unlocks Amount Denominated in Token          |
| dailyValue                | number       | Daily Linear Unlocks Amount Denominated in USD            |
| referencePrice            | number       | Reference Price used in daily value calculation           |
| referencePriceUpdatedTime | timestamp    | Reference Price Last Updated Time                         |
| allocationBreakdown       | object array | Unlocks data breakdown by each allocation                 |
| allocationName            | string       | Allocation Name                                           |
| standardAllocationName    | string       | Standard allocation of this allocation                    |
| linearAmount              | number       | Total Linear Unlocks Amount in token                      |
| linearValue               | number       | Total Linear Unlocks Value in USD                         |
| durationOfRate            | number       | Duration of Linear Rate                                   |
| beginDate                 | timestamp    | Begin date of the linear unlock                           |
| endDate                   | timestamp    | End date of the linear unlock                             |
| unlockPrecision           | string       | Precision of Unlock. Example: second, hour, day, week etc |

**Return Fields Explanation: Linear Allocation Breakdown**

| Fields                 | Data Type | Description                                               |
| ---------------------- | --------- | --------------------------------------------------------- |
| allocationName         | string    | Allocation Name                                           |
| standardAllocationName | string    | Standard allocation of this allocation                    |
| linearAmount           | number    | Total Linear Unlocks Amount in token                      |
| linearValue            | number    | Total Linear Unlocks Value in USD                         |
| durationOfRate         | number    | Duration of Linear Rate                                   |
| beginDate              | timestamp | Begin date of the linear unlock                           |
| endDate                | timestamp | End date of the linear unlock                             |
| unlockPrecision        | string    | Precision of Unlock. Example: second, hour, day, week etc |

**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>referencePrice</td><td>number</td><td>Reference Price used in total unlocks value calculation</td></tr><tr><td>referencePriceUpdatedTime</td><td>timestamp</td><td>Reference Price Last Updated Time</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>Allocation Breakdown</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>unlockDate</td><td>timestamp</td><td>Cliff unlock date</td></tr><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 etc</td></tr></tbody></table>