Skip to main content

​
Overview

Some vaults use async deposits, meaning the deposited funds are not immediately active. Instead, they enter a pending state and must be claimed once the vault processes them. The claim-deposit endpoint generates the transaction to finalize these pending deposits.
1

Deposit (already completed)

The user previously called deposit and the vault queued the funds for processing.
2

Create claim-deposit action

Call POST /v1/actions/claim-deposit/{opportunityId} to generate the claim transaction.
3

Sign & submit transaction

The user signs and submits the claim transaction. No further action needed.
This endpoint is only relevant for opportunities with async deposits (e.g., Mellow, Lagoon). For standard vaults, deposits are processed immediately and no claim is needed.

​
Create Claim Deposit

Generate the transaction to claim a pending async deposit. Unlike the deposit endpoint, this is a simplified request that only requires the user’s wallet address and distributor ID — no token or amount is needed since the vault already holds the pending deposit information. 
curl -X POST "https://earn.turtle.xyz/v1/actions/claim-deposit/{opportunityId}" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0x1234...",
    "distributorId": "your-distributor-id"
  }'
Path Parameters
​
opportunityId
uuid
required
The unique identifier of the opportunity with the pending deposit. Get this from the Opportunities API.
Body Parameters
​
userAddress
string
required
The user’s EVM wallet address. Must belong to a registered Turtle member and must have a pending deposit in this opportunity.
​
distributorId
string
required
Your distributor ID for attribution tracking.
Response 
{
  "actionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactions": [
    {
      "type": "claimDeposit",
      "transaction": {
        "to": "0x...",
        "data": "0x...",
        "value": "0",
        "gasLimit": "200000",
        "chainId": 1
      },
      "description": "Claim pending deposit"
    }
  ]
}

​
Transaction Object

Each transaction in the transactions array contains:
​
type
string
required
Transaction type, e.g. approve, deposit, withdraw, claimDeposit, cancelDeposit.
​
transaction
object
required
The raw transaction data to sign and submit.
​
transaction.to
string
required
Target contract address.
​
transaction.data
string
required
Encoded calldata (hex string with 0x prefix).
​
transaction.value
string
required
Value in wei. Usually "0" for token interactions; non-zero for native token deposits.
​
transaction.gasLimit
string
required
Estimated gas limit.
​
transaction.chainId
integer
required
Chain ID for the transaction.
​
description
string
required
Human-readable description of what this transaction does.
​
metadata
object
Optional metadata for swap transactions, including provider info, amount out, gas estimate, and route details.

​
Complete Example

const opportunityId = '550e8400-e29b-41d4-a716-446655440000';
const walletAddress = '0x1234...';

// 1. Create the claim-deposit action
const claimResponse = await fetch(
  `https://earn.turtle.xyz/v1/actions/claim-deposit/${opportunityId}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userAddress: walletAddress,
      distributorId: 'your-distributor-id',
    }),
  }
);
const { transactions } = await claimResponse.json();

// 2. Sign and submit the claim transaction
const tx = transactions[0];
const txResponse = await wallet.sendTransaction(tx.transaction);
await txResponse.wait();

​
Error Handling

Status Code: 403 Forbidden
{
  "error": "not_a_member",
  "message": "User is not a Turtle member. Please complete the membership flow first.",
  "docsUrl": "https://docs.turtle.club/sdk/earn-api/membership"
}
Solution: Complete the membership flow before calling action endpoints.
Status Code: 404 Not Found
{
  "error": "distributor_not_found",
  "message": "Distributor not found with the provided ID"
}
Solution: Verify your distributor ID is correct and active.
Status Code: 404 Not Found
{
  "error": "opportunity_not_found",
  "message": "Opportunity not found"
}
Solution: Check the opportunity ID using the Opportunities API.
  • Deposit - Generate the initial deposit transactions
  • Cancel Deposit - Cancel a pending async deposit instead of claiming it
  • Opportunities API - Discover available opportunities and their IDs