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

# Upcoming Token Unlocks

> Returns upcoming unlocks across all coins.<br/><br/>Available from&#58; <Badge color="orange">Pro</Badge><br/>Cost&#58; <Badge color="surface">1 credit per request</Badge>

<Tip>
  For a single coin's full unlock schedule use [/currencies/:id/vesting/events](/api-reference/currencies/unlock-events).
</Tip>


## OpenAPI

````yaml https://api.cryptorank.io/v3/documentation-json get /v3/currencies/upcoming-token-unlocks
openapi: 3.0.0
info:
  title: Cryptorank API V3
  description: >
    # Overview


    Cryptorank Public API v3 — comprehensive cryptocurrency data for B2B clients
    and partners.


    Useful Links:

    - [API Plans](https://cryptorank.io/public-api)

    - [Dashboard](https://cryptorank.io/public-api/dashboard)


    # Getting Started


    Primary Server URL:
    [https://api.cryptorank.io/v3/](https://api.cryptorank.io/v3/)


    **Authentication**


    Generate an API key in the
    [dashboard](https://cryptorank.io/public-api/dashboard) and pass it in the
    `X-Api-Key` header.


    Keep your keys secret — never commit them to public repositories or expose
    them in client-side code.
  version: 3.0.0
  contact:
    name: Cryptorank Team
    url: https://cryptorank.io
    email: info@cryptorank.io
servers:
  - url: https://api.cryptorank.io
security: []
tags: []
paths:
  /v3/currencies/upcoming-token-unlocks:
    get:
      tags:
        - Vesting & Token Unlocks
      summary: Upcoming Token Unlocks
      description: >-
        **Description**


        Returns upcoming unlocks across all coins.


        > **Tip:** For a single coin's full unlock schedule use
        [/currencies/:id/vesting/events](/api-reference/currencies/unlock-events).


        **Access**

        - Available from: **Pro**

        - Cost: 1 credit per request
      operationId: VestingController_getUpcomingTokenUnlocks
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (1-based). Returns up to 25 items per page.
          schema:
            minimum: 1
            maximum: 1000
            default: 1
            type: number
        - name: daysAhead
          required: false
          in: query
          description: Window for upcoming unlocks in days from today (inclusive).
          schema:
            minimum: 1
            maximum: 365
            default: 30
            type: number
        - name: minValue
          required: false
          in: query
          description: Lower bound on the unlock USD value (inclusive).
          schema:
            example: 1000000
            type: number
        - name: minPercentOfMcap
          required: false
          in: query
          description: >-
            Lower bound on the unlock size as a percent of the coin market
            capitalization (inclusive). Value is a percent, e.g. `5` means 5%.
          schema:
            type: number
            example: 1
        - name: sortBy
          required: false
          in: query
          description: Sort field.
          schema:
            default: date
            type: string
            enum:
              - id
              - date
              - unlockValue
              - percentOfMcap
        - name: sortOrder
          required: false
          in: query
          description: Sort direction.
          schema:
            default: asc
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - meta
                  - status
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CurrencyUpcomingTokenUnlockItemDto'
                  meta:
                    $ref: '#/components/schemas/ListMetaDto'
                  status:
                    $ref: '#/components/schemas/ResponseStatusDto'
        '400':
          description: Request validation failed
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - status
                    properties:
                      code:
                        type: string
                        enum:
                          - VALIDATION_ERROR
                        example: VALIDATION_ERROR
                      message:
                        type: string
                        example: Validation failed
                      status:
                        type: number
                        example: 400
        '401':
          description: API key is missing or invalid
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - status
                    properties:
                      code:
                        type: string
                        enum:
                          - API_KEY_MISSING
                          - API_KEY_INVALID
                        example: API_KEY_MISSING
                      message:
                        type: string
                        example: API key is missing
                      status:
                        type: number
                        example: 401
        '403':
          description: >-
            No active subscription, the endpoint is not available in your plan,
            or the request goes beyond what your plan allows
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - status
                    properties:
                      code:
                        type: string
                        enum:
                          - NO_ACTIVE_SUBSCRIPTION
                          - ENDPOINT_NOT_AVAILABLE
                          - PLAN_LIMIT_EXCEEDED
                        example: NO_ACTIVE_SUBSCRIPTION
                      message:
                        type: string
                        example: No active subscription found
                      status:
                        type: number
                        example: 403
        '429':
          description: Rate limit or credit limit exceeded
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - status
                    properties:
                      code:
                        type: string
                        enum:
                          - RATE_LIMIT_EXCEEDED
                          - DAILY_CREDITS_EXCEEDED
                          - MONTHLY_CREDITS_EXCEEDED
                        example: RATE_LIMIT_EXCEEDED
                      message:
                        type: string
                        example: Rate limit exceeded
                      status:
                        type: number
                        example: 429
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - status
                    properties:
                      code:
                        type: string
                        enum:
                          - INTERNAL_ERROR
                        example: INTERNAL_ERROR
                      message:
                        type: string
                        example: Internal server error
                      status:
                        type: number
                        example: 500
      security:
        - X-Api-Key: []
components:
  schemas:
    CurrencyUpcomingTokenUnlockItemDto:
      type: object
      properties:
        id:
          type: number
          example: 28
          description: Currency unique numeric identifier.
        name:
          type: string
          example: Ethereum
          description: Display name.
        symbol:
          type: string
          example: ETH
          nullable: true
          description: Native token symbol (e.g. 'ETH', 'BNB'); null when unknown.
        imageUrl:
          type: string
          example: https://images.cryptorank.io/coins/150x150.ethereum1524754012028.png
          nullable: true
          description: Coin logo (150×150); null when no image is available.
        time:
          type: number
          example: 1780272000000
          description: >-
            Unlock date — Unix milliseconds (start of day, UTC). When several
            events fall on the same day for one coin their token amounts are
            aggregated into a single entry.
        unlockTokens:
          type: string
          example: '1250000'
          description: Number of tokens that will be unlocked on `time` (raw token units).
        unlockValue:
          type: string
          example: '4625000'
          description: >-
            Value of the unlock at the current coin price, USD — `unlockTokens`
            × `price`, rounded to whole dollars.
        percentOfMcap:
          type: number
          example: 0.42
          description: >-
            Unlock value as a percent of the coin market capitalization (current
            circulating supply). Example: `0.42` means 0.42%.
        percentOfSupply:
          type: number
          example: 1.05
          description: >-
            Unlock token amount as a percent of the coin total supply (max
            supply with a fallback to total supply). Example: `1.05` means
            1.05%.
        price:
          type: string
          example: '3.70'
          description: Current coin price, USD (twelve fractional digits).
        marketCap:
          type: string
          example: '1100000000'
          description: Current coin market capitalization, USD, rounded to whole dollars.
        circulatingSupply:
          type: string
          example: '297000000'
          description: Current coin circulating supply (raw token units).
      required:
        - id
        - name
        - symbol
        - imageUrl
        - time
        - unlockTokens
        - unlockValue
        - percentOfMcap
        - percentOfSupply
        - price
        - marketCap
        - circulatingSupply
    ListMetaDto:
      type: object
      properties:
        page:
          type: number
          example: 1
          description: Current page number (1-based)
        pageSize:
          type: number
          example: 25
          description: >-
            Fixed number of items per page for this endpoint (varies per
            endpoint)
        hasNextPage:
          type: boolean
          example: true
          description: Whether a further page of results exists
      required:
        - page
        - pageSize
        - hasNextPage
    ResponseStatusDto:
      type: object
      properties:
        usedCredits:
          type: number
          example: 1
          description: Credits charged for this request
        timestamp:
          type: number
          example: 1780000000000
          description: Server time of the response. Unix timestamp in milliseconds
      required:
        - usedCredits
        - timestamp
  securitySchemes:
    X-Api-Key:
      name: X-Api-Key
      type: apiKey
      in: header

````