# Weekly Emission API v2

**Overview**

A weekly aggregated emission per token. The start date is expected to be a Sunday and end date a Saturday. This will include both linear and cliff unlocks that happened in the specified week. 

Included is the breakdown of beneficiaries into [standard allocation](https://docs.unlocks.app/docs/~/changes/Iamy4ACjYOBw6V1zBAnb/tokenunlocks-pro/standard-allocation), a Tokenomist™️ methodology for categorizing and grouping allocations from different projects into a comparable standard.

⬆️ v2 update: Provides more detailed breakdown of unlock amount and unlock value within the 'allocations' field.

See below for each field description.

## 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.

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

## **Endpoints: Emission API v2** <a href="#endpoints" id="endpoints"></a>

**Parameters**

Note: `tokenID` needs to be specified.

* tokenId (required): Get `tokenId` from [Token List API](/api-documents/api-endpoints/token-list-api.md)
* start (optional): The start date for time filtering in the format YYYY-MM-DD. Defaults to the earliest available date.
* end (optional):   The end date for time filtering in the format YYYY-MM-DD. Defaults to the current date.

**Get Specific Date Range Example:**

Replace the preferred start and end dates in indicated format.&#x20;

Including breakdown of : allocationName, standardAllocationName, unlockAmount, unlockValue, and totalCumulativeUnlockedAmount. See below for each field definitions.

```
curl -X 'GET' \
  'https://api.unlocks.app/v2/emission?tokenId=arbitrum&start=YYYY-MM-DD&end=YYYY-MM-DD' \
  -H 'x-api-key: $YOUR_API_KEY'
```

**Get Full Data Range Example:**

Remove date completely to call the full range.

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

**Response**

```json
{
    "metadata": {
        "queryDate": "2024-08-20T08:18:14Z"
    },
    "status": true,
    "data": [
              {
                "startDate": "2026-10-11T00:00:00Z",
                "endDate": "2026-10-18T00:00:00Z",
                "tokenName": "Arbitrum",
                "tokenSymbol": "ARB",
                "unlockAmount": 95997304.55646817,
                "unlockValue": 52539420.78105959,
                "referencePrice": 0.547301,
                "allocations": [
                  {
                    "allocationName": "Team, Future Team + Advisors",
                    "standardAllocationName": "Founder / Team",
                    "unlockAmount": 56125000,
                    "unlockValue": 30717268.625000004
                  },
                  {
                    "allocationName": "Investors",
                    "standardAllocationName": "Private Investors",
                    "unlockAmount": 36520833,
                    "unlockValue": 19987888.421733003
                  },
                  {
                    "allocationName": "Arbitrum DAO Treasury",
                    "standardAllocationName": "Reserve",
                    "unlockAmount": 3351471.556468172,
                    "unlockValue": 1834263.734326587
                  }
                ],
                "totalCumulativeUnlockedAmount": 6046002268.244544
              },
              {
                "startDate": "2026-10-18T00:00:00Z",
                "endDate": "2026-10-25T00:00:00Z",
                "tokenName": "Arbitrum",
                "tokenSymbol": "ARB",
                "unlockAmount": 3351471.556468172,
                "unlockValue": 1834263.734326587,
                "referencePrice": 0.547301,
                "allocations": [
                  {
                    "allocationName": "Arbitrum DAO Treasury",
                    "standardAllocationName": "Reserve",
                    "unlockAmount": 3351471.556468172,
                    "unlockValue": 1834263.734326587
                  }
                ],
                "totalCumulativeUnlockedAmount": 6049353739.801012
              },
              {
                "startDate": "2026-10-25T00:00:00Z",
                "endDate": "2026-11-01T00:00:00Z",
                "tokenName": "Arbitrum",
                "tokenSymbol": "ARB",
                "unlockAmount": 3351471.556468172,
                "unlockValue": 1834263.734326587,
                "referencePrice": 0.547301,
                "allocations": [
                  {
                    "allocationName": "Arbitrum DAO Treasury",
                    "standardAllocationName": "Reserve",
                    "unlockAmount": 3351471.556468172,
                    "unlockValue": 1834263.734326587
                  }
                ],
                "totalCumulativeUnlockedAmount": 6052705211.35748
              },
        ...
    ]
}
```

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

**Return Fields Explanation**

<table><thead><tr><th width="336">Fields</th><th>Data Type</th><th>Description</th></tr></thead><tbody><tr><td>startDate</td><td>timestamp</td><td>Start date of the aggregated emission</td></tr><tr><td>endDate</td><td>timestamp</td><td>End date of the aggregated emission</td></tr><tr><td>tokenName</td><td>string</td><td>Token name</td></tr><tr><td>tokenSymbol</td><td>string</td><td>Token symbol</td></tr><tr><td>unlockAmount</td><td>number</td><td>Total Unlock amount in date period</td></tr><tr><td>unlockValue</td><td>number</td><td>Total unlock value in date period</td></tr><tr><td>referencePrice</td><td>number</td><td>Reference price for unlockValue calculation</td></tr><tr><td>allocations</td><td>object array</td><td>Expand allocation details</td></tr><tr><td>totalCumulativeUnlockedAmount</td><td>number</td><td>Total unlocked amount from token TGE till specified endDate</td></tr></tbody></table>

**Return Fields Explanation: Allocations**

| Fields                 | Data Type | Description                            |
| ---------------------- | --------- | -------------------------------------- |
| allocationName         | string    | Allocation name                        |
| standardAllocationName | string    | Standard allocation of this allocation |
| unlockedAmount         | number    | Total Unlock amount in date period     |
| unlockedValue          | number    | Total unlock value in date period      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.unlocks.app/api-documents/api-endpoints/weekly-emission-api/weekly-emission-api-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.