Claim Rewards

Integrate on-chain reward claiming for token streams into your application

Overview

Claiming rewards from a token stream is a two-step process:

1. Fetch the Merkle proof from the Turtle API (Get Merkle Proofs)
2. Submit a claim transaction to the stream’s smart contract on-chain

No API key is needed for either step. Proofs are permissionless, and claiming is a direct on-chain interaction.

Your Application
    ↓ 1. GET /v2/streams/merkle_proofs
earn.turtle.xyz
    ↓ 2. Returns proof + amount + timestamp + contract address
Your Application
    ↓ 3. Build claim transaction
Stream Contract (on-chain)
    ↓ 4. User signs & submits
Rewards transferred to user wallet

Contract ABI

The stream contract exposes the following functions for claiming and display. This ABI is sufficient for all claim integration scenarios.

Stream contract

Each stream is a separate contract. The address is returned in the Merkle proof API response as contractAddress.

const STREAM_ABI = [
  "function claim(uint256 amount, uint40 timestamp, bytes32[] merkleProof) external returns (uint256)",
  "function canClaim(address user, uint256 amount, uint40 timestamp, bytes32[] merkleProof) external view returns (uint256)",
  "function getClaimedRewards(address user) external view returns (uint256)",
  "function getRewardToken() external view returns (address)"
];

Function	Type	Purpose
claim	Write	Claim rewards for the connected wallet
canClaim	View	Returns the unclaimed amount (use for display)
getClaimedRewards	View	Returns total already claimed by a user
getRewardToken	View	Returns the reward token address

StreamFactory contract

The StreamFactory owns all stream contracts and provides batch operations. Use it to claim from multiple streams in a single transaction.

const STREAM_FACTORY_ABI = [
  "function batchClaim((address stream, uint256 amount, uint40 rootTimestamp, bytes32[] merkleProof)[] claims, bool revertOnFailure) external returns (bool[])",
  "function batchClaimFor(address user, (address stream, uint256 amount, uint40 rootTimestamp, bytes32[] merkleProof)[] claims, bool revertOnFailure) external returns (bool[])",
  "function toggleOperatorForUser(address user, address operator) external"
];

Function	Type	Purpose
batchClaim	Write	Claim from multiple streams in one transaction
batchClaimFor	Write	Claim on behalf of a user (requires operator approval)
toggleOperatorForUser	Write	Approve or revoke an operator for a user

Show claimable amount

Call canClaim() as a staticCall (no gas, no transaction) to display the unclaimed balance before the user clicks “Claim.” It takes the same parameters from the Merkle proof API response plus the user’s address.

import { ethers } from 'ethers';

const STREAM_ABI = [
  "function canClaim(address user, uint256 amount, uint40 timestamp, bytes32[] merkleProof) external view returns (uint256)",
];

// 1. Fetch proof from Turtle API
const res = await fetch(
  `https://earn.turtle.xyz/v2/streams/merkle_proofs?wallet=${userAddress}&streamIds=${streamId}`
);
const { proofs } = await res.json();
const proof = proofs[0];

// 2. Convert timestamp from ISO 8601 to Unix epoch (uint40)
const timestamp = Math.floor(new Date(proof.timestamp).getTime() / 1000);

// 3. Call canClaim (staticCall, no gas)
const provider = new ethers.BrowserProvider(window.ethereum);
const contract = new ethers.Contract(proof.contractAddress, STREAM_ABI, provider);

const claimable = await contract.canClaim(
  userAddress,
  proof.amount,
  timestamp,
  proof.proof
);

console.log('Claimable:', ethers.formatUnits(claimable, 18));

canClaim() returns the actual unclaimed amount. No additional math required. It accounts for previous claims automatically.

Claim rewards

Submit a claim() transaction using the proof data. The contract uses a cumulative model: amount is the user’s total allocation across all snapshots, and the contract releases only the difference between the total and what has already been claimed.

import { ethers } from 'ethers';

const STREAM_ABI = [
  "function claim(uint256 amount, uint40 timestamp, bytes32[] merkleProof) external returns (uint256)",
  "function canClaim(address user, uint256 amount, uint40 timestamp, bytes32[] merkleProof) external view returns (uint256)",
];

