Opportunities - Turtle Docs

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

Overview

The Opportunities API is how you discover what a user can deposit into. Each opportunity carries its accepted tokens, chain, estimated APR, current TVL, incentives, and which deposit modes it supports. This page is the canonical reference for the Opportunity object; every other endpoint that returns one links here. There are three read endpoints:

GET /v2/opportunities/ lists the full catalog, with optional filters.
GET /v2/opportunities/{id} returns one opportunity by ID.
GET /v2/opportunities/distributors/{distributorId} returns the set configured for a distributor.

For the product context (what configuration is and why you’d scope a set), see Turtle Earn.

Get All Opportunities

Retrieve all available opportunities with simplified token information.

curl -X GET "https://earn.turtle.xyz/v2/opportunities/" \
  -H "X-API-Key: pk_live_xxxxx"

interface OpportunityResponse {
  data: Opportunity[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
}

const response = await fetch('https://earn.turtle.xyz/v2/opportunities/', {
  headers: { 'X-API-Key': 'pk_live_xxxxx' },
});
const data: OpportunityResponse = await response.json();

Query Parameters

chainIds

string

Comma-separated list of chain IDs to filter by. Example: 1,8453,42161 for Ethereum, Base, and Arbitrum.

depositToken

string

Filter by deposit token in the format address-chainId. Example: 0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7-43114.

tvlMin

number

Return only opportunities with TVL at or above this USD value. Example: 1000000 returns opportunities above $1M.

tvlMax

number

Return only opportunities with TVL at or below this USD value.

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "USDC Vault",
      "slug": "usdc-vault",
      "description": "Stable yield on USDC deposits",
      "type": "vault",
      "tvl": 5000000.50,
      "estimatedApr": 8.5,
      "featured": true,
      "minDepositAmountUsd": 0.01,
      "meta": {
        "directInteractionEnabled": true,
        "routedSwapEnabled": true,
        "depositEnabled": true,
        "withdrawEnabled": true,
        "asyncDeposit": false,
        "asyncWithdraw": false,
        "isSecondaryMarket": false,
        "depositDisabledReason": "",
        "withdrawalDisabledReason": ""
      },
      "depositTokens": [
        {
          "symbol": "USDC",
          "address": "0xA0b86991...",
          "chainId": 1,
          "decimals": 6,
          "logoUrl": "https://..."
        }
      ],
      "baseToken": {
        "symbol": "USDC",
        "address": "0xA0b86991...",
        "chainId": 1,
        "decimals": 6,
        "logoUrl": "https://..."
      },
      "receiptToken": {
        "symbol": "tUSDC",
        "address": "0x...",
        "chainId": 1,
        "decimals": 6,
        "logoUrl": "https://..."
      },
      "curator": {
        "id": "curator-uuid",
        "name": "Curator Name",
        "description": "Curator description",
        "iconUrl": "https://...",
        "landingUrl": "https://..."
      },
      "incentives": [
        {
          "id": "incentive-uuid",
          "name": "Incentive Name",
          "description": "Incentive description",
          "iconUrl": "https://...",
          "rewardType": "tokens",
          "rewardTypeName": "Tokens",
          "fdvEstimate": null,
          "tokenSupplyAllocation": null,
          "apr": 0.001,
          "minApr": null,
          "maxApr": null,
          "estPriceUsd": null,
          "indexed": false
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "totalPages": 1
  }
}

Get Opportunity by ID

Retrieve a single opportunity by its unique identifier.

curl -X GET "https://earn.turtle.xyz/v2/opportunities/b91fab34-3998-468b-adcf-645d9b68bc9c" \
  -H "X-API-Key: pk_live_xxxxx"

const opportunityId = 'b91fab34-3998-468b-adcf-645d9b68bc9c';
const response = await fetch(`https://earn.turtle.xyz/v2/opportunities/${opportunityId}`, {
  headers: { 'X-API-Key': 'pk_live_xxxxx' },
});
const opportunity = await response.json();

Path Parameters

uuid

required

Opportunity unique identifier.

Response Returns a single Opportunity object directly, using the structure documented under Response Fields.

Get Distributor Opportunities

Every distributor has a set of opportunities configured in the Client Portal. This endpoint returns only that set: the opportunities your users should see. Use it instead of the full catalog when you want to serve exactly what you have selected for your integration.

curl -X GET "https://earn.turtle.xyz/v2/opportunities/distributors/MpOgVDnc" \
  -H "X-API-Key: pk_live_xxxxx"

const distributorId = 'MpOgVDnc';
const response = await fetch(
  `https://earn.turtle.xyz/v2/opportunities/distributors/${distributorId}`,
  { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
);
const { data, pagination } = await response.json();

Path Parameters

distributorId

string

required

Your distributor ID. Find it under Distribution in the Client Portal.

Response Same shape as Get All Opportunities (a data array plus a pagination object), filtered to the configured set. An empty data array means no opportunities have been configured yet; that is a 200, not an error. Which endpoint to use

Scenario	Endpoint
Power your app with your configured opportunities	Get Distributor Opportunities
Browse the full Turtle catalog to decide what to enable	Get All Opportunities
Load a single opportunity for a detail page	Get Opportunity by ID

How configuration works: select opportunities in the Client Portal, which stores them in the distributor’s earn-details configuration, and this endpoint returns that selection. For the concept and how attribution ties to it, see Distributor Model.

Response Fields

The same Opportunity object is returned by all three endpoints above.

Opportunity Object

uuid

required

Opportunity unique identifier.

name

string

required

Opportunity display name.

slug

string

URL-friendly identifier for the opportunity.

description

string

Opportunity detailed description.

type

string

Opportunity type, for example vault or lending.

tvl

number

Total Value Locked in USD.

estimatedApr

number

Estimated annual percentage rate.

featured

boolean

Whether the opportunity is featured.

minDepositAmountUsd

number

Minimum deposit amount in USD. Deposits below this value are rejected.

Token Object

symbol

string

Token symbol, for example USDC or ETH.

address

string

Token contract address.

chainId

integer

Numeric chain ID the token belongs to.

decimals

integer

ERC20 decimals.

logoUrl

string

Token logo image URL.

Meta Object

directInteractionEnabled

boolean

Whether direct interaction with the opportunity is available. When true, the user can deposit the vault’s native token directly with mode=direct.

routedSwapEnabled

boolean

Whether entering via a routed swap is supported. When true, the user can deposit a different input token with mode=swap and the API routes through a DEX. See Deposit Modes.

depositEnabled

boolean

Whether deposits are currently enabled.

withdrawEnabled

boolean

Whether withdrawals are currently enabled.

asyncDeposit

boolean

Whether deposits settle asynchronously and require a follow-up claim.

asyncWithdraw

boolean

Whether withdrawals settle asynchronously.

isSecondaryMarket

boolean

Whether the opportunity can only be entered via a secondary market.

depositDisabledReason

string

Reason deposits are disabled, if any.

withdrawalDisabledReason

string

Reason withdrawals are disabled, if any.

Curator Object

uuid

Curator organization ID.

name

string

Curator name.

description

string

Curator description.

iconUrl

string

Curator icon image URL.

landingUrl

string

Curator website URL.

Incentive Object

uuid

Incentive unique identifier.

name

string

Incentive name.

description

string

Incentive description.

iconUrl

string

Incentive icon URL.

rewardType

string

Type of reward: points, tokens, yield, or vesting.

rewardTypeName

string

Human-readable reward type name.

apr

number

Annual percentage rate. May be null.

minApr

number

Minimum annual percentage rate. May be null.

maxApr

number

Maximum annual percentage rate. May be null.

fdvEstimate

number

Fully diluted valuation estimate. May be null.

tokenSupplyAllocation

number

Token supply allocation percentage. May be null.

estPriceUsd

number

Estimated price in USD. May be null.

indexed

boolean

Whether the incentive is indexed.

Operational Notes

Determining the deposit flow (instant vs async)

Some vaults settle deposits instantly; others (such as Mellow and Lagoon) are asynchronous and require a follow-up claim. In v2, the meta.asyncDeposit flag signals this: when true, the deposit settles asynchronously and the user must submit a follow-up claim. The meta.asyncWithdraw flag signals the same for withdrawals.

Empty distributor set

GET /v2/opportunities/distributors/{distributorId} returns { "data": [], "pagination": { "page": 1, "limit": 20, "total": 0, "totalPages": 0 } } when nothing is configured. Treat this as a prompt to configure the set in the Client Portal, not as a failure.

Error Handling

Missing or invalid API key

Status Code: 401 UnauthorizedSolution: Pass a valid X-API-Key header. See API Keys.

Opportunity or distributor not found

Status Code: 404 Not Found

{
  "code": 404,
  "status": "NOT_FOUND",
  "error": "distributor not found"
}

Solution: Verify the opportunity ID or distributor ID is correct and active.

Unexpected internal error

Status Code: 500 Internal Server ErrorSolution: Retry with exponential backoff and contact support if it persists.

​Overview

​Get All Opportunities

​Get Opportunity by ID

​Get Distributor Opportunities

​Response Fields

​Opportunity Object

​Token Object

​Meta Object

​Curator Object

​Incentive Object

​Operational Notes

​Error Handling

Overview

Get All Opportunities

Get Opportunity by ID

Get Distributor Opportunities

Response Fields

Opportunity Object

Token Object

Meta Object

Curator Object

Incentive Object

Operational Notes

Error Handling