Allocations API v2

⬆️ v2 update: Add Dynamic inflation rate. *value might differ to v1*

⬆️ v2 update: Provides more tokens that are listed with AI method. Add more field about listing method, see below for field description

Listing Method	Definition
INTERNAL	This token is listed and verified and cross checked across multiple sources by tokenomist
AI	This token has been listed using LLM assisted with single source.
EXTERNAL	This token is listed directly by the project team. It is first-party data and comes solely from the project's own source.

Getting Started

Base URL

https://api.unlocks.app

Authentication

Provide your api key in the x-api-key header.

GET https://api.unlocks.app/v2/allocations
HEADER: x-api-key: <YOUR_API_KEY>

Parameters

Note: tokenId needs to be specified.

• tokenId (required): Get tokenId from Token List API

Example:

curl -X 'GET' \
  'https://api.unlocks.app/v2/allocations?tokenId=optimism' \
  -H 'x-api-key: $YOUR_API_KEY'

Response

{
    "metadata": {
        "queryDate": "2026-01-08T10:17:39Z"
    },
    "status": true,
    "data": {
        "name": "Optimism",
        "symbol": "OP",
        "listedMethod": "INTERNAL",
        "maxSupply": 4294967296,
        "lastUpdatedDate": "2025-06-11T10:36:43Z",
        "totalUnlockedAmount": 1930591949.2000003,
        "totalLockedAmount": 274658779,
        "totalUntrackedAmount": 0.8000006675720215,
        "totalTBDLockedAmount": 2089716567,
        "allocations": [
            {
                "allocationName": "Core Contributors",
                "allocationType": "Scheduled",
                "standardAllocationName": "Founder / Team",
                "allocationUnlockedAmount": 716795218,
                "allocationLockedAmount": 99248568,
                "allocationAmount": 816043786,
                "trackedAllocationPercentage": 18.999999998835847
            },
            {
                "allocationName": "Retroactive Public Goods Funding",
                "allocationType": "TBD",
                "standardAllocationName": "Community",
                "allocationUnlockedAmount": 0,
                "allocationLockedAmount": 799993459,
                "allocationAmount": 799993459,
                "trackedAllocationPercentage": 18.62629920212233
            },
        ....
        ]
    }
}

The response includes time series data with the date (in UTC timezone), with granularity at the level of week.

Return Fields Explanation

Fields	Data Type	Description
name	string	Token Name
symbol	string	Token Symbol
listedMethod	string	Method of listing(INTERNAL, AI, EXTERNAL)
maxSupply	number	Max supply for the token (Will be null if no data are present)
lastUpdatedDate	timestamp	Last updated date of token
totalUnlockedAmount	number	Total current unlocked amount
totalLockedAmount	number	Total current locked token amount
totalUntrackedAmount	number	Total current untracked amount
totalTBDLockedAmount	number	Total current TBD locked amount

Return Fields Explanation: Allocations

Fields	Data Type	Description
allocationName	string	Allocation name
allocationType	string	Type of allocation (Schedule, TBD, Untracked)
standardAllocationName	string	Standard allocation of this allocation
allocationUnlockedAmount	number	Current unlocked amount of the allocation
allocationLockedAmount	number	Current locked amount of the allocation
allocationAmount	number	Total token amount assign to this allocation
trackedAllocationPercentage	number	Total track allocation percentage not include untrack