@zyfai/sdk 0.2.5 → 0.2.7

package/README.md

@@ -466,8 +466,32 @@ The SDK provides access to various analytics and data endpoints:
 const user = await sdk.getUserDetails();
 console.log("Smart Wallet:", user.user.smartWallet);
 console.log("Active Chains:", user.user.chains);
+console.log("Active Protocols:", user.user.protocols);
 ```
 
+#### Pause Agent
+
+Pause the agent by clearing all protocols. This effectively stops automated operations:
+
+```typescript
+// Pause the agent (clears all protocols)
+const result = await sdk.pauseAgent();
+
+if (result.success) {
+  console.log("Agent paused successfully");
+  console.log("User ID:", result.userId);
+}
+
+// Verify the agent is paused
+const userDetails = await sdk.getUserDetails();
+console.log("Active protocols:", userDetails.user.protocols.length); // Should be 0
+```
+
+**Note**:
+- User must be authenticated (automatically done via `connectAccount()`)
+- This sets the user's protocols to an empty array
+- To resume operations, call `updateUserProfile()` with the desired protocols
+
 #### Get TVL & Volume
 
 ```typescript
@@ -653,26 +677,27 @@ All examples are available in the `examples/` directory:
 7. **`get-protocols.ts`** - Fetch available protocols for a chain
 8. **`get-positions.ts`** - Get active positions for a wallet
 9. **`get-user-details.ts`** - Get authenticated user details
-10. **`get-tvl-volume.ts`** - Get TVL and trading volume
-11. **`get-active-wallets.ts`** - Get active wallets by chain
-12. **`get-smart-wallets-by-eoa.ts`** - Get smart wallets by EOA
-13. **`get-first-topup.ts`** - Get first deposit information
-14. **`get-history.ts`** - Get transaction history
+10. **`pause-agent.ts`** - Pause agent by clearing all protocols
+11. **`get-tvl-volume.ts`** - Get TVL and trading volume
+12. **`get-active-wallets.ts`** - Get active wallets by chain
+13. **`get-smart-wallets-by-eoa.ts`** - Get smart wallets by EOA
+14. **`get-first-topup.ts`** - Get first deposit information
+15. **`get-history.ts`** - Get transaction history
 
 ### Analytics & Earnings
 
-15. **`get-onchain-earnings.ts`** - Get/calculate onchain earnings
-16. **`get-daily-earnings.ts`** - Get daily earnings breakdown
-17. **`get-apy-history.ts`** - Get daily APY history with weighted averages
+16. **`get-onchain-earnings.ts`** - Get/calculate onchain earnings
+17. **`get-daily-earnings.ts`** - Get daily earnings breakdown
+18. **`get-apy-history.ts`** - Get daily APY history with weighted averages
 
 ### Opportunities & Rebalancing
 
-18. **`get-opportunities.ts`** - Get conservative and aggressive yield opportunities
-19. **`get-rebalance-info.ts`** - Get rebalance events and frequency tier
+19. **`get-opportunities.ts`** - Get conservative and aggressive yield opportunities
+20. **`get-rebalance-info.ts`** - Get rebalance events and frequency tier
 
 ### Premium Features
 
-20. **`get-debank-portfolio.ts`** - Get Debank multi-chain portfolio
+21. **`get-debank-portfolio.ts`** - Get Debank multi-chain portfolio
 
 ### Quick Start: Run the End-to-End Example
 

package/dist/index.d.mts

@@ -376,6 +376,50 @@ interface SdkKeyTVLResponse {
         walletsCount: number;
     };
 }
