Integrate Earn Vaults

Earn vaults are curated strategy vaults run through external vault providers (today, Exponent Strategy Vaults). 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 and Earn Vault Flows.

1. Find a vault

Get Earn Vaults 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.

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 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 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 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 to see whether a wallet has already accepted.

3. Deposit

Call Deposit to Earn Vault 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.

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.

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 returns a wallet’s share balance, cost basis and realized PnL in one vault, plus its open withdrawal requests. Get Earn Portfolio 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 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 or Get Earn Position. A request moves through 0 Pending → 1 Partial → 2 Fulfilled, or 3 Cancelled.

Claim. Claim Earn Withdrawal 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 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.

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

Getting Started

Transaction Endpoints

Data Endpoints

Guides

1. Find a vault

Reading vault configuration

2. Acknowledge the vault’s terms

3. Deposit

Sending the bundle

4. Track the position

5. Withdraw

Instant capacity

Queued requests

Building directly against the vault program

Common errors

​1. Find a vault

​Reading vault configuration

​2. Acknowledge the vault’s terms

​3. Deposit

​Sending the bundle

​4. Track the position

​5. Withdraw

​Instant capacity

​Queued requests

​Building directly against the vault program

​Common errors

1. Find a vault

Reading vault configuration

2. Acknowledge the vault’s terms

3. Deposit

Sending the bundle

4. Track the position

5. Withdraw

Instant capacity

Queued requests

Building directly against the vault program

Common errors