Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.turtle.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
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 /v1/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. 
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 claimFor(address user, uint256 amount, uint40 timestamp, bytes32[] merkleProof) external returns (uint256)",
  "function getRewardToken() external view returns (address)"
];
FunctionTypePurpose
claimWriteClaim rewards for the connected wallet
canClaimViewReturns the unclaimed amount — use for display
getClaimedRewardsViewReturns total already claimed by a user
claimForWriteClaim on behalf of another user
getRewardTokenViewReturns the reward token address

​
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/v1/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/v1/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);

​
Claim on behalf of a user

The claimFor() function lets a relayer or backend service claim on behalf of a user. The rewards are still sent to the user’s wallet — the caller just submits the transaction.
TypeScript
const timestamp = Math.floor(new Date(proof.timestamp).getTime() / 1000);

const tx = await contract.claimFor(
  userAddress,        // recipient — rewards go to this wallet
  proof.amount,
  timestamp,
  proof.proof
);

​
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/v1/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/v1/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

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.
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.
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).
Each stream has its own contract. If a user has rewards in multiple streams, you need to submit a separate claim() transaction for each one. The React component above handles this automatically.
Calling claim() when there is nothing new to claim will succeed but transfer zero tokens. There is no penalty for calling it multiple times.