+interface OpportunityPosition {
+    protocol: string;
+    pool: string;
+    apy: number;
+    tvl?: number;
+}
+interface BestOpportunityDetails {
+    protocol: string;
+    pool: string;
+    apy: number;
+    tvl: number;
+    zyfiTvl?: number;
+    poolApy?: number;
+    rewardsApy?: number;
+    protocolApy?: number;
+}
+interface BestOpportunityResponse {
+    success: boolean;
+    error?: string;
+    wallet?: Address;
+    chainId?: number;
+    strategy?: string;
+    token?: {
+        symbol: string;
+        address: string;
+        decimals: number;
+    };
+    currentPosition?: OpportunityPosition | null;
+    bestOpportunity?: BestOpportunityDetails | null;
+    shouldRebalance?: boolean;
+    apyImprovement?: number | null;
+    allOpportunities?: Array<{
+        protocol: string;
+        pool: string;
+        apy: number;
+        tvl: number;
+        zyfiTvl?: number;
+    }>;
+    userConfig?: {
+        autoSelectProtocols: boolean;
+        enabledProtocols: string[];
+    };
+    enabledChains?: number[];
+}
 interface PolicyData {
     policy: Address;
     initData: Hex;
@@ -466,6 +510,25 @@ declare class ZyfaiSDK {
      * ```
      */
     updateUserProfile(request: UpdateUserProfileRequest): Promise<UpdateUserProfileResponse>;
+    /**
+     * Pause the agent by clearing all protocols
+     * Sets the user's protocols to an empty array, effectively pausing automated operations
+     *
+     * @returns Response indicating success and updated user details
+     *
+     * @example
+     * ```typescript
+     * const sdk = new ZyfaiSDK({ apiKey: 'your-api-key' });
+     *
+     * // Connect account first
+     * await sdk.connectAccount();
+     *
+     * // Pause the agent
+     * const result = await sdk.pauseAgent();
+     * console.log('Agent paused:', result.success);
+     * ```
+     */
+    pauseAgent(): Promise<UpdateUserProfileResponse>;
     /**
      * Initialize user after Safe deployment
      * This method is automatically called after deploySafe to initialize user state
@@ -929,6 +992,32 @@ declare class ZyfaiSDK {
      * ```
      */
     getSdkKeyTVL(): Promise<SdkKeyTVLResponse>;
+    /**
+     * Get the best yield opportunity for a registered wallet.
+     *
+     * Returns the highest-APY opportunity available based on the wallet's strategy
+     * and enabled protocols. This reflects what the rebalance engine would select.
+     *
+     * @param walletAddress - The smart wallet address (must be registered)
+     * @param chainId - The chain ID to check opportunities on
+     * @returns Best opportunity details with comparison to current position
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.getBestOpportunity(walletAddress, 8453);
+     *
+     * console.log("Current position:", result.currentPosition);
+     * console.log("Best opportunity:", result.bestOpportunity);
+     * console.log("Should rebalance:", result.shouldRebalance);
+     * console.log("APY improvement:", result.apyImprovement);
+     *
+     * // List all available opportunities
+     * result.allOpportunities?.forEach(opp => {
+     *   console.log(`${opp.protocol} - ${opp.pool}: ${opp.apy}%`);
+     * });
+     * ```
+     */
+    getBestOpportunity(walletAddress: Address, chainId: SupportedChainId): Promise<BestOpportunityResponse>;
 }
 
-export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type ChainConfig, type ChainPortfolio, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type PolicyData, type Pool, type PortfolioToken, type Position, type PositionSlot, type PositionsResponse, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type UserDetails, type UserDetailsResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };
+export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type PortfolioToken, type Position, type PositionSlot, type PositionsResponse, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type UserDetails, type UserDetailsResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };

package/dist/index.d.ts

@@ -376,6 +376,50 @@ interface SdkKeyTVLResponse {
         walletsCount: number;
     };
 }
