Get Streams - Turtle Docs

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

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`

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 ErrorSolution: Retry the request and contact Turtle if the issue persists.

​Overview

​Endpoint

​Get all streams

​Get streams filtered by organization

​Get one stream by ID

​Response Example

​Response Semantics

​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

Stream Fields

`Stream`

`AdapterConfig`

`Point`

`StreamSnapshot`

Error Handling