---
name: Voltr
description: Use when building, managing, or operating yield-generating vaults on Solana, integrating DeFi protocols, querying vault data via API, or automating vault operations. Agents should reach for this skill when working with vault creation, strategy setup, fund allocation, monitoring, or building deposit/withdrawal flows.
metadata:
    mintlify-proj: voltr
    version: "1.0"
---

# Voltr Skill Reference

## Product Summary

Voltr is a permissionless framework for creating and managing yield-generating vaults on Solana. Vaults accept deposits in a single asset (USDC, SOL, etc.) and deploy those funds into DeFi strategies to generate yield. Users receive LP tokens representing their share; vault managers allocate capital between idle accounts and initialized strategies (Kamino lending, Jupiter swaps, Trustful protocols, etc.).

**Key files and commands:**
- SDK: `@voltr/vault-sdk` (instruction builders, PDA helpers, account fetchers)
- CLI: `sdk-scripts` repository — unified interface for all vault operations (`vault:init`, `kamino:market:deposit`, `spot:earn:withdraw`, etc.)
- API: `https://api.voltr.xyz` — public REST API for querying vault data and building unsigned transactions
- Config: JSON profile files define vault asset, cluster, and integration addresses; no secrets in profiles

**Primary docs:** https://docs.voltr.xyz

## When to Use

Reach for this skill when:
- **Creating vaults**: Initialize a new vault with asset, fees, and configuration via SDK or UI
- **Setting up strategies**: Add adaptors (Kamino, Spot, Trustful) and initialize specific strategies
- **Allocating funds**: Deploy idle vault assets into strategies or rebalance between them
- **Querying vault state**: Fetch vault data, positions, fees, or LP economics via API or SDK
- **Building user flows**: Construct deposit/withdraw transactions using the API or SDK
- **Automating operations**: Write bots or scripts to rebalance, claim rewards, or harvest fees
- **Monitoring vaults**: Track performance, health, and alerts using API or SDK helpers

## Quick Reference

### Vault Lifecycle

| Step | Role | Command / Method |
|---|---|---|
| Create vault | Admin | `vault:init` (CLI) or `getInitializeVaultInstructionAsync` (SDK) |
| Set LP metadata | Admin | `vault:set-token-metadata` (CLI) |
| Add adaptor | Admin | `vault:add-adaptor` (CLI) |
| Initialize strategy | Manager | `kamino:market:init`, `spot:swap:init`, etc. (CLI) |
| Allocate funds | Manager | `kamino:market:deposit`, `spot:earn:deposit` (CLI) |
| Monitor | Any | API `/vaults`, `/vault/{pubkey}` or SDK `fetchVault`, `getPositionAndTotalValuesForVault` |

### CLI Command Groups

| Group | Purpose | Example |
|---|---|---|
| `vault:*` | Core vault ops (init, deposit, withdraw, config) | `vault:deposit --amount 1000000` |
| `kamino:market:*` | Kamino lending | `kamino:market:deposit --amount 1000000` |
| `kamino:kvault:*` | Kamino vaults | `kamino:kvault:init` |
| `spot:swap:*` | Jupiter swaps | `spot:swap:buy --amount 1000000 --slippage-bps 50` |
| `spot:earn:*` | Jupiter Earn | `spot:earn:deposit --amount 1000000` |
| `trustful:*` | Trustful protocols | `trustful:arbitrary:deposit --amount 1000000` |

### Transaction Modes (CLI)

| Mode | Sends On-Chain? | Use Case |
|---|---|---|
| `print` (default) | No | Preview instruction count and metadata |
| `simulate` | No | Dry-run on-chain; check compute units and logs |
| `execute` | **Yes** | Sign and send for real |
| `multisig` | No | Emit base64 payload for multisig import |

**Always preview with `--mode print`, confirm with `--mode simulate`, then execute.**

### SDK Instruction Builders

