# Vault API

The Vault API provides access to vault information, protocol statistics, whitelisted assets, and transaction history. Most endpoints are public, but some require authentication for private vaults and admin operations.

### Protocol Statistics

#### Get Protocol Stats

Get protocol-level statistics including total TVL, max APY, and user counts.

```typescript
// Public endpoint - no authentication required
const stats = await sdk.vault.getProtocolStats();

console.log(`Total TVL: ${stats.stats.totalTvl}`);
console.log(`Max APY: ${stats.stats.maxApy}`);
console.log(`Total Users: ${stats.stats.totalUsers}`);
console.log(`Total Fund Managers: ${stats.stats.totalFundManagers}`);
console.log(`YPO: ${stats.stats.ypo}`);
```

#### Get Strategies

Get distinct strategy types available across all vaults.

```typescript
// Public endpoint
const strategies = await sdk.vault.getStrategies();

console.log(`Available strategies: ${strategies.strategies.join(", ")}`);
// Example output: ["DeFi", "Trading", "Lending", ...]
```

#### Refresh Protocol Stats

Refresh protocol statistics (requires authentication).

```typescript
const accessToken = localStorage.getItem("accessToken");

const refreshedStats = await sdk.vault.refreshProtocolStats(accessToken);
```

### Vault Information

#### Get All Vaults

Get a paginated list of vaults with optional filters.

```typescript
// Public endpoint
const vaults = await sdk.vault.getVaults({
  chainId: 1, // Ethereum
  status: "active", // Optional: 'active', 'inactive', etc.
  strategy: "DeFi", // Optional: filter by strategy
  page: 1,
  pageSize: 20,
});

console.log(`Found ${vaults.pagination.total} vaults`);
vaults.data.forEach((vault) => {
  console.log(`${vault.vaultKey}: ${vault.name} - TVL: ${vault.metrics.tvl}`);
});
```

**Filter Options:**

* `chainId` - Filter by blockchain chain ID
* `status` - Filter by vault status
* `strategy` - Filter by strategy type
* `page` - Page number (default: 1)
* `pageSize` - Items per page (default: 20, max: 100)

#### Get Vault by Key

Get a specific vault by its key and chain ID.

```typescript
// Public endpoint
const vault = await sdk.vault.getVaultByKey("yusd", 1); // Ethereum

console.log(`Vault: ${vault.vault.name}`);
console.log(`Symbol: ${vault.vault.symbol}`);
console.log(`TVL: ${vault.vault.metrics.tvl}`);
console.log(`APY (7d): ${vault.vault.metrics.apy7d}%`);
console.log(`Description: ${vault.vault.description}`);
```

#### Get Vault by Symbol

Get a vault by its symbol and chain ID.

```typescript
// Public endpoint
const vault = await sdk.vault.getVaultBySymbol("yUSD", 1);

console.log(`Vault Key: ${vault.vault.vaultKey}`);
```

#### Get Private Vault

Get a private vault (requires authentication).

```typescript
const accessToken = localStorage.getItem("accessToken");

const privateVault = await sdk.vault.getPrivateVaultByKey(
  "private-vault-key",
  "0x1234567890123456789012345678901234567890", // User address
  "user", // User role
  1, // Chain ID
  accessToken
);
```

#### Get Vault Details

Get detailed vault information including fact sheet data.

```typescript
// Public endpoint
const details = await sdk.vault.getVaultDetails("yusd", 1);

console.log(`Manager: ${details.vault.manager}`);
console.log(`Partner: ${details.vault.partner?.name}`);
console.log(`Rewards: ${details.vault.rewards?.length} reward tokens`);
```

#### Get Vault FAQs

Get frequently asked questions for a vault.

```typescript
// Public endpoint
const faqs = await sdk.vault.getVaultFaqs("yusd", 1);

faqs.faqs.forEach((faq) => {
  console.log(`Q: ${faq.question}`);
  console.log(`A: ${faq.answer}`);
});
```

### Whitelisted Assets

