> 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/weekly-emission-api/weekly-emission-api-v3.md).

# Weekly Emission API v3

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

⬆️ v3 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.

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

## **Endpoints: Emission API v3** <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/v3/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/v3/emission?tokenId=arbitrum' \
  -H 'x-api-key: $YOUR_API_KEY'
```

**Response**

```
{
                "startDate": "2026-10-11T00:00:00Z",
                "endDate": "2026-10-18T00:00:00Z",
                "tokenName": "Arbitrum",
                "tokenSymbol": "ARB",
                "listedMethod": "INTERNAL",
                "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
              }
}
```

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>listedMethod</td><td>string</td><td>Method of listing(INTERNAL, AI, EXTERNAL)</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      |