Skip to main content

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.

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.

Deposit

Generate deposit transactions for vault opportunities.

Withdraw

Generate withdrawal transactions from vault positions.

Claim Deposit

Claim processed deposits for async vaults.

Cancel Deposit

Cancel pending deposits before they are claimed.

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

1

Check opportunity depositStepsType

Read the opportunity’s transactionalProperties.depositStepsType to determine whether the vault is instant or complex.
2

Generate deposit transaction

Call POST /v1/actions/deposit/{opportunityId} with the wallet address, deposit amount, token, and mode.
3

User signs and broadcasts

Pass the returned transaction object to the user’s wallet for signing and submission.
4

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

Attribution recorded automatically

Turtle detects the on-chain transaction and attributes it to your distributor. No manual call required. See Distributor Model for details.