#### Get Whitelisted Assets

Get all whitelisted assets for a vault.

```typescript
// Public endpoint
const assets = await sdk.vault.getWhitelistedAssets("yusd", 1, false);

console.log(`Vault has ${assets.assets.length} whitelisted assets`);
assets.assets.forEach((asset) => {
  console.log(`${asset.symbol}: ${asset.address}`);
  console.log(`Deposit Enabled: ${asset.depositRedeemEnabled & 1 === 1}`);
  console.log(`Redeem Enabled: ${asset.depositRedeemEnabled & 2 === 2}`);
});
```

**Parameters:**

* `vaultKey` - Vault key identifier
* `chainId` - Blockchain chain ID
* `includeInactive` - Include inactive assets (default: false)

#### Get Whitelisted Asset

Get a specific whitelisted asset.

```typescript
// Public endpoint
const asset = await sdk.vault.getWhitelistedAsset(
  "yusd",
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC address
  1 // Ethereum
);

console.log(`Asset: ${asset.asset.symbol} (${asset.asset.name})`);
console.log(`Decimals: ${asset.asset.decimals}`);
```

#### Check Asset Whitelisted

Check if an asset is whitelisted for a vault.

```typescript
// Public endpoint
const checkResult = await sdk.vault.checkAssetWhitelisted(
  "yusd",
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  1
);

if (checkResult.isWhitelisted) {
  console.log("Asset is whitelisted");
  console.log(`Deposit Enabled: ${checkResult.depositEnabled}`);
  console.log(`Redeem Enabled: ${checkResult.redeemEnabled}`);
} else {
  console.log("Asset is not whitelisted");
}
```

#### Add Whitelisted Asset

Add a new whitelisted asset (requires admin authentication).

```typescript
const accessToken = localStorage.getItem("accessToken");

const newAsset = await sdk.vault.addWhitelistedAsset(
  accessToken,
  "yusd",
  {
    assetAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    assetSymbol: "USDC",
    assetName: "USD Coin",
    assetDecimals: 6,
    depositRedeemEnabled: 2, // 0 = none, 1 = deposit, 2 = both
  },
  1 // Chain ID
);
```

#### Remove Whitelisted Asset

Remove a whitelisted asset (requires admin authentication).

```typescript
const accessToken = localStorage.getItem("accessToken");

await sdk.vault.removeWhitelistedAsset(
  accessToken,
  "yusd",
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  1
);
```

### Transactions

All transaction endpoints require authentication and implement role-based filtering:

* **Regular users**: Automatically filtered to show only their own transactions
* **Admins/Moderators/Managers/LPs**: Can see all transactions

#### Get Transactions

Get transactions with pagination and filters.

```typescript
const accessToken = localStorage.getItem("accessToken");

const transactions = await sdk.vault.getTransactions(
  {
    chainId: 1,
    vaultAddress: "0x5bE91d34FeFbB7554497a74e25dC6df96bFef5DB",
    type: "deposit", // 'deposit' or 'redemption'
    status: "PROCESSED", // 'PENDING', 'PROCESSED', 'CANCELLED', 'NO-RETRY', 'FAILED'
    page: 1,
    pageSize: 20,
    startDate: "2024-01-01T00:00:00.000Z",
    endDate: "2024-01-31T23:59:59.999Z",
    // Admins can also filter by:
    // userAddress: "0x...",
    // receiverAddress: "0x...",
    // assetAddress: "0x...",
  },
  accessToken
);

console.log(`Found ${transactions.pagination.total} transactions`);
console.log(`Page ${transactions.pagination.page} of ${transactions.pagination.totalPages}`);

transactions.data.forEach((tx) => {
  console.log(`Transaction ${tx.id}:`);
  console.log(`  Type: ${tx.type}`);
  console.log(`  Status: ${tx.status}`);
  console.log(`  Amount: ${tx.amount}`);
  console.log(`  User: ${tx.userAddress}`);
  console.log(`  Timestamp: ${tx.timestamp}`);
});
```

