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

# Integrate Earn Vaults

Earn vaults are curated strategy vaults run through external vault providers (today, Exponent). A deposit mints vault shares (LP tokens) priced at the vault's NAV. Withdrawals redeem shares instantly from reserves or through a withdrawal queue.

This guide walks through the full flow. Data lives on the markets API (`https://tars.loopscale.com/v1/markets`). Transactions are built by the Pandora API (`https://tars.loopscale.com/v1/pandora`).

## 1. Find a vault

[Get Earn Vaults](/api-reference/data/earn/get-earn-vaults) lists every registered vault with its latest snapshot. The fields you need most:

| Field                                              | Meaning                                                                             |
| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `address`                                          | Vault address, used by every other endpoint                                         |
| `status`                                           | `0` Draft, `1` Active, `2` Paused, `3` Deprecated                                   |
| `acceptedAssetMint`                                | Default deposit token (the vault's underlying)                                      |
| `shareMint`                                        | The vault's LP token                                                                |
| `queueEnabled`, `instantEnabled`, `cancelEnabled`  | Which withdrawal paths the vault supports                                           |
| `requiresAcknowledgment`                           | Whether a wallet must accept the vault's terms before depositing                    |
| `latestSnapshot.navPerShareE18`                    | Value of one share in the underlying, scaled by 1e18                                |
| `latestSnapshot.totalAumAssets`                    | Vault AUM in underlying base units                                                  |
| `latestSnapshot.displayApyBps`, `realizedApyBps7d` | Forward-looking APY from the underlying positions, and realized APY from NAV change |

[Get Earn Vault History](/api-reference/data/earn/get-earn-vault-history) returns the same snapshot fields over time for charts.

## 2. Acknowledge the vault's terms

If `requiresAcknowledgment` is `true`, show the vault's terms and call [Acknowledge Earn Vault](/api-reference/transactions/earn/acknowledge) once per wallet before its first deposit. It only records the acceptance, so it builds no transaction.

## 3. Deposit

Call [Deposit to Earn Vault](/api-reference/transactions/earn/deposit) with the wallet and an amount in base units. The response carries two transactions in `txBase64s`: an AUM refresh, then the deposit. Sign both with the wallet and submit them in order as one Jito bundle (details in [Sending Earn transactions](/api-reference/transactions/earn/deposit#sending-earn-transactions)).

```bash theme={null}
curl -X POST https://tars.loopscale.com/v1/pandora/earn/vaults/deposit/tx \
  -H "Content-Type: application/json" \
  -d '{ "address": "<VAULT>", "wallet": "<WALLET>", "amount": "1000000" }'
```

## 4. Track the position

[Get Earn Position](/api-reference/data/earn/get-earn-position) returns a wallet's share balance, cost basis and realized PnL in one vault, plus its open withdrawal requests. [Get Earn Portfolio](/api-reference/data/earn/get-earn-portfolio) returns the same for every vault the wallet holds.

Position value in the underlying is `shareBalance × navPerShareE18 / 1e18`.

## 5. Withdraw

Call [Withdraw from Earn Vault](/api-reference/transactions/earn/withdraw-request) with `mode`:

* `instant` redeems from the vault's reserves right away, paying the fast-withdrawal cut, while reserves allow. Pass `mint` to receive a token other than the underlying.
* `queued` opens a withdrawal request. The response's `requestId` identifies it.

For a queued request, watch it with [Get Earn Withdrawal Queue](/api-reference/data/earn/get-earn-withdrawal-queue) or Get Earn Position. Once it is filled, [Claim Earn Withdrawal](/api-reference/transactions/earn/claim-withdrawal) pays out the tokens. Before then, [Cancel Earn Withdrawal](/api-reference/transactions/earn/cancel-withdrawal) returns the shares.

Every withdraw, claim and cancel response uses the same two-transaction bundle as a deposit.