# Token Unlock Explorer

> Model token vesting (cliff, linear, monthly, tranches, TGE) or audit a VestingWallet. Builds a token unlock schedule from its parameters — total, start, cliff, duration, linear / monthly / custom tranches and TGE percentage — and shows unlocked vs. locked amounts on any date and the next unlock. On-chain mode reads an OpenZeppelin VestingWallet (start, duration, released, releasable) and compares the schedule with what was actually released.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://tokenunlockexplorer.usefulweb.site/ (interactive tool at https://tokenunlockexplorer.usefulweb.site/tool)
- JSON API: POST https://tokenunlockexplorer.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://tokenunlockexplorer.usefulweb.site/api/v1/tool)
- OpenAPI: https://tokenunlockexplorer.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://tokenunlockexplorer.usefulweb.site/mcp - tool `token_unlock_explorer`

## Inputs
- mode (select): Mode
- totalTokens (number): Total tokens
- symbol (text): Token symbol
- startDate (date): Start / TGE date
- cliffMonths (integer): Cliff
- durationMonths (integer): Total vesting duration (from start, incl. cliff)
- schedule (select): Release type
- tgePercent (number): Unlocked at TGE
- tranches (textarea): Tranches (custom) - One "date, percent of total" per line.
- asOf (date): As of date - Defaults to today.
- chain (select): Chain (on-chain mode)
- vestingWallet (text): VestingWallet address
- token (text): Token address (blank = native coin)

## Method
- Unlocked(t) = TGE % of total at the start date, plus the remaining amount vesting from the start date to start + duration. Before the cliff only the TGE amount is unlocked; at the cliff everything accrued since the start unlocks at once (OpenZeppelin VestingWalletCliff semantics).
- Linear: continuous pro-rata by time. Monthly: equal steps on each monthly anniversary of the start date (day clamped to month end). Tranches: the listed percentages of the total on the listed dates (plus TGE).
- All dates are UTC. Amounts are computed per date; the sample table shows month-end points.
- On-chain mode reads an OpenZeppelin VestingWallet with eth_call: start(), duration(), cliff() (if present), released() / released(token), releasable() / releasable(token), owner() as beneficiary, plus the wallet's balance. Allocation = balance + released; scheduled vested = allocation × (now − start) / duration (0 before the cliff, full after the end), which equals released + releasable for an unmodified wallet.