@owney/sdk 0.7.25-beta.10 → 0.7.25-beta.12

package/dist/index.d.ts

@@ -70,7 +70,283 @@ type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
+/**
+ * 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): Promise<OwneyDepositResult>;
+    withdraw(state: ConnectionState, chainId: number, token: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress): Promise<AgentWithdrawResult>;
+    /** 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>;
+    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 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 AgentId = "zyfai" | "yieldseeker";
+type Asset = string;
+type AgentSupportedAsset = {
+    readonly symbol: string;
+    readonly minDepositAmount: string;
+};
+type AgentSupportedAssets = {
+    readonly chainId: number;
+    readonly chain?: string;
+    readonly assets: readonly AgentSupportedAsset[];
+};
+type AvailableAgent = {
+    id: AgentId;
+    isEnabled: boolean;
+    supportedChainIds: readonly number[];
+    supportedAssets: readonly AgentSupportedAssets[];
+};
+type AvailableAgentsOptions = {
+    chainId?: number;
+    asset?: Asset;
+    /** Disabled agents are omitted by default because they cannot accept funds. */
+    includeDisabled?: boolean;
+};
+/**
+ * A lookback window for any "last N days" read — the APY series, the daily
+ * earnings series. Named for the window itself, so nothing borrows the APY's
+ * name to ask for something else.
+ */
+type LookbackDays = "7D" | "14D" | "30D";
+/** Kept so existing callers keep compiling. Prefer `LookbackDays`. */
+type DailyApyDays = LookbackDays;
+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;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") to scope the history to a
+     * single asset. Without it the page blends every asset on the chain, so a
+     * consumer showing one asset at a time has to filter client-side — and a
+     * page whose entries all belong to the *other* asset then renders empty
+     * even though matching entries exist further back. Agents whose backends
+     * cannot filter by asset ignore this and return the whole chain's history.
+     */
+    tokenSymbol?: string;
+};
+type HistoryOptions = {
+    chainId?: number;
+    agentId?: AgentId;
+    filters?: HistoryFilters;
+};
+type WithdrawOptions = {
+    /** Exclude unresolved providers from aggregate withdrawals; direct agent requests are unchanged. */
+    excludeAgentIds?: AgentId[];
+    onProgress?: 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;
+    days: LookbackDays;
+    /**
+     * 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;
+};
+/**
+ * Options for the daily earnings series. Same shape as `AccountApyOptions` and
+ * deliberately its own type: the two reads answer different questions and are
+ * free to diverge.
+ */
+type DailyEarningsOptions = {
+    agentId?: AgentId;
+    days: LookbackDays;
+    /**
+     * Optional asset symbol (e.g. "USDC", "WETH") scoping the series to one
+     * asset on the active chain.
+     */
+    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 = {
+    onProgress?: FundingProgress;
+    amount: string;
+    asset: Asset;
+    depositCallback?: DepositCallback;
+    agentId?: AgentId;
+    onApproved?: () => void;
+};
+
+type FundingStage = "pending" | "confirmed" | "unknown" | "failed" | "not-applicable";
+/** 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;
+    txHash?: string;
+    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;
+        failure?: "network" | "unauthorized" | "forbidden" | "rate-limited" | "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;
+    positionsStatus: "available" | "unavailable";
+}
 interface OwneyDepositResult {
+    evidence?: FundingEvidence;
     txHash: string;
     smartWallet: string;
     amount: string;
@@ -79,6 +355,7 @@ 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. */
@@ -140,6 +417,7 @@ interface OwneyPendingAllocation {
     since?: string;
 }
 interface AgentBalance {
+    readMetadata?: AssetReadMetadata[];
     /** Authoritative native balances per asset/network, including idle and invested funds. */
     assetBalances?: OwneyToken[];
     smartWallet?: `0x${string}`;
@@ -233,6 +511,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;
@@ -261,6 +548,8 @@ interface AgentHistoryPosition {
     amount?: string;
 }
 interface AgentHistoryEntry {
+    /** Stable provider/transfer identity, independent of row order. */
+    id?: string;
     agent: AgentId;
     action: HistoryAction;
     date: string;
@@ -271,6 +560,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;
@@ -346,226 +637,6 @@ interface AccountDailyEarnings {
     assets: AssetDailyEarnings[];
 }
 
-type AgentId = "zyfai" | "yieldseeker";
-type Asset = string;
-type AgentSupportedAsset = {
-    readonly symbol: string;
-    readonly minDepositAmount: string;
-};
-type AgentSupportedAssets = {
-    readonly chainId: number;
-    readonly chain?: string;
-    readonly assets: readonly AgentSupportedAsset[];
-};
-type AvailableAgent = {
-    id: AgentId;
-    isEnabled: boolean;
-    supportedChainIds: readonly number[];
-    supportedAssets: readonly AgentSupportedAssets[];
-};
-type AvailableAgentsOptions = {
-    chainId?: number;
-    asset?: Asset;
-    /** Disabled agents are omitted by default because they cannot accept funds. */
-    includeDisabled?: boolean;
-};
-/**
- * A lookback window for any "last N days" read — the APY series, the daily
- * earnings series. Named for the window itself, so nothing borrows the APY's
- * name to ask for something else.
- */
-type LookbackDays = "7D" | "14D" | "30D";
-/** Kept so existing callers keep compiling. Prefer `LookbackDays`. */
-type DailyApyDays = LookbackDays;
-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;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") to scope the history to a
-     * single asset. Without it the page blends every asset on the chain, so a
-     * consumer showing one asset at a time has to filter client-side — and a
-     * page whose entries all belong to the *other* asset then renders empty
-     * even though matching entries exist further back. Agents whose backends
-     * cannot filter by asset ignore this and return the whole chain's history.
-     */
-    tokenSymbol?: string;
-};
-type HistoryOptions = {
-    agentId?: AgentId;
-    filters?: HistoryFilters;
-};
-type WithdrawOptions = {
-    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;
-    days: LookbackDays;
-    /**
-     * 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;
-};
-/**
- * Options for the daily earnings series. Same shape as `AccountApyOptions` and
- * deliberately its own type: the two reads answer different questions and are
- * free to diverge.
- */
-type DailyEarningsOptions = {
-    agentId?: AgentId;
-    days: LookbackDays;
-    /**
-     * Optional asset symbol (e.g. "USDC", "WETH") scoping the series to one
-     * asset on the active chain.
-     */
-    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;
-    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 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): 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;
-};
-
 declare class OwneySDK {
     private agents;
     private activeAgents;
@@ -590,6 +661,7 @@ declare class OwneySDK {
     private paymasterServiceUrl?;
     private cachedSponsoredCallsCallbacks;
     private readonly agentReads;
+    private readonly recoveredFundingReads;
     private readonly activationChecks;
     private readAgent;
     private initializingAgentsPromise;
@@ -632,6 +704,7 @@ declare class OwneySDK {
      */
     private getDefaultWethSponsoredCallback;
     private getAgent;
+    getActiveAgentIds(): AgentId[];
     private getActiveAgents;
     /**
      * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
@@ -747,6 +820,17 @@ declare class OwneySDK {
      */
     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;
+    }): Promise<FundingEvidence>;
+    /** 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>;
     /**
      * 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.
@@ -757,12 +841,16 @@ declare class OwneySDK {
      * @returns {AgentWithdrawResult} for a single agent, or {OwneyWithdrawResult} with per-agent results
      */
     withdraw(options: WithdrawOptions): Promise<OwneyWithdrawResult | AgentWithdrawResult>;
+    private withdrawFromAgents;
     /**
      * 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>;
     /**
      * 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.
@@ -932,9 +1020,13 @@ declare class YieldseekerAgent implements IAgent {
     private getReceiptClient;
     disconnect(): Promise<void>;
     activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
-    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback): Promise<OwneyDepositResult>;
-    withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string): Promise<AgentWithdrawResult>;
-    getBalances(state: ConnectionState, chainId: number): Promise<AgentBalance>;
+    deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress): Promise<OwneyDepositResult>;
+    withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress): Promise<AgentWithdrawResult>;
+    private withdrawInternal;
+    getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
+    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>;
     getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
     getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, tokenSymbol?: string): Promise<AccountAgentApy>;
     getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
@@ -1050,4 +1142,4 @@ type OwneySIWXConfig = {
  */
 declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
 
-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 RebalanceLog, type RpcUrlsConfig, type WithdrawOptions, YieldseekerAgent, type ZyfaiRpcUrlsConfig, createOwneySIWX, setOwneyDebug };
+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 RebalanceLog, type RpcUrlsConfig, type WithdrawOptions, YieldseekerAgent, type ZyfaiRpcUrlsConfig, createOwneySIWX, setOwneyDebug };