---
title: "Upcoming token unlocks (cliffs, periodic releases, final unlocks)"
method: GET
path: "/tokens/unlocks"
tags: ["Tokens"]
---

# Upcoming token unlocks (cliffs, periodic releases, final unlocks)

`GET /tokens/unlocks`

## Request

- Base URL: `https://madeonsol.com/api/v1`
- URL: `https://madeonsol.com/api/v1/tokens/unlocks`
- Auth: HTTP bearer

Upcoming **unlock events** across all active lock / vesting contracts inside a window — cliffs, periodic releases (hourly or coarser) and final unlocks — i.e. *which tokens have locked supply hitting the market this week, how much, from whose lock*. One entry per active contract = its **next** unlock event in the window ('event' = cliff | period | final | tranche), plus 'window_amount_*' = that contract's total release over the whole window. Continuous per-second streams (Streamflow payroll) contribute only their cliff/final events. Sort by soonest (default), largest_usd or largest_pct; filter by mint / program / kind / min_usd / min_pct_of_supply. PRO+.

## Query parameters

- `within` '1h' | '6h' | '24h' | '3d' | '7d' | '14d' | '30d' | '90d'
- `mint` string
- `program` 'streamflow' | 'jupiter_lock' | 'bonfida_vesting' | 'smithii_vesting' | 'sablier_lockup'
- `kind` 'lock' | 'vesting'
- `min_usd` number
- `min_pct_of_supply` number
- `sort` 'soonest' | 'largest_usd' | 'largest_pct'
- `limit` integer

## Response `200`

OK

- object
  - `window` object
    - `within` string
    - `from` string, date-time
    - `to` string, date-time
  - `unlocks` object[]
    - `unlock_at` string, date-time
    - `in_seconds` integer
    - `event` 'cliff' | 'period' | 'final' | 'tranche'
    - `amount_raw` string
    - `amount` number, nullable
    - `amount_usd` number, nullable
    - `amount_pct_of_supply` number, nullable
    - `window_amount_raw` string
    - `window_amount` number, nullable
    - `window_amount_usd` number, nullable
    - `window_amount_pct_of_supply` number, nullable
    - `mint` string
    - `token` object
      - `symbol` string, nullable
      - `name` string, nullable
      - `decimals` integer, nullable
      - `price_usd` number, nullable
      - `market_cap_usd` number, nullable
    - `lock` object: The contract this event belongs to (subset of the /tokens/{mint}/locks row)
  - `pagination` object
    - `limit` integer
    - `count` integer
    - `total_in_window` integer
    - `has_more` boolean
  - `meta` object

## Other responses

- `400`: Invalid query parameters
- `401`: Missing or invalid API key, or an expired free-tier key. Authentication-stage error: no `X-RateLimit-*` headers, no `_rid`.
- `403`: Forbidden. One of: the key's tier is below this endpoint's or parameter's gate (`tier_required` with an `upgrade` block); the public demo key used outside its allow-list (`demo_key_endpoint_not_allowed`); an invalid or revoked key; an origin-restricted key called from a disallowed origin (`code` `origin_not_allowed` / `origin_required`). `X-RateLimit-*` headers are present only on `tier_required`.
- `429`: Too many requests. Every 429 carries `Retry-After`. A quota 429 (`rate_limit_exceeded`, with `X-RateLimit-*`), a heavy-query concurrency 429 (`error_kind` `concurrency`/`capacity`), or the per-IP authentication-failure block (30 failed auths/min; plain `error` + `retry_after_seconds`, no `X-RateLimit-*`).
- `500`: Unexpected server error from the route (`Internal server error`, with `_rid`). Safe to retry with backoff. A failed API-key lookup is a 503 `auth_backend_unavailable`, never a 500.
- `503`: Temporarily unavailable — a Postgres statement timeout while the dataset is under load or maintenance (`statement_timeout`, with `X-RateLimit-*` and `_rid`), or the API-key lookup itself unavailable (`auth_backend_unavailable`, authentication stage: no `X-RateLimit-*`, no `_rid`, not counted as a failed authentication). Always carries `Retry-After`; honour it.

---

[API](https://skmtc.dev/madeonsol/apis/madeonsol-api.md) · [All operations](https://skmtc.dev/madeonsol/apis/madeonsol-api/llms.txt) · [OpenAPI document](https://skmtc.dev/madeonsol/apis/madeonsol-api/revisions/96ce84657f55?raw)