@zyfai/sdk 0.2.21 → 0.2.23

package/README.md

@@ -385,6 +385,43 @@ if (result.success) {
 - Token address is automatically selected based on chain (USDC for Base/Arbitrum, USDT for Plasma)
 - 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)
+
+If you execute deposits client-side (e.g., with Privy, Biconomy, or other sponsored/gasless transaction providers), use `logDeposit` to register the deposit with Zyfai's backend:
+
+```typescript
+// 1. Execute deposit with your own wallet implementation (e.g., Privy)
+const txHash = await privyWallet.sendTransaction({
+  to: safeAddress,
+  data: transferData, // ERC20 transfer encoded data
+});
+
+// 2. Log the deposit to Zyfai backend for tracking and yield optimization
+const result = await sdk.logDeposit(
+  8453,           // chainId
+  txHash,         // transaction hash from your wallet
+  "100000000"     // 100 USDC (6 decimals)
+);
+
+if (result.success) {
+  console.log("Deposit logged successfully");
+}
+```
+
+**When to use `logDeposit`:**
+
+- You use sponsored/gasless transactions (Privy, Biconomy, Gelato, etc.)
+- You have a custom wallet implementation
+- You need more control over transaction execution
+- You want to pay gas fees for your users
+
+**Parameters:**
+
+- `chainId`: Chain ID where the deposit was made
+- `txHash`: Transaction hash of the deposit (must start with "0x")
+- `amount`: Amount in least decimal units
+- `tokenAddress` (optional): Token address (auto-selected based on chain if not provided)
+
 ### 5. Withdraw Funds
 
 Initiate a withdrawal from your Safe. **Note: Withdrawals are processed asynchronously by the backend.**

package/dist/index.d.mts

@@ -112,7 +112,7 @@ interface staleBalances {
     balance: string;
     isPending: boolean;
 }
