> ## 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 Opportunities

> Discover available yield opportunities on Turtle

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

## Overview

The Opportunities API provides access to all available vaults, money markets, and earning opportunities offered by Turtle. Each opportunity includes detailed information about supported tokens, chains, estimated APR, and current TVL (Total Value Locked).

## Endpoints

### Get All Opportunities

Retrieve all available earning opportunities with simplified token information.

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

  ```typescript TypeScript theme={null}
  interface OpportunityResponse {
    opportunities: Opportunity[];
    total: number;
  }

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

**Query Parameters**

<ParamField query="chainIds" type="string">
  Comma-separated list of chain IDs to filter opportunities by.
  Example: `1,8453,42161` for Ethereum, Base, and Arbitrum.
</ParamField>

<ParamField query="depositToken" type="string">
  Filter by deposit token in format `address-chainId`.
  Example: `0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7-43114`
</ParamField>

<ParamField query="tvlGreaterThan" type="number">
  Filter opportunities with TVL greater than this value in USD.
  Example: `1000000` returns only opportunities with TVL above \$1M.
</ParamField>

**Response**

```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": [
        {
          "id": "token-uuid",
          "name": "USD Coin",
          "symbol": "USDC",
          "address": "0xA0b86991...",
          "decimals": 6,
          "logoUrl": "https://...",
          "isNative": false,
          "chain": {
            "id": "chain-uuid",
            "name": "Ethereum",
            "slug": "ethereum",
            "chainId": "1",
            "logoUrl": "https://...",
            "ecosystem": "evm",
            "status": "active",
            "explorerUrl": "https://etherscan.io"
          }
        }
      ],
      "baseToken": {
        "id": "token-uuid",
        "name": "USD Coin",
        "symbol": "USDC",
        "address": "0xA0b86991...",
        "decimals": 6,
        "logoUrl": "https://...",
        "isNative": false,
        "chain": {
          "id": "chain-uuid",
          "name": "Ethereum",
          "slug": "ethereum",
          "chainId": "1",
          "logoUrl": "https://...",
          "ecosystem": "evm",
          "status": "active",
          "explorerUrl": "https://etherscan.io"
        }
      },
      "receiptToken": {
        "id": "token-uuid",
        "name": "Turtle USDC Vault",
        "symbol": "tUSDC",
        "address": "0x...",
        "decimals": 6,
        "logoUrl": "https://...",
        "isNative": false,
        "chain": {
          "id": "chain-uuid",
          "name": "Ethereum",
          "slug": "ethereum",
          "chainId": "1",
          "logoUrl": "https://...",
          "ecosystem": "evm",
          "status": "active",
          "explorerUrl": "https://etherscan.io"
        }
      },
      "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,
          "status": "active",
          "estPriceUsd": null,
          "indexed": false
        }
      ],
      "minDepositAmountUsd": 0.01,
      "swapDirectEnabled": true,
      "swapRouteEnabled": true
    }
  ],
  "total": 12
}
```

### Get Opportunity by ID

Retrieve a specific opportunity by its unique identifier.

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v1/opportunities/b91fab34-3998-468b-adcf-645d9b68bc9c" \
    -H "X-API-Key: pk_live_xxxxx"
  ```

  ```typescript TypeScript theme={null}
  const opportunityId = 'b91fab34-3998-468b-adcf-645d9b68bc9c';
  const response = await fetch(`https://earn.turtle.xyz/v1/opportunities/${opportunityId}`, {
    headers: { 'X-API-Key': 'pk_live_xxxxx' }
  });
  const opportunity: Opportunity = await response.json();
  ```
</CodeGroup>

**Response**

Returns a single Opportunity object with the same structure as shown in the list response above.

### Get Opportunities by Distributor

Returns only the opportunities configured for a specific distributor. See the dedicated [Distributor Opportunities](/sdk/opportunities/distributor-opportunities) page for full documentation, use cases, and examples.

## Response Fields

### Opportunity Object

<ResponseField name="id" type="uuid" required>
  Opportunity unique identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Opportunity display name
</ResponseField>

<ResponseField name="description" type="string" required>
  Opportunity detailed description
</ResponseField>

<ResponseField name="type" type="string" required>
  Opportunity type (e.g., vault, lending)
</ResponseField>

<ResponseField name="tvl" type="number" required>
  Total Value Locked in USD
</ResponseField>

<ResponseField name="estimatedApr" type="number" required>
  Estimated Annual Percentage Rate
</ResponseField>

<ResponseField name="featured" type="boolean" required>
  Whether opportunity is featured
</ResponseField>

<ResponseField name="depositTokens" type="Token[]" required>
  Tokens accepted for deposit
</ResponseField>

<ResponseField name="baseToken" type="Token" required>
  Base token for the opportunity
</ResponseField>

<ResponseField name="receiptToken" type="Token" required>
  Token received as receipt for deposits
</ResponseField>

<ResponseField name="incentives" type="Incentive[]" required>
  Available incentives for this opportunity
</ResponseField>

<ResponseField name="minDepositAmountUsd" type="number">
  Minimum deposit amount in USD. Deposits below this value will be rejected.
</ResponseField>

<ResponseField name="swapDirectEnabled" type="boolean">
  Whether direct deposit mode is available for this opportunity. When true
  the user can deposit the vault's native token directly using `mode=direct`.
</ResponseField>

<ResponseField name="swapRouteEnabled" type="boolean">
  Whether swap/route deposit mode is available for this opportunity. When
  true the user can deposit a different input token using `mode=swap` and the
  API will route through a DEX automatically.
</ResponseField>

### Token Object

<ResponseField name="id" type="uuid" required>
  Token unique identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Token full name
</ResponseField>

<ResponseField name="symbol" type="string" required>
  Token symbol (e.g., USDC, ETH)
</ResponseField>

<ResponseField name="address" type="string" required>
  Token contract address
</ResponseField>

<ResponseField name="decimals" type="integer" required>
  Token decimal places
</ResponseField>

<ResponseField name="logoUrl" type="string" required>
  Token logo image URL
</ResponseField>

<ResponseField name="isNative" type="boolean" required>
  Whether token is native to the chain
</ResponseField>

<ResponseField name="chain" type="Chain" required>
  Chain information where token exists
</ResponseField>

### Chain Object

<ResponseField name="id" type="uuid" required>
  Chain unique identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Chain full name
</ResponseField>

<ResponseField name="slug" type="string" required>
  Chain URL-friendly identifier
</ResponseField>

<ResponseField name="chainId" type="string" required>
  Chain ID for wallet connections
</ResponseField>

<ResponseField name="logoUrl" type="string" required>
  Chain logo image URL
</ResponseField>

<ResponseField name="ecosystem" type="string" required>
  Blockchain ecosystem (e.g., EVM, Solana)
</ResponseField>

<ResponseField name="status" type="string" required>
  Chain operational status
</ResponseField>

<ResponseField name="explorerUrl" type="string" required>
  Block explorer base URL
</ResponseField>

### Incentive Object

<ResponseField name="id" type="uuid" required>
  Incentive unique identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Incentive name
</ResponseField>

<ResponseField name="description" type="string" required>
  Incentive description
</ResponseField>

<ResponseField name="iconUrl" type="string" required>
  Incentive icon URL
</ResponseField>

<ResponseField name="rewardType" type="string" required>
  Type of reward (points, tokens, yield, vesting)
</ResponseField>

<ResponseField name="rewardTypeName" type="string" required>
  Human-readable reward type name
</ResponseField>

<ResponseField name="fdvEstimate" type="number">
  Fully Diluted Valuation estimate
</ResponseField>

<ResponseField name="tokenSupplyAllocation" type="number">
  Token supply allocation percentage
</ResponseField>

<ResponseField name="apr" type="number">
  Annual Percentage Rate
</ResponseField>

<ResponseField name="minApr" type="number">
  Minimum Annual Percentage Rate
</ResponseField>

<ResponseField name="maxApr" type="number">
  Maximum Annual Percentage Rate
</ResponseField>

<ResponseField name="status" type="string" required>
  Incentive status (active, paused, ended)
</ResponseField>

<ResponseField name="estPriceUsd" type="number">
  Estimated price in USD
</ResponseField>

<ResponseField name="indexed" type="boolean" required>
  Whether incentive is indexed
</ResponseField>

## Related Endpoints

* [Deposit](/sdk/earn-api/actions/deposit) - Generate deposit transactions for an opportunity
* [Get Activity](/sdk/earn-api/deposits) - Track and query deposits through your distributor
* [Membership API](/sdk/authentication/register-wallet) - Connect wallets and create user memberships