Getting Started

Welcome to the Zyfai SDK documentation! This TypeScript SDK provides a comprehensive solution for interacting with the Zyfai Yield Optimization Engine, enabling you to deposit into Safe smart wallets, manage DeFi positions, and optimize yield across multiple protocols.

What is Zyfai SDK?

The Zyfai SDK is a powerful TypeScript library that simplifies interaction with Zyfai’s yield optimization infrastructure.

Two Ways to Earn Yield

The SDK offers two distinct approaches for earning yield:

Feature	Smart Wallet (Safe)	Vault
Type	Personal subaccount	Shared pool
Chains	Base, Arbitrum, Ethereum Mainnet	Base only
Assets	USDC, WETH, EURC	USDC
Control	Full ownership	Shares-based
Withdrawals	Direct	Async (request → claim)
Optimization	Automated rebalancing	Pool-managed
Use case	Advanced yield optimization	Simple deposit & earn

• Smart Wallet: On first deposit, a personal pre-deployed Safe (with session key) is assigned for automated yield optimization across Base, Arbitrum, and Mainnet
• Vault: Deposit into a shared vault on Base and receive shares representing your stake

Features

The SDK provides:

• Pre-deployed Smart Wallets: First depositFunds assigns an ERC-4337 / ERC-7579 Safe with a signed session key
• Flexible Authentication: Support for private keys and modern wallet providers with automatic SIWE authentication
• Multi-Chain Support: Base (8453), Arbitrum (42161), and Ethereum Mainnet (1)
• Multi-Asset Support: USDC, WETH, and EURC (EURC on Mainnet and Base)
• Yield Optimization: Access multiple DeFi protocols and strategies
• Position Tracking: Monitor and manage your DeFi positions across chains
• Analytics & Earnings: Track earnings, APY history, and portfolio performance
• SDK Key Analytics: Access wallet lists and TVL data without requiring wallet connection

Want to see the SDK in action before diving into the code? Check out our Official Demo Application.

🔗 Repo: github.com/ondefy/zyfai-sdk-demo
🔗 Website: demo.zyf.ai

This Vite + React demo integrated with Reown AppKit showcases:

• Wallet Connection (EOA via AppKit)
• Fund Management (Deposit / Withdrawal — first deposit onboards the Safe)
• Real-time Data Retrieval (Positions & Earnings)

Prerequisites

Before you begin, ensure your environment meets these requirements:

