> ## 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.

# Overview

> Generate and execute on-chain transactions against vault opportunities.

The Earn API lets you generate fully constructed on-chain transactions for depositing into, withdrawing from, and managing positions in DeFi vaults. All transactions are returned unsigned and ready for the user to sign with any wallet infrastructure.

<CardGroup cols={2}>
  <Card title="Deposit" icon="arrow-down-to-bracket" href="/sdk/earn-api/actions/deposit">
    Generate deposit transactions for vault opportunities.
  </Card>

  <Card title="Withdraw" icon="arrow-up-from-bracket" href="/sdk/earn-api/actions/withdraw">
    Generate withdrawal transactions from vault positions.
  </Card>

  <Card title="Claim Deposit" icon="check" href="/sdk/earn-api/actions/claim-deposit">
    Claim processed deposits for async vaults.
  </Card>

  <Card title="Cancel Deposit" icon="xmark" href="/sdk/earn-api/actions/cancel-deposit">
    Cancel pending deposits before they are claimed.
  </Card>
</CardGroup>

## Two deposit modes

The API supports two deposit modes depending on the opportunity:

* **Direct mode** (`mode=direct`) — The user deposits the vault's native token directly. Available when `swapDirectEnabled` is `true` on the opportunity.
* **Swap mode** (`mode=swap`) — The user deposits a different input token and the API routes through a DEX automatically before depositing. Available when `swapRouteEnabled` is `true` on the opportunity.

See [Swap Mode](/sdk/earn-api/swap-mode) for details on input token routing and slippage configuration.

## Instant vs async vaults

Some vaults complete deposits in a single transaction. Others use an async model where the deposit must be claimed after the vault processes the request.

Check `transactionalProperties.depositStepsType` on the opportunity object:

* **`instant`** — Deposit completes in a single transaction.
* **`complex`** — Deposit requires a separate claim step after the vault processes the request. Used by protocols like Mellow and Lagoon.

## Deposit lifecycle

<Steps>
  <Step title="Check opportunity depositStepsType">
    Read the opportunity's `transactionalProperties.depositStepsType` to determine whether the vault is instant or complex.
  </Step>

  <Step title="Generate deposit transaction">
    Call `POST /v1/actions/deposit/{opportunityId}` with the wallet address, deposit amount, token, and mode.
  </Step>

  <Step title="User signs and broadcasts">
    Pass the returned transaction object to the user's wallet for signing and submission.
  </Step>

  <Step title="Claim (complex vaults only)">
    If the vault is complex, wait for the vault protocol to process the request, then call `POST /v1/actions/claim-deposit` to finalize.
  </Step>

  <Step title="Attribution recorded automatically">
    Turtle detects the on-chain transaction and attributes it to your distributor. No manual call required. See [Distributor Model](/sdk/earn-api/distributor-model) for details.
  </Step>
</Steps>