> For the complete documentation index, see [llms.txt](https://docs.yo.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yo.xyz/integrations/integration-guides/individual-contracts.md).

# Individual Contracts

This guide explains how to interact with the `yoVaults` smart contracts (`yoETH, yoUSD, yoBTC, yoEUR, yoGOLD`). These contracts implement the [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) Tokenized Vault Standard, enabling users and integrators to deposit ERC-20 tokens ("assets") and receive yield-bearing yoTokens in return. 

The guide outlines how to:

* Connect to the vaults with Ethers.js
* Use read functions (`previewDeposit`, `previewMint`, `previewRedeem`) to estimate outcomes
* Execute deposit and redemption transactions
* Understand how yoTokens ↔ assets conversion works

> All vaults follow the same contract interface and live on **Base chain (chain ID 8453) and on Ethereum mainnet (chain ID 1)**.

NOTE: yoGOLD is only available on Ethereum. 

***

## ⚙️ Setup

### Install Ethers

```bash
npm install ethers
```

### Connect to an RPC & Instantiate the Contract

```ts
import { ethers } from "ethers";
import abi from "./yoAbi.json"; // Use the ABI attached below 

const provider = new ethers.JsonRpcProvider("https://mainnet.base.org"); // or use any RPC for Ethereum chain
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

const YO_VAULTS = {
  yoETH: "0x3a43aec53490cb9fa922847385d82fe25d0e9de7",
  yoUSD: "0x0000000f2eb9f69274678c76222b35eec7588a65",
  yoBTC: "0xbcbc8cb4d1e8ed048a6276a5e94a3e952660bcbc",
  ...,
};

const vault = new ethers.Contract(YO_VAULTS.yoETH, abi, signer); // Swap as needed
```

{% file src="/files/S6idsNvxUyPjEGiLcEiR" %}

***

## 🔍 Simulate with `preview*` and `convertTo` Functions

These functions estimate how many shares or assets you'll receive/spend before making a transaction or to price your position.

### Pricing your positions:

#### `maxWithdraw(owner)`

Returns the **maximum amount of assets** that can currently be withdrawn by the given address.

```ts
const maxAssets = await vault.maxWithdraw(await signer.getAddress());
```

#### `convertToAssets(shares)`

Estimate how many yoTokens you get for a given asset amount (excludes fees):

```ts
const yoTokens = await vault.convertToShares(ethers.parseUnits("1.0", 18));
```

### Quoting before building a transaction

#### `previewDeposit(assets)`

Estimate how many yoTokens you get for a given asset amount net of deposit fees:

```ts
const yoTokens = await vault.previewDeposit(ethers.parseUnits("1.0", 18));
```

#### `previewRedeem(shares)`

Estimate how many assets you'd get back when redeeming yoTokens net of withdrawal fees:

```ts
const assetsOut = await vault.previewRedeem(ethers.parseUnits("1.0", 18));
```

***

## ✍️ Execute Transactions

### `deposit(assets, receiver)`

Deposit a specific amount of assets and receive yoTokens in return:

```ts
const tx = await vault.deposit(
  ethers.parseUnits("1.0", 18),       // Assets to deposit
  await signer.getAddress()           // Receiver of yoTokens
);
await tx.wait();
```

***

### `redeem(yoTokens, receiver, owner)`

Burn yoTokens and receive assets in return. You **cannot request an exact asset amount**. See our Notes below.

```ts
const tx = await vault.redeem(
  ethers.parseUnits("1.0", 18),       // yoTokens to redeem
  await signer.getAddress(),          // Receiver of assets
  await signer.getAddress()           // Owner of shares
);
await tx.wait();
```

***

##  Recap: Share-to-Asset Logic

<table><thead><tr><th width="267.7734375">You Want To...</th><th width="125">Use This Function</th><th>Simulation Tool</th></tr></thead><tbody><tr><td>Deposit assets for yoTokens</td><td><code>deposit()</code></td><td><code>previewDeposit()</code></td></tr><tr><td>Mint exact amount of yoTokens</td><td><code>mint()</code> </td><td><code>previewMint()</code></td></tr><tr><td>Redeem yoTokens for assets</td><td><code>redeem()</code></td><td><code>previewRedeem()</code></td></tr></tbody></table>

***

## Notes

* All values must be parsed using correct decimals (e.g. `ethers.parseUnits("1.0", 18)`).
  * WETH / yoETH decimals: <mark style="color:red;">18</mark>&#x20;
  * cbBTC / yoBTC decimals: <mark style="color:red;">8</mark>
  * USDC / yoUSD decimals: <mark style="color:red;">6</mark>
  * USDT / yoUSDT decimals: <mark style="color:red;">6</mark>
  * EURC / yoEUR: <mark style="color:red;">6</mark>
  * XAUT / yoGOLD: <mark style="color:red;">6</mark>
* Only `redeem` is supported for withdrawals because depending on the withdrawal amount, the yoVault may not have enough available liquidity to fill the redeem order. In those cases, the withdrawal will remain pending for up to 24 hours. The protocol will fill the redeem order and send the assets automatically to the `receiver` specified in the `requestRedeem` transaction.&#x20;
* All the yoVaults follow the same ABI and differ only by address.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.yo.xyz/integrations/integration-guides/individual-contracts.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.