1. Node.js: Version 18.0.0 or higher
2. API Key: Obtain your SDK API Key from the Zyfai Dashboard
3. CORS Whitelist: Your application domain must be whitelisted on the Zyfai backend to allow API calls from the browser. Contact the Zyfai team with your domain (e.g. https://app.yourproject.com) to get it added. Without this, browser-side SDK calls will be blocked by CORS policy.

Installation

Install the SDK along with viem as a peer dependency.

Latest version: 0.2.50

npm

npm install @zyfai/sdk@0.2.50 viem

Architecture

The SDK bridges your application with two core backend systems:

System	Purpose	API Version
Execution API	Deposits, withdrawals, transactions, session management	/api/v1
Data API	Earnings, opportunities, APY history, analytics	/api/v2

---

Quick Start

Follow these steps to integrate Zyfai into your application.

1. Initialize the SDK

Create a new instance of the Zyfai SDK with your configuration:

import { ZyfaiSDK } from "@zyfai/sdk";

const sdk = new ZyfaiSDK({
  apiKey: "your-api-key",
  rpcUrls: {
    // Optional: Custom RPC URLs per chain
    8453: "https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
    42161: "https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY",
    9745: "https://your-plasma-rpc-provider.com",
  },
});

2. Connect an Account

The SDK handles SIWE (Sign-In with Ethereum) authentication automatically.

Option A: Backend/Node.js (Private Key)

const privateKey = "0x...";
const chainId = 42161; // Arbitrum

await sdk.connectAccount(privateKey, chainId);

Option B: Browser/Frontend (Wallet Provider)

// Works with any EIP-1193 provider (wagmi, web3-react, etc.)
const provider = window.ethereum; 

await sdk.connectAccount(provider);

connectAccount() performs the full SIWE handshake. No additional authentication logic is required in your application.

3. Fund Management (onboarding via deposit)

Zyfai uses Safe smart accounts to manage user funds. There is no separate deploy or session-key step.

The first depositFunds call associates the EOA with a pre-deployed Smart Account that already has a signed session key. The Safe is available immediately on Base, Arbitrum, and Ethereum Mainnet. This does not change how the user’s EOA works — they remain the owner of a linked Smart Wallet with session permissions for automated rebalancing.

Deposit

Transfer tokens from the EOA to the Safe smart wallet:

const userAddress = "0xUser...";
const chainId = 42161;
const amount = "100000000"; // 100 USDC (6 decimals)

// asset is required; strategy is optional (first deposit only, default: "conservative")
const deposit = await sdk.depositFunds(
  userAddress,
  chainId,
  amount,
  "USDC",
  "conservative"
);

// After first deposit, inspect the assigned Safe
const walletInfo = await sdk.getSmartWalletAddress(userAddress, chainId);
console.log(`Safe Address: ${walletInfo.address} (Deployed: ${walletInfo.isDeployed})`);

Strategy Options (applied on first deposit):

• "conservative" (default): Optimized for low-risk, stable yield.
• "aggressive": Optimized for higher yield with higher risk profile.

Supported assets: "USDC", "WETH", "EURC" (EURC on Mainnet and Base only).

Minimums apply to total Safe balance after deposit. Smaller top-ups are allowed if the Safe already meets the threshold.

Chain	USDC	WETH
Base / Arbitrum	$5	0.001 WETH
Ethereum Mainnet	$10,000	5 WETH

Withdrawal

Initiate a withdrawal from the Safe back to an EOA:

// Full withdrawal
await sdk.withdrawFunds(userAddress, chainId);

// Partial withdrawal
await sdk.withdrawFunds(userAddress, chainId, "50000000"); // 50 USDC

Withdrawals are processed asynchronously and will always complete — but not instantly. Follow these guidelines to handle them correctly:

• Do not poll the withdrawal endpoint repeatedly. Once a withdrawal is initiated, it will be processed. Polling adds unnecessary load and can lead to duplicate requests.
• Track withdrawal state locally. Save a flag in your local state (e.g. isPendingWithdrawal: true) as soon as withdrawFunds() is called. Use this flag to reflect a “pending” status in your UI.
• Use sdk.getHistory() to confirm when the transaction has landed on-chain. Poll this endpoint at a reasonable interval (e.g. every 15–30 seconds) and clear your local flag once the transaction appears.

// After calling withdrawFunds, set a local flag
localStorage.setItem("withdrawalPending", "true");

// Poll getHistory until the withdrawal appears
const history = await sdk.getHistory(userAddress, chainId);
const completed = history.some(tx => tx.type === "withdrawal");

if (completed) {
  localStorage.removeItem("withdrawalPending");
}

4. Monitor Performance

// Get current positions
const positions = await sdk.getPositions(userAddress, chainId);

// Get lifetime earnings
const wallet = await sdk.getSmartWalletAddress(userAddress, chainId);
const earnings = await sdk.getOnchainEarnings(wallet.address);

// Get 30-day APY history
const apy = await sdk.getDailyApyHistory(wallet.address, "30D");

---

Full Workflow Example

Here is a complete integration script:

import { ZyfaiSDK } from "@zyfai/sdk";

async function runWorkflow() {
  const sdk = new ZyfaiSDK({ apiKey: process.env.ZYFAI_API_KEY! });

  try {
    // 1. Setup
    await sdk.connectAccount(process.env.PRIVATE_KEY!, 42161);
    const user = "0x...";
    const chainId = 42161;

    // 2. Deposit (first call assigns pre-deployed Safe + session)
    const deposit = await sdk.depositFunds(user, chainId, "1000000", "USDC", "conservative");
    console.log("Deposit initiated:", deposit.txHash);

    // 4. Cleanup
    await sdk.disconnectAccount();
  } catch (err) {
    console.error("Workflow failed:", err);
  }
}

Advanced Configuration

Environment Variables

Store sensitive credentials securely:

# .env
ZYFAI_API_KEY=zy_...
PRIVATE_KEY=0x...

# Optional Custom RPCs
BASE_RPC_URL=https://...
ARBITRUM_RPC_URL=https://...

Custom RPC Setup

const sdk = new ZyfaiSDK({
  apiKey: process.env.ZYFAI_API_KEY!,
  rpcUrls: {
    8453: process.env.BASE_RPC_URL,
    42161: process.env.ARBITRUM_RPC_URL,
  },
});

Key Features Deep Dive

Pre-deployed Wallets

On first deposit, the backend assigns a pre-deployed Safe (with signed session key) to the EOA. The same Safe is available immediately on Base, Arbitrum, and Ethereum Mainnet.

Session Key Security

Session keys ship with the pre-deployed Safe. They cannot withdraw funds to arbitrary addresses; they are strictly limited to rebalancing assets within the Zyfai ecosystem.

Comprehensive Analytics

• Platform-wide: TVL, volume, and active user metrics.
• User-specific: Historical APY (7D/14D/30D), detailed earnings breakdown, and transaction logs.

Target Audience

• dApp Developers: Build DeFi apps with abstraction and yield optimization.
• DeFi Services: Manage Safe wallets and positions at scale.
• Wallet Providers: Embed yield optimization directly into your wallet UI.

Troubleshooting

• “No account connected”: Ensure sdk.connectAccount() is called and resolved before executing transactions.
• “Unsupported chain”: Verify the chain ID is supported (1, 8453, 42161).
• CORS Errors: In browsers, ensure your domain is whitelisted in the Zyfai Dashboard.

Next Steps

Check out the API Reference for a detailed list of all available methods.

Support

• GitHub: ondefy/zyfai-sdk
• Community: Join our Telegram.
• Website: zyf.ai