@agether/sdk 2.4.0 → 2.6.0

package/dist/index.d.mts

@@ -347,6 +347,12 @@ interface FundResult {
     amount: string;
     agentAccount: string;
 }
+interface WithdrawFromAccountResult {
+    tx: string;
+    token: string;
+    amount: string;
+    destination: string;
+}
 interface SupplyAssetResult {
     tx: string;
     amount: string;
@@ -394,6 +400,8 @@ declare class MorphoClient {
     private validationModule;
     private _accountAddress?;
     private _marketCache;
+    /** Dynamic token registry: symbol (uppercase) → { address, symbol, decimals } */
+    private _tokenCache;
     private _discoveredMarkets?;
     private _discoveredAt;
     constructor(config: MorphoClientConfig);
@@ -430,6 +438,21 @@ declare class MorphoClient {
     getBalances(): Promise<BalancesResult>;
     /** Transfer USDC from EOA to AgentAccount. */
     fundAccount(usdcAmount: string): Promise<FundResult>;
+    /**
+     * Withdraw (transfer) a token from AgentAccount to EOA.
+     * Executes an ERC-20 transfer via Safe UserOp.
+     *
+     * @param tokenSymbol - Token to withdraw (e.g. 'USDC', 'WETH', 'wstETH')
+     * @param amount - Amount to withdraw (human-readable, e.g. '100' for 100 USDC, or 'all')
+     */
+    withdrawToken(tokenSymbol: string, amount: string): Promise<WithdrawFromAccountResult>;
+    /**
+     * Withdraw ETH from AgentAccount to EOA.
+     * Executes a native ETH transfer via Safe UserOp.
+     *
+     * @param amount - ETH amount (e.g. '0.01' or 'all')
+     */
+    withdrawEth(amount: string): Promise<WithdrawFromAccountResult>;
     /**
      * Fetch USDC borrow markets on Base from Morpho API.
      * Caches results for 5 minutes.
@@ -662,6 +685,20 @@ declare class MorphoClient {
     private _findActiveMarket;
     /** Find the first market where the agent has a supply (lending) position. */
     private _findActiveSupplyMarket;
+    /**
+     * Resolve a token symbol or address to { address, symbol, decimals }.
+     *
+     * Uses the dynamic `_tokenCache` populated by `getMarkets()` from the
+     * Morpho GraphQL API — no hardcoded token list needed.
+     *
+     * @param symbolOrAddress - e.g. 'WETH', 'wstETH', or '0x4200...'
+     */
+    private _resolveToken;
+    /**
+     * Get all discovered collateral tokens (for balance iteration, etc.).
+     * Returns unique tokens from the Morpho API market discovery.
+     */
+    private _getDiscoveredTokens;
     /**
      * Compute net deposited amounts per market using Morpho GraphQL API.
      *
@@ -692,9 +729,14 @@ declare class MorphoClient {
  * Auto-Draw: When autoDraw is enabled and USDC balance is insufficient,
  * the client automatically borrows from Morpho Blue before paying.
  *
- * Spending Limits: Optional daily spending cap (dailySpendLimitUsdc) and
- * yield-limited spending (yieldLimitedSpending) to keep borrows within
- * theoretical collateral yield.
+ * Auto-Yield: When autoYield is enabled, the client first tries to cover
+ * the deficit from earned supply yield (principal untouched) before borrowing.
+ *
+ * Waterfall when both enabled: balance → yield → borrow
+ *
+ * Spending Limits: Optional daily spending cap (dailySpendLimitUsdc) with
+ * persistent state via onSpendingUpdate callback. The caller (e.g. plugin)
+ * is responsible for persisting and restoring state via initialSpendingState.
  *
  * Chain support: Base (8453), Base Sepolia (84532), Ethereum (1).
  */
@@ -717,21 +759,43 @@ interface X402BaseConfig {
      * Default: false
      */
     autoDraw?: boolean;
+    /**
+     * Auto-yield: when USDC is insufficient, try to cover the deficit from
+     * earned supply yield BEFORE borrowing. Withdraws only the yield portion
+     * (principal stays intact). Works independently or combined with autoDraw.
+     *
+     * Waterfall when both enabled: balance → yield → borrow
+     * Default: false
+     */
+    autoYield?: boolean;
     /**
      * Daily spending limit in USDC (e.g. '100' for $100/day).
      * Tracks cumulative daily borrows and rejects auto-draw if exceeded.
      */
     dailySpendLimitUsdc?: string;
-    /**
-     * When true, auto-calculates the daily spending limit based on
-     * theoretical yield of deposited collateral. Overrides dailySpendLimitUsdc.
-     */
-    yieldLimitedSpending?: boolean;
     /**
      * Safety margin: borrow this much extra beyond what's needed (in USDC, e.g. '1').
      * Helps avoid rounding issues. Default: '0.5'
      */
     autoDrawBuffer?: string;
+    /**
+     * Pre-loaded spending state from a previous session.
+     * Pass this to resume the daily spending tracker after a restart.
+     * If the date doesn't match today, it's ignored (fresh day).
+     */
+    initialSpendingState?: {
+        date: string;
+        totalBorrowed: string;
+    };
+    /**
+     * Called after every auto-draw borrow so the caller can persist the
+     * updated spending state (e.g. to a cache file). Receives the full
+     * SpendingTracker with the current date and cumulative amount.
+     */
+    onSpendingUpdate?: (state: {
+        date: string;
+        totalBorrowed: string;
+    }) => void;
     /**
      * ERC-7579 validator module address (e.g. Agether8004ValidationModule).
      * Required for Safe7579 smart wallets so that `isValidSignature` calls
@@ -774,8 +838,10 @@ interface X402Response<T = unknown> {
         txHash?: string;
     };
     autoDrawInfo?: {
-        borrowed: string;
-        borrowTx: string;
+        borrowed?: string;
+        borrowTx?: string;
+        yieldWithdrawn?: string;
+        yieldTx?: string;
         reason: string;
     };
 }
@@ -812,15 +878,23 @@ declare class X402Client {
     /** Get remaining daily spending allowance in USDC (human-readable) */
     getRemainingDailyAllowance(): string;
     /**
-     * Pay with auto-draw: Make an x402 request with automatic Morpho borrowing.
+     * Pay with auto-funding: Make an x402 request with automatic USDC sourcing.
      *
-     * Flow:
-     * 1. Check USDC balance on AgentAccount
-     * 2. Probe the URL to discover payment amount (if 402)
-     * 3. If insufficient USDC, calculate deficit
-     * 4. Check spending limit
-     * 5. Borrow from Morpho via MorphoClient
-     * 6. Proceed with x402 payment
+     * Uses a **plan-then-execute** approach: all reads happen first, and if the
+     * full deficit can't be covered the method fails with NO side-effects
+     * (no yield withdrawn, no USDC borrowed).
+     *
+     * Waterfall (when both autoYield + autoDraw enabled):
+     *   1. Check USDC balance on AgentAccount
+     *   2. Probe the URL to discover payment amount (if 402)
+     *   3. If insufficient USDC — PLANNING PHASE (read-only):
+     *      a. Calculate total available yield across supply positions
+     *      b. Calculate max borrowable from Morpho markets
+     *      c. Verify yield + borrow can cover full deficit — if not, fail immediately
+     *   4. EXECUTION PHASE (only if plan is feasible):
+     *      a. Withdraw needed yield from supply positions
+     *      b. Borrow remaining deficit from Morpho
+     *   5. Proceed with x402 payment
      */
     payWithAutoDraw<T = unknown>(url: string, opts?: RequestInit & {
         morphoClient?: any;
@@ -834,11 +908,10 @@ declare class X402Client {
     private _probePaymentAmount;
     /** Reset spending tracker if it's a new day */
     private _resetTrackerIfNewDay;
-    /** Track a new spending amount */
+    /** Track a new spending amount and notify the caller for persistence */
     private _trackSpending;
     /**
-     * Check if a borrow amount is within spending limits.
-     * Considers both fixed daily limits and yield-limited spending.
+     * Check if a borrow amount is within the fixed daily spending limit.
      */
     private _checkSpendingLimit;
 }
@@ -1211,4 +1284,4 @@ declare function getDefaultConfig(chainId: ChainId): AgetherConfig;
  */
 declare function createConfig(chainId: ChainId, options?: Partial<AgetherConfig>): AgetherConfig;
 
-export { ACCOUNT_FACTORY_ABI, AGENT_REPUTATION_ABI, AGETHER_4337_FACTORY_ABI, AGETHER_8004_SCORER_ABI, AGETHER_8004_VALIDATION_MODULE_ABI, AGETHER_HOOK_MULTIPLEXER_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type AgetherSigner, type AgetherViemWallet, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ENTRYPOINT_V07_ABI, ERC20_ABI, ERC8004_VALIDATION_MODULE_ABI, type FundResult, HOOK_MULTIPLEXER_ABI, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PayFromYieldResult, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, SAFE7579_ACCOUNT_ABI, SAFE_AGENT_FACTORY_ABI, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type SupplyAssetResult, type SupplyPositionResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawResult, type WithdrawSupplyResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getDefaultConfig, parseUnits, rateToBps };
+export { ACCOUNT_FACTORY_ABI, AGENT_REPUTATION_ABI, AGETHER_4337_FACTORY_ABI, AGETHER_8004_SCORER_ABI, AGETHER_8004_VALIDATION_MODULE_ABI, AGETHER_HOOK_MULTIPLEXER_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type AgetherSigner, type AgetherViemWallet, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ENTRYPOINT_V07_ABI, ERC20_ABI, ERC8004_VALIDATION_MODULE_ABI, type FundResult, HOOK_MULTIPLEXER_ABI, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PayFromYieldResult, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, SAFE7579_ACCOUNT_ABI, SAFE_AGENT_FACTORY_ABI, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type SupplyAssetResult, type SupplyPositionResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawFromAccountResult, type WithdrawResult, type WithdrawSupplyResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getDefaultConfig, parseUnits, rateToBps };

package/dist/index.d.ts

@@ -347,6 +347,12 @@ interface FundResult {
     amount: string;
     agentAccount: string;
 }
+interface WithdrawFromAccountResult {
+    tx: string;
+    token: string;
+    amount: string;
+    destination: string;
+}
 interface SupplyAssetResult {
     tx: string;
     amount: string;
@@ -394,6 +400,8 @@ declare class MorphoClient {
     private validationModule;
     private _accountAddress?;
     private _marketCache;
+    /** Dynamic token registry: symbol (uppercase) → { address, symbol, decimals } */
+    private _tokenCache;
     private _discoveredMarkets?;
     private _discoveredAt;
     constructor(config: MorphoClientConfig);
@@ -430,6 +438,21 @@ declare class MorphoClient {
     getBalances(): Promise<BalancesResult>;
     /** Transfer USDC from EOA to AgentAccount. */
     fundAccount(usdcAmount: string): Promise<FundResult>;
+    /**
+     * Withdraw (transfer) a token from AgentAccount to EOA.
+     * Executes an ERC-20 transfer via Safe UserOp.
+     *
+     * @param tokenSymbol - Token to withdraw (e.g. 'USDC', 'WETH', 'wstETH')
+     * @param amount - Amount to withdraw (human-readable, e.g. '100' for 100 USDC, or 'all')
+     */
+    withdrawToken(tokenSymbol: string, amount: string): Promise<WithdrawFromAccountResult>;
+    /**
+     * Withdraw ETH from AgentAccount to EOA.
+     * Executes a native ETH transfer via Safe UserOp.
+     *
+     * @param amount - ETH amount (e.g. '0.01' or 'all')
+     */
+    withdrawEth(amount: string): Promise<WithdrawFromAccountResult>;
     /**
      * Fetch USDC borrow markets on Base from Morpho API.
      * Caches results for 5 minutes.
@@ -662,6 +685,20 @@ declare class MorphoClient {
     private _findActiveMarket;
     /** Find the first market where the agent has a supply (lending) position. */
     private _findActiveSupplyMarket;
+    /**
+     * Resolve a token symbol or address to { address, symbol, decimals }.
+     *
+     * Uses the dynamic `_tokenCache` populated by `getMarkets()` from the
+     * Morpho GraphQL API — no hardcoded token list needed.
+     *
+     * @param symbolOrAddress - e.g. 'WETH', 'wstETH', or '0x4200...'
+     */
+    private _resolveToken;
+    /**
+     * Get all discovered collateral tokens (for balance iteration, etc.).
+     * Returns unique tokens from the Morpho API market discovery.
+     */
+    private _getDiscoveredTokens;
     /**
      * Compute net deposited amounts per market using Morpho GraphQL API.
      *
@@ -692,9 +729,14 @@ declare class MorphoClient {
  * Auto-Draw: When autoDraw is enabled and USDC balance is insufficient,
  * the client automatically borrows from Morpho Blue before paying.
  *
- * Spending Limits: Optional daily spending cap (dailySpendLimitUsdc) and
- * yield-limited spending (yieldLimitedSpending) to keep borrows within
- * theoretical collateral yield.
+ * Auto-Yield: When autoYield is enabled, the client first tries to cover
+ * the deficit from earned supply yield (principal untouched) before borrowing.
+ *
+ * Waterfall when both enabled: balance → yield → borrow
+ *
+ * Spending Limits: Optional daily spending cap (dailySpendLimitUsdc) with
+ * persistent state via onSpendingUpdate callback. The caller (e.g. plugin)
+ * is responsible for persisting and restoring state via initialSpendingState.
  *
  * Chain support: Base (8453), Base Sepolia (84532), Ethereum (1).
  */
@@ -717,21 +759,43 @@ interface X402BaseConfig {
      * Default: false
      */
     autoDraw?: boolean;
+    /**
+     * Auto-yield: when USDC is insufficient, try to cover the deficit from
+     * earned supply yield BEFORE borrowing. Withdraws only the yield portion
+     * (principal stays intact). Works independently or combined with autoDraw.
+     *
+     * Waterfall when both enabled: balance → yield → borrow
+     * Default: false
+     */
+    autoYield?: boolean;
     /**
      * Daily spending limit in USDC (e.g. '100' for $100/day).
      * Tracks cumulative daily borrows and rejects auto-draw if exceeded.
      */
     dailySpendLimitUsdc?: string;
-    /**
-     * When true, auto-calculates the daily spending limit based on
-     * theoretical yield of deposited collateral. Overrides dailySpendLimitUsdc.
-     */
-    yieldLimitedSpending?: boolean;
     /**
      * Safety margin: borrow this much extra beyond what's needed (in USDC, e.g. '1').
      * Helps avoid rounding issues. Default: '0.5'
      */
     autoDrawBuffer?: string;
+    /**
+     * Pre-loaded spending state from a previous session.
+     * Pass this to resume the daily spending tracker after a restart.
+     * If the date doesn't match today, it's ignored (fresh day).
+     */
+    initialSpendingState?: {
+        date: string;
+        totalBorrowed: string;
+    };
+    /**
+     * Called after every auto-draw borrow so the caller can persist the
+     * updated spending state (e.g. to a cache file). Receives the full
+     * SpendingTracker with the current date and cumulative amount.
+     */
+    onSpendingUpdate?: (state: {
+        date: string;
+        totalBorrowed: string;
+    }) => void;
     /**
      * ERC-7579 validator module address (e.g. Agether8004ValidationModule).
      * Required for Safe7579 smart wallets so that `isValidSignature` calls
@@ -774,8 +838,10 @@ interface X402Response<T = unknown> {
         txHash?: string;
     };
     autoDrawInfo?: {
-        borrowed: string;
-        borrowTx: string;
+        borrowed?: string;
+        borrowTx?: string;
+        yieldWithdrawn?: string;
+        yieldTx?: string;
         reason: string;
     };
 }
@@ -812,15 +878,23 @@ declare class X402Client {
     /** Get remaining daily spending allowance in USDC (human-readable) */
     getRemainingDailyAllowance(): string;
     /**
-     * Pay with auto-draw: Make an x402 request with automatic Morpho borrowing.
+     * Pay with auto-funding: Make an x402 request with automatic USDC sourcing.
      *
-     * Flow:
-     * 1. Check USDC balance on AgentAccount
-     * 2. Probe the URL to discover payment amount (if 402)
-     * 3. If insufficient USDC, calculate deficit
-     * 4. Check spending limit
-     * 5. Borrow from Morpho via MorphoClient
-     * 6. Proceed with x402 payment
+     * Uses a **plan-then-execute** approach: all reads happen first, and if the
+     * full deficit can't be covered the method fails with NO side-effects
+     * (no yield withdrawn, no USDC borrowed).
+     *
+     * Waterfall (when both autoYield + autoDraw enabled):
+     *   1. Check USDC balance on AgentAccount
+     *   2. Probe the URL to discover payment amount (if 402)
+     *   3. If insufficient USDC — PLANNING PHASE (read-only):
+     *      a. Calculate total available yield across supply positions
+     *      b. Calculate max borrowable from Morpho markets
+     *      c. Verify yield + borrow can cover full deficit — if not, fail immediately
+     *   4. EXECUTION PHASE (only if plan is feasible):
+     *      a. Withdraw needed yield from supply positions
+     *      b. Borrow remaining deficit from Morpho
+     *   5. Proceed with x402 payment
      */
     payWithAutoDraw<T = unknown>(url: string, opts?: RequestInit & {
         morphoClient?: any;
@@ -834,11 +908,10 @@ declare class X402Client {
     private _probePaymentAmount;
     /** Reset spending tracker if it's a new day */
     private _resetTrackerIfNewDay;
-    /** Track a new spending amount */
+    /** Track a new spending amount and notify the caller for persistence */
     private _trackSpending;
     /**
-     * Check if a borrow amount is within spending limits.
-     * Considers both fixed daily limits and yield-limited spending.
+     * Check if a borrow amount is within the fixed daily spending limit.
      */
     private _checkSpendingLimit;
 }
@@ -1211,4 +1284,4 @@ declare function getDefaultConfig(chainId: ChainId): AgetherConfig;
  */
 declare function createConfig(chainId: ChainId, options?: Partial<AgetherConfig>): AgetherConfig;
 
-export { ACCOUNT_FACTORY_ABI, AGENT_REPUTATION_ABI, AGETHER_4337_FACTORY_ABI, AGETHER_8004_SCORER_ABI, AGETHER_8004_VALIDATION_MODULE_ABI, AGETHER_HOOK_MULTIPLEXER_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type AgetherSigner, type AgetherViemWallet, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ENTRYPOINT_V07_ABI, ERC20_ABI, ERC8004_VALIDATION_MODULE_ABI, type FundResult, HOOK_MULTIPLEXER_ABI, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PayFromYieldResult, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, SAFE7579_ACCOUNT_ABI, SAFE_AGENT_FACTORY_ABI, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type SupplyAssetResult, type SupplyPositionResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawResult, type WithdrawSupplyResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getDefaultConfig, parseUnits, rateToBps };
+export { ACCOUNT_FACTORY_ABI, AGENT_REPUTATION_ABI, AGETHER_4337_FACTORY_ABI, AGETHER_8004_SCORER_ABI, AGETHER_8004_VALIDATION_MODULE_ABI, AGETHER_HOOK_MULTIPLEXER_ABI, AgentIdentityClient, type AgentIdentityClientOptions, AgentNotApprovedError, AgetherClient, type AgetherClientOptions, type AgetherConfig, AgetherError, type AgetherSigner, type AgetherViemWallet, type BalancesResult, type BorrowResult, ChainId, type ContractAddresses, type DepositAndBorrowResult, type DepositResult, ENTRYPOINT_V07_ABI, ERC20_ABI, ERC8004_VALIDATION_MODULE_ABI, type FundResult, HOOK_MULTIPLEXER_ABI, IDENTITY_REGISTRY_ABI, InsufficientBalanceError, MORPHO_BLUE_ABI, MorphoClient, type MorphoClientConfig, type MorphoMarketInfo, type MorphoMarketParams, type MorphoPosition, type PayFromYieldResult, type PaymentRequirements, type PositionResult, type RegisterResult, type RepayResult, SAFE7579_ACCOUNT_ABI, SAFE_AGENT_FACTORY_ABI, type ScoreAttestation, type ScoreResult, ScoringClient, type ScoringClientConfig, ScoringRejectedError, type SpendingTracker, type StatusResult, type SupplyAssetResult, type SupplyPositionResult, type TransactionResult, VALIDATION_REGISTRY_ABI, type WithdrawFromAccountResult, type WithdrawResult, type WithdrawSupplyResult, X402Client, type X402Config, type X402PaymentRequest, type X402PaymentResult, type X402Response, bpsToRate, createConfig, formatAPR, formatAddress, formatHealthFactor, formatPercent, formatTimestamp, formatUSD, formatUnits, getDefaultConfig, parseUnits, rateToBps };