> 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-v1.md).

# Weekly Emission API v1

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

## 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/v1/emission
HEADER: x-api-key: <YOUR_API_KEY>
```

## **Endpoints: Emission API v1** <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.

```
curl -X 'GET' \
  'https://api.unlocks.app/v1/emission?tokenId=optimisim&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/v1/emission?tokenId=optimisim' \
  -H 'x-api-key: $YOUR_API_KEY'
```

**Response**

```json
{
    "metadata": {
        "queryDate": "2024-06-24T13:31:20Z"
    },
    "status": true,
    "data": [
        {
            "startDate": "2023-06-25T00:00:00Z",
            "endDate": "2023-07-02T00:00:00Z",
            "tokenName": "Optimism",
            "tokenSymbol": "OP",
            "unlockAmount": 31341653,
            "unlockValue": 40744148.9,
            "referencePrice": 1.3,
            "allocations": [
                "Core Contributors",
                "Investors"
            ],
            "standardAllocations": [
                "Founder / Team",
                "Private Investors"
            ]
        },
        {
            "startDate": "2023-07-02T00:00:00Z",
            "endDate": "2023-07-09T00:00:00Z",
            "tokenName": "Optimism",
            "tokenSymbol": "OP",
            "unlockAmount": 0,
            "unlockValue": 0,
            "referencePrice": 1.34,
            "allocations": [],
            "standardAllocations": []
        },
        {
            "startDate": "2023-07-09T00:00:00Z",
            "endDate": "2023-07-16T00:00:00Z",
            "tokenName": "Optimism",
            "tokenSymbol": "OP",
            "unlockAmount": 1683000,
            "unlockValue": 2036430,
            "referencePrice": 1.21,
            "allocations": [
                "Governance Fund"
            ],
            "standardAllocations": [
                "Community"
            ]
        },
        {
            "startDate": "2023-07-16T00:00:00Z",
            "endDate": "2023-07-23T00:00:00Z",
            "tokenName": "Optimism",
            "tokenSymbol": "OP",
            "unlockAmount": 0,
            "unlockValue": 0,
            "referencePrice": 1.45,
            "allocations": [],
            "standardAllocations": []
        },
        ...
    ]
}
```

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                                 |
| ------------------- | ------------ | ------------------------------------------- |
| startDate           | timestamp    | Start date of the aggregated emission       |
| endDate             | timestamp    | End date of the aggregated emission         |
| tokenName           | string       | Token name                                  |
| tokenSymbol         | string       | Token symbol                                |
| unlockAmount        | number       | Total Unlock amount within specified period |
| unlockValue         | number       | Total Unlock value within specified period  |
| referencePrice      | number       | Reference price for unlockValue calculation |
| allocations         | object array | Allocation name                             |
| standardAllocations | object array | Standard allocation of this allocation      |