@zyfai/sdk 0.2.37 → 0.2.39

package/README.md

@@ -11,7 +11,7 @@ You can generate an api key from here: https://sdk.zyf.ai/
 
 - **Safe Smart Wallet Deployment**: Deploy Safe wallets with deterministic addresses
 - **Flexible Authentication**: Support for private keys and modern wallet providers
-- **Multi-Chain Support**: Works on Arbitrum, Base, and Plasma
+- **Multi-Chain Support**: Works on Ethereum Mainnet, Base, and Arbitrum
 - **Yield Optimization**: Access to multiple DeFi protocols and strategies
 - **Position Tracking**: Monitor and manage your DeFi positions across chains
 
@@ -136,11 +136,11 @@ if (result.success) {
 
 The SDK supports the following chains:
 
-| Chain    | Chain ID | Status |
-| -------- | -------- | ------ |
-| Arbitrum | 42161    | ✅     |
-| Base     | 8453     | ✅     |
-| Plasma   | 9745     | ✅     |
+| Chain            | Chain ID | Status |
+| ---------------- | -------- | ------ |
+| Ethereum Mainnet | 1        | ✅     |
+| Base             | 8453     | ✅     |
+| Arbitrum         | 42161    | ✅     |
 
 Example with different chains:
 
@@ -175,9 +175,9 @@ new ZyfaiSDK(config: SDKConfig | string)
   - If an object is provided:
     - `apiKey` (string): Your Zyfai API key (required)
     - `rpcUrls` (object, optional): Custom RPC URLs per chain to avoid rate limiting (optional, only needed for local operations like `getSmartWalletAddress`)
+      - `1` (string, optional): Ethereum Mainnet RPC URL
       - `8453` (string, optional): Base Mainnet RPC URL
       - `42161` (string, optional): Arbitrum One RPC URL
-      - `9745` (string, optional): Plasma Mainnet RPC URL
 
 **Examples:**
 
@@ -194,9 +194,9 @@ const sdk = new ZyfaiSDK({
 const sdk = new ZyfaiSDK({
   apiKey: "your-api-key",
   rpcUrls: {
+    1: "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY", // Ethereum Mainnet
     8453: "https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY", // Base
     42161: "https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY", // Arbitrum
-    9745: "https://your-plasma-rpc-provider.com", // Plasma
   },
 });
 ```
@@ -360,17 +360,23 @@ console.log("User ID:", result.userId);
 
 ### 4. Deposit Funds
 
-Transfer tokens to your Safe smart wallet. Token address is automatically selected based on chain:
+Transfer tokens to your Safe smart wallet. Token address is automatically selected based on chain and the requested asset (defaults to USDC):
 
-- **Base (8453) and Arbitrum (42161)**: USDC
-- **Plasma (9745)**: USDT
+- **Ethereum Mainnet (1), Base (8453), Arbitrum (42161)**: USDC (default) or WETH
+
+**Minimum portfolio balance (enforced on Safe balance + deposit amount):**
+
+- Ethereum Mainnet (1) / USDC: 5 USDC (test threshold — will be raised before production)
+- All other (chain, asset) pairs: no minimum enforced
+
+Only deposits on Mainnet in USDC that would leave the Safe below 5 USDC are rejected. Deposits on Base or Arbitrum, or in WETH, have no minimum today.
 
 ```typescript
-// Deposit 100 USDC (6 decimals) to Safe on Base
+// Deposit 10 USDC (6 decimals) to Safe on Base — no minimum on Base
 const result = await sdk.depositFunds(
   userAddress,
   8453, // Chain ID
-  "100000000" // Amount: 100 USDC = 100 * 10^6
+  "10000000" // Amount: 10 USDC = 10 * 10^6
 );
 
 if (result.success) {
@@ -382,7 +388,8 @@ if (result.success) {
 **Note:**
 
 - Amount must be in least decimal units. For USDC (6 decimals): 1 USDC = 1000000
-- Token address is automatically selected based on chain (USDC for Base/Arbitrum, USDT for Plasma)
+- Token address is automatically selected based on chain (USDC by default; pass `asset: "WETH"` to deposit WETH instead)
+- On Ethereum Mainnet, the total Safe balance in USDC must be at least 5 USDC after the deposit (test threshold); smaller top-ups are allowed if the Safe already holds enough USDC to meet the minimum
 - The SDK automatically authenticates via SIWE before logging the deposit with Zyfai's API, so no extra steps are required on your end once the transfer confirms
 
 #### Log External Deposit (For Sponsored Transactions)
@@ -996,7 +1003,7 @@ try {
 2. **Use Environment Variables**: Store keys in `.env` files
 3. **Check Deployment Status**: Always check if Safe is already deployed before deploying
 4. **Handle Errors Gracefully**: Implement proper error handling for all SDK methods
-5. **Validate Chain IDs**: Ensure you're using supported chains (Arbitrum, Base, Plasma)
+5. **Validate Chain IDs**: Ensure you're using supported chains (Ethereum Mainnet, Base, Arbitrum)
 6. **Use Explicit Parameters**: Always pass explicit `userAddress` and `chainId` to methods
 
 ## Environment Variables
@@ -1012,7 +1019,7 @@ ZYFAI_API_KEY=your-api-key
 PRIVATE_KEY=0x...
 
 # Optional: Chain ID (default: 8453 for Base)
-# Supported: 42161 (Arbitrum), 8453 (Base), 9745 (Plasma)
+# Supported: 1 (Ethereum Mainnet), 8453 (Base), 42161 (Arbitrum)
 CHAIN_ID=8453
 ```
 
@@ -1024,7 +1031,7 @@ Make sure to call `connectAccount()` before calling methods that require **signi
 
 ### "Unsupported chain" Error
 
-Check that the chain ID is in the supported chains list: Arbitrum (42161), Base (8453), or Plasma (9745).
+Check that the chain ID is in the supported chains list: Ethereum Mainnet (1), Base (8453), or Arbitrum (42161).
 
 ### SIWE Authentication Issues in Browser
 

package/dist/index.d.mts

@@ -7,9 +7,9 @@ type Address = `0x${string}`;
 type Hex = `0x${string}`;
 type Strategy = "conservative" | "aggressive";
 interface RpcUrlsConfig {
+    1?: string;
     8453?: string;
     42161?: string;
-    9745?: string;
 }
 interface SDKConfig {
     apiKey: string;
@@ -422,6 +422,46 @@ interface SdkKeyTVLResponse {
         walletsCount: number;
     };
 }
+interface UserPosition {
+    protocol: string;
+    pool: string;
+    tvl: number;
+}
+interface SimulateBestPositionsParams {
+    amount: number;
+    token: string;
+    networks: number | number[];
+    strategy: "conservative" | "aggressive";
+    minSplit?: number;
+    protocols?: string[];
+    pools?: string[];
+    userPositions?: UserPosition[];
+}
+interface SimulateCalldataItem {
+    contract_address: Address;
+    function_name: string;
+    parameters: string[];
+    value: string;
+    description: string;
+}
+interface SimulatedPosition {
+    protocol: string;
+    pool: string;
+    simulated_apy: number;
+    combined_apy: number;
+    amount: number;
+    amount_raw: string;
+    url: string;
+    tvl: number;
+    liquidity: number;
+    averageCombinedApy30Days: number;
+    calldata: SimulateCalldataItem[];
+}
+interface SimulateBestPositionsResponse {
+    success: boolean;
+    data: Record<string, SimulatedPosition[]>;
+    messages: Record<string, string>;
+}
 interface OpportunityPosition {
     protocol: string;
     pool: string;
@@ -551,8 +591,57 @@ interface VaultSharesResponse {
     shares: bigint;
     symbol: string;
 }
+interface DepegEvent {
+    token: string;
+    price: number;
+    deviation: number;
+    severity: "warning" | "critical";
+    previousSeverity?: string;
+    affectedPools: {
+        protocol: string;
+        pool: string;
+        chain: string;
+    }[];
+    timestamp: string;
+}
+interface NewCollateralDetectedEvent {
+    protocol: string;
+    pool: string;
+    chain: string;
+    asset: string;
+    exposureUsd: number;
+    percentOfTvl: number;
+    timestamp: string;
+}
+interface LiquidityDropEvent {
+    protocol: string;
+    pool: string;
+    chain: string;
+    asset: string;
+    previousLiquidityUsd: number;
+    currentLiquidityUsd: number;
+    dropPercent: number;
+    windowMinutes: number;
+    timestamp: string;
+}
+interface ZyfaiEventFilters {
+    chains?: string[];
+    protocols?: string[];
+    pools?: string[];
+}
+interface ZyfaiEventHandlers {
+    onDepeg?: (data: DepegEvent) => void;
+    onNewCollateralDetected?: (data: NewCollateralDetectedEvent) => void;
+    onLiquidityDrop?: (data: LiquidityDropEvent) => void;
+    onError?: (error: unknown) => void;
+}
+
+/**
+ * Chain Configuration for Zyfai SDK
+ * Supports Ethereum Mainnet, Arbitrum, and Base networks
+ */
 
-type SupportedChainId = 8453 | 42161 | 9745;
+type SupportedChainId = 1 | 8453 | 42161;
 interface ChainConfig {
     chain: Chain;
     rpcUrl: string;
@@ -839,22 +928,30 @@ declare class ZyfaiSDK {
      * Deposit funds from EOA to Safe smart wallet
      * Transfers tokens from the connected wallet to the user's Safe and logs the deposit
      *
-     * Token is automatically selected based on chain:
-     * - Base (8453) and Arbitrum (42161): USDC
-     * - Plasma (9745): USDT
+     * Token is automatically selected based on chain (USDC by default):
+     * - Ethereum Mainnet (1), Base (8453), Arbitrum (42161)
+     *
+     * Minimum portfolio balance enforced (Safe balance + deposit amount),
+     * configured per-chain in `MIN_PORTFOLIO_BALANCE`:
+     * - Ethereum Mainnet (1): 5 USDC (test threshold)
+     * - Base (8453) & Arbitrum (42161): no minimum
+     *
+     * If no minimum is configured for a given (chainId, asset) pair,
+     * the check is skipped.
      *
      * @param userAddress - User's address (owner of the Safe)
      * @param chainId - Target chain ID
      * @param amount - Amount in least decimal units (e.g., "100000000" for 100 USDC with 6 decimals)
+     * @param asset - Optional asset symbol ("USDC" or "WETH"). Defaults to "USDC".
      * @returns Deposit response with transaction hash
      *
      * @example
      * ```typescript
-     * // Deposit 100 USDC (6 decimals) to Safe on Base
+     * // Deposit 10,000 USDC (6 decimals) to Safe on Base
      * const result = await sdk.depositFunds(
      *   "0xUser...",
      *   8453,
-     *   "100000000" // 100 USDC = 100 * 10^6
+     *   "10000000000" // 10,000 USDC = 10_000 * 10^6
      * );
      * ```
      */
@@ -872,8 +969,7 @@ declare class ZyfaiSDK {
      * - Need more control over transaction execution
      *
      * Token is automatically selected based on chain if not provided:
-     * - Base (8453) and Arbitrum (42161): USDC
-     * - Plasma (9745): USDT
+     * - Ethereum Mainnet (1), Base (8453), Arbitrum (42161): USDC by default
      *
      * @param chainId - Chain ID where the deposit was made
      * @param txHash - Transaction hash of the deposit
@@ -1342,6 +1438,31 @@ declare class ZyfaiSDK {
      * ```
      */
     getAvailablePools(protocolId: string, strategy?: "conservative" | "aggressive"): Promise<GetPoolsResponse>;
+    /**
+     * Simulate the best yield positions for a given amount, splitting it across
+     * the top-ranked pools (up to minSplit positions) for the requested chains/strategy.
+     *
+     * Returns ready-to-execute calldata (approve + deposit) per position. The deposit
+     * calldata contains a "<RECEIVER>" placeholder that must be replaced with the
+     * actual receiving address (e.g. the user's Safe) before sending the transaction.
+     *
+     * @param params - Simulation parameters
+     * @returns Chain-keyed map of simulated positions with calldata
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.simulateBestPositions({
+     *   amount: 3000,
+     *   token: "USDC",
+     *   networks: 8453,
+     *   strategy: "conservative",
+     *   minSplit: 3,
+     *   protocols: ["aave", "compound", "morpho"],
+     * });
+     * console.log(result.data["8453"]);
+     * ```
+     */
+    simulateBestPositions(params: SimulateBestPositionsParams): Promise<SimulateBestPositionsResponse>;
     /**
      * Get currently selected pools for a protocol on a specific chain.
      *
@@ -1466,6 +1587,31 @@ declare class ZyfaiSDK {
      * ```
      */
     getVaultShares(userAddress?: string, chainId?: SupportedChainId): Promise<VaultSharesResponse>;
+    /**
+     * Subscribe to real-time Zyfai risk and liquidity events via WebSocket.
+     *
+     * Events: depeg, liquidity_trap, liquidity_restored, pool_status_change,
+     * new_collateral_detected, liquidity_drop.
+     *
+     * @param handlers - Callback per event type, plus onError
+     * @param filters - Optional protocol/pool filter sent to the server on subscribe
+     * @returns Cleanup function — call it to close the connection
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = sdk.subscribeToEvents(
+     *   {
+     *     onDepeg: (data) => console.log("Depeg detected:", data.token, data.severity),
+     *     onLiquidityDrop: (data) => console.log("Liquidity drop:", data.pool, data.dropPercent),
+     *   },
+     *   { protocols: ["morpho"], pools: ["gauntlet usdc core"] }
+     * );
+     *
+     * // Later, close the connection:
+     * unsubscribe();
+     * ```
+     */
+    subscribeToEvents(handlers: ZyfaiEventHandlers, filters?: ZyfaiEventFilters): () => void;
 }
 
 /**
@@ -1529,4 +1675,4 @@ type BankrProvider = ReturnType<typeof createBankrProvider>;
 
 declare const VAULT_ADDRESS: "0xD580071c47d4a667858B5FafAb85BC9C609beC5D";
 
-export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type ApyPosition, type BankrProvider, type BankrProviderConfig, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, type ChainTokenEarnings, type CustomizationConfig, type CustomizeBatchRequest, type CustomizeBatchResponse, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type GetPoolsResponse, type GetSelectedPoolsResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type LogDepositResponse, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type Portfolio, type PortfolioAssetBalance, type PortfolioByAssetType, type PortfolioByChain, type PortfolioDetailed, type PortfolioDetailedResponse, type PortfolioResponse, type PortfolioToken, type PositionSlot, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type RegisterAgentResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type TokenApy, type TokenEarnings, type UpdateUserProfileRequest, type UpdateUserProfileResponse, VAULT_ADDRESS, type VaultAsset, type VaultClaimResponse, type VaultDepositResponse, type VaultSharesResponse, type VaultWithdrawResponse, type VaultWithdrawStatusResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, createBankrProvider, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };
+export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type ApyPosition, type BankrProvider, type BankrProviderConfig, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, type ChainTokenEarnings, type CustomizationConfig, type CustomizeBatchRequest, type CustomizeBatchResponse, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DepegEvent, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type GetPoolsResponse, type GetSelectedPoolsResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type LiquidityDropEvent, type LogDepositResponse, type NewCollateralDetectedEvent, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type Portfolio, type PortfolioAssetBalance, type PortfolioByAssetType, type PortfolioByChain, type PortfolioDetailed, type PortfolioDetailedResponse, type PortfolioResponse, type PortfolioToken, type PositionSlot, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type RegisterAgentResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SimulateBestPositionsParams, type SimulateBestPositionsResponse, type SimulateCalldataItem, type SimulatedPosition, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type TokenApy, type TokenEarnings, type UpdateUserProfileRequest, type UpdateUserProfileResponse, type UserPosition, VAULT_ADDRESS, type VaultAsset, type VaultClaimResponse, type VaultDepositResponse, type VaultSharesResponse, type VaultWithdrawResponse, type VaultWithdrawStatusResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, type ZyfaiEventFilters, type ZyfaiEventHandlers, ZyfaiSDK, createBankrProvider, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };

package/dist/index.d.ts

@@ -7,9 +7,9 @@ type Address = `0x${string}`;
 type Hex = `0x${string}`;
 type Strategy = "conservative" | "aggressive";
 interface RpcUrlsConfig {
+    1?: string;
     8453?: string;
     42161?: string;
-    9745?: string;
 }
 interface SDKConfig {
     apiKey: string;
@@ -422,6 +422,46 @@ interface SdkKeyTVLResponse {
         walletsCount: number;
     };
 }
+interface UserPosition {
+    protocol: string;
+    pool: string;
+    tvl: number;
+}
+interface SimulateBestPositionsParams {
+    amount: number;
+    token: string;
+    networks: number | number[];
+    strategy: "conservative" | "aggressive";
+    minSplit?: number;
+    protocols?: string[];
+    pools?: string[];
+    userPositions?: UserPosition[];
+}
+interface SimulateCalldataItem {
+    contract_address: Address;
+    function_name: string;
+    parameters: string[];
+    value: string;
+    description: string;
+}
+interface SimulatedPosition {
+    protocol: string;
+    pool: string;
+    simulated_apy: number;
+    combined_apy: number;
+    amount: number;
+    amount_raw: string;
+    url: string;
+    tvl: number;
+    liquidity: number;
+    averageCombinedApy30Days: number;
+    calldata: SimulateCalldataItem[];
+}
+interface SimulateBestPositionsResponse {
+    success: boolean;
+    data: Record<string, SimulatedPosition[]>;
+    messages: Record<string, string>;
+}
 interface OpportunityPosition {
     protocol: string;
     pool: string;
@@ -551,8 +591,57 @@ interface VaultSharesResponse {
     shares: bigint;
     symbol: string;
 }
+interface DepegEvent {
+    token: string;
+    price: number;
+    deviation: number;
+    severity: "warning" | "critical";
+    previousSeverity?: string;
+    affectedPools: {
+        protocol: string;
+        pool: string;
+        chain: string;
+    }[];
+    timestamp: string;
+}
+interface NewCollateralDetectedEvent {
+    protocol: string;
+    pool: string;
+    chain: string;
+    asset: string;
+    exposureUsd: number;
+    percentOfTvl: number;
+    timestamp: string;
+}
+interface LiquidityDropEvent {
+    protocol: string;
+    pool: string;
+    chain: string;
+    asset: string;
+    previousLiquidityUsd: number;
+    currentLiquidityUsd: number;
+    dropPercent: number;
+    windowMinutes: number;
+    timestamp: string;
+}
+interface ZyfaiEventFilters {
+    chains?: string[];
+    protocols?: string[];
+    pools?: string[];
+}
+interface ZyfaiEventHandlers {
+    onDepeg?: (data: DepegEvent) => void;
+    onNewCollateralDetected?: (data: NewCollateralDetectedEvent) => void;
+    onLiquidityDrop?: (data: LiquidityDropEvent) => void;
+    onError?: (error: unknown) => void;
+}
+
+/**
+ * Chain Configuration for Zyfai SDK
+ * Supports Ethereum Mainnet, Arbitrum, and Base networks
+ */
 
-type SupportedChainId = 8453 | 42161 | 9745;
+type SupportedChainId = 1 | 8453 | 42161;
 interface ChainConfig {
     chain: Chain;
     rpcUrl: string;
@@ -839,22 +928,30 @@ declare class ZyfaiSDK {
      * Deposit funds from EOA to Safe smart wallet
      * Transfers tokens from the connected wallet to the user's Safe and logs the deposit
      *
-     * Token is automatically selected based on chain:
-     * - Base (8453) and Arbitrum (42161): USDC
-     * - Plasma (9745): USDT
+     * Token is automatically selected based on chain (USDC by default):
+     * - Ethereum Mainnet (1), Base (8453), Arbitrum (42161)
+     *
+     * Minimum portfolio balance enforced (Safe balance + deposit amount),
+     * configured per-chain in `MIN_PORTFOLIO_BALANCE`:
+     * - Ethereum Mainnet (1): 5 USDC (test threshold)
+     * - Base (8453) & Arbitrum (42161): no minimum
+     *
+     * If no minimum is configured for a given (chainId, asset) pair,
+     * the check is skipped.
      *
      * @param userAddress - User's address (owner of the Safe)
      * @param chainId - Target chain ID
      * @param amount - Amount in least decimal units (e.g., "100000000" for 100 USDC with 6 decimals)
+     * @param asset - Optional asset symbol ("USDC" or "WETH"). Defaults to "USDC".
      * @returns Deposit response with transaction hash
      *
      * @example
      * ```typescript
-     * // Deposit 100 USDC (6 decimals) to Safe on Base
+     * // Deposit 10,000 USDC (6 decimals) to Safe on Base
      * const result = await sdk.depositFunds(
      *   "0xUser...",
      *   8453,
-     *   "100000000" // 100 USDC = 100 * 10^6
+     *   "10000000000" // 10,000 USDC = 10_000 * 10^6
      * );
      * ```
      */
@@ -872,8 +969,7 @@ declare class ZyfaiSDK {
      * - Need more control over transaction execution
      *
      * Token is automatically selected based on chain if not provided:
-     * - Base (8453) and Arbitrum (42161): USDC
-     * - Plasma (9745): USDT
+     * - Ethereum Mainnet (1), Base (8453), Arbitrum (42161): USDC by default
      *
      * @param chainId - Chain ID where the deposit was made
      * @param txHash - Transaction hash of the deposit
@@ -1342,6 +1438,31 @@ declare class ZyfaiSDK {
      * ```
      */
     getAvailablePools(protocolId: string, strategy?: "conservative" | "aggressive"): Promise<GetPoolsResponse>;
+    /**
+     * Simulate the best yield positions for a given amount, splitting it across
+     * the top-ranked pools (up to minSplit positions) for the requested chains/strategy.
+     *
+     * Returns ready-to-execute calldata (approve + deposit) per position. The deposit
+     * calldata contains a "<RECEIVER>" placeholder that must be replaced with the
+     * actual receiving address (e.g. the user's Safe) before sending the transaction.
+     *
+     * @param params - Simulation parameters
+     * @returns Chain-keyed map of simulated positions with calldata
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.simulateBestPositions({
+     *   amount: 3000,
+     *   token: "USDC",
+     *   networks: 8453,
+     *   strategy: "conservative",
+     *   minSplit: 3,
+     *   protocols: ["aave", "compound", "morpho"],
+     * });
+     * console.log(result.data["8453"]);
+     * ```
+     */
+    simulateBestPositions(params: SimulateBestPositionsParams): Promise<SimulateBestPositionsResponse>;
     /**
      * Get currently selected pools for a protocol on a specific chain.
      *
@@ -1466,6 +1587,31 @@ declare class ZyfaiSDK {
      * ```
      */
     getVaultShares(userAddress?: string, chainId?: SupportedChainId): Promise<VaultSharesResponse>;
+    /**
+     * Subscribe to real-time Zyfai risk and liquidity events via WebSocket.
+     *
+     * Events: depeg, liquidity_trap, liquidity_restored, pool_status_change,
+     * new_collateral_detected, liquidity_drop.
+     *
+     * @param handlers - Callback per event type, plus onError
+     * @param filters - Optional protocol/pool filter sent to the server on subscribe
+     * @returns Cleanup function — call it to close the connection
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = sdk.subscribeToEvents(
+     *   {
+     *     onDepeg: (data) => console.log("Depeg detected:", data.token, data.severity),
+     *     onLiquidityDrop: (data) => console.log("Liquidity drop:", data.pool, data.dropPercent),
+     *   },
+     *   { protocols: ["morpho"], pools: ["gauntlet usdc core"] }
+     * );
+     *
+     * // Later, close the connection:
+     * unsubscribe();
+     * ```
+     */
+    subscribeToEvents(handlers: ZyfaiEventHandlers, filters?: ZyfaiEventFilters): () => void;
 }
 
 /**
@@ -1529,4 +1675,4 @@ type BankrProvider = ReturnType<typeof createBankrProvider>;
 
 declare const VAULT_ADDRESS: "0xD580071c47d4a667858B5FafAb85BC9C609beC5D";
 
-export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type ApyPosition, type BankrProvider, type BankrProviderConfig, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, type ChainTokenEarnings, type CustomizationConfig, type CustomizeBatchRequest, type CustomizeBatchResponse, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type GetPoolsResponse, type GetSelectedPoolsResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type LogDepositResponse, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type Portfolio, type PortfolioAssetBalance, type PortfolioByAssetType, type PortfolioByChain, type PortfolioDetailed, type PortfolioDetailedResponse, type PortfolioResponse, type PortfolioToken, type PositionSlot, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type RegisterAgentResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type TokenApy, type TokenEarnings, type UpdateUserProfileRequest, type UpdateUserProfileResponse, VAULT_ADDRESS, type VaultAsset, type VaultClaimResponse, type VaultDepositResponse, type VaultSharesResponse, type VaultWithdrawResponse, type VaultWithdrawStatusResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, createBankrProvider, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };
+export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type ApyPosition, type BankrProvider, type BankrProviderConfig, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, type ChainTokenEarnings, type CustomizationConfig, type CustomizeBatchRequest, type CustomizeBatchResponse, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DepegEvent, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type GetPoolsResponse, type GetSelectedPoolsResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type LiquidityDropEvent, type LogDepositResponse, type NewCollateralDetectedEvent, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type Portfolio, type PortfolioAssetBalance, type PortfolioByAssetType, type PortfolioByChain, type PortfolioDetailed, type PortfolioDetailedResponse, type PortfolioResponse, type PortfolioToken, type PositionSlot, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type RegisterAgentResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SimulateBestPositionsParams, type SimulateBestPositionsResponse, type SimulateCalldataItem, type SimulatedPosition, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type TokenApy, type TokenEarnings, type UpdateUserProfileRequest, type UpdateUserProfileResponse, type UserPosition, VAULT_ADDRESS, type VaultAsset, type VaultClaimResponse, type VaultDepositResponse, type VaultSharesResponse, type VaultWithdrawResponse, type VaultWithdrawStatusResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, type ZyfaiEventFilters, type ZyfaiEventHandlers, ZyfaiSDK, createBankrProvider, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };