# HYSP Vault

## Getting Started <a href="#getting-started" id="getting-started"></a>

The HYSP Vault SDK provides a simple interface for interacting with HYSP vault contracts on EVM networks. It supports both issuance (deposit) and redemption (withdraw) operations for tokenized assets.

**Option 1: TypeScript library**

You can install and import Wallet SDK for Javascript/TypeScript.

#### Step 1: Installing the Library <a href="#step-1-installing-the-library" id="step-1-installing-the-library"></a>

Install the npm library or yarn by copying the code below.

{% tabs %}
{% tab title="npm" %}

```sh
$ npm install @everstake/wallet-sdk-hysp
```

{% endtab %}

{% tab title="yarn" %}

```sh
$ yarn add @everstake/wallet-sdk-hysp
```

{% endtab %}
{% endtabs %}

#### Step 2: Import Wallet SDK <a href="#step-2-import-wallet-sdk" id="step-2-import-wallet-sdk"></a>

After installing the package, you can import the HYSP module and use the SDK:

**Import ES6**

```typescript
// import module
import { HYSP, ZeroReferrer } from "@everstake/wallet-sdk-hysp";
```

**Import ES5**

```typescript
// import module
const { HYSP, ZeroReferrer } = require("@everstake/wallet-sdk-hysp");
```

#### Step 3: Initialize the SDK <a href="#step-3-initialize-the-sdk" id="step-3-initialize-the-sdk"></a>

Before using any methods, you need to initialize the HYSP SDK with the target blockchain:

```typescript
import { HYSP, NetworkType, HYSPVaultType } from "@everstake/wallet-sdk-hysp";

// Create a new HYSP instance
const hysp = new HYSP();

// Initialize with network and vault type
await hysp.init(
  "eth_mainnet" as NetworkType, // Optional network: defaults to 'eth_mainnet'
  "https://your-rpc-url" // Optional: Custom RPC URL
);

console.log("Supported deposit tokens:", hysp.supportedIssuanceTokensAddresses);
console.log(
  "Supported redeem tokens:",
  hysp.supportedRedemptionTokensAddresses
);
```

#### Supported networks

Network types, which can be used for initialization:

* <mark style="color:yellow;">`eth_mainnet`</mark> - Ethereum Mainnet
* <mark style="color:yellow;">`base`</mark> - Base Mainnet

#### Deposit Flow Example <a href="#deposit-flow-example" id="deposit-flow-example"></a>

Here's a complete example showing how to deposit tokens:

```typescript
import { HYSP, ZeroReferrer } from "@everstake/wallet-sdk-hysp";
import { ethers } from "ethers";

async function hyspExample() {
  // Initialize SDK
  const hysp = new HYSP();
  await hysp.init();

  const walletAddress = "0x..."; // Your wallet address
  const tokenAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"; // USDC
  const depositAmount = 100.5; // Amount to deposit

  // 1. Check token balance
  const balance = await hysp.balanceOf(walletAddress, tokenAddress);
  console.log("Token balance:", balance.toString());

  // 2. Get deposit fee
  const depositFee = await hysp.getInstantDepositFee();
  console.log("Deposit fee:", depositFee, "%");

  // 3. Approve tokens for deposit
  const approveTx = await hysp.approveToIssuanceVault(
    walletAddress,
    tokenAddress,
    depositAmount
  );

  // ... (sign and send approveTx)

  // 4. Deposit tokens
  const depositTx = await hysp.depositInstant(
    walletAddress,
    tokenAddress,
    depositAmount,
    0, // minReceiveAmount
    ZeroReferrer
  );

  // ... (sign and send depositTx)

  console.log("Deposit completed!");
}
```

#### Redeem Flow Example <a href="#redeem-flow-example" id="redeem-flow-example"></a>

Here's an example showing how to redeem collateral tokens back to USDC:

