Get Streams

Retrieve confirmed streams, optionally filtered by stream ID or organization ID

Overview

GET /v2/streams/ returns confirmed streams. This is a public endpoint — no API key is required.

• If no query parameters are sent, the endpoint returns all confirmed streams.
• Use id to retrieve a specific stream by its UUID.
• Use orgId to filter results to streams belonging to a specific organization.

This endpoint is intended for backoffice dashboards, reporting tools, campaign managers, and partner integrations that need to inspect stream configurations.

Endpoint

Get all streams

curl

curl -X GET "https://earn.turtle.xyz/v2/streams/?withSnapshots=false&usersCount=false"

const response = await fetch(
  'https://earn.turtle.xyz/v2/streams/?withSnapshots=false&usersCount=false'
);

const data = await response.json();

Get streams filtered by organization

curl

curl -X GET "https://earn.turtle.xyz/v2/streams/?orgId=9f51b66a-d13a-4b55-8515-ae6e4ef7cf25"

const orgId = '9f51b66a-d13a-4b55-8515-ae6e4ef7cf25';

const response = await fetch(
  `https://earn.turtle.xyz/v2/streams/?orgId=${orgId}`
);

const data = await response.json();

Get one stream by ID

curl

curl -X GET "https://earn.turtle.xyz/v2/streams/?id=550e8400-e29b-41d4-a716-446655440000&withSnapshots=true&usersCount=true"

const streamId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://earn.turtle.xyz/v2/streams/?id=${streamId}&withSnapshots=true&usersCount=true`
);

const data = await response.json();

Query Parameters

id · uuid

Optional stream identifier. When provided, the endpoint filters the result set to that stream ID.

orgId · uuid

Optional organization identifier. When provided, the endpoint returns only streams belonging to that organization.

withSnapshots · boolean · default: "false"

Include the full historical snapshots array for each returned stream.

usersCount · boolean · default: "false"

Add userCount and activeUserCount to each included snapshot object.

Response Example

{
  "streams": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "chainId": 1,
      "contractAddress": "0x4C6F5a1aA2B9985d4A8b9189C2118E7f55E2f701",
      "userId": null,
      "orgId": "9f51b66a-d13a-4b55-8515-ae6e4ef7cf25",
      "admin": "0x1111111111111111111111111111111111111111",
      "type": 2,
      "createdAt": "2026-03-10T12:00:00Z",
      "updatedAt": "2026-03-10T12:15:00Z",
      "startTimestamp": "2026-03-11T00:00:00Z",
      "endTimestamp": "2026-04-11T00:00:00Z",
      "totalAmount": "2500000000000000000000",
      "creationConfirmedAt": "2026-03-10T12:04:32Z",
      "snapshotComputationPaused": false,
      "merkleTreeComputationPaused": true,
      "hashCommitmentPaused": true,
      "claimPaused": true,
      "customArgs": {
        "targetTokenId": "8cc2ed9d-bd59-42fd-9df5-329fa22497b6",
        "apr": "0.12",
        "targetToken": {
          "id": "8cc2ed9d-bd59-42fd-9df5-329fa22497b6",
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": 6,
          "isNative": false,
          "logoUrl": "https://...",
          "chain": {
            "id": "f4c8c3d9-6ae5-4dfa-8d33-7d7bb0a9e73c",
            "name": "Ethereum",
            "slug": "ethereum",
            "chainId": "1",
            "isTestnet": false,
            "logoUrl": "https://...",
            "ecosystem": "evm",
            "status": "active",
            "explorerUrl": "https://etherscan.io"
          },
          "active": true,
          "priceUsd": 1,
          "canonicalAssetId": "f4a35f17-7482-4d93-bc75-2ebd4f483d22",
          "streamsMinAmount": "1000000",
          "totalTurtleTvl": 10234567.12
        }
      },
      "adapters": [],
      "point": null,
      "strategy": "Fixed APR",
      "lastSnapshot": {
        "timestamp": "2026-03-11T00:00:00Z",
        "amountDistributed": "8123456789012345678",
        "amountBase": "8123456789012345678",
        "rootHash": null,
        "commitTxHash": null,
        "createdAt": "2026-03-11T00:01:00Z",
        "updatedAt": "2026-03-11T00:01:00Z",
        "tvl": "152340.12",
        "baseTvl": "152340.12",
        "baseApr": "0.105",
        "apr": "0.12",
        "rewardTokenPrice": "1.00",
        "customMetrics": {},
        "customArgs": {},
        "userCount": 124,
        "activeUserCount": 118
      },
      "committedSnapshot": null,
      "snapshots": [],
      "rewardToken": {
        "id": "56b0fab0-5c3e-49f6-a0a7-57e38d5ea999",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "chainId": 1,
        "logoUrl": "https://...",
        "isAllowedRewardToken": true
      }
    }
  ]
}