// 1. Fetch proof
const res = await fetch(
  `https://earn.turtle.xyz/v2/streams/merkle_proofs?wallet=${userAddress}&streamIds=${streamId}`
);
const { proofs } = await res.json();
const proof = proofs[0];

// 2. Convert timestamp from ISO 8601 to Unix epoch (uint40)
const timestamp = Math.floor(new Date(proof.timestamp).getTime() / 1000);

// 3. Connect signer
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const contract = new ethers.Contract(proof.contractAddress, STREAM_ABI, signer);

// 4. (Optional) Show claimable amount first
const claimable = await contract.canClaim(
  userAddress,
  proof.amount,
  timestamp,
  proof.proof
);
console.log('Claimable:', ethers.formatUnits(claimable, 18));

// 5. Submit claim transaction
const tx = await contract.claim(
  proof.amount,       // total cumulative allocation
  timestamp,          // Merkle root timestamp (uint40)
  proof.proof         // Merkle proof (bytes32[])
);

const receipt = await tx.wait();
console.log('Claimed successfully:', receipt.hash);

Batch claiming

If a user has rewards across multiple streams, you can claim all of them in a single transaction using batchClaim() on the StreamFactory instead of calling claim() on each stream contract separately.

import { ethers } from 'ethers';

const STREAM_FACTORY_ABI = [
  "function batchClaim((address stream, uint256 amount, uint40 rootTimestamp, bytes32[] merkleProof)[] claims, bool revertOnFailure) external returns (bool[])",
];

// 1. Fetch proofs for all streams
const params = new URLSearchParams({ wallet: userAddress });
streamIds.forEach((id) => params.append('streamIds', id));

const res = await fetch(
  `https://earn.turtle.xyz/v2/streams/merkle_proofs?${params}`
);
const { proofs } = await res.json();

// 2. Build batch claims array
const claims = proofs
  .filter((p) => p.amount && p.amount !== '0')
  .map((p) => ({
    stream: p.contractAddress,
    amount: p.amount,
    rootTimestamp: Math.floor(new Date(p.timestamp).getTime() / 1000),
    merkleProof: p.proof,
  }));

// 3. Submit single batch transaction to the StreamFactory
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const factory = new ethers.Contract(STREAM_FACTORY_ADDRESS, STREAM_FACTORY_ABI, signer);

const tx = await factory.batchClaim(claims, true); // revertOnFailure=true
const receipt = await tx.wait();

The StreamFactory address depends on the chain. Contact Turtle or check the block explorer for the deployed address on your target network.

Claim on behalf of a user

To claim on behalf of another user, use batchClaimFor() on the StreamFactory. The caller must first be approved as an operator by the user via toggleOperatorForUser().

// User approves the operator (one-time setup)
const tx1 = await factory.toggleOperatorForUser(userAddress, operatorAddress);
await tx1.wait();

// Operator claims on behalf of the user
const tx2 = await factory.batchClaimFor(userAddress, claims, true);
await tx2.wait();

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.

React component

A drop-in <StreamsClaimButton> component for React/Next.js applications. It fetches proofs, displays the claimable amount, and handles the claim transaction.

import { useState, useEffect } from 'react';
import { ethers } from 'ethers';

const STREAM_ABI = [
  "function claim(uint256 amount, uint40 timestamp, bytes32[] merkleProof) external returns (uint256)",
  "function canClaim(address user, uint256 amount, uint40 timestamp, bytes32[] merkleProof) external view returns (uint256)",
];

interface ClaimButtonProps {
  streamIds: string[];          // stream UUIDs to claim from
  walletAddress: string;        // connected wallet
  provider: ethers.Provider;    // provider for read calls
  signer: ethers.Signer;        // wallet signer for claim tx
  onSuccess?: (receipt: ethers.TransactionReceipt) => void;
  onError?: (error: Error) => void;
}