```typescript
async function redeemExample() {
  // Initialize SDK
  const hysp = new HYSP();
  await hysp.init();

  const walletAddress = "0x..."; // Your wallet address
  const usdcAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"; // USDC
  const redeemAmount = 50.0; // Amount to redeem

  // 1. Check collateral balance
  const collateralBalance = await hysp.balanceOf(walletAddress);
  console.log("Collateral balance:", collateralBalance.toString());

  // 2. Check redemption liquidity
  const liquidity = await hysp.getInstantRedeemLiquidityAmount(usdcAddress);
  console.log("Available liquidity:", liquidity.toString());

  // 3. Approve collateral for redemption
  const approveTx = await hysp.approveToRedemptionVault(
    walletAddress,
    redeemAmount
  );

  // ... (sign and send approveTx)

  const redeemRequestTx = await hysp.redeemRequest(
    walletAddress,
    usdcAddress,
    redeemAmount
  );
  // ... (sign and send redeemRequestTx)
  console.log("Redeem request created!");
}
```

#### Next Steps <a href="#next-steps" id="next-steps"></a>

Now that you have the SDK set up, you can explore the available methods:

* <mark style="color:yellow;">`Getting Info`</mark> - Retrieve vault information, balances, and fees
* <mark style="color:yellow;">`Deposit Instant`</mark> - Deposit tokens instantly
* <mark style="color:yellow;">`Redeem Instant`</mark> - Redeem tokens instantly
* <mark style="color:yellow;">`Redeem Request`</mark> - Create redeem requests for non-instant redemptions (no fee)
* <mark style="color:yellow;">`Approve Issuance`</mark> - Approve tokens for deposits
* <mark style="color:yellow;">`Approve Redemption`</mark> - Approve tokens for redemptions

## Getting Info <a href="#getting-vault-information" id="getting-vault-information"></a>

This page describes methods for retrieving information about HYSP vaults, including balances, fees, and liquidity.

**Get Instant Redeem Liquidity**

* <mark style="color:yellow;">`getInstantRedeemLiquidityAmount(outTokenAddress?)`</mark>: Retrieves the liquidity available for instant redemption in the redemption vault contract. Currently only supports USDC — returns `0` for any other token.

```typescript
import { HYSP } from "@everstake/wallet-sdk-hysp";

const hysp = new HYSP();
await hysp.init();

const usdcAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
const liquidity = await hysp.getInstantRedeemLiquidityAmount(usdcAddress);
console.log("Available liquidity:", liquidity.toString());
```

### **Get Minimum Redeem Amount** <a href="#get-minimum-redeem-amount" id="get-minimum-redeem-amount"></a>

* <mark style="color:yellow;">`minRedeemAmount(outTokenAddress?)`</mark>: Retrieves the minimum redeem amount from the redemption vault contract.

```typescript
const minAmount = await hysp.minRedeemAmount(usdcAddress);
console.log("Minimum redeem amount:", minAmount.toString());
```

### **Get Instant Deposit Fee** <a href="#get-instant-deposit-fee" id="get-instant-deposit-fee"></a>

* <mark style="color:yellow;">`getInstantDepositFee()`</mark>: Retrieves the instant deposit fee from the issuance vault contract.

```ts
const depositFee = await hysp.getInstantDepositFee();
console.log("Instant deposit fee:", depositFee, "%");
```

### **Get Instant Redeem Fee** <a href="#get-instant-redeem-fee" id="get-instant-redeem-fee"></a>

* <mark style="color:yellow;">`getInstantRedeemFee()`</mark>: Retrieves the instant redeem fee from the redemption vault contract.

```typescript
const redeemFee = await hysp.getInstantRedeemFee();
console.log("Instant redeem fee:", redeemFee, "%");
```

### **Get Oracle Price** <a href="#get-oracle-price" id="get-oracle-price"></a>

* <mark style="color:yellow;">`getPrice()`</mark>: Retrieves the price from the oracle contract.

```ts
const price = await hysp.getPrice();
console.log("Oracle price:", price.toString());
```

### **Get Token Balance** <a href="#get-token-balance" id="get-token-balance"></a>

* <mark style="color:yellow;">`balanceOf(address, erc20contractAddress?)`</mark>: Retrieves the balance of ERC20 token associated with vault or collateral token.

