Skip to main content

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.

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

​
Overview

Retrieve paginated deposit activity attributed to a specific distributor. Results are ordered by date descending. You can filter by opportunity or product to narrow results.
Looking for wallet-scoped activity across all distributors? See Wallet Activity for deposits and withdrawals by wallet address.

​
Endpoint

​
Get Deposits

curl -X GET "https://earn.turtle.xyz/v1/deposit/your-distributor-id?page=1&limit=20" \
  -H "X-API-Key: pk_live_xxxxx"
Path Parameters
​
distributor_id
string
required
The unique identifier of the distributor to retrieve deposits for.
Query Parameters
​
opportunity_id
uuid
Filter deposits to a specific opportunity.
​
product_id
uuid
Filter deposits to opportunities belonging to a specific product. When combined with opportunity_id, the opportunity must belong to the product — otherwise an empty page is returned.
​
page
integer
default:"1"
Page number for pagination.
​
limit
integer
default:"20"
Number of deposits per page (max: 100).
Response 
{
  "deposits": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "opportunityId": "550e8400-e29b-41d4-a716-446655440000",
      "interaction": "deposit",
      "txHash": "0xedfdf71e0e4daec5afcb87988821a8bccd5c282647c8e81a65a71181a44a8e51",
      "chainId": 1,
      "blockTimestamp": "2025-10-08T16:18:07Z",
      "walletAddress": "0xe84ef330b7b5c02fb3fbe05f2a31cb331c2b874c",
      "amountToken": "89.704738",
      "amountInUsd": "89.73",
      "tokenSymbol": "USDC",
      "tokenIconUrl": "https://icons.llama.fi/usd-coin.jpg",
      "isSwap": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": false
  }
}
​
deposits
array
Array of deposit activity items.
​
deposits[].id
uuid
Unique identifier for the interaction record.
​
deposits[].opportunityId
uuid
The opportunity the deposit was made into.
​
deposits[].interaction
string
Interaction type. Always deposit for this endpoint.
​
deposits[].txHash
string
On-chain transaction hash.
​
deposits[].chainId
integer
Chain ID where the transaction was executed.
​
deposits[].blockTimestamp
string
UTC timestamp of the block containing the transaction (ISO 8601).
​
deposits[].walletAddress
string
The depositor’s wallet address.
​
deposits[].amountToken
string
Deposit amount in token units (human-readable). May be absent if token metadata is unavailable.
​
deposits[].amountInUsd
string
Deposit amount in USD. May be absent if price data is unavailable.
​
deposits[].tokenSymbol
string
Symbol of the deposited token (e.g., USDC). May be absent if token metadata is unavailable.
​
deposits[].tokenIconUrl
string
URL to the token’s icon. May be absent.
​
deposits[].isSwap
boolean
Whether the deposit used swap mode.
​
pagination
object
Pagination metadata.
​
pagination.page
integer
Current page number.
​
pagination.limit
integer
Results per page.
​
pagination.total
integer
Total number of matching deposits.
​
pagination.totalPages
integer
Total number of pages.
​
pagination.hasNext
boolean
Whether a next page exists.
​
pagination.hasPrevious
boolean
Whether a previous page exists.

​
Filter by product

Retrieve deposits scoped to a specific product and its associated opportunities. 
const response = await fetch(
  `https://earn.turtle.xyz/v1/deposit/${distributorId}?product_id=${productId}&page=1&limit=50`,
  { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
);
const { deposits, pagination } = await response.json();

​
Paginate through all deposits

const getAllDeposits = async (distributorId: string) => {
  const all = [];
  let page = 1;

  while (true) {
    const response = await fetch(
      `https://earn.turtle.xyz/v1/deposit/${distributorId}?page=${page}&limit=100`,
      { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
    );
    const { deposits, pagination } = await response.json();
    all.push(...deposits);

    if (!pagination.hasNext) break;
    page++;
  }

  return all;
};

​
Error Handling

Status Code: 404 Not Found
{
  "error": {
    "status": "NOT_FOUND",
    "error": "distributor not found"
  }
}
Solution: Verify your distributor ID is correct and active.
Status Code: 400 Bad Request
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid opportunity_id: not-a-uuid"
  }
}
Solution: Both opportunity_id and product_id must be valid UUIDs.