**Filter Parameters:**

* `chainId` - Filter by blockchain chain ID
* `vaultAddress` - Filter by vault address
* `userAddress` - Filter by user address (admins only - regular users are automatically filtered)
* `receiverAddress` - Filter by receiver address
* `assetAddress` - Filter by asset address
* `type` - Filter by transaction type: `'deposit'` or `'redemption'`
* `status` - Filter by status: `'PENDING'`, `'PROCESSED'`, `'CANCELLED'`, `'NO-RETRY'`, or `'FAILED'`
* `startDate` - Filter by start date (ISO 8601 format)
* `endDate` - Filter by end date (ISO 8601 format)
* `page` - Page number (default: 1)
* `pageSize` - Items per page (default: 20, max: 100)

#### Get Transaction by ID

Get a specific transaction by its ID.

```typescript
const accessToken = localStorage.getItem("accessToken");

// Regular users: can only access their own transactions
// Admins: can access any transaction
const transaction = await sdk.vault.getTransactionById(1, accessToken);

console.log(`Transaction ${transaction.transaction.id}:`);
console.log(`  Type: ${transaction.transaction.type}`);
console.log(`  Status: ${transaction.transaction.status}`);
console.log(`  Hash: ${transaction.transaction.txnHash}`);
```

#### Get Transaction by Hash

Get a transaction by its blockchain transaction hash.

```typescript
const accessToken = localStorage.getItem("accessToken");

const transaction = await sdk.vault.getTransactionByHash(
  "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  1, // Chain ID
  accessToken
);

console.log(`Transaction found: ${transaction.transaction.id}`);
```

#### Get Transaction Filter Options

Get available filter options for transactions.

```typescript
const accessToken = localStorage.getItem("accessToken");

const filterOptions = await sdk.vault.getTransactionFilterOptions(accessToken);

console.log("Available chain IDs:", filterOptions.filters.chainIds);
console.log("Available statuses:", filterOptions.filters.statuses);
console.log("Available types:", filterOptions.filters.types);
```

### Complete Example

Here's a complete example combining multiple Vault API calls:

```typescript
import { YieldFiSDK } from "yieldfi-sdk";

async function vaultDashboard() {
  const sdk = await YieldFiSDK.create({
    gatewayUrl: "https://gw.yield.fi",
  });

  // 1. Get protocol statistics
  const stats = await sdk.vault.getProtocolStats();
  console.log(`Protocol TVL: $${stats.stats.totalTvl}`);

  // 2. Get available strategies
  const strategies = await sdk.vault.getStrategies();
  console.log(`Strategies: ${strategies.strategies.join(", ")}`);

  // 3. Get all vaults
  const vaults = await sdk.vault.getVaults({
    chainId: 1,
    page: 1,
    pageSize: 10,
  });

  // 4. Get details for each vault
  for (const vaultListItem of vaults.data) {
    const vault = await sdk.vault.getVaultByKey(vaultListItem.vaultKey, 1);
    console.log(`\n${vault.vault.name}:`);
    console.log(`  TVL: $${vault.vault.metrics.tvl}`);
    console.log(`  APY: ${vault.vault.metrics.apy7d}%`);

    // 5. Get whitelisted assets
    const assets = await sdk.vault.getWhitelistedAssets(
      vaultListItem.vaultKey,
      1,
      false
    );
    console.log(`  Whitelisted Assets: ${assets.assets.length}`);
  }

  // 6. Get user transactions (if authenticated)
  const accessToken = localStorage.getItem("accessToken");
  if (accessToken) {
    const transactions = await sdk.vault.getTransactions(
      {
        chainId: 1,
        page: 1,
        pageSize: 10,
      },
      accessToken
    );
    console.log(`\nYour Transactions: ${transactions.pagination.total}`);
  }
}

vaultDashboard();
```

### Next Steps

* Glassbook API - Partner transactions and referrals
* Examples - More vault operation examples


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.yield.fi/earn-with-yieldfi/integration-sdk/api-reference/vault-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.