> ## 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.
# Token Unlock Dynamics by Category
> Returns market-wide token unlock dynamics as a time series (history and forecast), split by coin primary category.
Available from: Advanced
Cost: 1 credit per request
Untracked allocations are excluded. Unlock value is computed from each token's current price, for both past and upcoming unlocks. Tokens whose price has stopped updating are left out.
Coins without a category are grouped into a single `Uncategorized` entry, always placed last, so the breakdown always adds up to `totalUnlockValue`.
Without `from`/`to` the window is skewed towards upcoming unlocks, sized to the selected `interval`. Both bounds snap to `interval` bucket starts. One response carries at most 366 daily, 520 weekly or 1000 monthly points — wider ranges have to be requested in slices.
## OpenAPI
````yaml https://api.cryptorank.io/v3/documentation-json get /v3/token-unlocks/dynamics/by-category
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/token-unlocks/dynamics/by-category:
get:
tags:
- Vesting & Token Unlocks
summary: Token Unlock Dynamics by Category
description: >-
**Description**
Returns market-wide token unlock dynamics as a time series (history and
forecast), split by coin primary category.
> **Note:** Untracked allocations are excluded. Unlock value is computed
from each token's current price, for both past and upcoming unlocks.
Tokens whose price has stopped updating are left out.
> **Note:** Coins without a category are grouped into a single
`Uncategorized` entry, always placed last, so the breakdown always adds
up to `totalUnlockValue`.
> **Tip:** Without `from`/`to` the window is skewed towards upcoming
unlocks, sized to the selected `interval`. Both bounds snap to
`interval` bucket starts. One response carries at most 366 daily, 520
weekly or 1000 monthly points — wider ranges have to be requested in
slices.
**Access**
- Available from: **Advanced**
- Cost: 1 credit per request
operationId: TokenUnlocksController_getDynamicsByCategory
parameters:
- name: interval
required: false
in: query
description: >-
Bucket size for aggregation: `1d` — daily, `1w` — weekly (ISO week,
starts Monday), `1m` — monthly.
schema:
default: 1m
type: string
enum:
- 1d
- 1w
- 1m
- name: from
required: false
in: query
description: >-
Lower bound on the unlock date, snapped down to the start of its
`interval` bucket. Accepts ISO 8601 string or Unix timestamp
(sec/ms). Defaults to the history side of the window for the
selected `interval`.
schema:
example: '2026-01-01T00:00:00.000Z'
type: string
- name: to
required: false
in: query
description: >-
Upper bound on the unlock date, snapped down to the start of its
`interval` bucket, which is then included in full. May be in the
future — upcoming unlocks are part of the series. Accepts ISO 8601
string or Unix timestamp (sec/ms). Defaults to the forecast side of
the window for the selected `interval`.
schema:
example: '2027-01-01T00:00:00.000Z'
type: string
- name: convert
required: false
in: query
description: >-
Fiat ISO code for monetary fields (e.g. USD, EUR, RUB, AED). See:
[GET
/v3/fiat/list](https://docs.cryptorank.io/api-reference/fiat/supported-fiat-currency-list).
schema:
default: USD
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
required:
- data
- status
properties:
data:
type: array
items:
$ref: >-
#/components/schemas/TokenUnlocksDynamicsByCategoryPointDto
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:
TokenUnlocksDynamicsByCategoryPointDto:
type: object
properties:
date:
type: string
example: '2026-08-01T00:00:00.000Z'
description: >-
Bucket start (ISO 8601 UTC). For `1w` the bucket starts on Monday;
for `1m` on the 1st.
totalUnlockValue:
type: string
example: '1250000000'
description: Total unlock value within the bucket, in the `convert` currency.
breakdown:
description: >-
Per-category split of `totalUnlockValue`, ordered by value
descending, with the `uncategorized` entry last.
type: array
items:
$ref: '#/components/schemas/UnlockCategoryBreakdownItemDto'
required:
- date
- totalUnlockValue
- breakdown
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
UnlockCategoryBreakdownItemDto:
type: object
properties:
id:
type: number
example: 54
nullable: true
description: >-
Category ID, usable as `categoryId` elsewhere. Null for the
uncategorized cut.
key:
type: string
example: gamefi
description: Category slug, or `uncategorized` for coins without a category.
name:
type: string
example: GameFi
description: Category name, or `Uncategorized` for coins without a category.
unlockValue:
type: string
example: '48200000'
description: >-
Unlock value of this category within the bucket, in the `convert`
currency.
required:
- id
- key
- name
- unlockValue
securitySchemes:
X-Api-Key:
name: X-Api-Key
type: apiKey
in: header
````