+interface OpportunityPosition {
+    protocol: string;
+    pool: string;
+    apy: number;
+    tvl?: number;
+}
+interface BestOpportunityDetails {
+    protocol: string;
+    pool: string;
+    apy: number;
+    tvl: number;
+    zyfiTvl?: number;
+    poolApy?: number;
+    rewardsApy?: number;
+    protocolApy?: number;
+}
+interface BestOpportunityResponse {
+    success: boolean;
+    error?: string;
+    wallet?: Address;
+    chainId?: number;
+    strategy?: string;
+    token?: {
+        symbol: string;
+        address: string;
+        decimals: number;
+    };
+    currentPosition?: OpportunityPosition | null;
+    bestOpportunity?: BestOpportunityDetails | null;
+    shouldRebalance?: boolean;
+    apyImprovement?: number | null;
+    allOpportunities?: Array<{
+        protocol: string;
+        pool: string;
+        apy: number;
+        tvl: number;
+        zyfiTvl?: number;
+    }>;
+    userConfig?: {
+        autoSelectProtocols: boolean;
+        enabledProtocols: string[];
+    };
+    enabledChains?: number[];
+}
 interface PolicyData {
     policy: Address;
     initData: Hex;
@@ -466,6 +510,25 @@ declare class ZyfaiSDK {
      * ```
      */
     updateUserProfile(request: UpdateUserProfileRequest): Promise<UpdateUserProfileResponse>;
+    /**
+     * Pause the agent by clearing all protocols
+     * Sets the user's protocols to an empty array, effectively pausing automated operations
+     *
+     * @returns Response indicating success and updated user details
+     *
+     * @example
+     * ```typescript
+     * const sdk = new ZyfaiSDK({ apiKey: 'your-api-key' });
+     *
+     * // Connect account first
+     * await sdk.connectAccount();
+     *
+     * // Pause the agent
+     * const result = await sdk.pauseAgent();
+     * console.log('Agent paused:', result.success);
+     * ```
+     */
+    pauseAgent(): Promise<UpdateUserProfileResponse>;
     /**
      * Initialize user after Safe deployment
      * This method is automatically called after deploySafe to initialize user state
@@ -929,6 +992,32 @@ declare class ZyfaiSDK {
      * ```
      */
     getSdkKeyTVL(): Promise<SdkKeyTVLResponse>;
+    /**
+     * Get the best yield opportunity for a registered wallet.
+     *
+     * Returns the highest-APY opportunity available based on the wallet's strategy
+     * and enabled protocols. This reflects what the rebalance engine would select.
+     *
+     * @param walletAddress - The smart wallet address (must be registered)
+     * @param chainId - The chain ID to check opportunities on
+     * @returns Best opportunity details with comparison to current position
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.getBestOpportunity(walletAddress, 8453);
+     *
+     * console.log("Current position:", result.currentPosition);
+     * console.log("Best opportunity:", result.bestOpportunity);
+     * console.log("Should rebalance:", result.shouldRebalance);
+     * console.log("APY improvement:", result.apyImprovement);
+     *
+     * // List all available opportunities
+     * result.allOpportunities?.forEach(opp => {
+     *   console.log(`${opp.protocol} - ${opp.pool}: ${opp.apy}%`);
+     * });
+     * ```
+     */
+    getBestOpportunity(walletAddress: Address, chainId: SupportedChainId): Promise<BestOpportunityResponse>;
 }
 
-export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type ChainConfig, type ChainPortfolio, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type PolicyData, type Pool, type PortfolioToken, type Position, type PositionSlot, type PositionsResponse, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type UserDetails, type UserDetailsResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };
+export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, DEFAULT_TOKEN_ADDRESSES, type DailyApyEntry, type DailyApyHistoryResponse, type DailyEarning, type DailyEarningsResponse, type DebankPortfolioResponse, type DeploySafeResponse, type DepositResponse, type ERC7739Context, type ERC7739Data, type FirstTopupResponse, type Hex, type HistoryEntry, type HistoryPosition, type HistoryResponse, type OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type PortfolioToken, type Position, type PositionSlot, type PositionsResponse, type Protocol, type ProtocolsResponse, type RebalanceFrequencyResponse, type SDKConfig, type SdkKeyTVLResponse, type Session, type SessionKeyResponse, type SmartWalletByEOAResponse, type SmartWalletResponse, type Strategy, type SupportedChainId, type TVLResponse, type UserDetails, type UserDetailsResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };

package/dist/index.js

@@ -74,7 +74,9 @@ var ENDPOINTS = {
   DATA_REBALANCE_FREQUENCY: (walletAddress) => `/data/rebalance-frequency?walletAddress=${walletAddress}`,
   // SDK Keys
   SDK_ALLOWED_WALLETS: "/data/sdk-allowed-wallets",
-  SDK_TVL: "/data/sdk-tvl"
+  SDK_TVL: "/data/sdk-tvl",
+  // Best Opportunity
+  BEST_OPPORTUNITY: (walletAddress, chainId) => `/data/best-opportunity?walletAddress=${walletAddress}&chainId=${chainId}`
 };
 var DATA_ENDPOINTS = {
   // User Initialization
@@ -791,6 +793,34 @@ var ZyfaiSDK = class {
       );
     }
   }
