Get Streams

All requests require an API key via the X-API-Key header. See Authentication for details.

Overview

GET /v1/streams/ returns streams scoped to the organization that owns the API key used in the request.

If no id query parameter is sent, the endpoint returns all confirmed streams for that organization.
If id is sent, the endpoint returns at most one stream: the stream whose identifier matches the provided value and belongs to the calling organization.

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

This endpoint is organization-scoped by design. It does not return streams belonging to other organizations, even if their IDs are known.

Endpoint

Get all streams for the calling organization

curl -X GET "https://earn.turtle.xyz/v1/streams/?withSnapshots=false&usersCount=false" \
  -H "X-API-Key: sk_live_xxxxx"

Get one stream by ID within the organization scope

curl -X GET "https://earn.turtle.xyz/v1/streams/?id=550e8400-e29b-41d4-a716-446655440000&withSnapshots=true&usersCount=true" \
  -H "X-API-Key: sk_live_xxxxx"

Query Parameters

uuid

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

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",
        "netTvl": "149100.20",
        "turtleTvl": "152340.12",
        "turtleNetTvl": "149100.20",
        "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 id means list all streams for the organization

If you omit id, the endpoint returns all confirmed streams belonging to the organization associated with the API key.

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 the stream does not exist in the caller’s organization scope.

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 streams visible to the organization that owns the API key.

`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), and 3 (Variable Rate).

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`

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.

netTvl

string | null

Net TVL at snapshot time when available.

turtleTvl

string | null

Turtle TVL at snapshot time when available.

turtleNetTvl

string | null

Turtle net TVL at snapshot time when available.

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

Missing or invalid API key

Status Code: 401 Unauthorized

{
  "error": "Invalid API key"
}

Solution: Pass a valid X-API-Key header belonging to an organization-scoped API key.

Unexpected internal error

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

Earn API

Streams API

Actions API

Overview

Endpoint

Get all streams for the calling organization

Get one stream by ID within the organization scope

Response Example

Response Semantics

Stream Fields

`Stream`

`AdapterConfig`

`Point`

`StreamSnapshot`

Error Handling

Earn API

Streams API

Actions API

​Overview

​Endpoint

​Get all streams for the calling organization

​Get one stream by ID within the organization scope

​Response Example

​Response Semantics

​Stream Fields

​Stream

​AdapterConfig

​Point

​StreamSnapshot

​Error Handling

Overview

Endpoint

Get all streams for the calling organization

Get one stream by ID within the organization scope

Response Example

Response Semantics

Stream Fields

`Stream`

`AdapterConfig`

`Point`

`StreamSnapshot`

Error Handling