A token vesting smart contract holds a token allocation and releases it to a recipient on a schedule, without anyone approving each release. This guide explains what's inside one, how the vesting maths works, how claiming and cancelling work on the main platforms, and what to check before you trust one.
A vesting contract stores the recipient, the amount and the schedule (start, cliff, end and release pattern). At any moment it can work out how much has vested, and the recipient claims the difference between that and what they've already claimed. Most vesting contracts don't send tokens on their own: someone has to call the claim function.
What a vesting contract stores
| Field | What it does |
|---|---|
| Recipient (beneficiary) | The wallet the vested tokens belong to |
| Token | Which token is being vested |
| Total amount | The full allocation |
| Start time | When vesting begins |
| Cliff (optional) | A date before which nothing can be claimed |
| End time or duration | When everything has vested |
| Release pattern | Linear, stepped, or a custom curve |
| Claimed so far | How much the recipient has already withdrawn |
| Cancel rights | Whether anyone can stop the schedule, and who |
How the vesting maths works
Every vesting contract answers one question: how much has vested by now? For a linear schedule the answer is simple:
- Before the start (or before the cliff): nothing.
- Between the start and the end: total amount × (time elapsed ÷ total duration).
- After the end: everything.
The claimable amount is then vested minus already claimed. Stepped schedules work the same way but jump at each release date instead of rising smoothly.
1,000,000 tokens vesting linearly over 365 days with no cliff. After 73 days, 200,000 have vested. If the recipient has already claimed 150,000, they can claim 50,000 more right now.
With a cliff, many contracts (OpenZeppelin's included) still measure the curve from the start date: nothing is claimable before the cliff, then everything that built up since the start becomes claimable at once.
Why you have to claim
Blockchains don't run code on a timer. A contract only acts when a transaction calls it, so vested tokens stay in the contract until someone calls its claim function, named withdraw, release, redeem or claim depending on the platform. On most platforms the recipient does this; some contracts let anyone trigger the release, but the tokens still go to the recipient. Superfluid is the main exception, streaming tokens into the recipient's balance continuously.
Unclaimed tokens are common. In our October 2026 study, about 1 in 4 finished Streamflow contracts still held tokens nobody had claimed. See what happens to unclaimed vested tokens.
How the main platforms implement vesting
| Contract | Chains | How positions work | Claim | Cancelling |
|---|---|---|---|---|
| OpenZeppelin VestingWallet | Any EVM chain (a template) | One contract per beneficiary, linear from a start time over a duration. VestingWalletCliff (OpenZeppelin 5.1+) adds a cliff. | release(token), callable by anyone, pays the owner | Not cancelable as written |
| Sablier | EVM chains | Each stream is an NFT, with linear, tranched or custom curves | withdraw | The sender can cancel if the stream was created cancelable |
| Hedgey | EVM chains | Each plan is an NFT; there are vesting plans and lockup plans | redeemPlans | Vesting plans can be revoked by their vesting admin; lockup plans can't |
| Streamflow | Solana | Each contract is a program account with an optional cliff amount and periodic releases | withdraw | Set per contract when it's created |
| Jupiter Lock | Solana | An escrow with a cliff amount, then a fixed amount per period for a set number of periods | claim | Set per escrow by its cancel mode |
For a platform-by-platform comparison, see token vesting platforms compared.
Reading a vesting contract on a block explorer
- 1Open the contract on Etherscan (or the chain's explorer), check it's verified, and go to Contract, then Read Contract.
- 2On an OpenZeppelin VestingWallet, read start, duration, end and owner. releasable(token) shows what can be claimed now and released(token) what has already been claimed.
- 3On Sablier, enter the stream ID into getDepositedAmount, withdrawableAmountOf and isCancelable.
- 4Check the token balance the contract actually holds. A schedule is only as good as the tokens behind it.
Solana vesting accounts can't be read this way in an explorer, so use the platform's own app or a tracker. Vestream reads both: scan any wallet to see its schedules across EVM chains and Solana.
Build your own or use a platform?
| Option | Pros | Cons |
|---|---|---|
| Vesting platform (Sablier, Hedgey, Streamflow, Magna and others) | Audited and maintained; recipients get an app to claim; positions show up in trackers | Some charge fees; less room for custom logic |
| Template (OpenZeppelin VestingWallet) | Simple, widely reviewed code; free | You deploy and verify each contract; no claim app; cancelling needs extra code |
| Fully custom contract | Any logic you need | Needs its own audit; investors may not trust it or be able to find it |
What to check before you trust a vesting contract
- Verified and audited. The source is verified on the explorer, and for a platform the audit covers the deployed version.
- Cancel rights. Who can cancel or revoke, and what happens to unvested tokens if they do.
- Upgradeability. Whether the contract can be upgraded, and by whom. An upgradeable contract can change its rules.
- Funding. Whether it holds the full allocation. A contract that pays many recipients from one shared pool is only as safe as that pool, and vesting pools have been drained by exploits before.
- Token quirks. Fee-on-transfer and rebasing tokens can break vesting maths and leave the contract unable to pay everything it owes.
Tracking vesting contracts
Vestream reads vesting contracts across 13 protocols and 13 chains, so recipients can see every schedule in one place and anyone can check a token's on-chain vesting. Developers can query the same data through the Vestream API or the MCP server.
Frequently Asked Questions
What is a token vesting smart contract?
A smart contract that holds tokens and releases them to a recipient on a schedule. It stores the recipient, amount, start, end and release pattern, and enforces the schedule without anyone approving each release.
How does a vesting contract calculate what I can claim?
It works out how much has vested so far from the schedule, for a linear schedule the total times the share of time elapsed, and subtracts what you've already claimed. The difference is claimable.
Do vesting contracts send tokens automatically?
Usually not. A contract only acts when a transaction calls it, so vested tokens wait until someone calls the claim function. Superfluid is the main exception, streaming tokens directly into the recipient's balance.
Can a vesting contract be cancelled?
Only if it was written or created to allow it. On Sablier the sender can cancel a stream created as cancelable, and Hedgey vesting plans can be revoked by their admin. Unvested tokens go back to the sender; vested tokens normally stay with the recipient.
What is OpenZeppelin VestingWallet?
An open-source Solidity contract that vests ETH and ERC-20 tokens linearly to one beneficiary over a set duration. Anyone can call release to send vested tokens to the beneficiary. A cliff version, VestingWalletCliff, has been available since OpenZeppelin Contracts 5.1.
Should I build my own vesting contract?
Usually not. Audited vesting platforms and the OpenZeppelin template cover most needs and are easier for investors to verify. A fully custom contract needs its own audit.