TOtokenomist
Unlock Events

Unlock Events List v5

Changed on

Cliff unlock events of every token in a date range, grouped by token and sorted by tokenId. Cliff unlocks only. A token whose events are all filtered out is left out. Free trial: only the 50 trial tokens.

get/v5/unlock/events/list

Request

  • Base URL
    https://api.tokenomist.ai
  • URL
    https://api.tokenomist.ai/v5/unlock/events/list
  • Auth
    API key in header x-api-key

Query parameters

minUnlockDatestring date

Earliest unlock date (YYYY-MM-DD). Defaults to the start of your plan's window (today minus its years back). Outside the window: 422 "unlock date must be within the allowed range: A to B".

maxUnlockDatestring date

Latest unlock 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 (today plus its years ahead). Outside the window, or before minUnlockDate: 422.

minMarketCapnumber

Minimum current market cap, in USD. When set, tokens without a market cap are left out.

minReleasedPercentagenumber

Minimum releasedPercentage of the token, in percent (0-100).

minTotalUnlockAmountnumber

Keep only events whose totalCliffAmount is at least this many tokens (not USD).

minValueToMarketCapnumber

Keep only events whose valueToMarketCap is at least this percent (5 means 5%). When set, events without a market cap are left out.

standardAllocationstring

Comma-separated standard allocations to keep. Allowed values: community, founderTeam, privateInvestors, publicInvestors, others, reserve; another value: 422. An event without a matching allocation is dropped; totalCliffAmount and totalCliffValue 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": [
    {
      "tokenId": "layerzero",
      "tokenName": "LayerZero",
      "tokenSymbol": "ZRO",
      "marketCap": 278811255,
      "releasedPercentage": 35.28,
      "listedMethod": "INTERNAL",
      "dataSource": "Whitepaper",
      "events": [
        {
          "unlockDate": "2025-11-20T11:00:00Z",
          "referencePrice": 1.4,
          "referencePriceUpdatedTime": "2025-11-20T11:00:00Z",
          "cliffUnlocks": {
            "totalCliffAmount": 92645833.3,
            "totalCliffValue": 129704166.62,
            "valueToMarketCap": 46.52,
            "allocationBreakdown": [
              {
                "allocationName": "Strategic Partners",
                "standardAllocationName": "Private Investors",
                "cliffAmount": 92645833.3,
                "cliffValue": 129704166.62,
                "unlockPrecision": "second"
              }
            ]
          },
          "latestUpdateDate": "2025-06-13T07:30:52Z"
        }
      ]
    }
  ]
}

Changes