```typescript
const walletAddress = "0x...";

// Get USDC balance
const usdcBalance = await hysp.balanceOf(walletAddress, usdcAddress);
console.log("USDC balance:", usdcBalance.toString());

// Get collateral token balance (default)
const collateralBalance = await hysp.balanceOf(walletAddress);
console.log("Collateral balance:", collateralBalance.toString());
```

### Get APY

* <mark style="color:yellow;">`getAPY()`</mark>: Retrieves the vault APY (Annual Percentage Yield) from the Midas API as a decimal number (for example, `0.05` means `5%`). The value is returned as a `number`.

```ts
const apy = await hysp.getAPY();
console.log("Vault APY:", apy);
```

### Get Redeem Requests

* <mark style="color:yellow;">`getRedeemRequests(address, filters?)`</mark>: Retrieves redeem requests for a given address by querying `RedeemRequest` events from the redemption vault. Returns an array of `RedeemRequestInfo` objects. Supports filtering and pagination.

**Parameters**

* <mark style="color:yellow;">`address`</mark> (string): The user address to fetch redeem requests for.
* <mark style="color:yellow;">`filters`</mark> (object, optional): Optional filters to narrow and paginate results.
  * <mark style="color:yellow;">`tokenOut`</mark> (string): Filter by output token address (applied at event level).
  * <mark style="color:yellow;">`fromId`</mark> (bigint): Filter requests with requestId >= this value (pagination - applied pre-multicall).
  * <mark style="color:yellow;">`status`</mark> (string): Filter by request status: `'Pending'`, `'Processed'`, or `'Canceled'` (applied post-multicall).
  * <mark style="color:yellow;">`limit`</mark> (number): Maximum number of results to return (pagination - applied after all other filters).

**Return type: `RedeemRequestInfo[]`**

| Field          | Type        | Description                                           |
| -------------- | ----------- | ----------------------------------------------------- |
| `requestId`    | `bigint`    | Unique request identifier                             |
| `sender`       | `string`    | Address of the requester                              |
| `tokenOut`     | `string`    | Token address to receive on redemption                |
| `amountMToken` | `BigNumber` | Amount of mToken to redeem                            |
| `feeAmount`    | `BigNumber` | Fee charged in mToken                                 |
| `status`       | `string`    | Request status: `Pending`, `Processed`, or `Canceled` |
| `mTokenRate`   | `BigNumber` | mToken rate at the time of the request                |
| `tokenOutRate` | `BigNumber` | Output token rate at the time of the request          |

**Code Examples**

Basic usage without filters:

```typescript
import { HYSP } from "@everstake/wallet-sdk-hysp";

const hysp = new HYSP();
await hysp.init();

const walletAddress = "0x...";
const requests = await hysp.getRedeemRequests(walletAddress);
console.log("Redeem requests:", requests);
// Example output:
// [
//   {
//     requestId: 1n,
//     sender: "0x...",
//     tokenOut: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
//     amountMToken: BigNumber(500),
//     feeAmount: BigNumber(0.5),
//     status: "Pending",
//     mTokenRate: BigNumber(1.05),
//     tokenOutRate: BigNumber(1),
//   }
// ]
```

Using filters:

```typescript
// Get first 10 requests
const firstPage = await hysp.getRedeemRequests(walletAddress, {
  limit: 10,
});

// Get next 10 requests starting from requestId 11
const secondPage = await hysp.getRedeemRequests(walletAddress, {
  fromId: 11n,
  limit: 10,
});

// Get only pending requests
const pendingRequests = await hysp.getRedeemRequests(walletAddress, {
  status: "Pending",
});
```

## Deposit instant

* <mark style="color:yellow;">`depositInstant(sender, tokenIn, amount, minReceiveAmount, referrerId)`</mark>: Prepares an instant deposit transaction that will deposit tokens with auto mint if account fits daily limit and token allowance. The prepared transaction will transfer token from the user, fee in tokenIn to feeReceiver, and mint collateral to user.

**Parameters**

