API Reference Overview

The Zyfai SDK provides a comprehensive TypeScript API for integrating DeFi yield optimization into your applications. All methods are fully typed and include built-in error handling.

Quick Links

• Getting Started - Full integration guide
• Agent Quickstart - Compact reference for AI agents

API Organization

The SDK methods are organized into logical categories matching the sidebar navigation.

Account Management

Manage wallet connections and SIWE authentication.

Method	Description
connectAccount	Connect wallet and authenticate with SIWE
disconnectAccount	Disconnect and clear authentication state

Smart Wallet

Resolve and manage Safe smart wallets. The Safe (with session key) is assigned on the first depositFunds call — there is no separate deploy or session-key API.

Method	Description
getSmartWalletAddress	Get assigned Safe address for an EOA
pauseAgent	Pause automated yield optimization
resumeAgent	Resume automated yield optimization

Fund Management

Deposit and withdraw funds from your Smart Wallet. First deposit onboards the user onto a pre-deployed Safe with a signed session key (Base, Arbitrum, Mainnet).

Method	Description
depositFunds	Transfer tokens to Smart Wallet (onboards on first deposit)
logDeposit	Log an external deposit into the user’s profile
withdrawFunds	Withdraw from active positions

User Data

Retrieve and update user profile, positions, and settings.

Method	Description
getPositions	Get active positions and idle balances
getPortfolio	Get detailed portfolio with balances by asset type
getUserDetails	Get current user profile and settings
updateUserProfile	Update strategy, protocols, splitting settings
getHistory	Get transaction history
customizeBatch	Configure protocol/pool preferences per chain
enableSplitting	Enable position splitting across pools
disableSplitting	Disable position splitting
updateMinSplits	Update minimum split count
getFirstTopup	Get first deposit information
getSmartWalletByEOA	Map EOA to smart wallet address

Earnings & Performance

Track and calculate earnings and APY.

Method	Description
calculateOnchainEarnings	Calculate earnings on-chain for a wallet
getOnchainEarnings	Get current and lifetime earnings
getDailyApyHistory	Get APY history with weighted averages
getDailyEarnings	Get daily earnings breakdown

Protocol Data

Access DeFi protocol information.

Method	Description
getAvailableProtocols	Get available protocols and pools by chain

Opportunities Data

Discover yield opportunities by risk profile.

Method	Description
getAPYPerStrategy	Get APY by strategy type and period
getConservativeOpportunities	Get low-risk yield opportunities
getAggressiveOpportunities	Get high-risk, high-reward opportunities
getActiveConservativeOppsRisk	Get risk data for conservative pools
getActiveAggressiveOppsRisk	Get risk data for aggressive pools
getConservativePoolStatus	Get conservative pool status
getAggressivePoolStatus	Get aggressive pool status

SDK Key Information

Get information about wallets and TVL for your SDK API key. No wallet connection required.

Method	Description
getSdkAllowedWallets	Get list of wallets created via your SDK key
getSdkKeyTVL	Get total TVL across all SDK wallets

Analytics & Metrics

Platform-wide analytics and metrics.

Method	Description
getTVL	Get total value locked across platform
getVolume	Get total trading volume
getActiveWallets	Get active wallets count by chain

Rebalancing

Monitor rebalancing activity.

Method	Description
getRebalanceFrequency	Get rebalance tier and frequency

ERC-8004

Agent identity registration on-chain.

Method	Description
registerAgentOnIdentityRegistry	Register agent on ERC-8004 Identity Registry

---

Intelligence Layer

Read-only access to the Zyfai yield engine. No wallet connection required — API key only. See the Intelligence Layer overview for the full context.

Yield Simulation

Method	Description
simulateBestPositions	Preview the best yield split for an amount, with blended APY and ready-to-run calldata

Real-Time Risk Events

Method	Description
subscribeToEvents	Subscribe to live depegs, liquidity drops, and new collateral events via WebSocket

---

Common Patterns

Authentication Required

Most methods require SIWE authentication, which is handled automatically when you call connectAccount():

// Authentication is automatic
await sdk.connectAccount(privateKey, chainId);

// Now all protected methods work
const user = await sdk.getUserDetails();

SDK Key Methods (No Wallet Required)

Some methods only require your SDK API key and don’t need a wallet connection:

// Initialize SDK with just your API key
const sdk = new ZyfaiSDK({ apiKey: "zyfai_your_key" });

// No wallet connection needed
const wallets = await sdk.getSdkAllowedWallets();
const tvl = await sdk.getSdkKeyTVL();

console.log("Wallets created via SDK:", wallets.allowedWallets.length);
console.log("Total TVL:", tvl.totalTvl);

These methods are ideal for:

• B2B dashboards showing client metrics
• Analytics and monitoring without user interaction
• Server-side reporting and billing

Chain IDs

The SDK supports three chains:

Chain	ID
Base	8453
Arbitrum	42161
Ethereum Mainnet	1

import { getSupportedChainIds, isSupportedChain } from "@zyfai/sdk";

const chains = getSupportedChainIds(); // [8453, 42161, 1]
const isValid = isSupportedChain(8453); // true

Error Handling

All methods throw typed errors:

try {
  await sdk.depositFunds(userAddress, chainId, amount, "USDC");
} catch (error) {
  console.error("Deposit failed:", error.message);
}

Amount Formatting

Token amounts are always in the least decimal units (wei):

// For USDC / EURC (6 decimals), 100 = 100 * 10^6
const amount = "100000000"; // 100 USDC

await sdk.depositFunds(userAddress, chainId, amount, "USDC");

Async Processing

Some operations like withdrawals are processed asynchronously:

// Withdrawal is queued
const result = await sdk.withdrawFunds(userAddress, chainId);
console.log(result.message); // "Withdrawal request sent"

// Check history later to see completion
const history = await sdk.getHistory(walletAddress, chainId);

---

Type Safety

The SDK is fully typed with TypeScript. Import types as needed:

import type {
  SDKConfig,
  DepositResponse,
  PositionsResponse,
  UpdateUserProfileResponse,
  SupportedChainId,
} from "@zyfai/sdk";

Response Format

All SDK methods return consistent response objects:

{
  success: boolean; // Operation success status
  // ... method-specific data
}

Rate Limiting

API calls are rate-limited. The SDK includes automatic retry logic with exponential backoff.

Support

• GitHub Issues
• Telegram
• Zyfai Website