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

​
Overview

GET /v2/wallets/activity/ The Wallet Activity endpoint returns on-chain earn interactions (deposits and withdrawals) for one or more wallet addresses across all opportunities and distributors. Results are ordered by date descending. This is a wallet-scoped endpoint. For distributor-scoped activity, see Distributor Activity. To pick between the three views (positions, wallet activity, distributor activity), see the Portfolio & Activity overview.

​
Endpoint

​
Get Wallet Activity

curl "https://earn.turtle.xyz/v2/wallets/activity/?addresses=0x3191F53d4d652F9cF37F74c554070d95e710c07f&page=1&limit=20" \
  -H "X-API-Key: pk_live_xxxxx"
Query Parameters
​
addresses
string
required
Comma-separated list of EVM wallet addresses. Maximum 1000 addresses per request. Addresses are case-insensitive.
​
page
integer
default:"1"
Page number for pagination.
​
limit
integer
default:"20"
Results per page (max: 100).
This is a GET endpoint. Pass all parameters in the query string; do not send a request body.

​
Response Example

{
  "activity": [
    {
      "id": "uuid",
      "opportunityId": "uuid",
      "interaction": "deposit",
      "txHash": "0xabc...",
      "chainId": 1,
      "blockTimestamp": "2024-11-01T12:00:00Z",
      "walletAddress": "0xabc...",
      "amountToken": "100.00",
      "amountInUsd": "99.50",
      "tokenSymbol": "USDC",
      "tokenIconUrl": "https://...",
      "isSwap": false
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false
  }
}

​
Response Fields

​
activity
array
Array of activity items. Each item uses the same activity-item shape as the deposit items returned by Distributor Activity, with one difference: interaction is deposit or withdraw here, where the distributor endpoint always returns deposit.
​
activity[].interaction
string
Type of interaction. One of deposit or withdraw.
​
pagination
object
Pagination metadata. Same shape as the pagination object on Distributor Activity.
​
pagination.page
integer
Current page number.
​
pagination.limit
integer
Results per page.
​
pagination.total
integer
Total number of matching interactions.
​
pagination.totalPages
integer
Total number of pages.
​
pagination.hasNext
boolean
Whether a next page exists.
​
pagination.hasPrevious
boolean
Whether a previous page exists.

​
Use Cases

​
Display Wallet Transaction History

Build a transaction history view for a user’s portfolio page. 
const getWalletHistory = async (walletAddress: string) => {
  const response = await fetch(
    `https://earn.turtle.xyz/v2/wallets/activity/?addresses=${walletAddress}&limit=50`,
    { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
  );
  const { activity, pagination } = await response.json();

  return { activity, pagination };
};

​
Query Multiple Wallets

Fetch activity across multiple wallets in a single request. Useful for users with multiple addresses or for building aggregate views. 
const addresses = [
  '0x3191F53d4d652F9cF37F74c554070d95e710c07f',
  '0xa1E7Db8d88BEd2bA0bEFb9bda654b98631c4b305'
].join(',');

const response = await fetch(
  `https://earn.turtle.xyz/v2/wallets/activity/?addresses=${addresses}&page=1&limit=100`,
  { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
);
const { activity } = await response.json();

​
Paginate Through All Results

const getAllActivity = async (walletAddress: string) => {
  let page = 1;
  let allActivity = [];

  while (true) {
    const response = await fetch(
      `https://earn.turtle.xyz/v2/wallets/activity/?addresses=${walletAddress}&page=${page}&limit=100`,
      { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
    );
    const { activity, pagination } = await response.json();
    allActivity.push(...activity);

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

  return allActivity;
};

​
Wallet Activity vs Distributor Activity

Wallet ActivityDistributor Activity
EndpointGET /v2/wallets/activity/GET /v2/deposit/{distributorId}
Scoped byWallet address(es)Distributor ID
InteractionsDeposits + withdrawalsDeposits only
Best forPortfolio UIs, user dashboardsDistributor attribution tracking
PaginationPage-based (page, limit)Page-based (page, limit)

​
Error Handling

Status Code: 400 Bad Request
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "addresses parameter is required"
  }
}
Solution: Include at least one valid EVM address in the addresses query parameter.
Status Code: 400 Bad Request
{
  "error": {
    "status": "INVALID_ARGUMENT",
    "error": "maximum 1000 addresses per request"
  }
}
Solution: Split your request into batches of 1000 addresses or fewer.
Status Code: 400 Bad RequestSolution: This is a GET endpoint. Remove any request body and pass parameters via the query string only.