export function StreamsClaimButton({
  streamIds,
  walletAddress,
  provider,
  signer,
  onSuccess,
  onError,
}: ClaimButtonProps) {
  const [loading, setLoading] = useState(false);
  const [status, setStatus] = useState<string>('');
  const [claimable, setClaimable] = useState<string | null>(null);

  // Fetch proofs and check claimable amount on mount
  useEffect(() => {
    (async () => {
      try {
        const ids = streamIds.join('&streamIds=');
        const res = await fetch(
          `https://earn.turtle.xyz/v2/streams/merkle_proofs?wallet=${walletAddress}&streamIds=${ids}`
        );
        const { proofs } = await res.json();
        if (!proofs || proofs.length === 0) return;

        let total = 0n;
        for (const proof of proofs) {
          if (!proof.amount || proof.amount === '0') continue;
          const contract = new ethers.Contract(
            proof.contractAddress,
            STREAM_ABI,
            provider
          );
          const ts = Math.floor(new Date(proof.timestamp).getTime() / 1000);
          const amount = await contract.canClaim(
            walletAddress,
            proof.amount,
            ts,
            proof.proof
          );
          total += amount;
        }
        setClaimable(ethers.formatUnits(total, 18));
      } catch {
        // Silently fail: button still works without display amount
      }
    })();
  }, [streamIds, walletAddress, provider]);

  const handleClaim = async () => {
    setLoading(true);
    setStatus('Fetching proof...');
    try {
      const ids = streamIds.join('&streamIds=');
      const res = await fetch(
        `https://earn.turtle.xyz/v2/streams/merkle_proofs?wallet=${walletAddress}&streamIds=${ids}`
      );
      const { proofs } = await res.json();

      if (!proofs || proofs.length === 0) {
        setStatus('No claimable rewards found');
        setLoading(false);
        return;
      }

      for (const proof of proofs) {
        if (!proof.amount || proof.amount === '0') continue;

        setStatus(`Claiming from ${proof.contractAddress.slice(0, 8)}...`);
        const ts = Math.floor(new Date(proof.timestamp).getTime() / 1000);
        const contract = new ethers.Contract(
          proof.contractAddress,
          STREAM_ABI,
          signer
        );
        const tx = await contract.claim(
          proof.amount,
          ts,
          proof.proof
        );
        const receipt = await tx.wait();
        onSuccess?.(receipt);
      }

      setClaimable('0');
      setStatus('Claimed!');
    } catch (err) {
      setStatus('Claim failed');
      onError?.(err as Error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button onClick={handleClaim} disabled={loading || claimable === '0'}>
      {loading
        ? status
        : claimable
          ? `Claim ${claimable} tokens`
          : 'Claim Rewards'}
    </button>
  );
}

Usage:

<StreamsClaimButton
  streamIds={['7e9c407e-3992-4587-b8e7-9a30f96b12b5']}
  walletAddress={connectedAddress}
  provider={provider}
  signer={signer}
  onSuccess={(receipt) => console.log('Claimed:', receipt)}
  onError={(err) => console.error('Failed:', err)}
/>

Operational Notes

Cumulative amount model

The amount parameter in claim() is the user’s total cumulative allocation, not the unclaimed delta. The contract tracks how much has already been claimed and releases only the difference. Users can claim at any time and always receive their full outstanding balance in a single transaction.

Amount is in raw token units

The amount from the API is in raw token units. Use ethers.formatUnits(amount, decimals) to convert to a human-readable number for display. Call getRewardToken() on the contract to get the token address, then query the token’s decimals() if needed (most stream reward tokens use 18 decimals). Always pass the raw value to the contract. Do not format it before sending the transaction.

Timestamp conversion

The API returns timestamp as an ISO 8601 string (e.g. "2026-05-20T13:05:10Z"), but the contract expects a uint40 Unix epoch in seconds. Convert before passing to the contract: Math.floor(new Date(proof.timestamp).getTime() / 1000).

Multiple streams

Each stream has its own contract. When calling claim() directly, you need a separate transaction per stream. The React component above handles this automatically. Alternatively, use batchClaim() on the StreamFactory to claim from all streams in a single transaction.

Claiming is idempotent

Calling claim() when there is nothing new to claim will succeed but transfer zero tokens. There is no penalty for calling it multiple times.