Unlock Events

Unlock Events v5

Changed on Nov 3, 2026

Cliff unlocks per token: one entry per unlock time, oldest first. Cliff unlocks only; allocations distributed as mining/validator rewards or yield farming are left out (see Daily Emission for linear releases). v5 moves tokenId to a path param, adds pagination, an optional standardAllocation filter and committedClaim data per allocation.

get/v5/unlock/events/{tokenId}

Request

Base URL
https://api.tokenomist.ai
URL
https://api.tokenomist.ai/v5/unlock/events/{tokenId}
Auth
API key in header x-api-key

Path parameters

tokenIdstring required

Token identifier (slug). Get from Token List API.

Query parameters

startstring date

Start date (YYYY-MM-DD). Defaults to the start of your plan's window (today minus its years back). Outside the window: 422 "Invalid Date Range".

endstring date

End date (YYYY-MM-DD) = 00:00 UTC that day: an unlock at exactly 00:00 is included, a later one that day is not. Defaults to the end of your plan's window. Outside the window: 422 "Invalid Date Range".

standardAllocationstring

Comma-separated list of standard allocations to filter by. Allowed values: community, founderTeam, privateInvestors, publicInvestors, others, reserve; another value: 422. An event without a matching allocation is dropped; cliffAmount and cliffValue are recalculated from the kept allocations, valueToMarketCap is not.

pageinteger

Page number, 1-based. 0 or omitted: page 1. A page past the last returns the last page again, so stop at metadata.totalPages. Negative: 400.

pageSizeinteger

Rows per page. 0 or omitted: 20. No maximum. Negative: 400.

Response

Successful response

statusboolean

Example response

{
  "metadata": {
    "queryDate": "2026-01-08T10:13:58Z",
    "credit": {
      "used": 213,
      "limit": 1000,
      "resetAt": "2026-08-01T00:00:00Z"
    },
    "page": 1,
    "pageSize": 50,
    "totalPages": 10,
    "total": 487
  },
  "data": [
    {
      "unlockDate": "2024-09-16T13:00:00Z",
      "tokenName": "Arbitrum",
      "tokenSymbol": "ARB",
      "listedMethod": "INTERNAL",
      "dataSource": "Whitepaper",
      "cliffUnlocks": {
        "cliffAmount": 92645833.29999995,
        "cliffValue": 49929711.58620228,
        "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-09-16T00:00:00Z",
            "unlockPrecision": "month",
            "committedClaim": {
              "amount": 1234567.89,
              "value": 987654.32,
              "timestamp": 1735689600
            }
          }
        ]
      },
      "latestUpdateDate": "2024-06-11T08:49:27Z"
    }
  ]
}

Changes

Nov 3, 202637c15ea7bdbd Revision changes
- breaking
  the response property /// became nullable for the status
- warning
  added the new enum value to the // response property for the response status
- warning
  added the new AI enum value to the // response property for the response status
- warning
  added the new EXTERNAL enum value to the // response property for the response status
- warning
  added the new INTERNAL enum value to the // response property for the response status
- info
  for the query request parameter page, the min was decreased from 1.00 to 0.00
- info
  for the query request parameter pageSize, the min was decreased from 1.00 to 0.00
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status

Operation history