Getting Started

Integrate YieldFi vaults seamlessly via our SDK. If you have any questions or run into issues during setup, feel free to raise them in our Discord channel or reach out directly on Telegram at SGYield.

Quick Start

Get started with the YieldFi SDK in just a few minutes. This guide will walk you through the essential steps to integrate the SDK into your application.

Step 1: Initialize the SDK

First, create an instance of the YieldFi SDK:

import { YieldFiSDK } from "yieldfi-sdk";

// Initialize SDK (async)
const sdk = await YieldFiSDK.create({
  gatewayUrl: "https://gw.yield.fi",
  partnerId: "your-partner-id", // Optional: for tracking
});

Step 2: Authenticate a User

The SDK uses Ethereum wallet signatures for authentication. Here's the complete flow:

// 1. Generate a nonce for the user's address
const nonce = await sdk.auth.generateNonce({
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
});

// 2. Sign the message with the user's wallet
// Using ethers.js v6
import { ethers } from "ethers";

const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const signature = await signer.signMessage(nonce.message);

// Or using MetaMask directly
const signature = await window.ethereum.request({
  method: "personal_sign",
  params: [nonce.message, userAddress],
});

// 3. Login with the signature
const authResponse = await sdk.auth.login({
  address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  signature,
  message: nonce.message,
});

// 4. Store tokens (you must manage storage yourself)
localStorage.setItem("accessToken", authResponse.accessToken);
localStorage.setItem("refreshToken", authResponse.refreshToken);
localStorage.setItem("user", JSON.stringify(authResponse.user));

Step 3: Query Vaults

Now you can query vault information:

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

console.log(`Found ${vaults.pagination.total} vaults`);

// Get a specific vault by key
const vault = await sdk.vault.getVaultByKey("yusd", 1);

console.log(`Vault: ${vault.vault.name}`);
console.log(`TVL: ${vault.vault.metrics.tvl}`);
console.log(`APY: ${vault.vault.metrics.apy7d}%`);

Step 4: Query Transactions (Authenticated)

To query transactions, you need an authenticated user:

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

// Get user's transactions
const transactions = await sdk.vault.getTransactions(
  {
    chainId: 1,
    type: "deposit",
    status: "PROCESSED",
    page: 1,
    pageSize: 20,
  },
  accessToken
);

console.log(`Found ${transactions.pagination.total} transactions`);
transactions.data.forEach((tx) => {
  console.log(`Transaction ${tx.id}: ${tx.type} - ${tx.status}`);
});

Step 5: Handle Errors

Always wrap SDK calls in try-catch blocks:

import {
  AuthenticationError,
  NetworkError,
  ValidationError,
} from "yieldfi-sdk";

try {
  const vault = await sdk.vault.getVaultByKey("yusd", 1);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Authentication failed:", error.message);
    // Redirect to login
  } else if (error instanceof NetworkError) {
    console.error("Network error:", error.message);
    // Show retry option
  } else if (error instanceof ValidationError) {
    console.error("Invalid input:", error.message);
    // Show validation error to user
  } else {
    console.error("Unexpected error:", error);
  }
}

Complete Example

Here's a complete example combining all the steps:

import { YieldFiSDK } from "yieldfi-sdk";
import { ethers } from "ethers";

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

  // 2. Check if user is already authenticated
  const storedToken = localStorage.getItem("accessToken");
  if (storedToken) {
    try {
      // Verify token is still valid by making an authenticated request
      const transactions = await sdk.vault.getTransactions(
        { chainId: 1, page: 1, pageSize: 1 },
        storedToken
      );
      console.log("User is authenticated");
    } catch (error) {
      // Token expired or invalid, clear storage
      localStorage.removeItem("accessToken");
      localStorage.removeItem("refreshToken");
      console.log("Session expired, please login again");
    }
  }

  // 3. Authenticate user (if not already authenticated)
  if (!storedToken) {
    const provider = new ethers.BrowserProvider(window.ethereum);
    const signer = await provider.getSigner();
    const address = await signer.getAddress();

    const nonce = await sdk.auth.generateNonce({ address });
    const signature = await signer.signMessage(nonce.message);

    const authResponse = await sdk.auth.login({
      address,
      signature,
      message: nonce.message,
    });

    localStorage.setItem("accessToken", authResponse.accessToken);
    localStorage.setItem("refreshToken", authResponse.refreshToken);
    localStorage.setItem("user", JSON.stringify(authResponse.user));
  }

  // 4. Query vaults
  const vaults = await sdk.vault.getVaults({ chainId: 1 });
  console.log(`Available vaults: ${vaults.pagination.total}`);

  return sdk;
}

// Initialize the app
initializeApp().then((sdk) => {
  console.log("SDK initialized successfully!");
});

Next Steps

• Configuration Guide - Learn about advanced configuration options

• Authentication Guide - Deep dive into authentication flows

• API Reference - Explore all available APIs