> ## Documentation Index > Fetch the complete documentation index at: https://zyfai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Technical Reference > Complete technical reference for the Zyfai SDK — architecture, configuration, types, and integration patterns. One-stop technical reference for the **Zyfai SDK** (`@zyfai/sdk`). This page is the canonical map of how the SDK is wired, what it exposes, and how to plug it into a backend, a frontend, or an AI agent. For per-method signatures see the [Smart Wallet API](/docs/sdk/api/overview) and the [Intelligence Layer](/docs/sdk/intelligence-layer). Create your own api key on the [SDK Dashboard](https://sma.zyf.ai) ## Architecture The SDK is a thin TypeScript layer that bridges your app with **two backend surfaces** and an **on-chain Safe smart account stack**. Everything is exposed through a single class: `ZyfaiSDK`, organized into the [Smart Wallet API](/docs/sdk/api/overview) (execution) and the [Intelligence Layer](/docs/sdk/intelligence-layer) (read-only engine access). ```mermaid theme={null} --- config: look: classic theme: neutral --- flowchart LR App@{ shape: rounded, label: "Your app
(Node.js, browser, AI agent)" } SDK@{ shape: rounded, label: "@zyfai/sdk
ZyfaiSDK class" } Exec@{ shape: rounded, label: "Execution API
/api/v1" } Data@{ shape: rounded, label: "Data API
/api/v2" } Chain@{ shape: rounded, label: "Safe7579 + ERC-4337
Base · Arbitrum · Ethereum" } App --> SDK SDK --> Exec SDK --> Data SDK --> Chain ``` | Layer | Responsibility | Versioning | | :---------------- | :------------------------------------------------------------ | :--------- | | **Execution API** | Deposits, withdrawals, transactions, session management | `/api/v1` | | **Data API** | Earnings, opportunities, APY history, platform analytics | `/api/v2` | | **On-chain** | Safe7579 smart accounts, ERC-4337 bundling, ERC-8004 identity | — | ## Installation `@zyfai/sdk` is published on the public npm registry. `viem` is a required peer dependency. **Latest version:** `0.2.45` ```bash theme={null} # npm npm install @zyfai/sdk@0.2.45 viem # pnpm pnpm add @zyfai/sdk@0.2.45 viem # yarn yarn add @zyfai/sdk@0.2.45 viem ``` Requirements: **Node 18+** or any modern browser. Your application domain must also be [CORS-whitelisted](/docs/sdk/getting-started#prerequisites) on the Zyfai backend. ## Configuration ### `SDKConfig` ```typescript theme={null} interface SDKConfig { apiKey: string; rpcUrls?: Partial>; } ``` | Field | Type | Required | Purpose | | :-------- | :------------------------------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | `string` | Yes | Project key (`zyfai_...`) — get one at [sma.zyf.ai](https://sma.zyf.ai) or [programmatically](/docs/sdk/agent-quickstart#programmatic-api-key-creation-agent-native) | | `rpcUrls` | `Partial>` | No | Custom RPC endpoints per chain (defaults to public RPCs — override in production) | ### Supported chains ```typescript theme={null} type SupportedChainId = 8453 | 42161 | 1; ``` | Chain | ID | Assets | | :--------------- | :---- | :--------------- | | Base | 8453 | USDC, WETH, EURC | | Arbitrum | 42161 | USDC, WETH | | Ethereum Mainnet | 1 | USDC, WETH, EURC | ```typescript theme={null} import { getSupportedChainIds, isSupportedChain } from "@zyfai/sdk"; getSupportedChainIds(); // [8453, 42161, 1] isSupportedChain(8453); // true ``` ### Environment variables ```bash theme={null} ZYFAI_API_KEY=zyfai_xxxxxxxxxxxxxxxx PRIVATE_KEY=0x... # backend only # Optional but recommended in production BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/... ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/... MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/... ``` ## Integration Patterns The SDK runs in three flavors. Pick the one that matches your runtime. ### Backend / Node.js (private key) ```typescript theme={null} import { ZyfaiSDK } from "@zyfai/sdk"; const sdk = new ZyfaiSDK({ apiKey: process.env.ZYFAI_API_KEY!, rpcUrls: { 8453: process.env.BASE_RPC_URL, 42161: process.env.ARBITRUM_RPC_URL, 1: process.env.MAINNET_RPC_URL, }, }); await sdk.connectAccount(process.env.PRIVATE_KEY!, 42161); ``` ### Frontend (EIP-1193 provider) Works with any EIP-1193 provider: wagmi, Reown AppKit, `window.ethereum`, web3-react. ```typescript theme={null} import { ZyfaiSDK } from "@zyfai/sdk"; const sdk = new ZyfaiSDK({ apiKey: process.env.NEXT_PUBLIC_ZYFAI_API_KEY! }); await sdk.connectAccount(provider, 8453); // SIWE handshake is automatic ``` ### Headless analytics (no wallet) Some methods only need the API key — useful for B2B dashboards, monitoring, billing. ```typescript theme={null} const sdk = new ZyfaiSDK({ apiKey: process.env.ZYFAI_API_KEY! }); const wallets = await sdk.getSdkAllowedWallets(); const tvl = await sdk.getSdkKeyTVL(); ``` ## Standard Flow For Smart Wallet integrations, every consumer goes through the same steps: ```text theme={null} 1. CONNECT sdk.connectAccount(...) 2. DEPOSIT sdk.depositFunds(eoa, chainId, amountInWei, asset, strategy?) 3. WITHDRAW sdk.withdrawFunds(eoa, chainId, amountInWei?, asset?) ``` The first `depositFunds` call associates the EOA with a **pre-deployed Safe** that already has a **signed session key**, live on Base, Arbitrum, and Mainnet at once. No `deploySafe` / `createSessionKey` APIs exist. This does not change the EOA itself. Notes: * Always pass the **EOA address** as `userAddress` — never the Safe address. The SDK resolves the backend-assigned Safe. * First deposit makes the Safe available on **all three chains** immediately (not only the `chainId` you deposited on). * Withdrawals are processed **asynchronously** — poll `sdk.getHistory()` for status. ## Strategies `depositFunds` (first deposit) and `updateUserProfile` accept a strategy that drives the Intelligence Engine's risk profile. | Strategy | Risk profile | Default | | :--------------- | :------------------------ | :------ | | `"conservative"` | Low-risk, stable yield | yes | | `"aggressive"` | Higher yield, higher risk | no | ```typescript theme={null} await sdk.depositFunds(eoa, 8453, "100000000", "USDC", "conservative"); await sdk.updateUserProfile({ strategy: "aggressive" }); ``` ## Session Keys Session keys are assigned with the pre-deployed Safe on first deposit. They allow Zyfai's Intelligence Engine to rebalance on the user's behalf — within strict, enforced limits. What a session key **can** do: * Move funds **between approved pools** on the same Safe * Trigger auto-compounding * Execute capital splitting across pools What a session key **cannot** do: * Withdraw to any external address * Interact with contracts outside the curator-managed registry * Sign arbitrary calldata (every transaction is byte-validated by the Security Proxy Gateway) See the [Session Keys product page](/docs/product/control/session-keys) and [Security Proxy Gateway](/docs/product/control/proxy) for the full enforcement model. ## Amount formatting Token amounts for deposits and withdrawals use **least decimal units** (wei-style): ```typescript theme={null} // For USDC / EURC (6 decimals), 100 = 100 * 10^6 await sdk.depositFunds(eoa, 8453, "100000000", "USDC"); ``` Earnings values (`totalEarningsByToken`, `totalEarningsByChain`, `daily_total_delta_by_token`) are returned as **decimal strings** (e.g. `"421.315354"`) — parse with `parseFloat()` when doing arithmetic. ## AI-Agent Integration The SDK is designed to be operated **by an autonomous agent**, not just a human-driven app. * **Programmatic API key creation** — agents can mint their own SDK key linked to their wallet, no human in the loop. See [Agent Quickstart → Programmatic API Key Creation](/docs/sdk/agent-quickstart#programmatic-api-key-creation-agent-native). * **ERC-8004 identity** — register the agent on-chain in the Identity Registry via `registerAgentOnIdentityRegistry`. * **Compact single-page reference** — the entire SDK surface is also exposed as a markdown skill at [`docs.zyf.ai/Skill.md`](https://docs.zyf.ai/Skill.md), optimized for LLM context windows. ## Type Safety The SDK ships full TypeScript typings. Import types as needed: ```typescript theme={null} import type { SDKConfig, SupportedChainId, DepositResponse, PositionsResponse, UpdateUserProfileResponse, OnchainEarningsResponse, SimulateBestPositionsResponse, } from "@zyfai/sdk"; ``` ## Response Format All SDK methods return consistent response objects: ```typescript theme={null} { success: boolean; // ...method-specific fields } ``` ## Error Handling ### Strategy * API errors are returned as response objects with `error` / `message` fields when recoverable * Network failures and 5xx responses are surfaced as thrown `Error` instances and retried with exponential backoff * On-chain errors bubble up from the underlying signer (viem / wallet provider) — user rejections appear as standard provider errors * `401` responses trigger automatic re-authentication; persistent failure throws ### Pattern ```typescript theme={null} try { await sdk.depositFunds(userAddress, chainId, amount, "USDC"); } catch (error) { const message = error instanceof Error ? error.message : String(error); if (message.includes("Safe not available")) return "Safe not assigned yet — retry deposit."; if (message.includes("User rejected")) return "Signing was rejected."; if (message.includes("No account")) return "Call sdk.connectAccount() first."; if (message.includes("Unsupported chain")) return "Chain must be 8453, 42161 or 1."; throw error; } ``` ### Common errors | Message | Cause | | :---------------------- | :------------------------------------------------------ | | `No account connected` | `connectAccount()` not called or has not resolved | | `Unsupported chain` | `chainId` is not one of `8453`, `42161`, `1` | | `Safe not available` | Safe not yet assigned / available for this EOA on chain | | `User rejected request` | User declined the signature in their wallet | | `401 Unauthorized` | API key invalid, expired, or wallet not whitelisted | ## Rate Limiting API calls are rate-limited per project key. The SDK applies automatic retry with exponential backoff on transient failures (network, 5xx, 429). ## Reporting Issues Include in every report: * SDK version (`@zyfai/sdk`) * Runtime (Node version, browser, framework) * API key **prefix only** (e.g. `zyfai_361ad4...`) — never the full key * Error message and stack trace * Minimal reproduction steps * Expected vs actual behavior Channels: [GitHub Issues](https://github.com/ondefy/zyfai-sdk/issues) · [Telegram](https://t.me/zkzyfi) · [zyf.ai](https://zyf.ai)