+  /**
+   * Pause the agent by clearing all protocols
+   * Sets the user's protocols to an empty array, effectively pausing automated operations
+   *
+   * @returns Response indicating success and updated user details
+   *
+   * @example
+   * ```typescript
+   * const sdk = new ZyfaiSDK({ apiKey: 'your-api-key' });
+   *
+   * // Connect account first
+   * await sdk.connectAccount();
+   *
+   * // Pause the agent
+   * const result = await sdk.pauseAgent();
+   * console.log('Agent paused:', result.success);
+   * ```
+   */
+  async pauseAgent() {
+    try {
+      const response = await this.updateUserProfile({
+        protocols: []
+      });
+      return response;
+    } catch (error) {
+      throw new Error(`Failed to pause agent: ${error.message}`);
+    }
+  }
   /**
    * Initialize user after Safe deployment
    * This method is automatically called after deploySafe to initialize user state
@@ -2262,6 +2292,43 @@ var ZyfaiSDK = class {
       );
     }
   }
+  /**
+   * Get the best yield opportunity for a registered wallet.
+   *
+   * Returns the highest-APY opportunity available based on the wallet's strategy
+   * and enabled protocols. This reflects what the rebalance engine would select.
+   *
+   * @param walletAddress - The smart wallet address (must be registered)
+   * @param chainId - The chain ID to check opportunities on
+   * @returns Best opportunity details with comparison to current position
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.getBestOpportunity(walletAddress, 8453);
+   *
+   * console.log("Current position:", result.currentPosition);
+   * console.log("Best opportunity:", result.bestOpportunity);
+   * console.log("Should rebalance:", result.shouldRebalance);
+   * console.log("APY improvement:", result.apyImprovement);
+   *
+   * // List all available opportunities
+   * result.allOpportunities?.forEach(opp => {
+   *   console.log(`${opp.protocol} - ${opp.pool}: ${opp.apy}%`);
+   * });
+   * ```
+   */
+  async getBestOpportunity(walletAddress, chainId) {
+    try {
+      const response = await this.httpClient.get(
+        ENDPOINTS.BEST_OPPORTUNITY(walletAddress, chainId)
+      );
+      return response;
+    } catch (error) {
+      throw new Error(
+        `Failed to get best opportunity: ${error.message}`
+      );
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.mjs

@@ -33,7 +33,9 @@ var ENDPOINTS = {
   DATA_REBALANCE_FREQUENCY: (walletAddress) => `/data/rebalance-frequency?walletAddress=${walletAddress}`,
   // SDK Keys
   SDK_ALLOWED_WALLETS: "/data/sdk-allowed-wallets",
-  SDK_TVL: "/data/sdk-tvl"
+  SDK_TVL: "/data/sdk-tvl",
+  // Best Opportunity
+  BEST_OPPORTUNITY: (walletAddress, chainId) => `/data/best-opportunity?walletAddress=${walletAddress}&chainId=${chainId}`
 };
 var DATA_ENDPOINTS = {
   // User Initialization
@@ -768,6 +770,34 @@ var ZyfaiSDK = class {
       );
     }
   }
+  /**
+   * Pause the agent by clearing all protocols
+   * Sets the user's protocols to an empty array, effectively pausing automated operations
+   *
+   * @returns Response indicating success and updated user details
+   *
+   * @example
+   * ```typescript
+   * const sdk = new ZyfaiSDK({ apiKey: 'your-api-key' });
+   *
+   * // Connect account first
+   * await sdk.connectAccount();
+   *
+   * // Pause the agent
+   * const result = await sdk.pauseAgent();
+   * console.log('Agent paused:', result.success);
+   * ```
+   */
+  async pauseAgent() {
+    try {
+      const response = await this.updateUserProfile({
+        protocols: []
+      });
+      return response;
+    } catch (error) {
+      throw new Error(`Failed to pause agent: ${error.message}`);
+    }
+  }
   /**
    * Initialize user after Safe deployment
    * This method is automatically called after deploySafe to initialize user state
@@ -2239,6 +2269,43 @@ var ZyfaiSDK = class {
       );
     }
   }
+  /**
+   * Get the best yield opportunity for a registered wallet.
+   *
+   * Returns the highest-APY opportunity available based on the wallet's strategy
+   * and enabled protocols. This reflects what the rebalance engine would select.
+   *
+   * @param walletAddress - The smart wallet address (must be registered)
+   * @param chainId - The chain ID to check opportunities on
+   * @returns Best opportunity details with comparison to current position
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.getBestOpportunity(walletAddress, 8453);
+   *
+   * console.log("Current position:", result.currentPosition);
+   * console.log("Best opportunity:", result.bestOpportunity);
+   * console.log("Should rebalance:", result.shouldRebalance);
+   * console.log("APY improvement:", result.apyImprovement);
+   *
+   * // List all available opportunities
+   * result.allOpportunities?.forEach(opp => {
+   *   console.log(`${opp.protocol} - ${opp.pool}: ${opp.apy}%`);
+   * });
+   * ```
+   */
+  async getBestOpportunity(walletAddress, chainId) {
+    try {
+      const response = await this.httpClient.get(
+        ENDPOINTS.BEST_OPPORTUNITY(walletAddress, chainId)
+      );
+      return response;
+    } catch (error) {
+      throw new Error(
+        `Failed to get best opportunity: ${error.message}`
+      );
+    }
+  }
 };
 export {
   DEFAULT_TOKEN_ADDRESSES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyfai/sdk",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "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",