Skip to main content
Requires an API key via the X-API-Key header. See API Keys.

​
Overview

POST /v1/actions/withdraw/{opportunityId} The withdraw endpoint generates transactions to redeem shares from a vault/opportunity. The typical flow is:
1

Create withdraw action

Call the endpoint to generate the transactions.
2

Sign & submit transactions

The user signs and submits each transaction in order (e.g., approve + withdraw). No further action needed.
All action endpoints require the user to be a Turtle member. Make sure the user has completed the membership flow before calling these endpoints.

​
Create Withdraw

Generate the transactions needed to withdraw from an opportunity. The response contains an ordered list of transactions the user must sign and submit (e.g., approve + withdraw). 
curl -X POST "https://earn.turtle.xyz/v1/actions/withdraw/{opportunityId}" \
  -H "X-API-Key: pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0x1234...",
    "amount": "1000000000000000000",
    "distributorId": "your-distributor-id",
    "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "slippageBps": 50
  }'
Path Parameters
​
opportunityId
uuid
required
The unique identifier of the opportunity to withdraw from. Get this from the Opportunities API.
Body Parameters
​
userAddress
string
required
The user’s EVM wallet address. Must belong to a registered Turtle member.
​
amount
string
required
The number of shares to redeem in the smallest unit. Must be greater than 0.
​
distributorId
string
required
Your distributor ID for attribution tracking.
​
tokenOut
string
The address of the token to receive after withdrawal. Required for some providers (e.g., Midas, Mellow, Veda). If not provided, the vault’s default withdraw token is used.
​
slippageBps
integer
Slippage tolerance in basis points. For example, 50 = 0.5% slippage. Only applied to opportunities that require it.
Response 
{
  "actionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transactions": [
    {
      "type": "approve",
      "transaction": {
        "to": "0x...",
        "data": "0x095ea7b3000000000000000000000000...",
        "value": "0",
        "gasLimit": "60000",
        "chainId": 1
      },
      "description": "Approve shares spending"
    },
    {
      "type": "withdraw",
      "transaction": {
        "to": "0x...",
        "data": "0x...",
        "value": "0",
        "gasLimit": "300000",
        "chainId": 1
      },
      "description": "Withdraw from vault"
    }
  ]
}

​
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

Here’s a full withdraw flow from start to finish: 
const opportunityId = '550e8400-e29b-41d4-a716-446655440000';
const walletAddress = '0x1234...';

// 1. Create the withdraw action
const withdrawResponse = await fetch(
  `https://earn.turtle.xyz/v1/actions/withdraw/${opportunityId}`,
  {
    method: 'POST',
    headers: { 'X-API-Key': 'pk_live_xxxxx', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userAddress: walletAddress,
      amount: '1000000000000000000', // shares to redeem
      distributorId: 'your-distributor-id',
      tokenOut: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // receive USDC
    }),
  }
);
const { transactions } = await withdrawResponse.json();

// 2. Sign and submit each transaction in order
for (const tx of transactions) {
  const txResponse = await wallet.sendTransaction(tx.transaction);
  await txResponse.wait(); // Wait for confirmation
}

​
Operational Notes

amount is the number of vault shares to redeem, expressed in the share token’s smallest unit. Pass the raw integer string. Never send a human-readable decimal.
The transactions array is ordered. A withdrawal typically returns an approve then a withdraw. Confirm each before broadcasting the next.
tokenOut sets the token the user receives. It is required for some providers (e.g., Midas, Mellow, Veda). If not provided, the vault’s default withdraw token is used.
slippageBps is the slippage tolerance in basis points (50 = 0.5%). It is only applied to opportunities that require it.
The user must be a registered Turtle member. Complete the membership flow first.

​
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.xyz/sdk/authentication/register-wallet"
}
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.
Status Code: 400 Bad Request
{
  "error": "INVALID_ARGUMENT",
  "message": "invalid tokenOut address format"
}
Solution: Provide a valid EVM address for the tokenOut field.