Skip to main content

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.

API Organization​

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

Account Management​

Manage wallet connections and SIWE authentication.

MethodDescription
connectAccountConnect wallet and authenticate with SIWE
disconnectAccountDisconnect and clear authentication state

Smart Wallet​

Deploy and manage Safe smart wallets with ERC-4337 account abstraction.

MethodDescription
getSmartWalletAddressGet deterministic Safe address for an EOA
deploySafeDeploy Safe wallet with gasless transactions
pauseAgentPause automated yield optimization
resumeAgentResume automated yield optimization

Session Keys​

Create and manage session keys for delegated transactions.

MethodDescription
createSessionKeyCreate session key with limited permissions

Fund Management​

Deposit and withdraw funds from your Smart Wallet.

MethodDescription
depositFundsTransfer tokens to Smart Wallet
withdrawFundsWithdraw from active positions

User Data​

Retrieve and update user profile, positions, and settings.

MethodDescription
getPositionsAndPortfolioGet active positions and idle balances
getUserDetailsGet current user profile and settings
updateUserProfileUpdate strategy, protocols, splitting settings
getHistoryGet transaction history
customizeBatchConfigure protocol/pool preferences per chain
enableSplittingEnable position splitting across pools
disableSplittingDisable position splitting
updateMinSplitsUpdate minimum split count
getFirstTopupGet first deposit information
getSmartWalletByEOAMap EOA to smart wallet address

Earnings & Performance​

Track and calculate earnings and APY.

MethodDescription
getDailyApyHistoryGet APY history with weighted averages
getOnchainEarningsGet current and lifetime earnings
getDailyEarningsGet daily earnings breakdown

Protocol Data​

Access DeFi protocol information.

MethodDescription
getAvailableProtocolsGet available protocols and pools by chain

Opportunities Data​

Discover yield opportunities by risk profile.

MethodDescription
getConservativeOpportunitiesGet low-risk yield opportunities
getAggressiveOpportunitiesGet high-risk, high-reward opportunities
getActiveConservativeOppsRiskGet risk data for conservative pools
getActiveAggressiveOppsRiskGet risk data for aggressive pools
getConservativePoolStatusGet conservative pool status
getAggressivePoolStatusGet aggressive pool status

SDK Key Information​

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

MethodDescription
getSdkAllowedWalletsGet list of wallets created via your SDK key
getSdkKeyTVLGet total TVL across all SDK wallets

Analytics & Metrics​

Platform-wide analytics and metrics.

MethodDescription
getTVLGet total value locked across platform
getAPYPerStrategyGet APY by strategy type and period
getVolumeGet total trading volume
getActiveWalletsGet active wallets count by chain

Rebalancing​

Monitor rebalancing activity.

MethodDescription
getRebalanceFrequencyGet rebalance tier and frequency

ERC-8004​

Agent identity registration on-chain.

MethodDescription
registerAgentOnIdentityRegistryRegister agent on ERC-8004 Identity Registry

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:

ChainID
Base8453
Arbitrum42161
Plasma9745
import { getSupportedChainIds, isSupportedChain } from "@zyfai/sdk";

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

Error Handling​

All methods throw typed errors:

try {
  await sdk.deploySafe(userAddress, chainId);
} catch (error) {
  if (error.message.includes("already deployed")) {
    console.log("Safe already exists");
  } else {
    console.error("Deployment failed:", error.message);
  }
}

Amount Formatting​

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

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

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

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,
  DeploySafeResponse,
  SessionKeyResponse,
  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​