Response Semantics

No parameters means list all streams

If you omit all query parameters, the endpoint returns all confirmed streams across all organizations.

id is a filter, not a path selector

If you send id, the endpoint still returns a streams array. The array will contain either one matching stream or be empty if no stream with that ID exists.

orgId narrows results to one organization

If you send orgId, only streams belonging to that organization are returned. You can combine orgId with id to look up a specific stream within a specific organization.

Stream Fields

The response body contains a streams array. Each item in that array is a Stream object with the fields described below.

streams: Stream[]

streams · Stream[] · required

List of confirmed streams matching the provided filters.

Stream

id · uuid

Unique stream identifier.

chainId · integer | null

Decimal EVM chain ID for on-chain streams. null for point-based streams that do not deploy a contract.

contractAddress · string | null

Deployed on-chain stream contract address when available. It can be null for point-based streams or token-based streams that are still pending confirmation.

userId · uuid | null

Optional user identifier associated with the stream when present.

orgId · uuid

Organization that owns the stream.

admin · string | null

Admin EVM address for the stream when applicable.

type · integer

Stream type. Supported values are 1 (Fixed Rate), 2 (Fixed APR), 3 (Daily Budget), 4 (Airdrop), and 5 (Yield Match).

createdAt · datetime

Timestamp when the stream record was created in Turtle’s backend.

updatedAt · datetime

Timestamp of the most recent update to the stream record.

startTimestamp · datetime

UTC start time for the stream.

endTimestamp · datetime | null

UTC end time for the stream when configured.

totalAmount · string | null

Total reward amount in base units when applicable.

creationConfirmedAt · datetime | null

Confirmation timestamp for stream creation. It can be null while a token-based stream is still pending on-chain creation.

snapshotComputationPaused · boolean

Whether snapshot computation is paused for the stream.

merkleTreeComputationPaused · boolean

Whether merkle tree computation is paused for the stream.

hashCommitmentPaused · boolean

Whether hash commitment updates are paused for the stream.

claimPaused · boolean

Whether claiming rewards is currently paused for the stream.

customArgs · object

Strategy-specific configuration object for the stream.

adapters · AdapterConfig[]

Persisted adapter configuration array. Each adapter item contains a type string and a params object.

point · Point | null

Point metadata when the stream uses a point-based reward source. null for token-based streams.

strategy · string

Human-readable strategy name for the stream.

lastSnapshot · StreamSnapshot | null

Most recent snapshot computed for the stream, if one exists.

committedSnapshot · StreamSnapshot | null

Most recent committed snapshot for the stream, if one exists.

snapshots · StreamSnapshot[]

Full snapshot history when withSnapshots=true. Otherwise this field can be empty or omitted.

rewardToken · SupportedToken | null

Reward-token metadata for token-based streams. This uses the public SupportedToken shape from Get Tokens.

AdapterConfig

type · string

Adapter type identifier.

params · object

Adapter-specific configuration object.

Point

See Get Points for the full Point schema and examples.

StreamSnapshot

APR-related snapshot fields are only populated for token-based streams. For point-based streams, baseApr, apr, and rewardTokenPrice are omitted from the snapshot.

timestamp · datetime

Snapshot timestamp.

amountDistributed · string

Amount distributed in the snapshot, encoded as a decimal string.

amountBase · string

Base amount used for the snapshot, encoded as a decimal string.

rootHash · string | null

Merkle root hash when the snapshot has one.

commitTxHash · string | null

Transaction hash of the commit operation when available.

createdAt · datetime

Timestamp when the snapshot record was created.

updatedAt · datetime

Timestamp of the latest update to the snapshot record.

tvl · string | null

Total value locked at snapshot time when available.

baseTvl · string | null

Base TVL at snapshot time when available.

baseApr · string | null

Base APR computed for the snapshot before adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, 0.05 means 5%). This is only populated for token-based streams.

apr · string | null

Effective APR computed for the snapshot after adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, 0.05 means 5%). This is only populated for token-based streams.

rewardTokenPrice · string | null

Time-weighted-average (TWA) USD price of the reward token across the snapshot interval. This is only populated for token-based streams.

customMetrics · object

Snapshot-specific computed metrics.

customArgs · object

Snapshot-specific custom arguments.

userCount · integer | null

Number of users represented in the snapshot when usersCount=true.

activeUserCount · integer | null

Number of active users represented in the snapshot when usersCount=true.

Error Handling

Unexpected internal error

Status Code: 500 Internal Server Error

Solution: Retry the request and contact Turtle if the issue persists.