> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turtle.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Distributor Opportunities

> Retrieve the curated set of opportunities configured for your distributor.

<Note>
  All requests require an API key via the `X-API-Key` header.
  See [Authentication](/sdk/authentication/api-keys) for details.
</Note>

## Overview

Every distributor on Turtle has a curated set of opportunities configured through the [Turtle Dashboard](https://dashboard.turtle.xyz). This endpoint returns only those opportunities — the ones your users should see.

Use this endpoint instead of [Get All Opportunities](/sdk/opportunities/get-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}`

<CodeGroup>
  ```bash curl theme={null}
  curl "https://earn.turtle.xyz/v1/opportunities/distributors/MpOgVDnc" \
    -H "X-API-Key: pk_live_xxxxx"
  ```

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

  ```python Python theme={null}
  import requests

  distributor_id = "MpOgVDnc"
  response = requests.get(
      f"https://earn.turtle.xyz/v1/opportunities/distributors/{distributor_id}",
      headers={"X-API-Key": "pk_live_xxxxx"}
  )
  data = response.json()
  ```
</CodeGroup>

**Path Parameters**

<ParamField path="distributor_id" type="string" required>
  Your unique distributor ID. Find this in the [Turtle Dashboard](https://dashboard.turtle.xyz) under your distributor settings.
</ParamField>

**Response**

Returns the same Opportunity object structure as [Get All Opportunities](/sdk/opportunities/get-opportunities), filtered to your distributor's configured set.

```json theme={null}
{
  "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](/sdk/opportunities/get-opportunities#response-fields) for the full Opportunity, Token, Chain, and Incentive object reference.

## When to use this endpoint

| Scenario                                                | Endpoint                                                                            |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Power your app with your curated opportunities          | **This endpoint**                                                                   |
| Browse the full Turtle catalog to decide what to enable | [Get All Opportunities](/sdk/opportunities/get-opportunities)                       |
| Fetch a single opportunity by ID for a detail page      | [Get Opportunity by ID](/sdk/opportunities/get-opportunities#get-opportunity-by-id) |

## How curation works

<Steps>
  <Step title="Configure in Dashboard">
    Log in to the [Turtle Dashboard](https://dashboard.turtle.xyz) and navigate to your distributor's opportunity settings. Select which opportunities to surface in your integration.
  </Step>

  <Step title="Saved to earnDetails">
    Your selections are stored in the distributor's `earnDetails` configuration. This controls which opportunities are returned by this endpoint.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  If no opportunities have been configured in the Dashboard, this endpoint returns an empty list. Head to the [Turtle Dashboard](https://dashboard.turtle.xyz) to set up your opportunity selection.
</Info>

## Use Cases

### Power a Custom Earn UI

Fetch your curated opportunities and display them in your UI. Users only see the vaults you've approved.

```typescript theme={null}
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.

```typescript theme={null}
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](/sdk/earn-api/actions/deposit) to build a full earn flow — list your opportunities, let the user pick one, then generate a deposit transaction.

```typescript theme={null}
// 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

<AccordionGroup>
  <Accordion title="Distributor Not Found">
    **Status Code:** 404 Not Found

    ```json theme={null}
    {
      "error": {
        "status": "NOT_FOUND",
        "error": "distributor not found"
      }
    }
    ```

    **Solution:** Verify your distributor ID is correct. Find it in the [Turtle Dashboard](https://dashboard.turtle.xyz).
  </Accordion>

  <Accordion title="Empty Response">
    **Status Code:** 200 OK

    ```json theme={null}
    {
      "opportunities": [],
      "total": 0
    }
    ```

    **This is not an error.** It means no opportunities have been configured for this distributor yet. Go to the [Turtle Dashboard](https://dashboard.turtle.xyz) to select which opportunities to surface.
  </Accordion>
</AccordionGroup>

## Related

* [Distributor Model](/sdk/earn-api/distributor-model) — How distributors work and how attribution is tracked
* [Get All Opportunities](/sdk/opportunities/get-opportunities) — Browse the full Turtle catalog
* [Deposit Action](/sdk/earn-api/actions/deposit) — Generate deposit transactions for an opportunity
* [Distributor Activity](/sdk/earn-api/deposits) — Track deposits attributed to your distributor