Token Unlock Schedule

GET/gateway/v1/token/tokenomics

Returns token unlock time-series with cumulative amounts, allocation breakdowns, total supply denominator, and unlocked-supply percentage.

Lookup: by project UUID (`id`) or token `symbol`. Filter by date range with `from`/`to` — defaults to the current calendar month when omitted.

Important: `unlock_amount` is a legacy alias for `cumulative_unlocked_amount`; it is already cumulative at each timestamp and must not be summed across rows. Use `unlocked_percentage_of_total_supply` for the unlock ratio.

Returns 404 if no token found.

Query Parameters

idstring

Surf project UUID. PREFERRED — always use this when available from a previous response. Takes priority over symbol.

Example: 25c6612a-395c-4974-94eb-3b5f9f4b2ed7

symbolstring

Token symbol like `ARB`, `OP`, or `APT`

Example: ARB

fromstring

Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`)

Example: 2024-01-01

tostring

End of time range. Accepts Unix seconds (`1735689600`) or date string (`2025-01-01`)

Example: 2025-01-01

Token Unlock Schedule

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/token/tokenomics?id=25c6612a-395c-4974-94eb-3b5f9f4b2ed7&symbol=ARB&from=2024-01-01&to=2025-01-01', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseTokenUnlockPoint.json",
  "data": [
    {
      "allocations": [
        {
          "amount": 123,
          "name": "<string>"
        }
      ],
      "cumulative_unlocked_amount": 123,
      "timestamp": 123,
      "total_supply": 123,
      "unlock_amount": 123,
      "unlocked_percentage_of_total_supply": 123
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}