# Buyback 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/buyback/{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 v4](https://docs.unlocks.app/api-documents/api-endpoints/token-list-api/token-list-api-v4)
* 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/buyback/hyperliquid?start=2024-10-01&end=2024-12-01' \
  -H 'x-api-key: $YOUR_API_KEY'
```

**Response**

```json
{
    "metadata": {
        "queryDate": "2025-11-05T10:08:39Z"
    },
    "status": true,
    "data": {
        "tokenId": "hyperliquid",
        "tokenName": "Hyperliquid",
        "tokenSymbol": "HYPE",
        "totalBuybackAmount": 318370.2349536178,
        "buybacks": [
            {
                "buybackEventLabel": "Missing HYPE Assistance Fund Buyback",
                "buybackType": "TREASURY_BUYBACK",
                "buybackDate": "2024-11-30T17:00:00Z",
                "tokenAmount": 159185.1174768089,
                "value": 1036295.1147740259,
                "spentAmount": null,
                "spentUnit": "",
                "targetAddress": "0xfefefefefefefefefefefefefefefefefefefefe",
                "buyerAddress": "0xfefefefefefefefefefefefefefefefefefefefe",
                "resolution": "period_net",
                "basis": "estimated"
            },
            {
                "buybackEventLabel": "Missing HYPE Assistance Fund Buyback",
                "buybackType": "TREASURY_BUYBACK",
                "buybackDate": "2024-11-29T17:00:00Z",
                "tokenAmount": 159185.1174768089,
                "value": 620821.9581595546,
                "spentAmount": null,
                "spentUnit": "",
                "targetAddress": "0xfefefefefefefefefefefefefefefefefefefefe",
                "buyerAddress": "0xfefefefefefefefefefefefefefefefefefefefe",
                "resolution": "period_net",
                "basis": "estimated"
            }
        ]
    }
}
```

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                                         |
| totalBuybackAmount | timestamp | Total buyback token amount up to latest tracked data |

**Return Fields Explanation: buybacks**

| Fields            | Data Type | Description                                                             |
| ----------------- | --------- | ----------------------------------------------------------------------- |
| buybackEventLabel | string    | Label of buyback event                                                  |
| buybackType       | string    | Type of buyback event                                                   |
| buybackDate       | string    | Date of buyback burn                                                    |
| tokenAmount       | number    | Buyback token amount                                                    |
| value             | number    | Historical USD value of token amount                                    |
| spentAmount       | number    | Amount actually spent by the project to buy back tokens                 |
| spentUnit         | string    | Unit of spent amount                                                    |
| targetAddress     | string    | Address of the buyback wallet or foundation                             |
| buyerAddress      | string    | Address doing the buyback purchases (usually target address if unknown) |
| resolution        | string    | Granularity of buyback event                                            |
| basis             | string    | Precision of the buyback reference                                      |