> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turtle.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdraw

> Generate ready-to-sign transactions for withdrawing from an opportunity

> [!NOTE]
>
> Requires an API key via the `X-API-Key` header. See [API Keys](https://docs.turtle.xyz/sdk/authentication/api-keys.md).&#x20;

## Overview

`POST /v2/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.

> [!NOTE]
>
> All action endpoints require the user to be a [Turtle member](https://docs.turtle.xyz/sdk/authentication/register-wallet.md). 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).

```bash curl theme={null}
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
  }'
```

```typescript TypeScript theme={null}
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**

**opportunityId** `uuid` *required*

The unique identifier of the opportunity to withdraw from. Get this from the [Opportunities API](https://docs.turtle.xyz/sdk/opportunities/get-opportunities.md).

**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**

```json theme={null}
{
  "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:

```typescript theme={null}
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

> [accordion] 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.

> [accordion] Submit transactions in order
>
> The `transactions` array is ordered. A withdrawal typically returns an `approve` then a `withdraw`. Confirm each before broadcasting the next.

> [accordion] 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.

> [accordion] slippageBps applies where required
>
> `slippageBps` is the slippage tolerance in basis points (`50` = 0.5%). It is only applied to opportunities that require it.

> [accordion] Membership is required
>
> The user must be a registered Turtle member. Complete the [membership flow](https://docs.turtle.xyz/sdk/authentication/register-wallet.md) first.

## Error Handling

> [accordion] User is not a Turtle member
>
> **Status Code:** 403 Forbidden
>
> ```json theme={null}
> {
>   "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](https://docs.turtle.xyz/sdk/authentication/register-wallet.md) before calling action endpoints.

> [accordion] Distributor not found
>
> **Status Code:** 404 Not Found
>
> ```json theme={null}
> {
>   "error": "distributor_not_found",
>   "message": "Distributor not found with the provided ID"
> }
> ```
>
> **Solution:** Verify your distributor ID is correct and active.

> [accordion] Opportunity not found
>
> **Status Code:** 404 Not Found
>
> ```json theme={null}
> {
>   "error": "opportunity_not_found",
>   "message": "Opportunity not found"
> }
> ```
>
> **Solution:** Check the opportunity ID using the [Opportunities API](https://docs.turtle.xyz/sdk/opportunities/get-opportunities.md).

> [accordion] Invalid tokenOut address
>
> **Status Code:** 400 Bad Request
>
> ```json theme={null}
> {
>   "error": "INVALID_ARGUMENT",
>   "message": "invalid tokenOut address format"
> }
> ```
>
> **Solution:** Provide a valid EVM address for the `tokenOut` field.

> [accordion] Insufficient share balance
>
> **Status Code:** 400 Bad Request
>
> ```json theme={null}
> {
>   "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.

## Related Endpoints

* [Deposit](https://docs.turtle.xyz/sdk/earn/deposit.md) - Generate deposit transactions
* [Get Opportunities](https://docs.turtle.xyz/sdk/opportunities/get-opportunities.md) - Discover available opportunities and their IDs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.