```typescript
// Vault lifecycle
getInitializeVaultInstructionAsync
getUpdateVaultConfigInstructionAsync
getCreateLpMetadataInstructionAsync

// User flows
getDepositVaultInstructionAsync
getRequestWithdrawVaultInstructionAsync
getWithdrawVaultInstructionAsync
getInstantWithdrawVaultInstructionAsync

// Manager/admin
getAddAdaptorInstructionAsync
getInitializeStrategyInstructionAsync
getDepositStrategyInstructionAsync
getWithdrawStrategyInstructionAsync
getHarvestFeeInstructionAsync
getCalibrateHighWaterMarkInstructionAsync
```

### SDK Read Helpers

```typescript
fetchVault(rpc, vaultAddress)
getPositionAndTotalValuesForVault(rpc, vaultAddress)
getCurrentAssetPerLpForVault(rpc, vaultAddress)
getAccumulatedAdminFeesForVault(rpc, vaultAddress)
getAccumulatedManagerFeesForVault(rpc, vaultAddress)
getHighWaterMarkForVault(rpc, vaultAddress)
getVaultLpSupplyBreakdown(rpc, vaultAddress)
```

### API Endpoints

| Endpoint | Method | Purpose |
|---|---|---|
| `/vaults` | GET | List all vaults with TVL, APY, allocations |
| `/vaults/tvl` | GET | Total TVL across all vaults by asset |
| `/vault/{pubkey}` | GET | Single vault details |
| `/vault/{pubkey}/deposit` | POST | Build unsigned deposit transaction |
| `/vault/{pubkey}/withdraw` | POST | Build unsigned withdrawal transaction |

## Decision Guidance

### When to Use CLI vs. SDK

| Scenario | Use CLI | Use SDK |
|---|---|---|
| Routine vault operations (deposit, rebalance, claim rewards) | ✓ | — |
| One-off admin tasks (init vault, add adaptor) | ✓ | — |
| Embedding Voltr in your own service or bot | — | ✓ |
| Custom instruction composition | — | ✓ |
| Building a user-facing app | — | ✓ (via API for reads) |

### When to Use API vs. SDK for Reads

| Use Case | Use API | Use SDK |
|---|---|---|
| User-facing dashboards | ✓ | — |
| Historical analytics | ✓ | — |
| Real-time operational checks | — | ✓ |
| Automation and bots | — | ✓ |
| Derived calculations (fees, HWM) | — | ✓ |

### When to Use Deposit vs. Instant Withdraw

| Scenario | Use |
|---|---|
| User wants to exit; no time pressure | `vault:request-withdraw` then `vault:withdraw` (respects lock period) |
| User wants immediate exit; vault has idle funds | `vault:instant-withdraw` (no waiting) |
| User wants to exit; vault is fully deployed | `vault:request-withdraw` (manager must rebalance before claim) |

## Workflow

### Creating and Operating a Vault

