> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenomist.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upcoming Unlock Events API v5

> Renamed start/end params and pagination

v5 update: **`minUnlockDate` and `maxUnlockDate` renamed to `start` and `end`. Adds pagination (`page`, `pageSize`).**


## OpenAPI

````yaml GET /v5/unlock/events/upcoming
openapi: 3.0.3
info:
  title: Tokenomist API
  description: >-
    Comprehensive time series data for crypto token unlocks, emissions,
    allocations, fundraising, burns, and buybacks.
  version: 1.0.0
servers:
  - url: https://api.tokenomist.ai
security:
  - apiKey: []
paths:
  /v5/unlock/events/upcoming:
    get:
      tags:
        - Upcoming Unlock Events
      summary: Upcoming Unlock Events v5
      description: >-
        Upcoming unlock events sorted by upcoming time. v5 renames the date
        params (start/end), adds pagination, and recalculates cliff aggregates
        after standardAllocation filtering.
      operationId: getUpcomingUnlockEventsV5
      parameters:
        - name: minMarketCap
          in: query
          required: false
          description: Filter out tokens below a certain market cap
          schema:
            type: number
        - name: minReleasedPercentage
          in: query
          required: false
          description: >-
            Filter out tokens below a certain percentage of released supply from
            0-100
          schema:
            type: number
        - name: start
          in: query
          required: false
          description: >-
            Start date for time filtering (YYYY-MM-DD). Renamed from
            minUnlockDate in v1.
          schema:
            type: string
            format: date
        - name: end
          in: query
          required: false
          description: >-
            End date for time filtering (YYYY-MM-DD). Renamed from maxUnlockDate
            in v1.
          schema:
            type: string
            format: date
        - name: minTotalUnlockAmount
          in: query
          required: false
          description: Filter out unlocks below a certain amount
          schema:
            type: number
        - name: minValueToMarketCap
          in: query
          required: false
          description: Filter out unlocks below a certain value to market cap from 0-100
          schema:
            type: number
        - name: standardAllocation
          in: query
          required: false
          description: >-
            Comma-separated standard allocations to filter by. Allowed values:
            community, founderTeam, privateInvestors, publicInvestors, reserve,
            others. Cliff aggregates are recalculated from the filtered
            allocations.
          schema:
            type: string
          example: community,founderTeam
        - name: page
          in: query
          required: false
          description: Page number (1-indexed).
          schema:
            type: integer
            minimum: 1
        - name: pageSize
          in: query
          required: false
          description: Number of rows per page.
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    $ref: '#/components/schemas/PaginatedMetadata'
                  status:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UpcomingUnlockEventV5Item'
components:
  schemas:
    PaginatedMetadata:
      type: object
      properties:
        queryDate:
          type: string
          format: date-time
          description: Timestamp of the query
          example: '2026-01-08T10:13:58Z'
        credit:
          $ref: '#/components/schemas/Credit'
        page:
          type: integer
          description: Current page number (1-indexed)
          example: 1
        pageSize:
          type: integer
          description: Number of items per page
          example: 50
        totalPages:
          type: integer
          description: Total number of pages available for the current query
          example: 10
        total:
          type: integer
          description: Total number of items across all pages
          example: 487
    UpcomingUnlockEventV5Item:
      type: object
      properties:
        tokenId:
          type: string
          example: layerzero
        tokenName:
          type: string
          example: LayerZero
        tokenSymbol:
          type: string
          example: ZRO
        marketCap:
          type: number
          nullable: true
          example: 278811255
        releasedPercentage:
          type: number
          example: 35.2833333550565
        listedMethod:
          type: string
          example: INTERNAL
        dataSource:
          type: string
          example: Whitepaper
        upcomingEvent:
          type: object
          properties:
            unlockDate:
              type: string
              format: date-time
              example: '2025-11-20T11:00:00Z'
            referencePrice:
              type: number
              example: 1.4
            referencePriceUpdatedTime:
              type: string
              format: date-time
              example: '2025-11-20T00:00:00Z'
            cliffUnlocks:
              $ref: '#/components/schemas/CliffUnlocksV5'
            latestUpdateDate:
              type: string
              format: date-time
              example: '2025-06-13T07:30:52Z'
    Credit:
      type: object
      description: >-
        Optional quota state for the calling account, returned on most
        authenticated responses (both success and error). Treat it as optional:
        it may be absent on unauthenticated requests, demo/playground responses,
        and briefly right after a monthly reset. `used` is near-real-time and
        may lag the true count by a request or two.
      properties:
        used:
          type: integer
          description: >-
            Requests counted in the current window (approximate / eventually
            consistent).
          example: 213
        limit:
          type: integer
          description: The plan's request quota for the window.
          example: 300
        resetAt:
          type: string
          format: date-time
          description: >-
            When the quota resets (RFC3339 UTC). Present for monthly plans;
            absent for lifetime-quota plans.
          example: '2026-08-01T00:00:00Z'
    CliffUnlocksV5:
      type: object
      properties:
        cliffAmount:
          type: number
          description: Total Unlock Amount Denominated in token
          example: 92645833.29999995
        cliffValue:
          type: number
          description: Total Unlock Value Denominated in USD
          example: 49929711.58620228
        valueToMarketCap:
          type: number
          description: Value / M.Cap in Percentage
          example: 2.7744266354166256
        allocationBreakdown:
          type: array
          items:
            $ref: '#/components/schemas/CliffAllocationBreakdownV5'
    CliffAllocationBreakdownV5:
      type: object
      properties:
        unlockDate:
          type: string
          format: date-time
          description: Cliff unlock date
          example: '2024-09-16T13:00:00Z'
        allocationName:
          type: string
          description: Allocation Name
          example: Investors
        standardAllocationName:
          type: string
          description: Standard allocation of this allocation
          example: Private Investors
        cliffAmount:
          type: number
          description: Unlock Amount Denominated in Token
          example: 36520833.29999995
        cliffValue:
          type: number
          description: Unlock Value Denominated in USD
          example: 19682209.211202275
        referencePrice:
          type: number
          description: Reference Price used in total unlocks value calculation
          example: 0.538931
        referencePriceUpdatedTime:
          type: string
          format: date-time
          description: Reference Price Last Updated Time
          example: '2024-08-19T07:30:24Z'
        unlockPrecision:
          type: string
          description: >-
            Precision of Unlock. Example: second, hour, day, week, unknown(for
            AI listed token only), etc
          example: month
        committedClaim:
          $ref: '#/components/schemas/CommittedClaim'
    CommittedClaim:
      type: object
      nullable: true
      description: >-
        Committed claim information for the allocation. Null when no committed
        claim data is available.
      properties:
        amount:
          type: number
          nullable: true
          description: Committed claim amount denominated in token
          example: 1234567.89
        value:
          type: number
          nullable: true
          description: Committed claim value denominated in USD
          example: 987654.32
        timestamp:
          type: integer
          nullable: true
          description: Unix timestamp of the committed claim
          example: 1735689600
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Tokenomist API key

````