-interface Position {
+interface Portfolio {
     user?: string;
     eoa?: Address;
     chains?: number[];
@@ -147,7 +147,7 @@ interface PositionSlot {
 interface PortfolioResponse {
     success: boolean;
     userAddress: string;
-    portfolio: Position;
+    portfolio: Portfolio;
 }
 interface UserDetails {
     id: string;
@@ -375,6 +375,10 @@ interface DepositResponse {
     smartWallet: string;
     amount: string;
 }
+interface LogDepositResponse {
+    success: boolean;
+    message: string;
+}
 interface WithdrawResponse {
     success: boolean;
     message: string;
@@ -808,6 +812,46 @@ declare class ZyfaiSDK {
      * ```
      */
     depositFunds(userAddress: string, chainId: SupportedChainId, amount: string): Promise<DepositResponse>;
+    /**
+     * Log a deposit that was executed client-side
+     *
+     * Use this method when you execute the deposit transaction yourself (e.g., with Privy,
+     * sponsored transactions, or any custom wallet implementation) and need to register
+     * the deposit with the Zyfai backend for tracking and yield optimization.
+     *
+     * This is useful for partners who:
+     * - Use sponsored/gasless transactions (Privy, Biconomy, etc.)
+     * - Have custom wallet implementations
+     * - 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
+     *
+     * @param chainId - Chain ID where the deposit was made
+     * @param txHash - Transaction hash of the deposit
+     * @param amount - Amount in least decimal units (e.g., "100000000" for 100 USDC with 6 decimals)
+     * @param tokenAddress - Optional: Token address (auto-selected based on chain if not provided)
+     * @returns Log deposit response with success status
+     *
+     * @example
+     * ```typescript
+     * // Execute deposit with Privy (sponsored transaction)
+     * const txHash = await privyWallet.sendTransaction({
+     *   to: safeAddress,
+     *   data: transferData,
+     * });
+     *
+     * // Log the deposit to Zyfai backend
+     * const result = await sdk.logDeposit(
+     *   8453,           // chainId
+     *   txHash,         // transaction hash from Privy
+     *   "100000000"     // 100 USDC
+     * );
+     * console.log(result.success); // true
+     * ```
+     */
+    logDeposit(chainId: SupportedChainId, txHash: string, amount: string, tokenAddress?: string): Promise<LogDepositResponse>;
     /**
      * Withdraw funds from Safe smart wallet
      * Initiates a withdrawal request to the Zyfai API
@@ -1283,4 +1327,4 @@ declare class ZyfaiSDK {
     registerAgentOnIdentityRegistry(smartWallet: string, chainId: SupportedChainId): Promise<RegisterAgentResponse>;
 }
 
-export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, 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 OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type PortfolioResponse, type PortfolioToken, type Position, 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 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, 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 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 UserDetails, type UserDetailsResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };

package/dist/index.d.ts

@@ -112,7 +112,7 @@ interface staleBalances {
     balance: string;
     isPending: boolean;
 }
-interface Position {
+interface Portfolio {
     user?: string;
     eoa?: Address;
     chains?: number[];
@@ -147,7 +147,7 @@ interface PositionSlot {
 interface PortfolioResponse {
     success: boolean;
     userAddress: string;
-    portfolio: Position;
+    portfolio: Portfolio;
 }
 interface UserDetails {
     id: string;
@@ -375,6 +375,10 @@ interface DepositResponse {
     smartWallet: string;
     amount: string;
 }
+interface LogDepositResponse {
+    success: boolean;
+    message: string;
+}
 interface WithdrawResponse {
     success: boolean;
     message: string;
@@ -808,6 +812,46 @@ declare class ZyfaiSDK {
      * ```
      */
     depositFunds(userAddress: string, chainId: SupportedChainId, amount: string): Promise<DepositResponse>;
+    /**
+     * Log a deposit that was executed client-side
+     *
+     * Use this method when you execute the deposit transaction yourself (e.g., with Privy,
+     * sponsored transactions, or any custom wallet implementation) and need to register
+     * the deposit with the Zyfai backend for tracking and yield optimization.
+     *
+     * This is useful for partners who:
+     * - Use sponsored/gasless transactions (Privy, Biconomy, etc.)
+     * - Have custom wallet implementations
+     * - 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
+     *
+     * @param chainId - Chain ID where the deposit was made
+     * @param txHash - Transaction hash of the deposit
+     * @param amount - Amount in least decimal units (e.g., "100000000" for 100 USDC with 6 decimals)
+     * @param tokenAddress - Optional: Token address (auto-selected based on chain if not provided)
+     * @returns Log deposit response with success status
+     *
+     * @example
+     * ```typescript
+     * // Execute deposit with Privy (sponsored transaction)
+     * const txHash = await privyWallet.sendTransaction({
+     *   to: safeAddress,
+     *   data: transferData,
+     * });
+     *
+     * // Log the deposit to Zyfai backend
+     * const result = await sdk.logDeposit(
+     *   8453,           // chainId
+     *   txHash,         // transaction hash from Privy
+     *   "100000000"     // 100 USDC
+     * );
+     * console.log(result.success); // true
+     * ```
+     */
+    logDeposit(chainId: SupportedChainId, txHash: string, amount: string, tokenAddress?: string): Promise<LogDepositResponse>;
     /**
      * Withdraw funds from Safe smart wallet
      * Initiates a withdrawal request to the Zyfai API
@@ -1283,4 +1327,4 @@ declare class ZyfaiSDK {
     registerAgentOnIdentityRegistry(smartWallet: string, chainId: SupportedChainId): Promise<RegisterAgentResponse>;
 }
 
-export { type APYPerStrategy, type APYPerStrategyResponse, type ActionData, type ActiveWallet, type ActiveWalletsResponse, type AddWalletToSdkResponse, type Address, type BestOpportunityDetails, type BestOpportunityResponse, type ChainConfig, type ChainPortfolio, 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 OnchainEarnings, type OnchainEarningsResponse, type OpportunitiesResponse, type Opportunity, type OpportunityPosition, type PolicyData, type Pool, type PortfolioResponse, type PortfolioToken, type Position, 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 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, 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 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 UserDetails, type UserDetailsResponse, type VolumeResponse, type WalletTVL, type WithdrawResponse, ZyfaiSDK, getChainConfig, getDefaultTokenAddress, getSupportedChainIds, isSupportedChain };

package/dist/index.js

@@ -1650,6 +1650,71 @@ var _ZyfaiSDK = class _ZyfaiSDK {
       throw new Error(`Deposit failed: ${error.message}`);
     }
   }
+  /**
+   * Log a deposit that was executed client-side
+   *
+   * Use this method when you execute the deposit transaction yourself (e.g., with Privy,
+   * sponsored transactions, or any custom wallet implementation) and need to register
+   * the deposit with the Zyfai backend for tracking and yield optimization.
+   *
+   * This is useful for partners who:
+   * - Use sponsored/gasless transactions (Privy, Biconomy, etc.)
+   * - Have custom wallet implementations
+   * - 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
+   *
+   * @param chainId - Chain ID where the deposit was made
+   * @param txHash - Transaction hash of the deposit
+   * @param amount - Amount in least decimal units (e.g., "100000000" for 100 USDC with 6 decimals)
+   * @param tokenAddress - Optional: Token address (auto-selected based on chain if not provided)
+   * @returns Log deposit response with success status
+   *
+   * @example
+   * ```typescript
+   * // Execute deposit with Privy (sponsored transaction)
+   * const txHash = await privyWallet.sendTransaction({
+   *   to: safeAddress,
+   *   data: transferData,
+   * });
+   *
+   * // Log the deposit to Zyfai backend
+   * const result = await sdk.logDeposit(
+   *   8453,           // chainId
+   *   txHash,         // transaction hash from Privy
+   *   "100000000"     // 100 USDC
+   * );
+   * console.log(result.success); // true
+   * ```
+   */
+  async logDeposit(chainId, txHash, amount, tokenAddress) {
+    try {
+      if (!isSupportedChain(chainId)) {
+        throw new Error(`Unsupported chain ID: ${chainId}`);
+      }
+      if (!txHash || !txHash.startsWith("0x")) {
+        throw new Error("Valid transaction hash is required");
+      }
+      if (!amount || isNaN(Number(amount)) || Number(amount) <= 0) {
+        throw new Error("Valid amount is required");
+      }
+      const token = tokenAddress || getDefaultTokenAddress(chainId);
+      await this.httpClient.post(ENDPOINTS.LOG_DEPOSIT, {
+        chainId,
+        transaction: txHash,
+        token,
+        amount
+      });
+      return {
+        success: true,
+        message: "Deposit logged successfully"
+      };
+    } catch (error) {
+      throw new Error(`Log deposit failed: ${error.message}`);
+    }
+  }
   /**
    * Withdraw funds from Safe smart wallet
    * Initiates a withdrawal request to the Zyfai API

package/dist/index.mjs

@@ -1628,6 +1628,71 @@ var _ZyfaiSDK = class _ZyfaiSDK {
       throw new Error(`Deposit failed: ${error.message}`);
     }
   }
+  /**
+   * Log a deposit that was executed client-side
+   *
+   * Use this method when you execute the deposit transaction yourself (e.g., with Privy,
+   * sponsored transactions, or any custom wallet implementation) and need to register
+   * the deposit with the Zyfai backend for tracking and yield optimization.
+   *
+   * This is useful for partners who:
+   * - Use sponsored/gasless transactions (Privy, Biconomy, etc.)
+   * - Have custom wallet implementations
+   * - 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
+   *
+   * @param chainId - Chain ID where the deposit was made
+   * @param txHash - Transaction hash of the deposit
+   * @param amount - Amount in least decimal units (e.g., "100000000" for 100 USDC with 6 decimals)
+   * @param tokenAddress - Optional: Token address (auto-selected based on chain if not provided)
+   * @returns Log deposit response with success status
+   *
+   * @example
+   * ```typescript
+   * // Execute deposit with Privy (sponsored transaction)
+   * const txHash = await privyWallet.sendTransaction({
+   *   to: safeAddress,
+   *   data: transferData,
+   * });
+   *
+   * // Log the deposit to Zyfai backend
+   * const result = await sdk.logDeposit(
+   *   8453,           // chainId
+   *   txHash,         // transaction hash from Privy
+   *   "100000000"     // 100 USDC
+   * );
+   * console.log(result.success); // true
+   * ```
+   */
+  async logDeposit(chainId, txHash, amount, tokenAddress) {
+    try {
+      if (!isSupportedChain(chainId)) {
+        throw new Error(`Unsupported chain ID: ${chainId}`);
+      }
+      if (!txHash || !txHash.startsWith("0x")) {
+        throw new Error("Valid transaction hash is required");
+      }
+      if (!amount || isNaN(Number(amount)) || Number(amount) <= 0) {
+        throw new Error("Valid amount is required");
+      }
+      const token = tokenAddress || getDefaultTokenAddress(chainId);
+      await this.httpClient.post(ENDPOINTS.LOG_DEPOSIT, {
+        chainId,
+        transaction: txHash,
+        token,
+        amount
+      });
+      return {
+        success: true,
+        message: "Deposit logged successfully"
+      };
+    } catch (error) {
+      throw new Error(`Log deposit failed: ${error.message}`);
+    }
+  }
   /**
    * Withdraw funds from Safe smart wallet
    * Initiates a withdrawal request to the Zyfai API

package/package.json

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