Withdraw

Requires an API key via the X-API-Key header. See API Keys.

Overview

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

Create withdraw action

Call the endpoint to generate the transactions.

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/v2/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
  }'

const opportunityId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://earn.turtle.xyz/v2/actions/withdraw/${opportunityId}`,
  {
    method: 'POST',
    headers: { 'X-API-Key': 'pk_live_xxxxx', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userAddress: '0x1234...',
      amount: '1000000000000000000', // shares to redeem in smallest unit
      distributorId: 'your-distributor-id',
      tokenOut: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
      slippageBps: 50,
    }),
  }
);
const data = await response.json();

Path Parameters

uuid

required

The unique identifier of the opportunity to withdraw from. Get this from the Opportunities API.

Body Parameters

string

required

The user’s EVM wallet address. Must belong to a registered Turtle member.

string

required

The number of shares to redeem in the smallest unit. Must be greater than 0.

string

required

Your distributor ID for attribution tracking.

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.

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:

string

required

Transaction type, e.g. approve, deposit, withdraw, claimDeposit, cancelDeposit.

object

required

The raw transaction data to sign and submit.

string

required

Target contract address.

string

required

Encoded calldata (hex string with 0x prefix).

string

required

Value in wei. Usually "0" for token interactions; non-zero for native token deposits.

string

required

Estimated gas limit.

integer

required

Chain ID for the transaction.

string

required

Human-readable description of what this transaction does.

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/v2/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 in shares, in the smallest unit

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.

Submit transactions in order

The transactions array is ordered. A withdrawal typically returns an approve then a withdraw. Confirm each before broadcasting the next.

tokenOut is required for some providers

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 applies where required

slippageBps is the slippage tolerance in basis points (50 = 0.5%). It is only applied to opportunities that require it.

Membership is required

The user must be a registered Turtle member. Complete the membership flow first.

Error Handling

User is not a Turtle member

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.

Distributor not found

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.

Opportunity not found

Status Code: 404 Not Found

{
  "error": "opportunity_not_found",
  "message": "Opportunity not found"
}

Solution: Check the opportunity ID using the Opportunities API.

Invalid tokenOut address

Status Code: 400 Bad Request

{
  "error": "INVALID_ARGUMENT",
  "message": "invalid tokenOut address format"
}

Solution: Provide a valid EVM address for the tokenOut field.

Status Code: 400 Bad Request

{
  "code": 400,
  "status": "INVALID_ARGUMENT",
  "error": "insufficient token balance"
}

The API reads the user’s on-chain share balance before building the withdraw transactions and rejects the request when the wallet holds fewer shares than amount.Solution: Lower amount to at most the wallet’s current share balance for the opportunity.

Deposit - Generate deposit transactions
Get Opportunities - Discover available opportunities and their IDs

Get Started

Products

Reference

Overview

Create Withdraw

Transaction Object

Complete Example

Operational Notes

Error Handling

​Overview

​Create Withdraw

​Transaction Object

​Complete Example

​Operational Notes

​Error Handling

​Related Endpoints

Overview

Create Withdraw

Transaction Object

Complete Example

Operational Notes

Error Handling

Related Endpoints