---
title: "Token Unlock Schedule"
method: GET
path: "/gateway/v1/token/tokenomics"
tags: ["Token"]
---

# 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

- `id` string — Surf project UUID. PREFERRED — always use this when available from a previous response. Takes priority over symbol.
- `symbol` string — Token symbol like `ARB`, `OP`, or `APT`
- `from` string — Start of time range. Accepts Unix seconds (`1704067200`) or date string (`2024-01-01`)
- `to` string — End of time range. Accepts Unix seconds (`1735689600`) or date string (`2025-01-01`)

## Response `200`

OK

- DataResponseTokenUnlockPoint
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` TokenUnlockPoint[], nullable, required
    - `allocations` TokenUnlockAllocationItem[], nullable — Breakdown by allocation
      - `amount` number, double, required — Decimal-adjusted allocation amount
      - `name` string, required — Allocation name
    - `cumulative_unlocked_amount` number, double, required — Cumulative total tokens unlocked up to this timestamp (decimal-adjusted). Use this for unlocked-supply ratios.
    - `timestamp` integer, required — Unix timestamp in seconds
    - `total_supply` number, double — Token total supply used as the denominator for unlocked_percentage_of_total_supply
    - `unlock_amount` number, double, required — Legacy alias for cumulative_unlocked_amount. This is cumulative and must not be summed across rows.
    - `unlocked_percentage_of_total_supply` number, double — Cumulative unlocked amount divided by total_supply, expressed as a percentage from 0 to 100
  - `meta` OffsetMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable
    - `has_more` boolean — Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required — Maximum number of items returned in this response
    - `offset` integer, required — Number of items skipped (pagination offset)
    - `total` integer — Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer — Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/498f461e81c4/schema)