# Burn API v1

## 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/v1/burn/{tokenId}
</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](https://docs.unlocks.app/api-documents/api-endpoints/token-list-api)
* 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 is the furthest available date.

**Example:**

```
curl -X 'GET' \
  'https://api.unlocks.app/v1/burn/aptos?start=2024-12-01&end=2024-12-02' \
  -H 'x-api-key: $YOUR_API_KEY'
```

**Response**

```json
{
    "metadata": {
        "queryDate": "2025-11-05T09:38:54Z"
    },
    "status": true,
    "data": {
        "tokenId": "aptos",
        "tokenName": "Aptos",
        "tokenSymbol": "APT",
        "totalBurnAmount": 923.148539,
        "burns": [
            {
                "burnEventLabel": "Aptos Gas Fees",
                "burnType": "PROGRAMMATIC",
                "burnDate": "2024-12-02T00:00:00Z",
                "amount": 511.326899,
                "metadata": {
                    "burners": [
                        "PROJECT"
                    ],
                    "burnReasons": [
                        "GOVERNANCE"
                    ]
                }
            },
            {
                "burnEventLabel": "Aptos Gas Fees",
                "burnType": "PROGRAMMATIC",
                "burnDate": "2024-12-01T00:00:00Z",
                "amount": 411.82164,
                "metadata": {
                    "burners": [
                        "PROJECT"
                    ],
                    "burnReasons": [
                        "GOVERNANCE"
                    ]
                }
            }
        ]
    }
}
```

The response includes time series data with the unix timestamp.

**Return Fields Explanation**

| Fields          | Data Type | Description                                          |
| --------------- | --------- | ---------------------------------------------------- |
| tokenId         | string    | Identifier to call for a Dataset                     |
| tokenName       | string    | Token Name                                           |
| tokenSymbol     | string    | Token Symbol                                         |
| totalBurnAmount | timestamp | Total burned token amount up to latest tracked data. |

**Return Fields Explanation: burns**

| Fields         | Data Type | Description         |
| -------------- | --------- | ------------------- |
| burnEventLabel | string    | Label of burn event |
| burnType       | string    | Type of burn event  |
| burnDate       | string    | date of token burn  |
| amount         | number    | Burn amount         |

**Return Fields Explanation: metadata**

| Fields      | Data Type | Description                       |
| ----------- | --------- | --------------------------------- |
| burners     | string    | Type of burner                    |
| burnReasons | string    | Type of purpose of the burn event |