---
title: "Upcoming unlock events across all active RHC lock / vesting contracts (PRO+)"
method: GET
path: "/rhc/tokens/unlocks"
tags: ["Robinhood Chain"]
---

# Upcoming unlock events across all active RHC lock / vesting contracts (PRO+)

`GET /rhc/tokens/unlocks`

## Request

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

Upcoming unlock EVENTS on Robinhood Chain — each active token lock / vesting contract's NEXT cliff, tranche or final unlock inside the window: which tokens have supply hitting the market this week, how much, from whose lock. `amount_*` is the next event, `window_amount_*` that contract's total release over the whole window; linear per-second streams (Sablier linear, HoodLock / Titan vesting) contribute cliff / final events only. Token subject only (LP locks excluded). Candidates come off the writer-maintained `next_unlock_at` column (rolled forward every 2 min) so every active contract is considered per call; 60 s in-process cache with the window quantised to the same bucket. Prices with an implied market cap above $100B are treated as phantom → usd null. Tier: **PRO+**.

## Query parameters

- `within` '1h' | '6h' | '24h' | '3d' | '7d' | '14d' | '30d' | '90d'
- `token` string
- `family` string
- `kind` 'lock' | 'vesting'
- `min_usd` number
- `min_pct_of_supply` number
- `sort` 'soonest' | 'largest_usd' | 'largest_pct'
- `limit` integer

## Response `200`

OK.

- object
  - `chain` 'robinhood'
  - `window` object
    - `within` string
    - `from` string, date-time
    - `to` string, date-time
  - `unlocks` object[]
    - `unlock_at` string, date-time
    - `in_seconds` integer
    - `event` 'cliff' | '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
    - `token_address` string
    - `token` object
    - `lock` object: lock_id, locker, locker_name, family, kind, name, sender, recipient, amount_*, locked_*, cliff_at, end_at, cancelable_by_sender, tx_hash.
  - `pagination` object
    - `limit` integer
    - `count` integer
    - `total_in_window` integer
    - `has_more` boolean
    - `candidates_capped` boolean
  - `coverage` object
  - `meta` object

## Other responses

- `400`: Invalid query parameters (code invalid_query).
- `401`: Missing or invalid API key, or an expired free-tier key. Authentication-stage error: no `X-RateLimit-*` headers, no `_rid`.
- `403`: PRO+ 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)