Opportunities

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 the Distribution overview.

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

string

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

string

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

number

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

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

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.

string

required

Opportunity display name.

string

URL-friendly identifier for the opportunity.

string

Opportunity detailed description.

string

Opportunity type, for example vault or lending.

number

Total Value Locked in USD.

number

Estimated annual percentage rate.

boolean

Whether the opportunity is featured.

number

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

OpportunityMeta

Interaction and availability flags for the opportunity. See Meta Object.

Token[]

Tokens accepted for deposit.

Token

Base token for the opportunity.

Token

Token received as a receipt for deposits.

Curator

Curator organization for the opportunity.

Incentive[]

Incentives available on this opportunity.

Token Object

string

Token symbol, for example USDC or ETH.

string

Token contract address.

integer

Numeric chain ID the token belongs to.

integer

ERC20 decimals.

string

Token logo image URL.

Meta Object

boolean

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

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.

boolean

Whether deposits are currently enabled.

boolean

Whether withdrawals are currently enabled.

boolean

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

boolean

Whether withdrawals settle asynchronously.

boolean

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

string

Reason deposits are disabled, if any.

string

Reason withdrawals are disabled, if any.

Curator Object

uuid

Curator organization ID.

string

Curator name.

string

Curator description.

string

Curator icon image URL.

string

Curator website URL.

Incentive Object

uuid

Incentive unique identifier.

string

Incentive name.

string

Incentive description.

string

Incentive icon URL.

string

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

string

Human-readable reward type name.

number

Annual percentage rate. May be null.

number

Minimum annual percentage rate. May be null.

number

Maximum annual percentage rate. May be null.

number

Fully diluted valuation estimate. May be null.

number

Token supply allocation percentage. May be null.

number

Estimated price in USD. May be null.

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.

Get Started

Products

Reference

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

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