> For the complete documentation index, see [llms.txt](https://docs.unlocks.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unlocks.app/api-documents/api-endpoints/allocations-api/allocations-api-v2.md).

# 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

<table><thead><tr><th width="190">Listing Method</th><th>Definition</th></tr></thead><tbody><tr><td>INTERNAL</td><td>This token is listed and verified and cross checked across multiple sources by tokenomist</td></tr><tr><td>AI</td><td>This token has been listed using LLM assisted with single source. </td></tr><tr><td>EXTERNAL</td><td>This token is listed directly by the project team. It is first-party data and comes solely from the project's own source.</td></tr></tbody></table>

## Getting Started

#### **Base URL** <a href="#base-url" id="base-url"></a>

```
https://api.unlocks.app
```

#### **Authentication** <a href="#authentication" id="authentication"></a>

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

<pre><code><strong>GET https://api.unlocks.app/v2/allocations
</strong>HEADER: x-api-key: &#x3C;YOUR_API_KEY>
</code></pre>

**Parameters**

Note: `tokenId` needs to be specified.

* tokenId (required): Get `tokenId` from [Token List API](/api-documents/api-endpoints/token-list-api.md)

**Example:**

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

**Response**

```json
{
    "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 |