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

​
Overview

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.

​
Endpoint

​
Get Wallet Activity

curl "https://earn.turtle.xyz/v1/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. Do not send a request body — it will return an error.
Response 
{
  "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
  }
}
Activity Object
​
id
string
Unique identifier for the interaction.
​
opportunityId
string
The opportunity this interaction belongs to.
​
interaction
string
Type of interaction: deposit or withdraw.
​
txHash
string
On-chain transaction hash.
​
chainId
integer
Chain ID where the transaction occurred.
​
blockTimestamp
string
ISO 8601 timestamp of the on-chain transaction.
​
walletAddress
string
The wallet address that performed the interaction.
​
amountToken
string
Human-readable token amount (already adjusted for decimals). Present when available.
​
amountInUsd
string
USD value of the interaction at time of transaction. Present when available.
​
tokenSymbol
string
Symbol of the deposited or withdrawn token. Present when available.
​
tokenIconUrl
string
URL to the token icon. Present when available.
​
isSwap
boolean
Whether the deposit used swap mode.

​
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/v1/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/v1/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/v1/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 /v1/wallets/activityGET /v1/deposit/{distributor_id}
Scoped byWallet address(es)Distributor ID
InteractionsDeposits + withdrawalsDeposits only
Best forPortfolio UIs, user dashboardsDistributor attribution tracking
PaginationPage-based (page, hasNext)Offset-based (offset, 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.