Get Tokens - Turtle Docs

Overview

GET /v2/streams/tokens returns the active tokens supported for stream creation on a specific chain. This is a public endpoint — no API key is required. Use this endpoint in two different ways:

To resolve the tokens that can be used as targetTokenId inside stream customArgs.
To resolve the tokens that can be used as rewardTokenId for token-based streams.

For reward-token selection, use the tokens where isAllowedRewardToken is true.

The chainId query parameter for this endpoint is the decimal EVM chain ID.

Supported Chains by Use Case

`targetTokenId` chains

For targetTokenId, this endpoint can be queried with any of the following decimal chain IDs.

Mainnet

Chain	Decimal chainId
`Abstract`	`2741`
`Arbitrum`	`42161`
`Avalanche`	`43114`
`Base`	`8453`
`BeraChain`	`80094`
`Blast`	`81457`
`BSC`	`56`
`Ethereum`	`1`
`Fraxtal`	`238`
`Gnosis`	`100`
`HyperEVM`	`999`
`Ink`	`57073`
`Katana`	`747474`
`Linea`	`59144`
`Linea-Sepolia`	`59141`
`Manta`	`169`
`Mantle`	`5000`
`Metis`	`1088`
`Mezo`	`31612`
`Mode Network`	`34443`
`Monad`	`143`
`Optimism`	`10`
`Peaq`	`3338`
`Plasma`	`9745`
`Polygon`	`137`
`Polygon zkEVM`	`1101`
`Scroll`	`534352`
`Sonic`	`146`
`Swell`	`1923`
`TAC`	`239`
`Unichain`	`130`
`Worldchain`	`480`
`XLayer`	`196`
`Zircuit`	`48900`
`ZkSync`	`324`

Testnet

Chain	Decimal chainId
`Sepolia`	`11155111`
`Linea-Sepolia`	`59141`

`rewardToken` chains

This same endpoint is also used for rewardToken, but stream creation currently supports rewardToken only on these 5 networks:

Mainnet

Chain	Decimal chainId
`Ethereum`	`1`
`Base`	`8453`
`Avalanche`	`43114`
`BSC`	`56`

Testnet

Chain	Decimal chainId
`Sepolia`	`11155111`

Sepolia is included here specifically so you can test stream creation with rewardToken before moving to mainnet. If you need TURTLE test tokens on Sepolia (0xa78559593289728719bc46e7559ebdee5bc5ef7a) for testing, please contact the Turtle team to request them. On any of those supported networks, a stream can use both values on the same chain: a rewardToken for the reward asset and a targetTokenId inside customArgs for the tracked target token. The difference is not that they must belong to different chains. The difference is that rewardToken is currently limited to this smaller subset, while targetTokenId supports the broader list above.

Endpoint

curl -X GET "https://earn.turtle.xyz/v2/streams/tokens?chainId=1"

const chainId = 1;

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

const data = await response.json();

Query Parameters

chainId

integer

required

Decimal EVM chain ID. This is required. Use the decimal chainId values listed above.

Response Example

{
  "tokens": [
    {
      "id": "56b0fab0-5c3e-49f6-a0a7-57e38d5ea999",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "chainId": 1,
      "logoUrl": "https://cdn.example.com/tokens/usdc.png",
      "isAllowedRewardToken": true
    },
    {
      "id": "9f6ef77b-3ea5-4d2c-8d64-91e9e4c8b123",
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "chainId": 1,
      "logoUrl": "https://cdn.example.com/tokens/usdt.png",
      "isAllowedRewardToken": false
    }
  ]
}

Response Fields

tokens: SupportedToken[]

tokens

SupportedToken[]

List of active tokens that can be used for streams on the requested chain.

`SupportedToken` fields

uuid

Unique token identifier in Turtle’s config catalog.

address

string

Token contract address.

name

string

Token name.

symbol

string

Token symbol.

decimals

integer

Decimal precision used by the token.

chainId

integer

Decimal EVM chain ID for the token.

logoUrl

string

Token logo URL.

isAllowedRewardToken

boolean

Whether the token can be used as rewardTokenId for token-based stream creation on that chain.

Important Notes

chainId is required

Requests without chainId, or with chainId = 0, are rejected with 400 Invalid Argument.

Only active non-native tokens are returned

The handler excludes inactive tokens and filters out native assets, so this endpoint returns the currently usable non-native token set for stream creation.

rewardToken and targetTokenId can coexist on the same chain

A stream can use both a rewardToken and a targetTokenId on the same supported network. The distinction here is support scope, not mutual exclusion: rewardToken is currently limited to the 5-chain subset listed above, while targetTokenId supports the broader chain list documented on this page.

Use `isAllowedRewardToken == true` for reward-token selection

When selecting a rewardTokenId for POST /v2/streams/, choose one of the returned tokens where isAllowedRewardToken is true. Tokens with isAllowedRewardToken = false can still be valid for other use cases such as targetTokenId, but not as the stream reward token.

Use the decimal chainId from this page

When calling this endpoint, send the decimal EVM chainId shown in the tables above.

Error Handling

Missing chainId

Status Code: 400 Bad Request

{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "chainId is required"
  }
}

Solution: Send a valid decimal EVM chain ID in the chainId query parameter.

Unexpected internal error

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

​Overview

​Supported Chains by Use Case

​targetTokenId chains

​Mainnet

​Testnet

​rewardToken chains

​Mainnet

​Testnet

​Endpoint

​Response Example

​Response Fields

​SupportedToken fields

​Important Notes

​Error Handling

Overview

Supported Chains by Use Case

`targetTokenId` chains

Mainnet

Testnet

`rewardToken` chains

Mainnet

Testnet

Endpoint

Response Example

Response Fields

`SupportedToken` fields

Important Notes

Error Handling