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.

This endpoint is permissionless — no API key is required. Merkle proofs are public data that anyone can verify on-chain.

​
Overview

GET /v1/streams/merkle_proofs returns Merkle proofs for a wallet across one or more token streams. Each proof contains everything needed to call claim() on the stream’s smart contract: the cumulative allocation amount, the proof array, the contract address, and the chain ID. Use this endpoint when building a claim UI on a partner website or in any frontend that needs to submit on-chain claim transactions.
This endpoint returns proofs for token-based streams only. Point-based streams do not have on-chain Merkle trees.

​
Endpoint

curl -X GET "https://earn.turtle.xyz/v1/streams/merkle_proofs?wallet=0x...&streamIds=7e9c407e-3992-4587-b8e7-9a30f96b12b5"
To query multiple streams, repeat the streamIds parameter: 
curl -X GET "https://earn.turtle.xyz/v1/streams/merkle_proofs?wallet=0x...&streamIds=7e9c407e-3992-4587-b8e7-9a30f96b12b5&streamIds=6ab3c09e-a384-436e-ba8b-c30d249bdf83"
Query Parameters
​
wallet
string
required
The user’s EVM wallet address.
​
streamIds
string[]
required
One or more stream UUIDs to fetch proofs for. Repeat the parameter for multiple streams. You can find your stream IDs via Get Streams or from your Turtle dashboard.

​
Response Example

{
  "proofs": [
    {
      "streamId": "7e9c407e-3992-4587-b8e7-9a30f96b12b5",
      "chainId": 8453,
      "contractAddress": "0x...",
      "amount": "1500000000000000000000",
      "proof": [
        "0xabc123...",
        "0xdef456...",
        "0x789012..."
      ],
      "rootHash": "0x...",
      "timestamp": "2026-05-20T13:05:10Z"
    }
  ]
}

​
Response Fields

​
proofs
StreamMerkleProof[]
required
Array of Merkle proofs, one per requested stream where the wallet has an allocation.

​
StreamMerkleProof

​
streamId
uuid
The stream this proof belongs to.
​
chainId
integer
Decimal EVM chain ID where the stream contract is deployed (e.g. 8453 for Base, 1 for Ethereum).
​
contractAddress
string
The stream contract address to call claim() on.
​
amount
string
Total cumulative allocation in raw token units. This is the total ever allocated to the wallet, not the unclaimed balance. The contract tracks what has already been claimed. Call getRewardToken() on the stream contract to look up the token’s decimals for display formatting.
​
proof
string[]
Array of bytes32 hashes for Merkle verification, passed directly to the contract’s claim() function.
​
rootHash
string
The Merkle root hash this proof was generated against.
​
timestamp
string
ISO 8601 timestamp of the Merkle root used for validation. Passed to the contract as a uint40.

​
Operational Notes

The amount field is cumulative — it represents the wallet’s total allocation across all snapshots, not a per-snapshot delta. The on-chain contract tracks how much has already been claimed and releases the difference when claim() is called.
Proofs are recomputed on each snapshot cycle. Between snapshots, the same proof data is returned. There is no need to poll this endpoint — fetch once when the user is ready to claim.
If the wallet has no allocation in any of the requested streams, the proofs array will be empty. This is not an error — it means the wallet is not a participant in those streams.
Pass amount, timestamp, and proof directly to the stream contract’s claim() function. See Claim Rewards for the full on-chain integration guide.

​
Error Handling

Status Code: 400 Bad Request
{
  "error": "wallet and streamIds are required"
}
Solution: Ensure both wallet and at least one streamIds parameter are present.
Status Code: 500 Internal Server ErrorSolution: Retry the request and contact Turtle if the issue persists.