1. **Prepare prerequisites**
   - Separate admin and manager keypairs
   - ~0.15 SOL for vault creation + additional SOL for operations
   - Asset mint address (e.g., USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`)
   - Reliable RPC endpoint

2. **Create the vault**
   ```bash
   pnpm cli -- --profile configs/my-vault.json --mode execute \
     vault:init --manager <MANAGER_PUBKEY> --name "My Vault" --max-cap 100000000000
   ```
   Record the printed vault address in your profile.

3. **Set LP token metadata** (optional but recommended)
   ```bash
   pnpm cli -- --profile configs/my-vault.json --mode execute \
     vault:set-token-metadata --name "My Vault Token" --symbol MYVAULT --uri https://...
   ```

4. **Add adaptors and initialize strategies**
   ```bash
   # Add Kamino adaptor (default)
   pnpm cli -- --profile configs/my-vault.json --mode execute vault:add-adaptor
   
   # Initialize a Kamino market strategy
   pnpm cli -- --profile configs/my-vault.json --mode execute kamino:market:init
   ```

5. **Allocate funds**
   ```bash
   # Deposit idle funds into the strategy
   pnpm cli -- --profile configs/my-vault.json --mode execute kamino:market:deposit --amount 1000000
   ```

6. **Monitor and rebalance**
   - Query vault state: `vault:query:position`
   - Check strategy positions: `vault:query:strategy-positions`
   - Rebalance as needed: withdraw from one strategy, deposit to another
   - Claim rewards: `kamino:market:claim-reward`
   - Harvest fees: `vault:harvest-fee`

### Building a Deposit Flow (API)

1. **Request unsigned transaction**
   ```bash
   curl -X POST https://api.voltr.xyz/vault/{vault_pubkey}/deposit \
     -H "Content-Type: application/json" \
     -d '{"userAddress": "...", "amount": 1000000}'
   ```

2. **Deserialize and sign** (client-side)
   ```typescript
   const tx = VersionedTransaction.deserialize(Buffer.from(response.transaction, 'base58'));
   tx.sign([userKeypair]);
   ```

3. **Send to Solana**
   ```typescript
   const sig = await connection.sendTransaction(tx);
   ```

## Common Gotchas

- **`maxCap: 0n` means zero capacity, not unlimited.** Use the full u64 max value for uncapped vaults.
- **Keep admin and manager as separate keypairs.** If one is compromised, the other limits damage.
- **Never execute blind.** Always `--mode print` then `--mode simulate` before `--mode execute`.
- **Vault description must fit on-chain.** Oversized metadata causes transaction failure.
- **Idle funds are required for user withdrawals.** If all funds are deployed, users experience delays.
- **Keypairs never go in profiles.** Use flags or env vars; keep keypair files outside the repo.
- **RPC URL resolution order:** `--rpc-url` flag → `RPC_URL` env → `HELIUS_RPC_URL` env → profile `rpcUrl`.
- **Strategy initialization is adaptor-specific.** Use the CLI to derive accounts; don't wire them by hand.
- **Multisig vaults can't use `vault:init`.** A fresh vault keypair must sign initialization; use `--mode execute` locally.
- **Rewards often need swapping.** Claimed rewards are usually not the vault's base asset; include swap logic in automation.
- **Fee harvesting is manual.** Accumulated fees don't auto-harvest; call `vault:harvest-fee` periodically.
- **High water mark tracks peak asset-per-LP.** Performance fees only apply to profit above the HWM; calibrate after losses.

## Verification Checklist

Before submitting vault operations:

- [ ] Profile is valid: `pnpm cli -- --profile configs/my-vault.json check` succeeds
- [ ] Keypairs are set in env or flags (never in profile)
- [ ] RPC is reachable and not rate-limited
- [ ] Admin and manager keypairs are funded with SOL
- [ ] Transaction previewed with `--mode print` — instruction count looks reasonable
- [ ] Transaction simulated with `--mode simulate` — no errors, compute units acceptable
- [ ] For multisig vaults: using `--mode multisig --multisig-address <VAULT_SIGNER_PDA>`
- [ ] Vault has idle funds before users request withdrawals
- [ ] Reward claiming includes swap logic if reward mint ≠ asset mint
- [ ] Fee parameters (performance, management, redemption, issuance) are within acceptable ranges
- [ ] Monitoring alerts are set for falling share price, high idle balance, transaction failures

## Resources

**Comprehensive navigation:** https://docs.voltr.xyz/llms.txt

**Critical pages:**
- [Vault Owners Overview](https://docs.voltr.xyz/vault-owners/overview) — roles, lifecycle, next steps
- [CLI & Scripts](https://docs.voltr.xyz/vault-owners/operations/cli-and-scripts) — unified CLI reference, profiles, transaction modes, recipes
- [API Overview](https://docs.voltr.xyz/developers/api-overview) — transaction building, base URL, authentication
- [SDK Reference](https://docs.voltr.xyz/developers/sdk-reference) — instruction builders, PDA helpers, read helpers

---

> For additional documentation and navigation, see: https://docs.voltr.xyz/llms.txt