> ## Documentation Index
> Fetch the complete documentation index at: https://loopscale.mintlify.site/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 Strategy Vaults](https://loopscale.mintlify.site/protocol-concepts/earn-vault-architecture.md)). 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`). For how the vault works underneath, see [Earn Vault Architecture](https://loopscale.mintlify.site/protocol-concepts/earn-vault-architecture.md) and [Earn Vault Flows](https://loopscale.mintlify.site/protocol-concepts/earn-vault-flows.md).

## 1. Find a vault

[Get Earn Vaults](https://loopscale.mintlify.site/api-reference/data/earn/get-earn-vaults.md) lists every registered vault with its latest snapshot. That includes Draft vaults that aren't open for deposits yet, so filter on `status == 1` before offering deposits. 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) |
| `acceptedAssetMints` | Tokens Loopscale offers for deposit and payout, underlying first |
| `shareMint` | The vault's LP token |
| `queueEnabled`, `instantEnabled`, `cancelEnabled` | Which withdrawal paths the vault offers |
| `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.headlineApyBps` | The APY to display: forward APY (or 7-day realized return when there's none) plus rewards |
| `latestSnapshot.displayApyBps` | Forward-looking APY from the vault's current positions |
| `latestSnapshot.realizedReturnBps7d` | Annualized NAV change over 7 days (also `24h` and `30d`) |

`realizedApyBps*` fields are deprecated aliases of `realizedReturnBps*`. Use the new names.

> [!WARNING]
>
> The transaction endpoints don't check `status`, the withdrawal flags, or `requiresAcknowledgment`. They'll build a deposit for a Draft vault or a cancel on a vault with `cancelEnabled: false` (the latter then fails onchain). Gate these in your own UI, the way the Loopscale app does.

[Get Earn Vault History](https://loopscale.mintlify.site/api-reference/data/earn/get-earn-vault-history.md) returns the same snapshot fields over time for charts, newest first. Snapshots are taken every 15 minutes.

### Reading vault configuration

`parsedAccountJson.exponentStrategyVault` on [Get Earn Vault](https://loopscale.mintlify.site/api-reference/data/earn/get-earn-vault.md) is the decoded onchain vault account. Fields worth knowing:

| Path | Meaning |
| - | - |
| `tokenEntries[]` | Tokens the vault can hold, deposit, and pay out in |
| `strategyPositions[]` | Positions tracked for NAV |
| `financials` | `aumInBase` (idle), `aumInBaseInPositions` (deployed), `lpBalance`, pending withdrawals, instant-window state |
| `reservesConfig.reservesShareBp` | Idle reserve floor, in bps of AUM |
| `reservesConfig.fastWithdrawalCutBp` | Extra fee on instant withdrawals, in bps |
| `reservesConfig.managementFeeBps` | Management fee in **millionths** (`10000` = 1%/yr) |
| `reservesConfig.withdrawalPeriod` | `Interval` lock time, or `WeeklySchedule` (`daysOfWeek` bitmask, bit 0 = Sunday, UTC) |
| `normalWithdrawalCutBp` | Standard withdrawal fee, in bps |
| `maxAumSupply` | Deposit cap |
| `proposalVoteConfig` | Voting period, timelock, rejection threshold (in millionths) |
| `roles` | Manager, curator, allocator, and sentinel keys |

## 2. Acknowledge the vault's terms

If `requiresAcknowledgment` is `true`, show the vault's terms and call [Acknowledge Earn Vault](https://loopscale.mintlify.site/api-reference/transactions/earn/acknowledge.md) once per wallet before its first deposit. It only records the acceptance (a timestamp on the wallet's position), so it builds no transaction. Check `acknowledgedAt` on [Get Earn Position](https://loopscale.mintlify.site/api-reference/data/earn/get-earn-position.md) to see whether a wallet has already accepted.

## 3. Deposit

Call [Deposit to Earn Vault](https://loopscale.mintlify.site/api-reference/transactions/earn/deposit.md) 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.

```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" }'
```

Pass `minLpOut` to protect against NAV moving between quote and landing. You can estimate expected shares as `amount × 1e18 / navPerShareE18`. Deposits fail onchain if they would exceed the vault's deposit cap.

### Sending the bundle

The two transactions must land in the same slot, because the vault program rejects price data that wasn't refreshed in the current slot. Any Jito-compatible sender works. The action transaction already pays the tip.

```ts theme={null}
import { VersionedTransaction } from "@solana/web3.js";
import bs58 from "bs58";

const { txBase64s } = await res.json();

const txs = txBase64s.map((b64: string) =>
  VersionedTransaction.deserialize(Buffer.from(b64, "base64"))
);

// Keep existing signatures (a queued request is pre-signed by its request account).
const signed = await wallet.signAllTransactions(txs);

await fetch("https://mainnet.block-engine.jito.wtf/api/v1/bundles", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "sendBundle",
    params: [signed.map((tx) => bs58.encode(tx.serialize()))],
  }),
});
```

Transactions carry a blockhash from build time, so sign and send promptly. If a bundle doesn't land, rebuild rather than resending, since the AUM refresh has to be current.

## 4. Track the position

[Get Earn Position](https://loopscale.mintlify.site/api-reference/data/earn/get-earn-position.md) returns a wallet's share balance, cost basis and realized PnL in one vault, plus its open withdrawal requests. [Get Earn Portfolio](https://loopscale.mintlify.site/api-reference/data/earn/get-earn-portfolio.md) returns the same for every vault the wallet holds, including vaults where it only has open withdrawal requests.

```
position value (underlying) = (shareBalance + queuedShares) × navPerShareE18 / 1e18
```

`shareBalance` is the wallet's live share-token balance. `queuedShares` are shares sitting in escrow behind open withdrawal requests, and they still earn until filled. Cost basis is average cost across both. `feesPaidAssets` isn't populated yet and reads `0`.

## 5. Withdraw

Call [Withdraw from Earn Vault](https://loopscale.mintlify.site/api-reference/transactions/earn/withdraw-request.md) with `mode`:

* `instant` redeems from the vault's reserves right away, paying the withdrawal fee plus the instant fee, while reserves and the per-window instant cap allow.
* `queued` opens a withdrawal request. The response's `requestId` identifies it.

Either mode accepts `mint` to pick a payout token from `acceptedAssetMints`. Instant mode pays it out directly. For queued requests the mint is recorded as a preference: the manager chooses the payout token(s) at fill time, so check `fills` on the request for what was actually paid.

### Instant capacity

Before offering instant mode, estimate capacity from the vault account:

```
reserve headroom = reservesShareBp × totalAum / 1e4 − value of pending queued shares
window headroom  = instant window cap − already withdrawn this window
capacity         = min(reserve headroom, window headroom, payout token's idle balance)
```

If a request is larger than capacity, the transaction fails onchain. Offer queued mode instead.

### Queued requests

Watch a queued request with [Get Earn Withdrawal Queue](https://loopscale.mintlify.site/api-reference/data/earn/get-earn-withdrawal-queue.md) or Get Earn Position. A request moves through `0` Pending → `1` Partial → `2` Fulfilled, or `3` Cancelled.

* **Claim.** [Claim Earn Withdrawal](https://loopscale.mintlify.site/api-reference/transactions/earn/claim-withdrawal.md) pays out everything filled so far. It succeeds only once `sharesFilled > sharesClaimed` **and** the vault's withdrawal period has unlocked (the lock interval, or the next scheduled withdrawal day).
* **Cancel.** [Cancel Earn Withdrawal](https://loopscale.mintlify.site/api-reference/transactions/earn/cancel-withdrawal.md) returns the shares. It needs `cancelEnabled`, and the vault's cancel cooldown to have passed. The Loopscale app only offers it while nothing has been filled.

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

## Building directly against the vault program

The Pandora API is the easiest path, but you can also build transactions yourself with Exponent's TypeScript SDK (`@exponent-labs/exponent-sdk`). The Pandora endpoints use the same calls:

| Action | SDK call on `ExponentVault` |
| - | - |
| Load vault | `ExponentVault.load({ connection, address })` |
| Refresh prices + AUM | `ixsRefreshStrategyVaultPrices(...)`, `ixRefreshAum(...)` |
| Deposit | `ixsDepositLiquidity(...)` |
| Instant withdraw | `ixExecuteWithdrawalFromReservesWithResolvedAumAccounts(...)` |
| Queue withdrawal | `ixQueueWithdrawal(...)` (returns the instruction and a new request keypair that must sign) |
| Claim | `ixExecuteWithdrawalWithResolvedAumAccounts(...)` |
| Cancel | `ixCancelWithdrawal(...)` |
| Instant capacity | `fetchInstantWithdrawalCapacity`, `fetchUserInstantWithdrawalCapacity`, `fetchInstantWithdrawalQuote` |

You're then responsible for the same-slot bundling, Kamino/Scope reserve refreshes (Scope's refresh must be the first instruction in its transaction), and lookup tables. See [Exponent's strategy vault developer docs](https://docs.exponent.finance/developer-strategy-vaults/overview).

## Common errors

| Code | Name | Meaning |
| - | - | - |
| 6015 | `LpSupplyMaximumExceeded` | Deposit would exceed the vault's deposit cap |
| 6016 | `MinLpOutNotMet` | NAV moved past your `minLpOut` |
| 6025 / 6098 | `WithdrawalNotReady` / `WithdrawalLockTimeNotElapsed` | Claim before the withdrawal period unlocked |
| 6058 | `WithdrawalsBlocked` | The sentinel has paused withdrawals |
| 6080 | `StalePriceData` | A price wasn't refreshed in the same slot; send the bundle together, or rebuild |
| 6106 | `ReservesExceeded` | Instant withdrawal would take reserves below the floor; use queued |
| 6116 | `WithdrawalCancelCooldownNotElapsed` | Cancel attempted too soon after the request |
| 6123 | `AumRefreshRequired` | The action was sent without the AUM refresh in front of it |
| 6124 | `NavAumCircuitBreakerActive` | NAV moved more than the vault allows; actions are paused until the sentinel clears it |


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