> For the complete documentation index, see [llms.txt](https://docs.wasabi.xyz/_/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wasabi.xyz/_/overview/technical-documentation/vault-integration-guide.md).

# Vault Integration Guide

This guide will walk you through the core concepts, smart contract interactions, and API endpoints needed to integrate Wasabi Vaults into your application.

Wasabi Vaults are built on the [ERC-4626 Tokenized Vault Standard](https://ethereum.org/developers/docs/standards/tokens/erc-4626/), providing a yield-bearing interface for liquidity providers.

### 1. Core Concepts

#### ERC-4626 Standard

By following the ERC-4626 standard, Wasabi Vaults ensure compatibility with the broader DeFi ecosystem. This standardizes the way users deposit assets, withdraw assets, and manage shares.

[Vault Interface: IERC4626.sol](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/interfaces/IERC4626.sol)

#### Vault Shares vs. Underlying Tokens

When you deposit assets into a Wasabi Vault, you receive Vault Shares in return.

* Underlying Tokens: The asset you deposit (e.g., WETH, USDC).
* Shares: A representation of your proportional ownership of the vault's total assets.

#### Yield Generation

The value of a vault share increases over time as interest is paid into the vault by borrowers or generated through protocol activities.

* Important: Your Vault Share balance stays the same, but each share becomes redeemable for a larger amount of the underlying token as the vault accrues value.

***

### 2. Smart Contract Integration

#### Depositing Assets

To supply liquidity to a vault, use the `deposit` function.

Solidity

```solidity
function deposit(uint256 assets, address receiver) external returns (uint256 shares);
```

* assets: The amount of the underlying token to deposit.
* receiver: The address that will receive the vault shares.
* *Note: You must approve the Vault contract to spend your tokens before calling this.*

#### Depositing Gas Tokens

For depositing native (gas) tokens, like ETH or BERA (on Berachain), you can call the depositEth function. Provide the gas token as payable amount.

```solidity
/// @dev Deposits ETH into the vault (only WETH vault)
function depositEth(address receiver) external payable returns (uint256);
```

#### Checking Balances

To track a user's position, use the following standard functions:

* `balanceOf(address user)`: Returns the number of shares the user currently holds.
* `maxWithdraw(address user)`: Returns the total number of underlying tokens the user is currently entitled to withdraw (Principal + Interest).

#### Withdrawing Assets

To exit a position, you can use the `withdraw` function.

Solidity

```solidity
function withdraw(
    uint256 assets, address receiver, address owner
) external returns (uint256 shares);
```

**How to Withdraw the Maximum Balance**

There are two primary ways to perform a full exit from a vault:

1. Using Assets: Call `maxWithdraw(user)` to get the total token value, then pass that value into the `withdraw` function.
2. Using Shares: Call `balanceOf(user)` to get the total share count, then call the `redeem` function to burn all shares in exchange for the underlying tokens.

***

### 3. Wasabi Vaults API

For off-chain data, historical stats, and portfolio overviews, use our REST API.

#### General Vault Statistics

Fetch global data for all Wasabi Vaults, including TVL, APR, and asset addresses.

* Endpoint: [GET /vaults/stats](https://api.wasabi.xyz/swagger-ui/index.html#/Vaults/Get%20Vault%20Stats)

#### Individual User Stats

Fetch current statistics for a specific user's deposit within a specific vault.

* Endpoint: [GET /vaults/lp-stats](https://api.wasabi.xyz/swagger-ui/index.html#/Vaults/getLPVaultStats)

#### User Portfolio

Fetch a comprehensive view of a user's vault portfolio across all deposited assets for a specific chain.

* Endpoint: [GET /vaults/portfolio](https://api.wasabi.xyz/swagger-ui/index.html#/Vaults/getLpVaultPortfolio)