Skip to main content

​
Overview

The Deposits API allows you to track all deposits made through a specific distributor. You can filter deposits by referral code and depositor address to monitor specific wallet activities and attribution.

​
Endpoint

​
Get Deposits

Retrieve deposit transactions for a specific distributor with optional filtering. 
curl -X GET "https://earn.turtle.xyz/v1/deposit/your-distributor-id?limit=100&offset=0"
Path Parameters
​
distributor_id
string
required
The unique identifier of the distributor to track deposits for
Query Parameters
​
depositor
string
Filter deposits by a specific wallet address
​
limit
integer
default:"100"
Maximum number of deposits to return (max: 2000)
​
offset
integer
default:"0"
Number of deposits to skip for pagination
Response Example 
{
  "deposits": [
  {
      "tx_hash": "0xedfdf71e0e4daec5afcb87988821a8bccd5c282647c8e81a65a71181a44a8e51",
      "depositor": "0xe84ef330b7b5c02fb3fbe05f2a31cb331c2b874c",
      "deposited_token_address": "0x80c34bd3a3569e126e7055831036aa7b212cb159",
      "deposited_token_decimals": 6,
      "deposited_token_logo": "https://icons.llama.fi/yearn-finance.jpg",
      "deposited_token_name": "vbUSDC yVault",
      "deposited_token_symbol": "yvvbUSDC",
      "deposited_value": "89.7047380783814025568",
      "deposited_amount_usd": "89.728672",
      "target": "0x203a662b0bd271a6ed5a60edfbd04bfce608fd36",
      "chain": 747474,
      "timestamp": "2025-10-08T16:18:07.330449"
    }
  ]
}

​
Use Cases

​
Track All Distributor Deposits

Monitor all deposits made through your distributor to track total volume and activity. 
const getAllDeposits = async (distributorId) => {
  const response = await fetch(
    `https://earn.turtle.xyz/v1/deposit/${distributorId}?limit=1000`
  );
  const { deposits } = await response.json();

  return deposits;
};

​
Track Specific Wallet Deposits

Query deposits from a specific wallet address to understand individual user activity. 
const getWalletDeposits = async (distributorId, walletAddress) => {
  const response = await fetch(
    `https://earn.turtle.xyz/v1/deposit/${distributorId}?depositor=${walletAddress}`
  );
  const { deposits } = await response.json();

  const totalDeposited = deposits.reduce((sum, deposit) => {
    return sum + deposit.deposited_amount_usd;
  }, 0);

  console.log(`Wallet ${walletAddress} deposited: ${totalDeposited.toString()}`);

  return deposits;
};

​
Important Notes

Deposits are automatically tracked when using the Route API with a valid distributor_id parameter. Make sure to always include your distributor ID when requesting routes to ensure proper attribution.
The limit parameter has a maximum value of 2000. For larger datasets, use pagination with the offset parameter.

​
Error Handling

​
Common Errors

Status Code: 404 Not FoundResponse:
{
  "error": {
    "status": "NOT_FOUND",
    "error": "distributor not found"
  }
}
Solution: Verify your distributor ID is correct and active
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "invalid depositor address"
  }
}
Solution: Ensure the depositor address is a valid Ethereum address
Status Code: 400 Bad RequestResponse:
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "limit must be between 1 and 2000"
  }
}
Solution: Use a limit value between 1 and 2000
⌘I