@owney/sdk 0.6.6-beta.1 → 0.6.6-beta.3

package/dist/index.d.cts

@@ -8,19 +8,92 @@ interface OwneySDKConfig {
      * Example: { 8453: "https://...", 42161: "https://..." }
      */
     zyfaiRpcUrls?: ZyfaiRpcUrlsConfig;
+    /**
+     * Optional override for the Owney routing API base URL used by the sponsored
+     * deposit callbacks (defaults to the OWNEY_ROUTING_API_BASE_URL env var, then
+     * the production URL). Set this to point at a local/staging routing API,
+     * e.g. "http://localhost:3000", when testing sponsor changes.
+     */
+    routingApiBaseUrl?: string;
 }
 interface ConnectionState {
     provider: any;
     walletAddress: `0x${string}`;
     chainId: number | null;
 }
-declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT"];
-declare const SUPPORTED_CHAIN_IDS: readonly [8453, 42161];
-declare const SUPPORTED_CHAINS: readonly ["BASE", "ARBITRUM"];
+declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT", "WETH"];
+declare const SUPPORTED_CHAIN_IDS: readonly [8453, 42161, 1];
+declare const SUPPORTED_CHAINS: readonly ["BASE", "ARBITRUM", "ETHEREUM"];
 type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
+type AgentId = "zyfai" | "sail";
+type Asset = string;
+type AgentSupportedAsset = {
+    readonly symbol: string;
+    readonly minDepositAmount: string;
+};
+type AgentSupportedAssets = {
+    readonly chainId: number;
+    readonly chain?: string;
+    readonly assets: readonly AgentSupportedAsset[];
+};
+type DailyApyDays = "7D" | "14D" | "30D";
+type HistoryFilters = {
+    fromDate?: string;
+    toDate?: string;
+    /** Max entries returned per call. Defaults to 10. */
+    limit?: number;
+    /** Opaque cursor returned by a previous getHistory call. */
+    cursor?: string;
+};
+type HistoryOptions = {
+    agentId?: AgentId;
+    filters?: HistoryFilters;
+};
+type WithdrawOptions = {
+    asset: Asset;
+    amount?: string;
+    agentId?: AgentId;
+};
+type AccountApyOptions = {
+    agentId?: AgentId;
+    days: DailyApyDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the daily APY series
+     * to a specific asset on the active chain. Without it the series blends every
+     * position on the chain, so two assets sharing a chain (USDC and WETH on
+     * Base/Arbitrum) would render one merged line. Agents whose backends do not
+     * expose per-asset positions ignore this. (ROUT-186)
+     */
+    tokenSymbol?: string;
+};
+type AllocationApyOptions = {
+    agentId?: AgentId;
+};
+type AgentsApyOptions = {
+    agentId?: AgentId;
+    days: DailyApyDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the APY to a
+     * specific asset+chain. Ignored by agents whose backends do not yet
+     * support per-asset APY.
+     */
+    tokenSymbol?: string;
+    /**
+     * Optional chain id for per-asset APY lookups. Typically paired with
+     * `tokenSymbol`.
+     */
+    chainId?: number;
+};
+type DepositOptions = {
+    amount: string;
+    asset: Asset;
+    depositCallback?: DepositCallback;
+    agentId?: AgentId;
+};
+
 interface OwneyDepositResult {
     txHash: string;
     smartWallet: string;
@@ -28,12 +101,6 @@ interface OwneyDepositResult {
 }
 interface OwneyMultiDepositResult {
     agentResults: Record<string, OwneyDepositResult>;
-    /**
-     * Per-agent failure messages for agents that errored during a diversified
-     * deposit. Present only when at least one (but not all) agents failed —
-     * the deposit is partial, not total. Omitted when every agent succeeded.
-     */
-    agentErrors?: Record<string, string>;
 }
 interface AgentWithdrawResult {
     txHash?: string;
@@ -201,13 +268,25 @@ interface IAgent {
     readonly supportedAssets: readonly AgentSupportedAssets[];
     disconnect(): Promise<void>;
     activateAgent(state: ConnectionState, chainId: number): Promise<void>;
-    deposit(state: ConnectionState, chainId: number, amount: string, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
+    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
     withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
     getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
     getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
-    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays): Promise<AccountAgentApy>;
+    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, 
+    /**
+     * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
+     * single asset on the chain. Agents without per-asset positions ignore it.
+     */
+    tokenSymbol?: string): Promise<AccountAgentApy>;
     getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
     getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
+    /**
+     * Ensure the given asset uses backend protocol auto-selection
+     * (`autoSelectProtocols: true`). Optional capability — only agents whose
+     * backend models per-asset protocol selection implement it. Returns whether
+     * a write occurred (`false` = already enabled / not supported).
+     */
+    ensureAutoSelectProtocols?(state: ConnectionState, chainId: number, asset: "USDC" | "WETH"): Promise<boolean>;
     getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
 }
 /**
@@ -221,64 +300,6 @@ type AgentApyOptions = {
     chainId?: number;
 };
 
-type AgentId = "zyfai" | "sail" | "surfliquid";
-type Asset = string;
-type AgentSupportedAsset = {
-    readonly symbol: string;
-    readonly minDepositAmount: string;
-};
-type AgentSupportedAssets = {
-    readonly chainId: number;
-    readonly chain?: string;
-    readonly assets: readonly AgentSupportedAsset[];
-};
-type DailyApyDays = "7D" | "14D" | "30D";
-type HistoryFilters = {
-    fromDate?: string;
-    toDate?: string;
-    /** Max entries returned per call. Defaults to 10. */
-    limit?: number;
-    /** Opaque cursor returned by a previous getHistory call. */
-    cursor?: string;
-};
-type HistoryOptions = {
-    agentId?: AgentId;
-    filters?: HistoryFilters;
-};
-type WithdrawOptions = {
-    asset: Asset;
-    amount?: string;
-    agentId?: AgentId;
-};
-type AccountApyOptions = {
-    agentId?: AgentId;
-    days: DailyApyDays;
-};
-type AllocationApyOptions = {
-    agentId?: AgentId;
-};
-type AgentsApyOptions = {
-    agentId?: AgentId;
-    days: DailyApyDays;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") to scope the APY to a
-     * specific asset+chain. Ignored by agents whose backends do not yet
-     * support per-asset APY.
-     */
-    tokenSymbol?: string;
-    /**
-     * Optional chain id for per-asset APY lookups. Typically paired with
-     * `tokenSymbol`.
-     */
-    chainId?: number;
-};
-type DepositOptions = {
-    amount: string;
-    asset: Asset;
-    depositCallback?: DepositCallback;
-    agentId?: AgentId;
-};
-
 declare class OwneySDK {
     private agents;
     private activeAgents;
@@ -291,7 +312,9 @@ declare class OwneySDK {
     private state;
     private apiKey;
     private zyfaiRpcUrls?;
+    private routingApiBaseUrl?;
     private cachedSponsoredCallback;
+    private cachedWethSponsoredCallback;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
     /**
@@ -326,6 +349,13 @@ declare class OwneySDK {
      * `TransferWithAuthorization`, then POSTs to the sponsor API.
      */
     private getDefaultSponsoredCallback;
+    /**
+     * Lazily builds (and caches) the default Permit2 sponsored WETH deposit
+     * callback used when the caller omits `depositCallback` for a WETH
+     * deposit. Mirrors `getDefaultSponsoredCallback()` but signs a Permit2
+     * `PermitTransferFrom` instead of an EIP-3009 authorization.
+     */
+    private getDefaultWethSponsoredCallback;
     private getAgent;
     private getActiveAgents;
     private ensureAgentsInitialized;
@@ -354,6 +384,32 @@ declare class OwneySDK {
      * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
      */
     deposit(options: DepositOptions): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
+    /**
+     * Invokes `agent.deposit` with the resolved sponsored callback, composing
+     * two independent auto-recovery mechanisms:
+     *
+     * 1. Missing Permit2 allowance: when the app did not supply its own
+     *    callback and the attempt fails with `PERMIT2_APPROVAL_REQUIRED` on a
+     *    WETH deposit, this is the wallet's first gasless WETH deposit. We send
+     *    the one-time (user-paid) Permit2 approval via `approvePermit2()` and
+     *    retry the SAME sponsored attempt once. Bounded to one approval attempt
+     *    per call so a wallet/agent that keeps reporting the allowance as
+     *    missing can't loop forever. If `approvePermit2()` itself throws (e.g.
+     *    the user rejects the wallet prompt), that error propagates as-is —
+     *    the user said no to a transaction, so we must not turn around and ask
+     *    them to pay for a different one via the fallback below.
+     * 2. `shouldFallbackToUserPaid`: the SDK's own WETH sponsor path failed at
+     *    the infrastructure layer in a provably safe-to-retry way, so we warn
+     *    and retry once with `undefined`, falling through to a user-paid
+     *    native deposit. This still applies after a successful Permit2
+     *    approval retry (the retried sponsored attempt can itself hit a safe
+     *    sponsor failure).
+     *
+     * Any other error — an app-supplied callback's own failure in particular —
+     * propagates unchanged. Scoped per agent invocation so one agent's failure
+     * doesn't force a retry of sibling agents in a multi-agent split.
+     */
+    private depositWithFallback;
     private getMinDepositAmount;
     private splitDepositAmount;
     private validateMinDepositAmount;
@@ -366,17 +422,6 @@ declare class OwneySDK {
     private hasExistingBalance;
     private validateAssetSupport;
     private getEligibleAgents;
-    /**
-     * Agent ids the routing API provisioned for this org that support the given
-     * chain + asset, ordered by preference ({@link AGENT_ELIGIBILITY_ORDER},
-     * surfliquid first). Returns `[]` when the org has no compatible agent — never
-     * throws on an empty org. Loads agent keys on first call (apiKey only, no
-     * wallet), so the UI can resolve which agent to use before the user connects.
-     *
-     * This is the source of truth for agent availability: an agent appears here
-     * iff the routing API returned its key. No per-app feature flags.
-     */
-    getEligibleAgentIds(chainId: number, asset: string): Promise<AgentId[]>;
     /**
      * Withdraw funds from a specific agent, or all agents that support the active chain+asset if agentId is omitted.
      * Validates that the asset is supported by the target agent(s) on the active chain.
@@ -407,7 +452,7 @@ declare class OwneySDK {
      * @param options.days - Lookback period: "7D", "14D", or "30D"
      * @returns {AccountAgentApy} for a single agent, or {OwneyAccountApy} with totalApy and per-agent breakdown
      */
-    getAccountApy({ agentId, days, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
+    getAccountApy({ agentId, days, tokenSymbol, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
     /**
      * Get transaction history for a specific agent, or all agents.
      *
@@ -432,6 +477,23 @@ declare class OwneySDK {
      * @returns {AgentUserProfile} for a single agent, or {OwneyUserProfile} with per-agent profiles
      */
     getUserProfile(agentId?: AgentId): Promise<OwneyUserProfile | AgentUserProfile>;
+    /**
+     * Ensure the given asset uses backend protocol auto-selection for the active
+     * chain's account. No-op (returns false) for agents that don't support it.
+     * @param asset - "USDC" or "WETH".
+     * @param agentId - Agent to target. Defaults to "zyfai".
+     * @returns whether a profile write occurred.
+     */
+    ensureAutoSelectProtocols(asset: "USDC" | "WETH", agentId?: AgentId): Promise<boolean>;
+    /**
+     * One-time, user-paid approval of Permit2 on the sponsored WETH token for
+     * the active chain. Required once per wallet per chain before gasless WETH
+     * deposits; afterwards deposit() is signature-only. Resolves only after the
+     * approval transaction is mined (1 confirmation), so a subsequent deposit()
+     * will see the new allowance; throws if the transaction reverted.
+     * @returns the approval transaction hash.
+     */
+    approvePermit2(asset?: "WETH"): Promise<`0x${string}`>;
     /**
      * Get the agent's average APY performance over a time period. Does not require a wallet connection.
      * @param options - Contains agentId (optional) and days ("7D", "14D", or "30D")
@@ -455,7 +517,7 @@ declare class OwneySDK {
     getAllocationApy({ agentId, }?: AllocationApyOptions): Promise<OwneyAllocationApy>;
 }
 
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_ALL_FAILED" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_SAIL_ERROR" | "API_SAIL_TIMEOUT" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_SAIL_ERROR" | "API_SAIL_TIMEOUT" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;

package/dist/index.d.ts

@@ -8,19 +8,92 @@ interface OwneySDKConfig {
      * Example: { 8453: "https://...", 42161: "https://..." }
      */
     zyfaiRpcUrls?: ZyfaiRpcUrlsConfig;
+    /**
+     * Optional override for the Owney routing API base URL used by the sponsored
+     * deposit callbacks (defaults to the OWNEY_ROUTING_API_BASE_URL env var, then
+     * the production URL). Set this to point at a local/staging routing API,
+     * e.g. "http://localhost:3000", when testing sponsor changes.
+     */
+    routingApiBaseUrl?: string;
 }
 interface ConnectionState {
     provider: any;
     walletAddress: `0x${string}`;
     chainId: number | null;
 }
-declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT"];
-declare const SUPPORTED_CHAIN_IDS: readonly [8453, 42161];
-declare const SUPPORTED_CHAINS: readonly ["BASE", "ARBITRUM"];
+declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT", "WETH"];
+declare const SUPPORTED_CHAIN_IDS: readonly [8453, 42161, 1];
+declare const SUPPORTED_CHAINS: readonly ["BASE", "ARBITRUM", "ETHEREUM"];
 type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
+type AgentId = "zyfai" | "sail";
+type Asset = string;
+type AgentSupportedAsset = {
+    readonly symbol: string;
+    readonly minDepositAmount: string;
+};
+type AgentSupportedAssets = {
+    readonly chainId: number;
+    readonly chain?: string;
+    readonly assets: readonly AgentSupportedAsset[];
+};
+type DailyApyDays = "7D" | "14D" | "30D";
+type HistoryFilters = {
+    fromDate?: string;
+    toDate?: string;
+    /** Max entries returned per call. Defaults to 10. */
+    limit?: number;
+    /** Opaque cursor returned by a previous getHistory call. */
+    cursor?: string;
+};
+type HistoryOptions = {
+    agentId?: AgentId;
+    filters?: HistoryFilters;
+};
+type WithdrawOptions = {
+    asset: Asset;
+    amount?: string;
+    agentId?: AgentId;
+};
+type AccountApyOptions = {
+    agentId?: AgentId;
+    days: DailyApyDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the daily APY series
+     * to a specific asset on the active chain. Without it the series blends every
+     * position on the chain, so two assets sharing a chain (USDC and WETH on
+     * Base/Arbitrum) would render one merged line. Agents whose backends do not
+     * expose per-asset positions ignore this. (ROUT-186)
+     */
+    tokenSymbol?: string;
+};
+type AllocationApyOptions = {
+    agentId?: AgentId;
+};
+type AgentsApyOptions = {
+    agentId?: AgentId;
+    days: DailyApyDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the APY to a
+     * specific asset+chain. Ignored by agents whose backends do not yet
+     * support per-asset APY.
+     */
+    tokenSymbol?: string;
+    /**
+     * Optional chain id for per-asset APY lookups. Typically paired with
+     * `tokenSymbol`.
+     */
+    chainId?: number;
+};
+type DepositOptions = {
+    amount: string;
+    asset: Asset;
+    depositCallback?: DepositCallback;
+    agentId?: AgentId;
+};
+
 interface OwneyDepositResult {
     txHash: string;
     smartWallet: string;
@@ -28,12 +101,6 @@ interface OwneyDepositResult {
 }
 interface OwneyMultiDepositResult {
     agentResults: Record<string, OwneyDepositResult>;
-    /**
-     * Per-agent failure messages for agents that errored during a diversified
-     * deposit. Present only when at least one (but not all) agents failed —
-     * the deposit is partial, not total. Omitted when every agent succeeded.
-     */
-    agentErrors?: Record<string, string>;
 }
 interface AgentWithdrawResult {
     txHash?: string;
@@ -201,13 +268,25 @@ interface IAgent {
     readonly supportedAssets: readonly AgentSupportedAssets[];
     disconnect(): Promise<void>;
     activateAgent(state: ConnectionState, chainId: number): Promise<void>;
-    deposit(state: ConnectionState, chainId: number, amount: string, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
+    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
     withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
     getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
     getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
-    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays): Promise<AccountAgentApy>;
+    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, 
+    /**
+     * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
+     * single asset on the chain. Agents without per-asset positions ignore it.
+     */
+    tokenSymbol?: string): Promise<AccountAgentApy>;
     getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
     getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
+    /**
+     * Ensure the given asset uses backend protocol auto-selection
+     * (`autoSelectProtocols: true`). Optional capability — only agents whose
+     * backend models per-asset protocol selection implement it. Returns whether
+     * a write occurred (`false` = already enabled / not supported).
+     */
+    ensureAutoSelectProtocols?(state: ConnectionState, chainId: number, asset: "USDC" | "WETH"): Promise<boolean>;
     getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
 }
 /**
@@ -221,64 +300,6 @@ type AgentApyOptions = {
     chainId?: number;
 };
 
-type AgentId = "zyfai" | "sail" | "surfliquid";
-type Asset = string;
-type AgentSupportedAsset = {
-    readonly symbol: string;
-    readonly minDepositAmount: string;
-};
-type AgentSupportedAssets = {
-    readonly chainId: number;
-    readonly chain?: string;
-    readonly assets: readonly AgentSupportedAsset[];
-};
-type DailyApyDays = "7D" | "14D" | "30D";
-type HistoryFilters = {
-    fromDate?: string;
-    toDate?: string;
-    /** Max entries returned per call. Defaults to 10. */
-    limit?: number;
-    /** Opaque cursor returned by a previous getHistory call. */
-    cursor?: string;
-};
-type HistoryOptions = {
-    agentId?: AgentId;
-    filters?: HistoryFilters;
-};
-type WithdrawOptions = {
-    asset: Asset;
-    amount?: string;
-    agentId?: AgentId;
-};
-type AccountApyOptions = {
-    agentId?: AgentId;
-    days: DailyApyDays;
-};
-type AllocationApyOptions = {
-    agentId?: AgentId;
-};
-type AgentsApyOptions = {
-    agentId?: AgentId;
-    days: DailyApyDays;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") to scope the APY to a
-     * specific asset+chain. Ignored by agents whose backends do not yet
-     * support per-asset APY.
-     */
-    tokenSymbol?: string;
-    /**
-     * Optional chain id for per-asset APY lookups. Typically paired with
-     * `tokenSymbol`.
-     */
-    chainId?: number;
-};
-type DepositOptions = {
-    amount: string;
-    asset: Asset;
-    depositCallback?: DepositCallback;
-    agentId?: AgentId;
-};
-
 declare class OwneySDK {
     private agents;
     private activeAgents;
@@ -291,7 +312,9 @@ declare class OwneySDK {
     private state;
     private apiKey;
     private zyfaiRpcUrls?;
+    private routingApiBaseUrl?;
     private cachedSponsoredCallback;
+    private cachedWethSponsoredCallback;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
     /**
@@ -326,6 +349,13 @@ declare class OwneySDK {
      * `TransferWithAuthorization`, then POSTs to the sponsor API.
      */
     private getDefaultSponsoredCallback;
+    /**
+     * Lazily builds (and caches) the default Permit2 sponsored WETH deposit
+     * callback used when the caller omits `depositCallback` for a WETH
+     * deposit. Mirrors `getDefaultSponsoredCallback()` but signs a Permit2
+     * `PermitTransferFrom` instead of an EIP-3009 authorization.
+     */
+    private getDefaultWethSponsoredCallback;
     private getAgent;
     private getActiveAgents;
     private ensureAgentsInitialized;
@@ -354,6 +384,32 @@ declare class OwneySDK {
      * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
      */
     deposit(options: DepositOptions): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
+    /**
+     * Invokes `agent.deposit` with the resolved sponsored callback, composing
+     * two independent auto-recovery mechanisms:
+     *
+     * 1. Missing Permit2 allowance: when the app did not supply its own
+     *    callback and the attempt fails with `PERMIT2_APPROVAL_REQUIRED` on a
+     *    WETH deposit, this is the wallet's first gasless WETH deposit. We send
+     *    the one-time (user-paid) Permit2 approval via `approvePermit2()` and
+     *    retry the SAME sponsored attempt once. Bounded to one approval attempt
+     *    per call so a wallet/agent that keeps reporting the allowance as
+     *    missing can't loop forever. If `approvePermit2()` itself throws (e.g.
+     *    the user rejects the wallet prompt), that error propagates as-is —
+     *    the user said no to a transaction, so we must not turn around and ask
+     *    them to pay for a different one via the fallback below.
+     * 2. `shouldFallbackToUserPaid`: the SDK's own WETH sponsor path failed at
+     *    the infrastructure layer in a provably safe-to-retry way, so we warn
+     *    and retry once with `undefined`, falling through to a user-paid
+     *    native deposit. This still applies after a successful Permit2
+     *    approval retry (the retried sponsored attempt can itself hit a safe
+     *    sponsor failure).
+     *
+     * Any other error — an app-supplied callback's own failure in particular —
+     * propagates unchanged. Scoped per agent invocation so one agent's failure
+     * doesn't force a retry of sibling agents in a multi-agent split.
+     */
+    private depositWithFallback;
     private getMinDepositAmount;
     private splitDepositAmount;
     private validateMinDepositAmount;
@@ -366,17 +422,6 @@ declare class OwneySDK {
     private hasExistingBalance;
     private validateAssetSupport;
     private getEligibleAgents;
-    /**
-     * Agent ids the routing API provisioned for this org that support the given
-     * chain + asset, ordered by preference ({@link AGENT_ELIGIBILITY_ORDER},
-     * surfliquid first). Returns `[]` when the org has no compatible agent — never
-     * throws on an empty org. Loads agent keys on first call (apiKey only, no
-     * wallet), so the UI can resolve which agent to use before the user connects.
-     *
-     * This is the source of truth for agent availability: an agent appears here
-     * iff the routing API returned its key. No per-app feature flags.
-     */
-    getEligibleAgentIds(chainId: number, asset: string): Promise<AgentId[]>;
     /**
      * Withdraw funds from a specific agent, or all agents that support the active chain+asset if agentId is omitted.
      * Validates that the asset is supported by the target agent(s) on the active chain.
@@ -407,7 +452,7 @@ declare class OwneySDK {
      * @param options.days - Lookback period: "7D", "14D", or "30D"
      * @returns {AccountAgentApy} for a single agent, or {OwneyAccountApy} with totalApy and per-agent breakdown
      */
-    getAccountApy({ agentId, days, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
+    getAccountApy({ agentId, days, tokenSymbol, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
     /**
      * Get transaction history for a specific agent, or all agents.
      *
@@ -432,6 +477,23 @@ declare class OwneySDK {
      * @returns {AgentUserProfile} for a single agent, or {OwneyUserProfile} with per-agent profiles
      */
     getUserProfile(agentId?: AgentId): Promise<OwneyUserProfile | AgentUserProfile>;
+    /**
+     * Ensure the given asset uses backend protocol auto-selection for the active
+     * chain's account. No-op (returns false) for agents that don't support it.
+     * @param asset - "USDC" or "WETH".
+     * @param agentId - Agent to target. Defaults to "zyfai".
+     * @returns whether a profile write occurred.
+     */
+    ensureAutoSelectProtocols(asset: "USDC" | "WETH", agentId?: AgentId): Promise<boolean>;
+    /**
+     * One-time, user-paid approval of Permit2 on the sponsored WETH token for
+     * the active chain. Required once per wallet per chain before gasless WETH
+     * deposits; afterwards deposit() is signature-only. Resolves only after the
+     * approval transaction is mined (1 confirmation), so a subsequent deposit()
+     * will see the new allowance; throws if the transaction reverted.
+     * @returns the approval transaction hash.
+     */
+    approvePermit2(asset?: "WETH"): Promise<`0x${string}`>;
     /**
      * Get the agent's average APY performance over a time period. Does not require a wallet connection.
      * @param options - Contains agentId (optional) and days ("7D", "14D", or "30D")
@@ -455,7 +517,7 @@ declare class OwneySDK {
     getAllocationApy({ agentId, }?: AllocationApyOptions): Promise<OwneyAllocationApy>;
 }
 
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_ALL_FAILED" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_SAIL_ERROR" | "API_SAIL_TIMEOUT" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_SAIL_ERROR" | "API_SAIL_TIMEOUT" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;