Skip to main content
Every token stream pays out the same way under the hood. The backend commits a Merkle root of the latest reward snapshot on-chain, and a wallet presents a Merkle proof to the Stream contract to receive its balance. Claims are cumulative: one transaction always pays the full outstanding amount, and claiming when nothing new is owed simply transfers zero. What you choose as a partner is where that claim happens. There are three paths, and they are not exclusive. Most campaigns start on Turtle and add an embedded or delegated flow later.
Claiming applies to token streams only. Point streams have no on-chain claim; points accrue off-chain and convert at a future TGE. Reward timing follows the reward type: TVL-based streams accrue continuously and each Merkle commit makes newly accrued rewards claimable, while deposit-based rewards become claimable at each cliff — there is no mid-cliff claiming.

​
Pick a path

​
1. Through Turtle

The default. LPs connect their wallet on Turtle’s app and claim their accrued rewards there. You do nothing beyond running the stream; Turtle hosts the claim UI, fetches the proofs, and submits the transactions from the LP’s wallet. Your stream shows up in three places in the Turtle app:
  • On the Streams page (app.turtle.xyz/streams), where LPs browse every live, scheduled, and ended stream, with its reward asset, type, schedule, TVL, and estimated reward rate. Each stream has its own page with a deposit simulator and the full terms.
  • On the opportunity page of the vault it pays on, as a badge in the header, a line in the deposit panel’s APR breakdown, and a row in the Incentive Streams table.
  • In Portfolio › Earnings (app.turtle.xyz/portfolio?tab=earnings), where LPs claim. Each claimable balance is a row with a Claim button (or Switch Network when the wallet is on another chain). Deposit-based rewards that have not reached a cliff yet appear under Vesting Rewards on the same tab.
Streams page

The Streams page in the Turtle app.

Portfolio Earnings tab

LPs claim from Portfolio › Earnings.

For the LP-side walkthrough, see Track Your Rewards. This is the right starting point for every campaign. The other two paths are upgrades, not requirements.

​
2. Embedded on your own front end

If you want LPs to claim without leaving your site, embed the claim flow. It is a two-step integration: an API call, then an on-chain transaction signed by the user’s wallet.
1

Fetch the user's Merkle proof

Call GET /v2/streams/merkle_proofs with the user’s wallet address and your stream IDs. The endpoint requires your Turtle API key on the X-API-Key header — a publishable key (pk_live_) works from browser code. The response contains everything the claim needs: the cumulative amount, the proof array, the Stream contract address, and the root timestamp.
2

Show the claimable balance (optional)

Call canClaim() on the Stream contract as a read-only call to display the user’s unclaimed balance before they click claim. It accounts for previous claims automatically.
3

Submit the claim from the user's wallet

Call claim(amount, timestamp, proof) on the Stream contract with the values from the API. The user signs; rewards transfer straight to their wallet.
The API returns the timestamp as an ISO 8601 string, but the contract expects Unix epoch seconds. Convert it before every contract call: Math.floor(new Date(timestamp).getTime() / 1000). This is the most common integration mistake.
If a user has rewards across several streams, claim them all in one transaction with batchClaim() on the StreamFactory instead of one transaction per stream. The full integration guide, including contract ABIs, working code, and a drop-in React claim button, is in the API docs:

Get Merkle Proofs

The proof endpoint: authentication, parameters, response fields, and how they map to the claim call.

Claim Rewards

Contract ABIs, claim and batch-claim code, and the prebuilt React component.

​
3. Delegated claiming (auto-claim)

For a fully managed experience, you can claim on behalf of your users: rewards land in their wallets without them signing anything, and you cover the gas. This runs on the StreamFactory’s operator model.
1

The user approves you as an operator

A one-time on-chain approval: the user calls toggleOperatorForUser() on the StreamFactory to authorize your operator address. The same call revokes the approval later.
2

You claim for them

Your service fetches proofs from the same endpoint, using your API key, then calls batchClaimFor() on the StreamFactory. Rewards transfer to the user’s wallet, not yours.
claim() on the Stream contract can only be called by the user themselves. Delegated claiming always goes through the StreamFactory’s batchClaimFor() with prior operator approval, so a user’s rewards can never be claimed by an address they have not explicitly authorized.
This path suits wallets, exchanges, and platforms whose users expect rewards to just appear, and campaigns where claim gas would otherwise eat into small allocations. The operator calls and code are covered in Claim Rewards.

​
Good to know

  • The proof call needs your API key; the claim itself does not. Fetching Merkle proofs goes through the Earn API and requires an X-API-Key header. The on-chain claim is permissionless — any wallet holding a valid proof can call the contract directly. See API Keys.
  • Claims are cumulative. The proof amount is the user’s total allocation to date. The contract releases only what has not been claimed yet, so LPs never need to claim on a schedule to keep up.
  • Claiming stays open after a stream ends. Rewards committed on-chain remain claimable; ending or pausing a stream does not take anything away from LPs. See Managing a Stream.
  • New balances appear with each Merkle commit. Rewards accrue continuously but become claimable when the next root is committed on-chain, roughly every 12 hours. For deposit-based streams, each tier’s rewards join the claimable balance at that tier’s cliff.