@owney/sdk 0.7.26 → 0.7.27-beta.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import * as viem from 'viem';
+import { Address, Hex } from 'viem';
 import { SIWXConfig } from '@reown/appkit-controllers';
 
 /**
@@ -220,7 +222,9 @@ type SwapOrderStatus = "pending" | "executed" | "expired" | "cancelled" | "refun
  * of the flow and the one place a user would otherwise think nothing is
  * happening.
  */
-type SwapStage = "withdrawing" | "withdrawn" | "quoting" | "wrapping" | "wrapped" | "approving" | "building" | "signing" | "swapping" | "swapped" | "depositing" | "refunding" | "refunded";
+type SwapStage = "withdrawing" | "withdrawn"
+/** Withdrawal incomplete or unconfirmed; no swap was submitted. */
+ | "withdrawal-incomplete" | "quoting" | "wrapping" | "wrapped" | "approving" | "building" | "signing" | "swapping" | "swapped" | "depositing" | "refunding" | "refunded";
 /**
  * Which way the funds travel, which decides what each side may be.
  *
@@ -246,19 +250,34 @@ type SwapQuoteParams = {
     direction?: SwapDirection;
 };
 
-type ZyfaiRpcUrlsConfig = Partial<Record<(typeof SUPPORTED_CHAIN_IDS)[number], string>>;
+type RpcUrlsConfig = Partial<Record<(typeof SUPPORTED_CHAIN_IDS)[number], string>>;
+/** @deprecated Use RpcUrlsConfig. */
+type ZyfaiRpcUrlsConfig = RpcUrlsConfig;
 interface OwneySDKConfig {
     apiKey: string;
+    /**
+     * Optional per-chain RPC overrides used for application-owned reads and
+     * transaction receipt polling. Missing chains use the Owney routing API's
+     * read-only RPC proxy. No upstream RPC credentials are included in the SDK.
+     * Wallet providers remain responsible for account access, chain switching,
+     * signatures, and transaction submission.
+     */
+    rpcUrls?: RpcUrlsConfig;
     /**
      * Optional per-chain RPC overrides for Zyfai SDK network calls.
      * Example: { 8453: "https://...", 42161: "https://..." }
+     * @deprecated Use rpcUrls so every agent shares the same read transport.
      */
     zyfaiRpcUrls?: ZyfaiRpcUrlsConfig;
+    /** Optional Owney Yieldseeker proxy base URL override for integration tests. */
+    yieldseekerApiBaseUrl?: string;
+    /** Optional SIWE origin override. Defaults to the requesting browser origin. */
+    yieldseekerSiweOrigin?: string;
     /**
      * Optional override for the Owney routing API base URL used by all routing
-     * calls (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.
+     * calls. RPC proxy requests use OWNEY_ROUTING_API_BASE_URL when this is
+     * omitted; without either value, all rpcUrls must be configured.
+     * Set this to a local/staging routing API when testing sponsor changes.
      */
     routingApiBaseUrl?: string;
     /**
@@ -300,7 +319,134 @@ type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
-type AgentId = "zyfai";
+/**
+ * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
+ * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
+ * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
+ * must not be normalised anywhere.
+ *
+ * An empty array means "no usable pools on this chain".
+ */
+type OrgPoolSelection = {
+    protocolId: string;
+    chainId: number;
+    pools: string[];
+};
+/**
+ * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
+ * narrowed appear. Optional so an older routing API, which does not return the
+ * field, still parses; undefined and null both mean "change nothing".
+ */
+type OrgPoolPolicy = {
+    autoApproveProtocols: boolean;
+    autoApprovePools: boolean;
+    selections: OrgPoolSelection[];
+};
+/**
+ * The organization's agent execution policy, or null when the partner has never
+ * configured one — in which case the agents leave the user's profile alone.
+ */
+type OrgAgentConfig = {
+    splittingMode: "none" | "automatic" | "force";
+    minSplits: number | null;
+    poolPolicy?: OrgPoolPolicy | null;
+};
+
+type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
+interface IAgent {
+    readonly id: string;
+    readonly supportedChainIds: readonly OwneySupportedChainId[];
+    readonly supportedAssets: readonly AgentSupportedAssets[];
+    /**
+     * Describes how `AgentBalance.tokens` relates to `positions`.
+     * Most adapters expose token totals that already include deployed positions.
+     * Providers such as Yieldseeker expose idle wallet tokens separately, so
+     * withdrawal planning must add matching position amounts.
+     */
+    readonly balanceComposition?: "tokens-include-positions" | "tokens-plus-positions";
+    /**
+     * Whether a withdrawal requires an owner-approved wallet transaction.
+     * Aggregate withdrawals run these agents before relayer-only agents so a
+     * rejected wallet request cannot happen after another leg has committed.
+     */
+    readonly withdrawalRequiresWalletApproval?: boolean;
+    disconnect(): Promise<void>;
+    activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
+    /**
+     * Apply the organization's agent policy to this user's account.
+     *
+     * Optional: an agent that has no equivalent knob simply omits it, which is why
+     * this is not part of `activateAgent`'s signature. Declared on the interface
+     * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
+     * ticket asks for a design that can also cover Surf, which has no adapter yet.
+     *
+     * Implementations must be **non-fatal**: this runs during activation as a side
+     * effect, so a failure has to leave the user connected and their profile
+     * unchanged rather than break the connect.
+     */
+    applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
+    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>): Promise<OwneyDepositResult>;
+    withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress): Promise<AgentWithdrawResult>;
+    /** A newly observed pool allocation invalidates this asset's portfolio cache only. */
+    invalidateAllocationRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
+    /** Invalidate only the confirmed asset. This hook must not sign or submit transactions. */
+    invalidateFundingRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number): void;
+    /** End accelerated balance reads only for the exact snapshot the caller displayed. */
+    endFundingBalanceRefresh?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
+    getFundingHistory?(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
+    getFundingWallet?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
+    /** Verify the displayed remaining balance after a receipt-confirmed payout.
+     * Undefined means unknown; never substitute a failed read with zero. */
+    verifyWithdrawalBalance?(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
+    /** Read-only chain proof when indexed withdrawal components are incomplete.
+     * Returns raw owner-withdrawable units; unavailable proof must throw.
+     * minimumAmount is the raw liquidity required from this agent for a typed
+     * plan, so adapters can expand discovery when known positions fall short. */
+    getWithdrawableBalance?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
+    /** Optional positive proof for a repeat deposit; unknown must fall back to portfolio validation. */
+    hasExistingDepositFunds?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
+    getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
+    getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    /**
+     * Refresh the agent's earnings snapshot when its backend supports doing so.
+     * Implementations own freshness and request-deduplication policy.
+     */
+    refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    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>;
+    /**
+     * Daily cumulative earnings in token units, scoped to a chain/asset, using
+     * the provider's earnings basis. Include an opening snapshot when available
+     * so the "recent earnings" subline can difference the endpoints. (ROUT-452)
+     */
+    getDailyEarnings?(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
+    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>;
+}
+/**
+ * Optional filters for per-agent APY lookups.
+ * - `tokenSymbol` / `chainId` scope the APY to a specific asset+chain when
+ *   the underlying provider supports it (Zyfai). Agents whose backends do
+ *   not yet support per-asset APY will ignore these options.
+ */
+type AgentApyOptions = {
+    tokenSymbol?: string;
+    chainId?: number;
+};
+
+type AgentId = "zyfai" | "yieldseeker";
 type Asset = string;
 type AgentSupportedAsset = {
     readonly symbol: string;
@@ -349,13 +495,26 @@ type HistoryFilters = {
     tokenSymbol?: string;
 };
 type HistoryOptions = {
+    chainId?: number;
     agentId?: AgentId;
     filters?: HistoryFilters;
 };
 type WithdrawOptions = {
+    /** Yieldseeker V2 only. "auto" requests sponsorship for a verified V2 wallet. */
+    gasMode?: "auto" | "sponsored" | "paid";
+    /** Exclude unresolved providers from aggregate withdrawals; direct agent requests are unchanged. */
+    excludeAgentIds?: AgentId[];
+    onProgress?: FundingProgress;
+    /**
+     * Durable pre-dispatch checkpoint for adapters with a recoverable operation ID.
+     * Rejection prevents submission; progress observers remain non-fatal.
+     */
+    onBeforeSubmission?: FundingProgress;
     asset: Asset;
     amount?: string;
     agentId?: AgentId;
+    /** Called after each agent returns; callback failures never change a financial result. */
+    onAgentResult?: (agentId: AgentId, result: AgentWithdrawResult) => void;
 };
 type AccountApyOptions = {
     agentId?: AgentId;
@@ -402,6 +561,12 @@ type AgentsApyOptions = {
     chainId?: number;
 };
 type DepositOptions = {
+    /** Resume only these already signed relayer bytes; never create a new authorization. */
+    resumeTxHash?: `0x${string}`;
+    onProgress?: FundingProgress;
+    /** Awaited immediately before dispatch. Throwing prevents submission.
+     * All legs of an atomic batch are checkpointed together. */
+    onBeforeSubmission?: (evidence: FundingEvidence[]) => void | Promise<void>;
     amount: string;
     asset: Asset;
     depositCallback?: DepositCallback;
@@ -409,40 +574,85 @@ type DepositOptions = {
     onApproved?: () => void;
 };
 
-/**
- * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
- * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
- * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
- * must not be normalised anywhere.
- *
- * An empty array means "no usable pools on this chain".
- */
-type OrgPoolSelection = {
-    protocolId: string;
-    chainId: number;
-    pools: string[];
-};
-/**
- * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
- * narrowed appear. Optional so an older routing API, which does not return the
- * field, still parses; undefined and null both mean "change nothing".
- */
-type OrgPoolPolicy = {
-    autoApproveProtocols: boolean;
-    autoApprovePools: boolean;
-    selections: OrgPoolSelection[];
-};
-/**
- * The organization's agent execution policy, or null when the partner has never
- * configured one — in which case the agents leave the user's profile alone.
- */
-type OrgAgentConfig = {
-    splittingMode: "none" | "automatic" | "force";
-    minSplits: number | null;
-    poolPolicy?: OrgPoolPolicy | null;
+type FundingStage = "pending" | "confirmed" | "unknown" | "failed" | "not-applicable";
+/** Hash-bound v0.6 recovery metadata. Deliberately excludes the owner signature. */
+type UnsignedUserOperationEvidence = {
+    sender: string;
+    nonce: string;
+    initCode: string;
+    callData: string;
+    callGasLimit: string;
+    verificationGasLimit: string;
+    preVerificationGas: string;
+    maxFeePerGas: string;
+    maxPriorityFeePerGas: string;
+    paymasterAndData: string;
 };
-
+/** Evidence about one provider leg. Amounts are token base units, never USD. */
+interface FundingEvidence {
+    agentId: AgentId;
+    chainId: number;
+    token: OwneySupportedTokens;
+    walletAddress: string;
+    agentWallet?: string;
+    intendedAmount: string;
+    confirmedAmount?: string;
+    /** Receipt delivery and fulfillment of a typed requested amount are separate facts. */
+    amountCompletion?: "complete" | "shortfall";
+    /** Verified difference between the typed request and the actual owner payout. */
+    shortfallAmount?: string;
+    txHash?: string;
+    /** Persisted before a sponsored EOA operation is sent. */
+    userOpHash?: string;
+    /** Lets recovery verify a consumed nonce even if a bundler forgets the operation. */
+    userOperation?: UnsignedUserOperationEvidence;
+    /** Base Account calls ID used to recover an uncertain wallet submission. */
+    callsId?: string;
+    /** Deposit execution was attempted, rather than only prepared. Not confirmation. */
+    depositSubmission?: "started";
+    blockNumber?: string;
+    logIndexes?: number[];
+    transferLogs?: {
+        logIndex: number;
+        amountRaw: string;
+    }[];
+    /** Sanitized execution-request evidence. Attempted does not prove server acceptance. */
+    withdrawalRequest?: {
+        attempted: boolean;
+        method?: "GET" | "POST";
+        path?: "/users/withdraw" | "/users/partial-withdraw";
+        elapsedMs?: number;
+        /** Actual response status captured before the vendor replaces the HTTP error. */
+        httpStatus?: number;
+        failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "insufficient-balance" | "session-key-missing" | "withdrawal-in-progress" | "other";
+    };
+    transfer: FundingStage;
+    registration: FundingStage;
+    delivery: FundingStage;
+}
+type FundingProgress = (evidence: FundingEvidence) => void;
+interface AssetReadMetadata {
+    chainId: number;
+    asset: string;
+    fetchedAt?: number;
+    /** When the underlying provider request started; preserved on cached reads. */
+    requestedAt?: number;
+    /** SDK cache generation, not an onchain block or provider timestamp. */
+    readVersion?: number;
+    providerUpdatedAt?: string;
+    snapshotId?: string;
+    blockNumber?: string;
+    netDepositsRaw?: string;
+    /** Display-only agreement with a post-payout read. Does not prove that
+     * provider accounting, history or allocations include the transaction. */
+    withdrawalCheck?: {
+        txHash: string;
+        blockNumber: string;
+    };
+    positionsStatus: "available" | "unavailable";
+}
 interface OwneyDepositResult {
+    evidence?: FundingEvidence;
     txHash: string;
     smartWallet: string;
     amount: string;
@@ -451,16 +661,28 @@ interface OwneyMultiDepositResult {
     agentResults: Record<string, OwneyDepositResult>;
 }
 interface AgentWithdrawResult {
+    evidence?: FundingEvidence;
     txHash?: string;
     type: "full" | "partial";
-    /** Smallest-unit amount, or a provider sentinel such as "all" for a full request. */
+    /** Owner payout or clearing all MAX positions still needs verification. */
+    completion?: "unverified";
+    /** Confirmed smallest-unit amount; "0" when no owner payout is verified.
+     * Legacy providers may return a sentinel such as "all" for a full request. */
     amount: string;
+    /** Yieldseeker typed withdrawal fulfilled after an exactly verified fee
+     * deduction. Amount remains the confirmed net owner payout, and the gross
+     * amount must equal that payout plus the fee, all in token base units. */
+    feeAdjustment?: {
+        grossAmount: string;
+        feeAmount: string;
+    };
 }
 interface OwneyWithdrawResult {
     agentResult: Record<AgentId, AgentWithdrawResult>;
     /**
-     * Sum of reported smallest-unit amounts; null when a full withdrawal's
-     * amount is not yet known. An accepted request is not proof of settlement.
+     * Sum of confirmed smallest-unit amounts; null while any returned leg's
+     * payout is not yet known, including typed requests accepted asynchronously.
+     * Evidence-less custom adapters retain their confirmed-amount contract.
      */
     totalWithdrawn: string | null;
 }
@@ -478,6 +700,10 @@ interface OwneyPosition {
     pool?: string;
     asset: string;
     amount: string;
+    /** Provider-native raw quantity; may represent vault shares, not the underlying asset. */
+    amountRaw?: string;
+    /** Withdrawable underlying asset amount in that asset's smallest units. */
+    withdrawableAmountRaw?: string;
     apy?: number;
     tvl?: number;
     /** Pool liquidity. Prepared slot — Zyfai will add this to its portfolio
@@ -508,10 +734,20 @@ interface OwneyPendingAllocation {
     since?: string;
 }
 interface AgentBalance {
+    readMetadata?: AssetReadMetadata[];
+    /** Authoritative native balances per asset/network, including idle and invested funds. */
+    assetBalances?: OwneyToken[];
     smartWallet?: `0x${string}`;
     totalBalance: string;
     /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
     totalBalanceAsset: string;
+    /**
+     * Describes whether `tokens` already includes deployed `positions`.
+     * Consumers must add matching positions only for `tokens-plus-positions`;
+     * doing so for Zyfai would double-count, while omitting it for Yieldseeker
+     * makes its balance disappear as soon as idle funds enter a vault.
+     */
+    balanceComposition?: "tokens-include-positions" | "tokens-plus-positions";
     tokens: OwneyToken[];
     /**
      * Per-protocol/pool positions when the agent's portfolio payload includes
@@ -526,10 +762,14 @@ interface OwneyBalances {
     /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
     totalBalanceAsset: string;
     agentBalances: Record<AgentId, AgentBalance>;
-    /** Omitted agents failed to load; they must not be interpreted as zero. */
-    agentErrors?: Record<AgentId, string>;
+    /**
+     * Per-agent read failures when an aggregate balance request returned only a
+     * partial result. Callers may display the successful balances, but funding
+     * operations must not interpret a missing agent as having a zero balance.
+     */
+    agentErrors?: Partial<Record<AgentId, string>>;
     /** Absolute provider cooldown deadlines (Unix milliseconds). */
-    agentRetryAt?: Record<AgentId, number>;
+    agentRetryAt?: Partial<Record<AgentId, number>>;
 }
 interface AgentEarnings {
     smartWallet: `0x${string}`;
@@ -539,6 +779,10 @@ interface AgentEarnings {
 interface OwneyEarnings {
     totalEarnings: string;
     agentEarnings: Record<AgentId, AgentEarnings>;
+    /** Per-agent failures when an aggregate read returned a partial result. */
+    agentErrors?: Partial<Record<AgentId, string>>;
+    /** Absolute provider cooldown deadlines (Unix milliseconds). */
+    agentRetryAt?: Partial<Record<AgentId, number>>;
 }
 type ApyByChainAndAsset = Partial<Record<OwneySupportedChainId, Partial<Record<OwneySupportedTokens, number>>>>;
 /** A single day's net APY for the connected account, as a percentage number. */
@@ -584,6 +828,15 @@ interface OwneyAllocationApy {
 }
 type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
 interface HistoryTransaction {
+    tokenAddress?: string;
+    agentWallet?: string;
+    logIndexes?: number[];
+    transferLogs?: {
+        logIndex: number;
+        amountRaw: string;
+    }[];
+    amountRaw?: string;
+    blockNumber?: string;
     txHashes: string[];
     chainId?: number;
     tokenSymbol?: string;
@@ -612,6 +865,8 @@ interface AgentHistoryPosition {
     amount?: string;
 }
 interface AgentHistoryEntry {
+    /** Stable provider/transfer identity, independent of row order. */
+    id?: string;
     agent: AgentId;
     action: HistoryAction;
     date: string;
@@ -622,6 +877,8 @@ interface AgentHistoryEntry {
     positions?: AgentHistoryPosition[];
 }
 interface OwneyAgentHistory {
+    agentErrors?: Partial<Record<AgentId, string>>;
+    agentRetryAt?: Partial<Record<AgentId, number>>;
     data: AgentHistoryEntry[];
     /** True iff a subsequent page exists; pair with `nextCursor`. */
     hasMore: boolean;
@@ -662,15 +919,15 @@ interface AgentApy {
 interface OwneyAgentApy {
     agentApy: Record<AgentId, AgentApy>;
 }
-/** One day's cumulative NET earnings for a single asset. */
+/** One day's cumulative earnings for a single asset. */
 interface DailyEarningsPoint {
     /** ISO date string for the day, e.g. "2026-09-01". */
     date: string;
     /**
-     * Earnings accumulated from the start of the returned series up to and
-     * including this day, net of the agent's performance fee, denominated in the
-     * asset's own units. A running total of daily deltas, so it measures the
-     * window — not the wallet's lifetime.
+     * Cumulative earnings in the asset's own units, using the provider's earnings
+     * basis. A provider may return lifetime totals or a running window total;
+     * difference the last and opening points to measure earnings over the window.
+     * Aggregate series normalize each component's opening value before summing.
      */
     amount: number;
 }
@@ -679,8 +936,9 @@ interface AssetDailyEarnings {
     /** Asset symbol, e.g. "USDC" / "WETH". */
     asset: string;
     /**
-     * Ascending by date. Days the wallet held nothing of this asset are absent
-     * rather than zero — a zero would read as "earned nothing that day".
+     * Ascending by date, including an opening snapshot before the requested
+     * window when available. Provider gaps remain absent; aggregates carry the
+     * most recent cumulative value across dates reported by other providers.
      */
     points: DailyEarningsPoint[];
 }
@@ -697,70 +955,7 @@ interface AccountDailyEarnings {
     assets: AssetDailyEarnings[];
 }
 
-type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
-interface IAgent {
-    readonly id: string;
-    readonly supportedChainIds: readonly OwneySupportedChainId[];
-    readonly supportedAssets: readonly AgentSupportedAssets[];
-    disconnect(): Promise<void>;
-    activateAgent(state: ConnectionState, chainId: number): Promise<void>;
-    /**
-     * Apply the organization's agent policy to this user's account.
-     *
-     * Optional: an agent that has no equivalent knob simply omits it, which is why
-     * this is not part of `activateAgent`'s signature. Declared on the interface
-     * rather than only on ZyfaiAgent so the contract stays agent-neutral — the
-     * ticket asks for a design that can also cover Surf, which has no adapter yet.
-     *
-     * Implementations must be **non-fatal**: this runs during activation as a side
-     * effect, so a failure has to leave the user connected and their profile
-     * unchanged rather than break the connect.
-     */
-    applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
-    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>;
-    /**
-     * Refresh the agent's earnings snapshot when its backend supports doing so.
-     * Implementations own freshness and request-deduplication policy.
-     */
-    refreshEarnings?(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
-    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>;
-    /**
-     * Daily cumulative NET earnings for the window, scoped to a chain/asset.
-     * Backs the "recent earnings" subline, whose figure must reconcile with the
-     * balance headline directly above it. (ROUT-452)
-     */
-    getDailyEarnings?(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
-    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>;
-}
-/**
- * Optional filters for per-agent APY lookups.
- * - `tokenSymbol` / `chainId` scope the APY to a specific asset+chain when
- *   the underlying provider supports it (Zyfai). Agents whose backends do
- *   not yet support per-asset APY will ignore these options.
- */
-type AgentApyOptions = {
-    tokenSymbol?: string;
-    chainId?: number;
-};
-
-type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_FAILED" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
+type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "AGENT_ACTIVATION_PARTIAL_FAILURE" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_IN_PROGRESS" | "DEPOSIT_CHECKPOINT_FAILED" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_INVALID_AMOUNT" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_IN_PROGRESS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_BALANCE_UNAVAILABLE" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_UNCONFIRMED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_SWAP_INCOMPLETE" | "WITHDRAW_FAILED" | "WITHDRAW_INVALID_AMOUNT" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "AGENT_API_ERROR" | "AGENT_AUTH_FAILED" | "AGENT_INVALID_RESPONSE" | "AGENT_TIMEOUT" | "AGENT_TRANSACTION_REVERTED" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "EARNINGS_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
@@ -920,10 +1115,15 @@ declare class OwneySDK {
      */
     private disabledAgents;
     private state;
+    private connectionRevision;
+    private disconnectingAgents;
     private apiKey;
     private orgAgentConfig;
     private orgAgentConfigPromise;
+    private rpcUrls?;
     private zyfaiRpcUrls?;
+    private yieldseekerApiBaseUrl?;
+    private yieldseekerSiweOrigin?;
     private routingApiBaseUrl?;
     private referralSource?;
     private cachedSponsoredCallback;
@@ -931,7 +1131,11 @@ declare class OwneySDK {
     private paymasterServiceUrl?;
     private cachedSponsoredCallsCallbacks;
     private readonly agentReads;
+    private readonly recoveredFundingReads;
+    private fundingBalanceChecks;
     private readonly activationChecks;
+    private readonly withdrawalSubmissions;
+    private readonly withdrawalSwapSubmissions;
     private readAgent;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
@@ -946,6 +1150,8 @@ declare class OwneySDK {
      * After calling this, `connect()` must be called again before using agent methods.
      */
     disconnect(): Promise<void>;
+    private clearConnectionState;
+    private disconnectAgents;
     private isAgentDisabled;
     /**
      * Check if the SDK has an active connection state.
@@ -960,28 +1166,20 @@ declare class OwneySDK {
     private requireState;
     private requireChainId;
     private requireConnectedProvider;
-    /**
-     * Lazily builds (and caches) the default EIP-3009 sponsored deposit callback
-     * used when the caller omits `depositCallback`. Wraps the connected EIP-1193
-     * provider with viem `custom(provider)` to read token meta and sign the
-     * `TransferWithAuthorization`, then POSTs to the sponsor API.
-     */
+    private getPaidRpcClient;
+    /** Builds the default USDC batch callback for the connected wallet. */
     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.
-     */
+    /** Builds the wallet-native sponsored calls callback for compatible paymasters. */
     private getDefaultSponsoredCallsCallback;
     /**
      * 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.
+     * single-use batch authorization instead of an EIP-3009 authorization.
      */
     private getDefaultWethSponsoredCallback;
     private getAgent;
+    getActiveAgentIds(): AgentId[];
     private getActiveAgents;
     /**
      * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
@@ -1014,7 +1212,8 @@ declare class OwneySDK {
      *   If provided, ALL specified agents must support the chainId or the call
      *   throws before activating any agent.
      */
-    activateAgent(chainId: number, agentId?: AgentId[]): Promise<void>;
+    activateAgent(chainId: number, agentId?: AgentId[], asset?: OwneySupportedTokens): Promise<void>;
+    private assertActivationSession;
     /**
      * Activate agents ONE AT A TIME, each followed by its org policy.
      *
@@ -1028,10 +1227,9 @@ declare class OwneySDK {
      * Serializing costs no real wall-clock: the user can only approve one prompt
      * at a time anyway.
      *
-     * Every agent is attempted even if an earlier one fails, so one declined
-     * signature can't deny the remaining agents their turn. The first failure is
-     * rethrown (matching the previous `Promise.all` rejection) once all agents
-     * have had a chance to activate.
+     * Stop at the first failure so a canceled sign-in does not open another
+     * agent's wallet prompt. Report any earlier successes for diagnostics; the
+     * app discards the session when the complete sign-in does not succeed.
      */
     private activateAgentsInTurn;
     /**
@@ -1042,7 +1240,8 @@ declare class OwneySDK {
      * @param options.asset - Asset symbol to deposit (e.g. "USDC")
      * @param options.depositCallback - Callback that performs the token transfer and returns a tx hash.
      *   When agentId is omitted, this callback is invoked once per eligible agent with that agent's
-     *   split amount and smart wallet address — expect multiple wallet prompts.
+     *   split amount and smart wallet address. Default sponsored deposits batch
+     *   all shares into one signature; custom callbacks still run once per agent.
      * @param options.agentId - Optional explicit target. Otherwise split equally,
      *   or fund remaining agents when a recovery deposit cannot meet every minimum.
      * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
@@ -1052,10 +1251,12 @@ declare class OwneySDK {
      * 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
+     * 1. Missing Permit2 allowance outside the atomic Base-USDC path: when the
+     *    app did not supply its own callback and the attempt fails with
+     *    `PERMIT2_APPROVAL_REQUIRED`, this is the wallet's first Permit2 deposit
+     *    for that token. Base USDC bundles a gasless ERC-2612 approval inside
+     *    its sponsored deposit and never reaches this branch. Other tokens 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.
@@ -1076,6 +1277,7 @@ declare class OwneySDK {
     private depositWithFallback;
     private getMinDepositAmount;
     private splitDepositAmount;
+    private formatAgentName;
     private validateMinDepositAmount;
     /**
      * Whether the user already holds a non-zero balance with `agent` for the
@@ -1086,6 +1288,48 @@ declare class OwneySDK {
     private hasExistingBalance;
     private validateAssetSupport;
     private getEligibleAgents;
+    /**
+     * Run owner-approved withdrawals before relayer-only withdrawals. Wallet
+     * approval is the only point at which the user can cancel the aggregate
+     * operation, so no relayer leg should commit before it has completed.
+     */
+    private orderAgentsForWithdrawal;
+    private isUserRejectedWithdrawal;
+    private captureReadScope;
+    /** Revalidate a saved transfer against the authenticated account and actual receipt. */
+    inspectFunding(evidence: FundingEvidence, direction: "deposit" | "withdraw", options?: {
+        balanceRefreshUntil?: number;
+        refreshBalance?: boolean;
+        requireAmountMatch?: boolean;
+    }): Promise<FundingEvidence>;
+    /** Resolve a saved sponsored-withdrawal ID without opening a wallet prompt. */
+    resolveSponsoredWithdrawalEvidence(evidence: FundingEvidence, options?: {
+        submittedAt?: number;
+    }): Promise<FundingEvidence>;
+    /** Recover an EIP-5792 deposit or payout using this account's exact batch ID. */
+    resolveWalletCallsFundingEvidence(evidence: FundingEvidence, direction: "deposit" | "withdraw"): Promise<FundingEvidence>;
+    /** Whether a foreground deposit can resume the same signed batch, never a
+     * fresh authorization. The batch rail independently rechecks the exact plan. */
+    canResumePendingDeposit(evidences: FundingEvidence[], amount: string): Promise<boolean>;
+    /** Optional post-payout display proof; receipt verification and the provider
+     * adapter must agree before attaching it to this exact balance object. */
+    verifyWithdrawalBalance(evidence: FundingEvidence, balance: AgentBalance): Promise<AgentBalance>;
+    /** A display acknowledgement controls polling only; it never confirms a financial outcome. */
+    endFundingBalanceRefresh(evidence: FundingEvidence, read: AssetReadMetadata): boolean;
+    /** History lookup for receipt recovery; adapters may not authenticate or sign here. */
+    getFundingHistory(evidence: FundingEvidence, fromDate: string, options?: Pick<HistoryFilters, "cursor" | "toDate">): Promise<OwneyAgentHistory>;
+    recoverDepositRegistration(evidence: FundingEvidence): Promise<FundingEvidence>;
+    /** On-chain version and ownership status for this owner's Yieldseeker agent. */
+    getYieldseekerWalletStatus(asset: OwneySupportedTokens): Promise<YieldseekerWalletStatus | null>;
+    /** Deployment gate; an unavailable response keeps the current paid path. */
+    isYieldseekerWithdrawalSponsorshipAvailable(): Promise<boolean>;
+    isYieldseekerUpgradeSponsorshipAvailable(): Promise<boolean>;
+    private isYieldseekerSponsorshipAvailable;
+    /** Explicit V1-to-V2 upgrade, confirmed on chain before returning. */
+    upgradeYieldseekerWallet(asset: OwneySupportedTokens, gasMode?: "paid" | "sponsored"): Promise<{
+        txHash: viem.Hex;
+        status: YieldseekerWalletStatus;
+    }>;
     /** Lazily built so an app that never swaps pays nothing for it. */
     private swapApiClient?;
     private swapApi;
@@ -1377,10 +1621,9 @@ declare class OwneySDK {
      * Quoting before the tokens land would size the swap against a balance that
      * is not there yet.
      *
-     * The swap is therefore sized from the MEASURED arrival, exactly as the
-     * deposit path sizes its deposit from the measured swap output. On a full
-     * withdrawal there is no other number available — "MAX" has no figure until
-     * the agent picks one.
+     * Wait for each participating agent's owner payout and size one swap from
+     * their confirmed net amounts. A first wallet increase cannot establish
+     * that every payout arrived. Failed or incomplete withdrawals stop here.
      *
      * **Failure here is not symmetrical with the deposit path.** A failed
      * deposit-swap leaves the user holding what they started with. A failed
@@ -1407,6 +1650,8 @@ declare class OwneySDK {
         /** Percent, classic rail only. Fusion+ prices through its auction. */
         slippage?: number;
         onSwapProgress?: (stage: SwapStage) => void;
+        /** Receipt evidence for the existing funding/recovery tracker. */
+        onWithdrawalProgress?: FundingProgress;
         /**
          * Fires once the order is with the relayer, before the watch.
          *
@@ -1455,12 +1700,21 @@ declare class OwneySDK {
      * @returns {AgentWithdrawResult} for a single agent, or {OwneyWithdrawResult} with per-agent results
      */
     withdraw(options: WithdrawOptions): Promise<OwneyWithdrawResult | AgentWithdrawResult>;
+    private withdrawFromAgents;
+    /** Read-only invalidation after new pool-deposit activity. Does not restart
+     * funding reconciliation, bypass cooldowns, or authorize a transaction. */
+    invalidateAllocationRead(scope: Pick<FundingEvidence, "agentId" | "walletAddress" | "chainId" | "token">): boolean;
     /**
      * Get the user's balances for a specific agent, or aggregated across all agents.
      * @param agentId - Optional. Agent to query. Omit for aggregated balances.
      * @returns {AgentBalance} for a single agent, or {OwneyBalances} with totalBalance and per-agent breakdown
      */
-    getBalances(agentId?: AgentId): Promise<OwneyBalances | AgentBalance>;
+    getBalances(agentId?: AgentId, options?: {
+        chainId?: number;
+        asset?: OwneySupportedTokens;
+    }): Promise<OwneyBalances | AgentBalance>;
+    /** Preserve failure objects for withdrawal recovery without changing public balance results. */
+    private readAggregatedBalances;
     /**
      * Get the user's on-chain earnings for a specific agent, or aggregated across all agents.
      * @param agentId - Optional. Agent to query. Omit for aggregated earnings.
@@ -1472,6 +1726,7 @@ declare class OwneySDK {
      * Agents without a refresh capability fall back to their current snapshot.
      */
     refreshEarnings(agentId?: AgentId): Promise<OwneyEarnings | AgentEarnings>;
+    private aggregateEarnings;
     /**
      * Get the weighted APY for the user's account over a time period.
      * When querying all agents, the total APY is a balance-weighted average.
@@ -1481,10 +1736,8 @@ declare class OwneySDK {
      * @returns {AccountAgentApy} for a single agent, or {OwneyAccountApy} with totalApy and per-agent breakdown
      */
     /**
-     * Daily cumulative NET earnings for the selected chain/asset, backing the
-     * "recent earnings" subline. Net is computed as Zyfai's own
-     * `lifetime + unrealized + current x 0.9`, so the figure reconciles with the
-     * balance headline rather than reading ~11% high. (ROUT-452)
+     * Daily cumulative earnings in the selected asset's units, backing the
+     * "recent earnings" subline. Each adapter uses its provider's earnings basis.
      *
      * Unlike getAccountApy this does NOT blend across agents: earnings are
      * summed, not weighted, and an agent that fails to report must not silently
@@ -1526,14 +1779,17 @@ declare class OwneySDK {
      */
     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.
+     * User-paid approval of Permit2 on the selected token for the active chain.
+     * Grants the maximum ERC20 allowance so later deposits do not require another
+     * approval. Resolves after one confirmation so the subsequent deposit attempt
+     * sees the new allowance. Deposit retries pass their captured chain id so a
+     * concurrent activation cannot redirect the approval to another network.
+     *
+     * @param requiredAmount Raw base-unit amount the pending deposit must cover.
+     * @param expectedChainId Chain captured by the deposit that requested approval.
      * @returns the approval transaction hash.
      */
-    approvePermit2(asset?: "WETH"): Promise<`0x${string}`>;
+    approvePermit2(asset?: OwneySupportedTokens, requiredAmount?: bigint, expectedChainId?: OwneySupportedChainId): 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")
@@ -1557,6 +1813,170 @@ declare class OwneySDK {
     getAllocationApy({ agentId, }?: AllocationApyOptions): Promise<OwneyAllocationApy>;
 }
 
+type YieldseekerAuthDependencies = {
+    origin?: string;
+    now?: () => Date;
+    nonce?: () => string;
+};
+
+type YieldseekerFetch = typeof fetch;
+
+type YieldseekerTransaction = {
+    from: `0x${string}`;
+    to: `0x${string}`;
+    data: `0x${string}`;
+    value: string;
+    chainId: number;
+};
+
+type YieldseekerWalletStatus = {
+    agentWallet: Address;
+    owner: Address;
+    ownerPath: "eoa" | "smart";
+    asset: Address;
+    implementation: Address;
+    version: "v1" | "v2" | "unknown";
+    upgradeAvailable: boolean;
+    /** The factory, owner, base asset, and provider wallet mapping all agree. */
+    verified: boolean;
+};
+
+type YieldseekerAgentOptions = {
+    baseUrl?: string;
+    routingApiBaseUrl?: string;
+    fetchFn?: YieldseekerFetch;
+    auth?: YieldseekerAuthDependencies;
+    /** Dedicated read transport; Base is used for receipt polling. */
+    rpcUrls?: RpcUrlsConfig;
+    /** Test seam for the wallet-submission/receipt boundary. */
+    transactionExecutor?: (state: ConnectionState, chainId: number, transaction: YieldseekerTransaction, onReceipt?: (receipt: viem.TransactionReceipt) => void) => Promise<Hex>;
+    /** Test seam for transactions submitted outside transactionExecutor. */
+    unwindReceiptWaiter?: (state: ConnectionState, chainId: number, transactionHash: Hex) => Promise<void>;
+};
+declare class YieldseekerAgent implements IAgent {
+    readonly id = "yieldseeker";
+    readonly balanceComposition: "tokens-plus-positions";
+    readonly withdrawalRequiresWalletApproval = true;
+    readonly supportedChainIds: readonly [8453];
+    readonly supportedAssets: readonly [{
+        readonly chainId: 8453;
+        readonly chain: "BASE";
+        readonly assets: readonly [{
+            readonly symbol: "USDC";
+            readonly minDepositAmount: "10000000";
+        }, {
+            readonly symbol: "WETH";
+            readonly minDepositAmount: "1";
+        }];
+    }];
+    private readonly api;
+    private readonly auth;
+    private readonly rpcUrls?;
+    private readonly owneyApiKey;
+    private readonly routingApiBaseUrl?;
+    private receiptClient?;
+    private readonly withdrawalVersionCache;
+    private readonly pendingUpgrades;
+    private readonly transactionExecutor?;
+    private readonly unwindReceiptWaiter?;
+    private readonly agentContexts;
+    private readonly balanceContexts;
+    private readonly balanceVaults;
+    private readonly users;
+    private readonly pendingAgents;
+    private readonly pendingWalletContexts;
+    private readonly readCache;
+    private readonly pendingReads;
+    private readGeneration;
+    private readonly portfolioVersions;
+    private readonly snapshotFailures;
+    private readonly standardReadFailures;
+    private readonly reconcileUntil;
+    private readonly allocationRefresh;
+    private readonly activityRefreshUntil;
+    private readonly snapshotMovements;
+    private readonly movementEpochs;
+    private readonly yieldOptions;
+    private readonly pendingYieldOptions;
+    constructor(owneyApiKey: string, options?: YieldseekerAgentOptions);
+    private getReceiptClient;
+    /** Reads the actual proxy implementation; Yieldseeker's API walletType is not a version check. */
+    getWalletStatus(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, useCachedV2?: boolean): Promise<YieldseekerWalletStatus | null>;
+    private rememberWalletStatus;
+    /** Explicit owner action. This never runs as a side effect of withdrawal. */
+    upgradeWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, gasMode?: "paid" | "sponsored"): Promise<{
+        txHash: Hex;
+        status: YieldseekerWalletStatus;
+    }>;
+    disconnect(): Promise<void>;
+    activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
+    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>): Promise<OwneyDepositResult>;
+    withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress): Promise<AgentWithdrawResult>;
+    private withdrawInternal;
+    /** A withdrawal-only liquidity floor; display snapshots never authorize it. */
+    getWithdrawableBalance(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, minimumAmount?: bigint): Promise<bigint>;
+    private readVaultLiquidity;
+    private validateWithdrawalPositions;
+    private withdrawalVaultHints;
+    private readWithdrawalPositions;
+    private resolveWithdrawalLiquidity;
+    getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
+    verifyWithdrawalBalance(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
+    invalidateAllocationRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
+    invalidateFundingRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number): void;
+    endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
+    getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
+    hasExistingDepositFunds(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
+    getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
+    getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, tokenSymbol?: string): Promise<AccountAgentApy>;
+    getDailyEarnings(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
+    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
+    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
+    getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
+    private loadYieldOptions;
+    private userKey;
+    private contextKey;
+    private assertSession;
+    private cachedRead;
+    private agentListKey;
+    private listAgents;
+    private contextForAgent;
+    private resolveUser;
+    private forgetUser;
+    private ensureAgent;
+    private findAgent;
+    private resolveAgent;
+    private loadPortfolio;
+    private loadActivityPortfolio;
+    private resolvePortfolioContexts;
+    private portfolioVersion;
+    private portfolioCacheMs;
+    private snapshotMovement;
+    private advancePortfolioVersion;
+    private requestPortfolioSnapshot;
+    private portfolioSnapshot;
+    private loadPortfolioContext;
+    private loadActivityContext;
+    private loadPortfolioParts;
+    private deployAgent;
+    private refreshSnapshotAfterMovement;
+    private agentPath;
+    private walletRequest;
+    private providerRequest;
+    private mapApiError;
+    private submitTransaction;
+    private waitForReceipt;
+    private assertTransaction;
+    private assertAgent;
+    private isOwneyAgent;
+    private assetForAgent;
+    private isTransactionHash;
+    private assertChain;
+    private assertOptionalChain;
+    private assertAsset;
+    private invalidResponse;
+}
+
 declare class InvalidHistoryCursorError extends Error {
     readonly code: "invalid_cursor";
     constructor(message: string);
@@ -1634,4 +2054,4 @@ type StoredOrder = {
  */
 declare function listOrders(now?: number): StoredOrder[];
 
-export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type AssetDailyEarnings, type AvailableAgent, type AvailableAgentsOptions, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositCallback, type DepositOptions, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LookbackDays, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type PendingDeposit, type RebalanceLog, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };
+export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type AssetDailyEarnings, type AssetReadMetadata, type AvailableAgent, type AvailableAgentsOptions, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositCallback, type DepositOptions, type FundingEvidence, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LookbackDays, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type PendingDeposit, type RebalanceLog, type RpcUrlsConfig, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type UnsignedUserOperationEvidence, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, YieldseekerAgent, type YieldseekerWalletStatus, type ZyfaiRpcUrlsConfig, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };