Skip to main content

​
Overview

For vaults with async deposits, a deposit may sit in a pending/queued state before the vault processes it. If the user wants to recover their funds instead of waiting for the vault to process them, the cancel-deposit endpoint generates the transaction to cancel the pending deposit.
1

Deposit is pending

The user previously called deposit and the funds are queued, waiting to be processed.
2

Create cancel-deposit action

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

Sign & submit transaction

The user signs and submits the cancel transaction. Funds are returned to the user.
This endpoint is only relevant for opportunities with async deposits (e.g., Mellow, Lagoon). For standard vaults, deposits are processed immediately and cannot be cancelled.

​
Create Cancel Deposit

Generate the transaction to cancel a pending async deposit. Like claim-deposit, this is a simplified request — the vault already knows which deposit to cancel based on the user’s address. 
curl -X POST "https://earn.turtle.xyz/v1/actions/cancel-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": "cancelDeposit",
      "transaction": {
        "to": "0x...",
        "data": "0x...",
        "value": "0",
        "gasLimit": "200000",
        "chainId": 1
      },
      "description": "Cancel 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 cancel-deposit action
const cancelResponse = await fetch(
  `https://earn.turtle.xyz/v1/actions/cancel-deposit/${opportunityId}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userAddress: walletAddress,
      distributorId: 'your-distributor-id',
    }),
  }
);
const { transactions } = await cancelResponse.json();

// 2. Sign and submit the cancel 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
  • Claim Deposit - Claim a pending async deposit instead of cancelling
  • Opportunities API - Discover available opportunities and their IDs