Get Streams

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.

To display the rate a stream is currently distributing, read estimatedLiveApr — not lastSnapshot.apr. lastSnapshot.apr is a historical value tied to its own snapshot timestamp and stays populated forever after a stream is paused or ends. See Live APR vs snapshot APR.

Endpoint

Get all streams

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 -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 -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

uuid

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

uuid

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

boolean

default:"false"

Include the full historical snapshots array for each returned stream.

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
      },
      "estimatedLiveApr": "0.12"
    }
  ]
}

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.

Live APR vs snapshot APR

The response exposes two different APR values, and they answer two different questions.

Field	What it means	When to use it
`estimatedLiveApr`	The rate the stream is currently distributing. Only set while the stream is actively accruing.	Anywhere you show a stream’s present rate.
`lastSnapshot.apr`	The APR computed for that snapshot, valid as of `lastSnapshot.timestamp`.	Historical reporting, charts, reconciliation.

A paused or ended stream keeps its last snapshot indefinitely, so lastSnapshot.apr keeps returning the stream’s final rate long after it stopped distributing. Reading it as the current rate is the mistake estimatedLiveApr exists to prevent. estimatedLiveApr is sourced from lastSnapshot.apr and is null when any of these hold:

the stream has no snapshot yet, or the last snapshot has no apr — for example, point-based streams;
snapshotComputationPaused is true;
the stream has ended — endTimestamp is in the past;
lastSnapshot.timestamp is more than 24 hours old.

The 24-hour bound exists because snapshots accrue every 12 hours, so it tolerates one missed accrual run before the live estimate is withdrawn.

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[]

Stream[]

required

List of confirmed streams matching the provided filters.

`Stream`

uuid

Unique stream identifier.

integer | null

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

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.

uuid | null

Optional user identifier associated with the stream when present.

uuid

Organization that owns the stream.

string | null

Admin EVM address for the stream when applicable.

integer

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

datetime

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

datetime

Timestamp of the most recent update to the stream record.

datetime

UTC start time for the stream.

datetime | null

UTC end time for the stream when configured.

string | null

Total reward amount in base units when applicable.

datetime | null

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

boolean

Whether snapshot computation is paused for the stream.

boolean

Whether merkle tree computation is paused for the stream.

boolean

Whether hash commitment updates are paused for the stream.

boolean

Whether claiming rewards is currently paused for the stream.

object

Strategy-specific configuration object for the stream.

AdapterConfig[]

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

Point | null

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

string

Human-readable strategy name for the stream.

StreamSnapshot | null

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

StreamSnapshot | null

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

StreamSnapshot[]

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

SupportedToken | null

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

string | null

Estimated APR the stream is currently distributing, expressed as a decimal fraction — multiply by 100 for the percentage (for example, 0.12 means 12%).Use this field, not lastSnapshot.apr, whenever you display a stream’s current rate. It is sourced from lastSnapshot.apr but only returned while the stream is actively accruing: it is null when the stream has no snapshot APR, when snapshotComputationPaused is true, when the stream has ended, or when lastSnapshot.timestamp is more than 24 hours old. A null value means no live rate is available — it does not mean 0%. See Live APR vs snapshot APR.

`AdapterConfig`

string

Adapter type identifier.

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.

datetime

Snapshot timestamp.

string

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

string

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

string | null

Merkle root hash when the snapshot has one.

string | null

Transaction hash of the commit operation when available.

datetime

Timestamp when the snapshot record was created.

datetime

Timestamp of the latest update to the snapshot record.

string | null

Total value locked at snapshot time when available.

string | null

Base TVL at snapshot time when available.

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.

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.This is a historical value, valid as of timestamp. On lastSnapshot it keeps returning the stream’s final rate after the stream is paused or ends, so do not treat it as the current rate — use the stream-level estimatedLiveApr for that.

string | null

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

object

Snapshot-specific computed metrics.

object

Snapshot-specific custom arguments.

integer | null

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

integer | null

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

Error Handling

Unexpected internal error

Status Code: 500 Internal Server ErrorSolution: Retry the request and contact Turtle if the issue persists.

Get Started

Products

Reference

Overview

Endpoint

Get all streams

Get streams filtered by organization

Get one stream by ID

Response Example

Response Semantics

Live APR vs snapshot APR

Stream Fields

`Stream`

`AdapterConfig`

`Point`

`StreamSnapshot`

Error Handling

​Overview

​Endpoint

​Get all streams

​Get streams filtered by organization

​Get one stream by ID

​Response Example

​Response Semantics

​Live APR vs snapshot APR

​Stream Fields

​Stream

​AdapterConfig

​Point

​StreamSnapshot

​Error Handling

Overview

Endpoint

Get all streams

Get streams filtered by organization

Get one stream by ID

Response Example

Response Semantics

Live APR vs snapshot APR

Stream Fields

`Stream`

`AdapterConfig`

`Point`

`StreamSnapshot`

Error Handling