> For the complete documentation index, see [llms.txt](https://docs.augustdigital.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augustdigital.io/developers/typescript-sdk/code-examples/vaults.md).

# Vault Actions

### Overview

The August SDK provides comprehensive vault querying capabilities across all supported chains. Vaults follow the ERC4626 standard and include additional features for loan management, allocations, and user positions.

> For detailed vault SDK functions, please refer to the [SDK reference page](/developers/typescript-sdk/api.md)

#### Vault Versions

| Version | Description        | Chains             |
| ------- | ------------------ | ------------------ |
| `evm-0` | Legacy vaults      | Ethereum, Arbitrum |
| `evm-1` | Standard vaults    | All EVM chains     |
| `evm-2` | Multi-asset vaults | Ethereum, Base     |
| `sol-0` | Solana vaults      | Solana Mainnet     |

### Get All Vaults

Fetch all vaults across configured networks with optional enrichment.

```typescript
import AugustSDK from '@augustdigital/sdk'

const sdk = new AugustSDK({ appName: 'your-app-name' })

sdk.getVaults(options?: {
  chainIds?: number[];
  loans?: boolean;
  allocations?: boolean;
  wallet?: string;
  solanaWallet?: string;
}): Promise<IVault[]>
```

#### Parameters

| Parameter              | Type       | Required | Description                             |
| ---------------------- | ---------- | -------- | --------------------------------------- |
| `options.chainIds`     | `number[]` | No       | Filter by specific chain IDs            |
| `options.loans`        | `boolean`  | No       | Include loan data (default: true)       |
| `options.allocations`  | `boolean`  | No       | Include allocation data (default: true) |
| `options.wallet`       | `string`   | No       | EVM wallet to fetch positions for       |
| `options.solanaWallet` | `string`   | No       | Solana wallet to fetch positions for    |

#### Returns

Array of `IVault` objects

### Get Single Vault

Fetch detailed data for a specific vault with optional enrichment.

```typescript
sdk.getVault({
  vault: string;
  chainId?: number;
  options?: {
    loans?: boolean;
    allocations?: boolean;
    wallet?: string;
    solanaWallet?: string;
  };
}): Promise<IVault>
```

#### Parameters

| Parameter              | Type      | Required | Description                                    |
| ---------------------- | --------- | -------- | ---------------------------------------------- |
| `vault`                | `string`  | Yes      | Vault contract address or program ID           |
| `chainId`              | `number`  | No       | Chain ID (uses active network if not provided) |
| `options.loans`        | `boolean` | No       | Include loan data (default: true)              |
| `options.allocations`  | `boolean` | No       | Include allocation data (default: true)        |
| `options.wallet`       | `string`  | No       | EVM wallet for position data                   |
| `options.solanaWallet` | `string`  | No       | Solana wallet for position data                |

#### Returns

Single `IVault` object

### Get Vault Loans

Fetch active loan data for a vault (EVM-0 vaults only).

```typescript
sdk.getVaultLoans({
  vault: string;
  chainId?: number;
}): Promise<IVaultLoan[]>
```

#### Returns

Array of loan objects with borrower, principal, interest, and APR data.

### Get Vault Allocations

> **This is the data behind the "Vault Exposure" section on the Upshift app.** One call returns exactly what the Upshift UI renders — read `exposurePerCategory` for the pre-bucketed view (`supplying` / `borrowing` / `wallet` / `lending` legs plus per-category USD totals). It lives on the root `sdk`, requires an RPC provider for the vault's chain, and needs `keys.august` to populate the CeFi/OTC legs. See the [Transparency Dashboard](#transparency-dashboard) section for the per-card methods.

> Authentication is required for this function

Fetch DeFi, CeFi, and OTC allocation breakdowns for a vault.

```typescript
sdk.getVaultAllocations({
  vault: string;
  chainId?: number;
}): Promise<IVaultAllocations>
```

#### Returns

Object containing `defi`, `cefi`, `otc`, and `tokens` arrays.

### Transparency Dashboard

Every tab and card of the Upshift per-vault **Transparency** page is available as an individual read method on `sdk.apiModule`, so you can compose exactly the subset you want — e.g. the Performance tab without the collateral-ratio card. All methods:

* are **public** (no API key), one HTTPS request each, **zero RPC** from the SDK — no `providers` config needed;
* are **snapshot-backed** (positions/oracle refresh hourly; cache ≥ 60 s on your side);
* throw `AugustValidationError` on a bad address / chain id / date / limit **before** any request is made; non-2xx API responses surface as `AugustServerError` (`AugustRateLimitError` on 429, `AugustTimeoutError` on timeout);
* the `chainId`-taking methods are **EVM-only** (Solana/Stellar vaults have no transparency data). `getVaultBackingSeries` / `getVaultSmoothedApy` are keyed by vault address alone;
* date windows (`startDate` / `endDate`) are `YYYY-MM-DD` and **both inclusive**.

Minimal construction — no RPC provider and no API key are needed for anything in this section:

```typescript
import AugustSDK from '@augustdigital/sdk';

const sdk = new AugustSDK({ appName: 'tori-finance', keys: {} });
```

| Dashboard surface                                                                       | Method                                                                                      | Returns                              |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ |
| Overview → strategy breakdown, backing composition, vault buffer, wallets, headline TVL | `getVaultPositionSnapshot({ vault, chainId })`                                              | `ITransparencyPositions`             |
| Overview → APY last 30 days · Performance → APY Over Time                               | `getVaultSmoothedApy({ vault, daysAgo?, averagingPeriodDays?, applySmoothing? })`           | `ITransparencyApySeries`             |
| Performance → Backing vs Supply · Collateral Ratio · sidebar 7d deltas                  | `getVaultBackingSeries({ vault, startDate?, endDate?, limit? })`                            | `ITransparencyRatioPoint[]`          |
| Performance → Allocation Over Time                                                      | `getVaultHistoricalAllocations({ vault, chainId, startDate?, endDate? })`                   | `ITransparencyHistoricalAllocations` |
| Performance → fees card                                                                 | `getVaultFeeConfig({ vault, chainId })`                                                     | `ITransparencyFees`                  |
| Performance → share price / TVL history                                                 | `sdk.getVaultHistoricalTimeseries(...)` (root `sdk`, existing)                              | —                                    |
| NAV Oracle tab                                                                          | `getVaultOracleClassification(vault, chainId)` (existing; positional args)                  | `IOracleClassification`              |
| Governance → Vault Roles                                                                | `getVaultGovernanceRoles({ vault, chainId })`                                               | `ITransparencyGovernanceRoles`       |
| Governance → Vault Permissions                                                          | `getVaultGovernancePermissions({ vault, chainId })`                                         | `ITransparencyGovernancePermissions` |
| Governance → Pending Timelocks                                                          | `getVaultGovernanceTimelocks({ vault, chainId, status? })`                                  | `ITransparencyTimelocks`             |
| Governance → Audit Log                                                                  | `getVaultGovernanceAuditLog({ vault, chainId, category?, before?, limit? })`                | `ITransparencyAuditLog`              |
| Vault Exposure section (main pool page)                                                 | `sdk.getVaultAllocations({ vault, chainId })` (root `sdk`; needs RPC + API key — see above) | `IVaultAllocations`                  |

#### Reproducing the Overview headline numbers

```typescript
const pos = await sdk.apiModule.getVaultPositionSnapshot({
  vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA',
  chainId: 143,
});

// Headline "Total NAV" on the page is the vault-reported figure from the SAME snapshot:
const headline = pos.reported_tvl ?? pos.total_nav;
// Vault Buffer = liquidity sitting on the vault contract itself:
const deployed = pos.subaccounts.reduce((a, s) => a + s.total_usd, 0);
const vaultBuffer = Math.max(0, pos.total_nav - deployed);
// Every field is from `pos.snapshot_at` — show it as "Last updated".
```

Notes:

* **Borrow legs are negative.** In `ITransparencyTokenExposure`, `role: 'borrow'` rows carry negative `usd_value` and `balance`; a protocol group's `total_usd` is already the net.
* **Pricing follows the published methodology.** Hard-pegged stables price at their peg (the same overrides the NAV Oracle tab lists), so `total_usd` values match the dashboard exactly rather than raw market prices.
* **`getVaultBackingSeries` returns newest-first, hourly points** — sort ascending before charting; `adjusted_redeem_ratio * 100` is the collateral-ratio percent.
* **`getVaultSmoothedApy` is the ONLY way to match the app's APY charts**: the backend applies a rolling-median/mean smoothing filter server-side; recomputing APY locally from share ratios will not match. `values` are decimal fractions (0.0245 = 2.45%), `labels` are `M/D/YYYY`.
* **Audit-log pagination**: pass `before` = the last returned entry's `timestamp` **verbatim** while `has_more` is true (exclusive cursor). Audit and timelock timestamps are naive-UTC (no `Z`); `snapshot_at` carries one.
* **Units**: `pct_of_nav` / `pct_of_subaccount` / `pct_of_tvl` are fractions (0.25 = 25%); the fee `*_pct` fields are already percents (2 = 2%).
* **Pending Timelocks is often empty** — the default filter is `scheduled`; pass `status: 'all'` to show history (the Audit Log covers the same events).
* **Governance `warnings`**: Safe / Fordefi enrichment failures degrade rows and append a warning code rather than failing the call — check the array if a role looks incomplete. Codes seen in the wild: `safe_api_unavailable`, `fordefi_api_unavailable`, `fordefi_partial_coverage` (expected — AA subaccounts are never Fordefi keys), `timelock_duration_unavailable`.

#### Example — a Performance tab without the collateral-ratio card

```typescript
const vault = '0x955256B31097dDf47a9E47A95aDfDFB4460D8522';
const [apy, allocations, fees] = await Promise.all([
  sdk.apiModule.getVaultSmoothedApy({ vault, daysAgo: 90 }),
  sdk.apiModule.getVaultHistoricalAllocations({ vault, chainId: 1, startDate: '2026-08-01' }),
  sdk.apiModule.getVaultFeeConfig({ vault, chainId: 1 }),
]);
```

### Get Vault Annualized APY

Fetch annualized APY metrics for specific vaults.

> **Supported Vaults**: cUSDO, tETH, wstETH, rsETH
>
> **Deprecation Notice**: The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated and will be removed on 2026-01-01. Use `liquidAPY30Day` and `liquidAPY7Day` instead.

```typescript
sdk.getVaultAnnualizedApy({
  vault: string;
}): Promise<IVaultAnnualizedApy>
```

#### Parameters

| Parameter | Type     | Required | Description            |
| --------- | -------- | -------- | ---------------------- |
| `vault`   | `string` | Yes      | Vault contract address |

#### Returns

`IVaultAnnualizedApy` object with liquidity APY and annualized metrics.

### Get Vault Historical Timeseries

Fetch comprehensive historical timeseries data for a vault including TVL, APY, PnL, share price, and other metrics.

```typescript
sdk.getVaultHistoricalTimeseries({
  vault: string;
  nDays?: number;
}): Promise<IHistoricalTimeseriesResponse>
```

#### Parameters

| Parameter | Type     | Required | Description                                             |
| --------- | -------- | -------- | ------------------------------------------------------- |
| `vault`   | `string` | Yes      | Vault contract address                                  |
| `nDays`   | `number` | No       | Number of days of historical data (default: 30, min: 1) |

#### Returns

Historical timeseries data object with date string keys containing TVL, APY, PnL, and share price.

### Get Vault TVL

Fetch current or historical total value locked (TVL) for a vault.

```typescript
sdk.getVaultTvl({
  vault: string;
  chainId?: number;
  historical?: {
    daysAgo?: number;
    order?: 'asc' | 'desc';
    interval?: 'days' | 'weeks' | 'months' | 'years';
  };
}): Promise<{ value: INormalizedNumber; timestamp: string }[]>
```

#### Returns

Array of TVL data points with timestamps.

### Get Vault Positions

Fetch user positions across one or all vaults.

```typescript
sdk.getVaultPositions({
  vault?: string;
  wallet?: string;
  chainId?: number;
  showAllVaults?: boolean;
  solanaWallet?: string;
}): Promise<IVaultPosition[]>
```

#### Parameters

| Parameter       | Type      | Required | Description                                      |
| --------------- | --------- | -------- | ------------------------------------------------ |
| `vault`         | `string`  | No       | Specific vault address (omit for all vaults)     |
| `wallet`        | `string`  | No       | EVM wallet address                               |
| `solanaWallet`  | `string`  | No       | Solana wallet address                            |
| `chainId`       | `number`  | No       | Filter by specific chain                         |
| `showAllVaults` | `boolean` | No       | Include vaults with no position (default: false) |

#### Returns

Array of vault position objects.

### Get Available Redemptions

Fetch claimable redemption requests for a vault and wallet.

```typescript
sdk.getVaultAvailableRedemptions({
  vault: string;
  chainId?: number;
  wallet?: string;
  verbose?: boolean;
}): Promise<{
  availableRedemptions: IVaultAvailableRedemption[];
  pendingRedemptions: IVaultAvailableRedemption[];
}>
```

#### Returns

Object with `availableRedemptions` (ready to claim) and `pendingRedemptions` (waiting for lag period).

### Get Vault Withdrawals

Fetch withdrawal summary and pending withdrawal queue for a vault.

```typescript
sdk.getVaultWithdrawals({
  vault: string;
  chainId?: number;
}): Promise<IVaultWithdrawals>
```

#### Parameters

| Parameter | Type     | Required | Description                                    |
| --------- | -------- | -------- | ---------------------------------------------- |
| `vault`   | `string` | Yes      | Vault contract address                         |
| `chainId` | `number` | No       | Chain ID (uses active network if not provided) |

#### Returns

`IVaultWithdrawals` object containing total withdrawals and pending queue.

### Get Vault PnL

Fetch vault-level profit and loss (not user-specific).

```typescript
sdk.getVaultPnl({
  vault: string;
  chainId?: number;
}): Promise<IVaultPnl>
```

#### Parameters

| Parameter | Type     | Required | Description                                    |
| --------- | -------- | -------- | ---------------------------------------------- |
| `vault`   | `string` | Yes      | Vault contract address                         |
| `chainId` | `number` | No       | Chain ID (uses active network if not provided) |

#### Returns

`IVaultPnl` object with total PnL in native token and USD.

### Get User Lifetime PnL

Calculate lifetime profit and loss for a user in a specific vault.

```typescript
sdk.getVaultUserLifetimePnl({
  vault: string;
  wallet: string;
  chainId?: number;
}): Promise<IVaultUserLifetimePnl>
```

#### Parameters

| Parameter | Type     | Required | Description                                    |
| --------- | -------- | -------- | ---------------------------------------------- |
| `vault`   | `string` | Yes      | Vault contract address                         |
| `wallet`  | `string` | Yes      | User wallet address                            |
| `chainId` | `number` | No       | Chain ID (uses active network if not provided) |

#### Returns

`IVaultUserLifetimePnl` object with realized and unrealized PnL.

### Get Yield Last Realized

Get the timestamp when yield was last realized for a vault.

```typescript
sdk.getYieldLastRealizedOn({
  vault: string;
  chainId?: number;
}): Promise<number>
```

#### Parameters

| Parameter | Type     | Required | Description                                    |
| --------- | -------- | -------- | ---------------------------------------------- |
| `vault`   | `string` | Yes      | Vault contract address                         |
| `chainId` | `number` | No       | Chain ID (uses active network if not provided) |

#### Returns

Unix timestamp (in seconds) when yield was last realized.

### Get Borrower Health Factor

> Authentication is required for this function

Get the borrower's health factor by vault.

```typescript
sdk.getVaultBorrowerHealthFactor({
  chainId?: number;
}): Promise<Record<string, number>>
```

#### Parameters

| Parameter | Type     | Required | Description                 |
| --------- | -------- | -------- | --------------------------- |
| `chainId` | `number` | No       | Filter by specific chain ID |

#### Returns

Object mapping vault addresses to their borrower health factors.

### IVault Interface

All vault getter methods return the `IVault` interface:

#### Key Fields

**`depositAssets`** - Array of all supported deposit tokens including:

* Underlying asset (always first)
* Adapter tokens (if available)
* Whitelisted assets (for multi-asset vaults)

**`version`** - Determines which deposit/withdrawal functions to use:

* `evm-0`, `evm-1`: 2-param deposit
* `evm-2`: 3-param deposit with asset selection

**`position`** - User-specific data (when wallet provided):

* Wallet balance
* Available redemptions
* Pending redemptions
* Redeemable amount

### Get User History

```typescript
sdk.getUserHistory({
  wallet: string;
  chainId?: number;
  vault?: string;
}): Promise<IVaultUserHistoryItem[]>
```

Returns user transaction history (deposits, withdrawals, etc.).

### Get User Transfers

```typescript
sdk.getUserTransfers({
  wallet: string;
  chainId?: number;
  vault?: string;
}): Promise<IVaultTransfer[]>
```

Returns vault share transfer history for a user.

### Get Staking Positions

```typescript
sdk.getStakingPositions(
  wallet?: string,
  chainId?: number
): Promise<IActiveStakingPosition[]>
```

Returns active reward staking positions.

### Examples

#### Complete Vault Query

```typescript
const vault = await sdk.getVault({
  vault: '0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42',
  chainId: 1,
  options: {
    loans: true,
    allocations: true,
    wallet: '0xYourWallet...',
  },
});

// Basic info
console.log(vault.name);
console.log(vault.version);
console.log(vault.apy.apy);

// Deposit options
console.log(
  'Can deposit:',
  vault.depositAssets.map((a) => a.symbol),
);

// User position
if (vault.position) {
  console.log('Your balance:', vault.position.walletBalance.normalized);
  console.log(
    'Available redemptions:',
    vault.position.availableRedemptions.length,
  );
}

// Loans (if available)
if (vault.loans) {
  console.log('Active loans:', vault.loans.length);
}
```

#### Filter Vaults by Criteria

```typescript
const vaults = await sdk.getVaults();

// High APY vaults
const highYield = vaults.filter((v) => v.apy.apy > 10);

// Featured vaults
const featured = vaults.filter((v) => v.isFeatured);

// Active vaults only
const active = vaults.filter((v) => v.status === 'active');

// Vaults with deposits enabled
const depositable = vaults.filter((v) => !v.isDepositPaused);

// Multi-asset vaults
const multiAsset = vaults.filter((v) => v.version === 'evm-2');
```

#### Check Deposit Options

```typescript
const vault = await sdk.getVault({
  vault: '0x5Fde59415625401278c4d41C6beFCe3790eb357f',
  chainId: 1,
});

// Show all deposit options to user
console.log('You can deposit:');
vault.depositAssets.forEach((asset) => {
  console.log(`- ${asset.symbol} (${asset.address})`);
});
// Output:
// - wstETH (0x7f39...)  <- Underlying
// - WETH (0xC02a...)    <- Adapter
// - ETH (0x0000...)     <- Adapter
```

### Error Handling

```typescript
try {
  const vault = await sdk.getVault({
    vault: vaultAddress,
    chainId: 1,
  });
} catch (error) {
  if (error.message.includes('Missing RPC URL')) {
    console.error('Configure RPC for this chain');
  } else if (error.message.includes('not found')) {
    console.error('Vault does not exist');
  } else {
    console.error('Failed to fetch vault:', error.message);
  }
}
```