Guides

Token Vesting Smart Contracts: How They Work (2026)

What's inside a token vesting smart contract, how the vesting maths works, why you have to claim, how Sablier, Hedgey, Streamflow, Jupiter Lock and OpenZeppelin implement it, and what to check.

·9 min read·By Non Fungible Howard

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.

💡The short answer

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

FieldWhat it does
Recipient (beneficiary)The wallet the vested tokens belong to
TokenWhich token is being vested
Total amountThe full allocation
Start timeWhen vesting begins
Cliff (optional)A date before which nothing can be claimed
End time or durationWhen everything has vested
Release patternLinear, stepped, or a custom curve
Claimed so farHow much the recipient has already withdrawn
Cancel rightsWhether 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.

🧮Worked example

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

ContractChainsHow positions workClaimCancelling
OpenZeppelin VestingWalletAny 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 ownerNot cancelable as written
SablierEVM chainsEach stream is an NFT, with linear, tranched or custom curveswithdrawThe sender can cancel if the stream was created cancelable
HedgeyEVM chainsEach plan is an NFT; there are vesting plans and lockup plansredeemPlansVesting plans can be revoked by their vesting admin; lockup plans can't
StreamflowSolanaEach contract is a program account with an optional cliff amount and periodic releaseswithdrawSet per contract when it's created
Jupiter LockSolanaAn escrow with a cliff amount, then a fixed amount per period for a set number of periodsclaimSet 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

  1. 1Open the contract on Etherscan (or the chain's explorer), check it's verified, and go to Contract, then Read Contract.
  2. 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.
  3. 3On Sablier, enter the stream ID into getDepositedAmount, withdrawableAmountOf and isCancelable.
  4. 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?

OptionProsCons
Vesting platform (Sablier, Hedgey, Streamflow, Magna and others)Audited and maintained; recipients get an app to claim; positions show up in trackersSome charge fees; less room for custom logic
Template (OpenZeppelin VestingWallet)Simple, widely reviewed code; freeYou deploy and verify each contract; no claim app; cancelling needs extra code
Fully custom contractAny logic you needNeeds 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.

Track your own token vesting

Paste any wallet, see every unlock across 13 protocols and 13 chains. Free, no sign-up.

Never miss a token unlock

Vestream tracks every vesting you're owed across 13 protocols and sends a push alert the moment your tokens unlock. Free on iOS and Android.

Download on the App StoreGet it on Google Play

Compare Free and Pro

More from Vestream Resources