@zyfai/sdk 0.2.38 → 0.2.39

package/dist/index.d.mts

@@ -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,6 +591,50 @@ 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
@@ -1354,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.
      *
@@ -1478,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;
 }
 
 /**
@@ -1541,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

@@ -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,6 +591,50 @@ 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
@@ -1354,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.
      *
@@ -1478,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;
 }
 
 /**
@@ -1541,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.js

@@ -47,6 +47,7 @@ var import_axios = __toESM(require("axios"));
 // src/config/endpoints.ts
 var API_ENDPOINT = "https://api.zyf.ai";
 var DATA_API_ENDPOINT = "https://defiapi.zyf.ai";
+var WS_ENDPOINT = "wss://defiapi.zyf.ai/ws/events";
 var API_VERSION = "/api/v1";
 var DATA_API_VERSION = "/api/v2";
 var ENDPOINTS = {
@@ -80,6 +81,21 @@ var ENDPOINTS = {
   SDK_TVL: "/data/sdk-tvl",
   // Agent Identity Registry
   AGENT_TOKEN_URI: "/users/me/agent-token-uri",
+  // Simulation
+  SIMULATE_BEST_POSITIONS: (params) => {
+    const networks = Array.isArray(params.networks) ? params.networks.join(",") : params.networks;
+    const query = [
+      `amount=${params.amount}`,
+      `token=${params.token}`,
+      `networks=${networks}`,
+      `strategy=${params.strategy}`
+    ];
+    if (params.minSplit !== void 0) query.push(`minSplit=${params.minSplit}`);
+    if (params.protocols?.length) query.push(`protocols=${params.protocols.join(",")}`);
+    if (params.pools?.length) query.push(`pools=${params.pools.join(",")}`);
+    if (params.userPositions?.length) query.push(`userPositions=${encodeURIComponent(JSON.stringify(params.userPositions))}`);
+    return `/simulate/best-positions?${query.join("&")}`;
+  },
   // Customization
   CUSTOMIZE_BATCH: "/customization/customize-batch",
   CUSTOMIZATION_POOLS: (protocolId, strategy) => `/customization/pools?protocolId=${protocolId}${strategy ? `&strategy=${strategy}` : ""}`,
@@ -3095,6 +3111,54 @@ var _ZyfaiSDK = class _ZyfaiSDK {
       );
     }
   }
+  // ============================================================================
+  // Simulation
+  // ============================================================================
+  /**
+   * 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"]);
+   * ```
+   */
+  async simulateBestPositions(params) {
+    try {
+      if (!isValidPublicStrategy(params.strategy)) {
+        throw new Error(
+          `Invalid strategy: ${params.strategy}. Must be "conservative" or "aggressive".`
+        );
+      }
+      const internalStrategy = toInternalStrategy(params.strategy);
+      const response = await this.httpClient.get(
+        ENDPOINTS.SIMULATE_BEST_POSITIONS({
+          ...params,
+          strategy: internalStrategy
+        })
+      );
+      return response;
+    } catch (error) {
+      throw new Error(
+        `Failed to simulate best positions: ${error.message}`
+      );
+    }
+  }
   /**
    * Get currently selected pools for a protocol on a specific chain.
    *
@@ -3537,6 +3601,78 @@ var _ZyfaiSDK = class _ZyfaiSDK {
       symbol: tokenSymbol
     };
   }
+  // ============================================================================
+  // WebSocket Event Stream
+  // ============================================================================
+  /**
+   * 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, filters) {
+    let ws = null;
+    let closed = false;
+    const connect = () => {
+      ws = new globalThis.WebSocket(WS_ENDPOINT);
+      ws.onopen = () => {
+        const msg = { type: "subscribe" };
+        if (filters && (filters.chains?.length || filters.protocols?.length || filters.pools?.length)) {
+          msg.filters = filters;
+        }
+        ws.send(JSON.stringify(msg));
+      };
+      ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data);
+          if (msg.type !== "event") return;
+          switch (msg.eventType) {
+            case "depeg":
+              handlers.onDepeg?.(msg.data);
+              break;
+            case "new_collateral_detected":
+              handlers.onNewCollateralDetected?.(msg.data);
+              break;
+            case "liquidity_drop":
+              handlers.onLiquidityDrop?.(msg.data);
+              break;
+          }
+        } catch {
+        }
+      };
+      ws.onerror = (error) => {
+        handlers.onError?.(error);
+      };
+      ws.onclose = () => {
+        if (!closed) {
+          setTimeout(connect, 3e3);
+        }
+      };
+    };
+    connect();
+    return () => {
+      closed = true;
+      ws?.close();
+    };
+  }
 };
 // ============================================================================
 // Agent Identity Registry

package/dist/index.mjs

@@ -4,6 +4,7 @@ import axios from "axios";
 // src/config/endpoints.ts
 var API_ENDPOINT = "https://api.zyf.ai";
 var DATA_API_ENDPOINT = "https://defiapi.zyf.ai";
+var WS_ENDPOINT = "wss://defiapi.zyf.ai/ws/events";
 var API_VERSION = "/api/v1";
 var DATA_API_VERSION = "/api/v2";
 var ENDPOINTS = {
@@ -37,6 +38,21 @@ var ENDPOINTS = {
   SDK_TVL: "/data/sdk-tvl",
   // Agent Identity Registry
   AGENT_TOKEN_URI: "/users/me/agent-token-uri",
+  // Simulation
+  SIMULATE_BEST_POSITIONS: (params) => {
+    const networks = Array.isArray(params.networks) ? params.networks.join(",") : params.networks;
+    const query = [
+      `amount=${params.amount}`,
+      `token=${params.token}`,
+      `networks=${networks}`,
+      `strategy=${params.strategy}`
+    ];
+    if (params.minSplit !== void 0) query.push(`minSplit=${params.minSplit}`);
+    if (params.protocols?.length) query.push(`protocols=${params.protocols.join(",")}`);
+    if (params.pools?.length) query.push(`pools=${params.pools.join(",")}`);
+    if (params.userPositions?.length) query.push(`userPositions=${encodeURIComponent(JSON.stringify(params.userPositions))}`);
+    return `/simulate/best-positions?${query.join("&")}`;
+  },
   // Customization
   CUSTOMIZE_BATCH: "/customization/customize-batch",
   CUSTOMIZATION_POOLS: (protocolId, strategy) => `/customization/pools?protocolId=${protocolId}${strategy ? `&strategy=${strategy}` : ""}`,
@@ -3071,6 +3087,54 @@ var _ZyfaiSDK = class _ZyfaiSDK {
       );
     }
   }
+  // ============================================================================
+  // Simulation
+  // ============================================================================
+  /**
+   * 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"]);
+   * ```
+   */
+  async simulateBestPositions(params) {
+    try {
+      if (!isValidPublicStrategy(params.strategy)) {
+        throw new Error(
+          `Invalid strategy: ${params.strategy}. Must be "conservative" or "aggressive".`
+        );
+      }
+      const internalStrategy = toInternalStrategy(params.strategy);
+      const response = await this.httpClient.get(
+        ENDPOINTS.SIMULATE_BEST_POSITIONS({
+          ...params,
+          strategy: internalStrategy
+        })
+      );
+      return response;
+    } catch (error) {
+      throw new Error(
+        `Failed to simulate best positions: ${error.message}`
+      );
+    }
+  }
   /**
    * Get currently selected pools for a protocol on a specific chain.
    *
@@ -3513,6 +3577,78 @@ var _ZyfaiSDK = class _ZyfaiSDK {
       symbol: tokenSymbol
     };
   }
+  // ============================================================================
+  // WebSocket Event Stream
+  // ============================================================================
+  /**
+   * 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, filters) {
+    let ws = null;
+    let closed = false;
+    const connect = () => {
+      ws = new globalThis.WebSocket(WS_ENDPOINT);
+      ws.onopen = () => {
+        const msg = { type: "subscribe" };
+        if (filters && (filters.chains?.length || filters.protocols?.length || filters.pools?.length)) {
+          msg.filters = filters;
+        }
+        ws.send(JSON.stringify(msg));
+      };
+      ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data);
+          if (msg.type !== "event") return;
+          switch (msg.eventType) {
+            case "depeg":
+              handlers.onDepeg?.(msg.data);
+              break;
+            case "new_collateral_detected":
+              handlers.onNewCollateralDetected?.(msg.data);
+              break;
+            case "liquidity_drop":
+              handlers.onLiquidityDrop?.(msg.data);
+              break;
+          }
+        } catch {
+        }
+      };
+      ws.onerror = (error) => {
+        handlers.onError?.(error);
+      };
+      ws.onclose = () => {
+        if (!closed) {
+          setTimeout(connect, 3e3);
+        }
+      };
+    };
+    connect();
+    return () => {
+      closed = true;
+      ws?.close();
+    };
+  }
 };
 // ============================================================================
 // Agent Identity Registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyfai/sdk",
-  "version": "0.2.38",
+  "version": "0.2.39",
   "description": "TypeScript SDK for Zyfai Yield Optimization Engine - Deploy Safe smart wallets, manage session keys, and interact with DeFi protocols",
   "main": "dist/index.js",
   "module": "dist/index.mjs",