* <mark style="color:yellow;">`sender`</mark> (string): The address of the transaction sender
* <mark style="color:yellow;">`tokenIn`</mark> (string): The token address to deposit (must be supported by issuance vault)
* <mark style="color:yellow;">`amount`</mark> (BigNumberish): The amount to deposit
* <mark style="color:yellow;">`minReceiveAmount`</mark> (BigNumberish): The minimum amount to receive (slippage protection)
* <mark style="color:yellow;">`referrerId`</mark> (string): The referrer ID as bytes32 (use <mark style="color:yellow;">`ZeroReferrer`</mark> for no referrer)

**Code Example**

```typescript
import { HYSP, ZeroReferrer } from "@everstake/wallet-sdk-hysp";
import { ethers } from "ethers";

// Initialize SDK
const hysp = new HYSP();
await hysp.init();

const walletAddress = "0x...";
const usdcAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
const depositAmount = 100.0;

// Create deposit transaction
const depositTx = await hysp.depositInstant(
  walletAddress,
  usdcAddress,
  depositAmount,
  0, // minReceiveAmount
  ZeroReferrer
);

// Sign and send transaction
const signer = await ethers.getSigner();
const txResponse = await signer.sendTransaction(depositTx);
await txResponse.wait();
```

**Calculating minReceiveAmount**

The <mark style="color:yellow;">`minReceiveAmount`</mark> can be calculated using the oracle price to provide slippage protection:

```typescript
// Calculate minimum receive amount with slippage protection
const price = await hysp.getPrice();
const depositFee = await hysp.getInstantDepositFee();
const slippageTolerance = 0.01; // 1% slippage tolerance

// Calculate expected output after fees
const grossOutput = new BigNumber(depositAmount).multipliedBy(price);
const feeAmount = grossOutput.multipliedBy(depositFee / 100);
const expectedOutput = grossOutput.minus(feeAmount);

// Apply slippage tolerance
const minReceiveAmount = expectedOutput.multipliedBy(1 - slippageTolerance);

// Create deposit transaction with slippage protection
const depositTx = await hysp.depositInstant(
  walletAddress,
  usdcAddress,
  depositAmount,
  minReceiveAmount,
  ZeroReferrer
);
```

**Prerequisites**

* Token must be approved for issuance vault before depositing (use <mark style="color:yellow;">`approveToIssuanceVault()`</mark>)
* Token must be in <mark style="color:yellow;">`hysp.supportedIssuanceTokensAddresses`</mark>
* Sufficient token balance required

## Redeem Instant

* <mark style="color:yellow;">`redeemInstant(sender, tokenOut, amount, minReceiveAmount)`</mark>: Prepares an instant redeem transaction that will redeem mToken to tokenOut if daily limit and allowance not exceeded. The prepared transaction will burn mToken from the user, transfer fee in mToken to feeReceiver, and transfer tokenOut to user.

**Parameters**

* <mark style="color:yellow;">`sender`</mark> (string): The address of the transaction sender
* <mark style="color:yellow;">`tokenOut`</mark> (string): The token address to redeem to (must be supported by redemption vault)
* <mark style="color:yellow;">`amount`</mark> (BigNumberish): The amount of mToken to redeem
* <mark style="color:yellow;">`minReceiveAmount`</mark> (BigNumberish): The minimum amount of tokenOut to receive (slippage protection)

**Code Example**

```typescript
import { HYSP } from "@everstake/wallet-sdk-hysp";
import { ethers } from "ethers";

// Initialize SDK
const hysp = new HYSP();
await hysp.init();

const walletAddress = "0x...";
const usdcAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
const redeemAmount = "50.0";

// Create redeem transaction
const redeemTx = await hysp.redeemInstant(
  walletAddress,
  usdcAddress,
  redeemAmount,
  0 // minReceiveAmount
);

// Sign and send transaction
const signer = await ethers.getSigner();
const txResponse = await signer.sendTransaction(redeemTx);
await txResponse.wait();
```

**Prerequisites**

* Collateral tokens must be approved for redemption vault before redeeming (use <mark style="color:yellow;">`approveToRedemptionVault()`</mark>)
* Token must be in <mark style="color:yellow;">`hysp.supportedRedemptionTokensAddresses`</mark>
* Sufficient collateral balance required
* Vault must have sufficient liquidity for instant redemption

## **Redeem Request**

* <mark style="color:yellow;">`redeemRequest(sender, tokenOut, amount)`</mark>: Prepares a redeem request transaction if tokenOut is not fiat. The prepared transaction will transfer amount in mToken to contract and fee in mToken to feeReceiver. This method is used when instant redemption is not possible due to liquidity constraints.

**Parameters**

* <mark style="color:yellow;">`sender`</mark> (string): The address of the transaction sender
* <mark style="color:yellow;">`tokenOut`</mark> (string): The token address to redeem to (must be supported by redemption vault)
* <mark style="color:yellow;">`amount`</mark> (BigNumberish): The amount of mToken to redeem

**Code Example**

```typescript
import { HYSP } from "@everstake/wallet-sdk-hysp";
import { ethers } from "ethers";

// Initialize SDK
const hysp = new HYSP();
await hysp.init();

const walletAddress = "0x...";
const usdcAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
const redeemAmount = "500.0";

// Create redeem request transaction
const redeemRequestTx = await hysp.redeemRequest(
  walletAddress,
  usdcAddress,
  redeemAmount
);

// Sign and send transaction
const signer = await ethers.getSigner();
const txResponse = await signer.sendTransaction(redeemRequestTx);
await txResponse.wait();
```

**Prerequisites**

* Token must be in <mark style="color:yellow;">`hysp.supportedRedemptionTokensAddresses`</mark>
* Sufficient collateral balance required
* Token must not be a fiat token

## Approve Issuance

* <mark style="color:yellow;">`approveToIssuanceVault(sender, tokenAddress, amount)`</mark>: Prepares an approval transaction that will approve the issuance vault to spend a specified amount of a given token on behalf of the sender. This transaction must be executed before depositing tokens.

**Parameters**

* <mark style="color:yellow;">`sender`</mark> (string): The address of the transaction sender
* <mark style="color:yellow;">`tokenAddress`</mark> (string): The address of the ERC20 token to approve (must be supported by issuance vault)
* <mark style="color:yellow;">`amount`</mark> (BigNumberish): The amount of tokens to approve

**Code Example**

```typescript
import { HYSP } from "@everstake/wallet-sdk-hysp";
import { ethers } from "ethers";

// Initialize SDK
const hysp = new HYSP();
await hysp.init();

const walletAddress = "0x...";
const usdcAddress = "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48";
const approveAmount = "100.0";

// Create approval transaction
const approveTx = await hysp.approveToIssuanceVault(
  walletAddress,
  usdcAddress,
  approveAmount
);

// Sign and send transaction
const signer = await ethers.getSigner();
const txResponse = await signer.sendTransaction(approveTx);
await txResponse.wait();
```

**Prerequisites**

* Token must be in <mark style="color:yellow;">`hysp.supportedIssuanceTokensAddresses`</mark>
* Sufficient token balance required
* Sufficient ETH for gas fees

## Approve Redemption

* <mark style="color:yellow;">`approveToRedemptionVault(sender, amount)`</mark>: Prepares an approval transaction that will approve the redemption vault to spend a specified amount of the collateral token on behalf of the sender. This transaction must be executed before redeeming tokens.

**Parameters**

* <mark style="color:yellow;">`sender`</mark> (string): The address of the transaction sender
* <mark style="color:yellow;">`amount`</mark> (BigNumberish): The amount of collateral tokens to approve

**Code Example**

```typescript
import { HYSP } from "@everstake/wallet-sdk-hysp";
import { ethers } from "ethers";

// Initialize SDK
const hysp = new HYSP();
await hysp.init();

const walletAddress = "0x...";
const redeemAmount = "50.0";

// Create approval transaction
const approveTx = await hysp.approveToRedemptionVault(
  walletAddress,
  redeemAmount
);

// Sign and send transaction
const signer = await ethers.getSigner();
const txResponse = await signer.sendTransaction(approveTx);
await txResponse.wait();
```

**Prerequisites**

* Sufficient collateral token balance required
* Sufficient ETH for gas fees


---

# 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.everstake.one/integrations/everstake-products/wallet-sdk/protocols/hysp-vault.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.