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

​
Overview

Every distributor on Turtle has a curated set of opportunities configured through the Turtle Dashboard. This endpoint returns only those opportunities — the ones your users should see. Use this endpoint instead of Get All Opportunities when you want to serve the exact opportunity set you’ve selected for your integration.

​
Endpoint

GET https://earn.turtle.xyz/v1/opportunities/distributors/{distributor_id} 
curl "https://earn.turtle.xyz/v1/opportunities/distributors/MpOgVDnc" \
  -H "X-API-Key: pk_live_xxxxx"
Path Parameters
​
distributor_id
string
required
Your unique distributor ID. Find this in the Turtle Dashboard under your distributor settings.
Response Returns the same Opportunity object structure as Get All Opportunities, filtered to your distributor’s configured set. 
{
  "opportunities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "USDC Vault",
      "description": "Stable yield on USDC deposits",
      "type": "vault",
      "tvl": 5000000.50,
      "estimatedApr": 8.5,
      "featured": true,
      "depositTokens": [Token],
      "baseToken": Token,
      "receiptToken": Token,
      "incentives": [Incentive],
      "minDepositAmountUsd": 0.01,
      "swapDirectEnabled": true,
      "swapRouteEnabled": true
    }
  ],
  "total": 5
}
See Get Opportunities for the full Opportunity, Token, Chain, and Incentive object reference.

​
When to use this endpoint

ScenarioEndpoint
Power your widget or app with your curated opportunitiesThis endpoint
Browse the full Turtle catalog to decide what to enableGet All Opportunities
Fetch a single opportunity by ID for a detail pageGet Opportunity by ID

​
How curation works

1

Configure in Dashboard

Log in to the Turtle Dashboard and navigate to your distributor’s opportunity settings. Select which opportunities to surface in your integration.
2

Saved to earnDetails

Your selections are stored in the distributor’s earnDetails configuration. This controls which opportunities are returned by this endpoint.
3

Call this endpoint

Use GET /v1/opportunities/distributors/{distributor_id} in your frontend to fetch only your curated set. Your users see exactly what you’ve selected.
If no opportunities have been configured in the Dashboard, this endpoint returns an empty list. Head to the Turtle Dashboard to set up your opportunity selection.

​
Use Cases

​
Power an Earn Widget

Fetch your curated opportunities and display them in your UI. Users only see the vaults you’ve approved. 
const getMyOpportunities = async (distributorId: string) => {
  const response = await fetch(
    `https://earn.turtle.xyz/v1/opportunities/distributors/${distributorId}`,
    { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
  );
  const { opportunities } = await response.json();

  // Sort by APR for display
  return opportunities.sort((a, b) => b.estimatedApr - a.estimatedApr);
};

​
Filter by Chain at Runtime

The endpoint returns your full curated set. You can further filter client-side if your UI supports chain switching. 
const getOpportunitiesByChain = async (distributorId: string, chainId: number) => {
  const response = await fetch(
    `https://earn.turtle.xyz/v1/opportunities/distributors/${distributorId}`,
    { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
  );
  const { opportunities } = await response.json();

  return opportunities.filter(opp =>
    opp.depositTokens.some(token => token.chain.chainId === String(chainId))
  );
};

​
Build a Deposit Flow

Combine with the Deposit Action to build a full earn flow — list your opportunities, let the user pick one, then generate a deposit transaction. 
// 1. Fetch your curated opportunities
const { opportunities } = await getMyOpportunities('MpOgVDnc');

// 2. User selects an opportunity
const selected = opportunities[0];

// 3. Generate deposit transaction
const depositResponse = await fetch(
  `https://earn.turtle.xyz/v1/actions/deposit/${selected.id}`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'pk_live_xxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      userAddress: '0x...',
      tokenIn: selected.depositTokens[0].address,
      amount: '1000000', // 1 USDC in wei
      distributorId: 'MpOgVDnc',
      mode: 'direct'
    })
  }
);
const { transactions } = await depositResponse.json();
// 4. Submit transactions to user's wallet for signing

​
Error Handling

Status Code: 404 Not Found
{
  "error": {
    "status": "NOT_FOUND",
    "error": "distributor not found"
  }
}
Solution: Verify your distributor ID is correct. Find it in the Turtle Dashboard.
Status Code: 200 OK
{
  "opportunities": [],
  "total": 0
}
This is not an error. It means no opportunities have been configured for this distributor yet. Go to the Turtle Dashboard to select which opportunities to surface.