@owney/sdk 0.6.0-beta.0 → 0.6.0-beta.2

package/dist/index.d.cts

@@ -14,97 +14,13 @@ interface ConnectionState {
     walletAddress: `0x${string}`;
     chainId: number | null;
 }
-declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT"];
+declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT", "WETH"];
 declare const SUPPORTED_CHAIN_IDS: readonly [8453, 42161];
 declare const SUPPORTED_CHAINS: readonly ["BASE", "ARBITRUM"];
 type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
-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>;
-    deposit(state: ConnectionState, chainId: number, amount: string, 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>;
-    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
-    pause(state: ConnectionState, chainId: number): Promise<OwneyAgentStatus>;
-    resume(state: ConnectionState, chainId: number): Promise<OwneyAgentStatus>;
-    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
-    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" | "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;
-};
-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;
@@ -128,10 +44,29 @@ interface OwneyToken {
     asset: OwneySupportedTokens;
     amount: string;
 }
+interface OwneyPosition {
+    /** Raw chain identifier as returned by the agent (chain id or name); not coerced. */
+    chain: string;
+    protocol: string;
+    protocolId?: string;
+    pool?: string;
+    asset: string;
+    amount: string;
+    apy?: number;
+    tvl?: number;
+    /** Pool liquidity. Prepared slot — Zyfai will add this to its portfolio
+     *  response later; undefined until then. */
+    liquidity?: number;
+}
 interface AgentBalance {
     smartWallet?: `0x${string}`;
     totalBalance: string;
     tokens: OwneyToken[];
+    /**
+     * Per-protocol/pool positions when the agent's portfolio payload includes
+     * them (zyfai). Omitted for agents that don't expose positions (sail).
+     */
+    positions?: OwneyPosition[];
 }
 interface OwneyBalances {
     totalBalance: string;
@@ -158,6 +93,17 @@ interface OwneyAccountApy {
     agentApy: Record<AgentId, AccountAgentApy>;
     apyByChainAndAsset: ApyByChainAndAsset;
 }
+interface AllocationAgentApy {
+    /** Account-wide weighted APY for this agent, as a decimal string. */
+    totalApy: string;
+    apyByChainAndAsset: ApyByChainAndAsset;
+}
+interface OwneyAllocationApy {
+    /** Account-wide weighted APY across all active agents, as a decimal string. */
+    totalApy: string;
+    apyByChainAndAsset: ApyByChainAndAsset;
+    agentApy: Record<AgentId, AllocationAgentApy>;
+}
 type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
 interface HistoryTransaction {
     txHashes: string[];
@@ -168,6 +114,15 @@ interface HistoryTransaction {
 interface RebalanceLog {
     fromProtocol: string;
     toProtocol: string;
+    /**
+     * Pool/vault sub-label for the source position (e.g. "USDC Core"), when the
+     * agent exposes one. Lets consumers disambiguate moves within the same
+     * protocol ("Morpho · USDC Core → Morpho · Spark USDC"). Absent when the
+     * agent only reports a bare protocol name.
+     */
+    fromPool?: string;
+    /** Pool/vault sub-label for the destination position. See {@link fromPool}. */
+    toPool?: string;
     tokenSymbol: string;
     amount: string;
     status: "success" | "failed";
@@ -195,11 +150,6 @@ interface OwneyAgentHistory {
     /** Opaque cursor for the next page. Present iff `hasMore === true`. */
     nextCursor?: string;
 }
-interface OwneyAgentStatus {
-    success: boolean;
-    strategy?: string;
-    protocols?: string[];
-}
 interface AgentUserProfile {
     address: string;
     smartWallet: string;
@@ -223,8 +173,92 @@ interface OwneyAgentApy {
 }
 interface OwneyAgentAllocation {
     agentAllocation: Record<AgentId, number>;
+    /** Per-agent positions. Empty array for agents that don't expose positions. */
+    agentPositions: Record<AgentId, OwneyPosition[]>;
 }
 
+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>;
+    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>;
+    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
+    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
+    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" | "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;
+};
+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;
@@ -237,6 +271,7 @@ declare class OwneySDK {
     private state;
     private apiKey;
     private zyfaiRpcUrls?;
+    private cachedSponsoredCallback;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
     /**
@@ -263,6 +298,14 @@ declare class OwneySDK {
     getActiveChainId(): number | null;
     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 getDefaultSponsoredCallback;
     private getAgent;
     private getActiveAgents;
     private ensureAgentsInitialized;
@@ -352,18 +395,6 @@ declare class OwneySDK {
      * @returns {OwneyAgentHistory} `data` (up to `limit` entries), `hasMore`, `nextCursor`.
      */
     getHistory(params?: HistoryOptions): Promise<OwneyAgentHistory>;
-    /**
-     * Pause an agent's automated operations. The agent will stop rebalancing until resumed.
-     * @param agentId - The agent to pause (e.g. "zyfai")
-     * @returns OwneyAgentStatus with success flag
-     */
-    pauseAgent(agentId: AgentId): Promise<OwneyAgentStatus>;
-    /**
-     * Resume an agent's automated operations.
-     * @param agentId - The agent to resume (e.g. "zyfai")
-     * @returns OwneyAgentStatus with success flag
-     */
-    resumeAgent(agentId: AgentId): Promise<OwneyAgentStatus>;
     /**
      * Get the user's profile for a specific agent, or all agents.
      * @param agentId - Optional. Agent to query. Omit for all agents.
@@ -388,9 +419,19 @@ declare class OwneySDK {
      * @returns Object with agent names as keys and allocation percentages as values
      */
     getAgentAllocation(): Promise<OwneyAgentAllocation>;
+    /**
+     * Allocation-weighted APY from the current portfolio: each pool's APY
+     * weighted by the user's position value in it. More accurate per-user than
+     * the historical 30D APY. (ROUT-228)
+     * @param options.agentId - Optional. Scope to one agent. Omit to aggregate
+     *   positions across all active agents.
+     */
+    getAllocationApy({ agentId, }?: {
+        agentId?: AgentId;
+    }): 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" | "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" | "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" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
@@ -433,4 +474,4 @@ type OwneySIWXConfig = {
  */
 declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
 
-export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentHistoryPosition, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, InvalidHistoryCursorError, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAgentStatus, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneySDK, OwneySDKConfig, OwneySIWXConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions, createOwneySIWX };
+export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentHistoryPosition, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, AllocationAgentApy, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, InvalidHistoryCursorError, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAllocationApy, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneyPosition, OwneySDK, OwneySDKConfig, OwneySIWXConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions, createOwneySIWX };

package/dist/index.d.ts

@@ -14,97 +14,13 @@ interface ConnectionState {
     walletAddress: `0x${string}`;
     chainId: number | null;
 }
-declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT"];
+declare const SUPPORTED_TOKENS: readonly ["USDC", "USDT", "WETH"];
 declare const SUPPORTED_CHAIN_IDS: readonly [8453, 42161];
 declare const SUPPORTED_CHAINS: readonly ["BASE", "ARBITRUM"];
 type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
 type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
 type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
 
-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>;
-    deposit(state: ConnectionState, chainId: number, amount: string, 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>;
-    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
-    pause(state: ConnectionState, chainId: number): Promise<OwneyAgentStatus>;
-    resume(state: ConnectionState, chainId: number): Promise<OwneyAgentStatus>;
-    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
-    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" | "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;
-};
-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;
@@ -128,10 +44,29 @@ interface OwneyToken {
     asset: OwneySupportedTokens;
     amount: string;
 }
+interface OwneyPosition {
+    /** Raw chain identifier as returned by the agent (chain id or name); not coerced. */
+    chain: string;
+    protocol: string;
+    protocolId?: string;
+    pool?: string;
+    asset: string;
+    amount: string;
+    apy?: number;
+    tvl?: number;
+    /** Pool liquidity. Prepared slot — Zyfai will add this to its portfolio
+     *  response later; undefined until then. */
+    liquidity?: number;
+}
 interface AgentBalance {
     smartWallet?: `0x${string}`;
     totalBalance: string;
     tokens: OwneyToken[];
+    /**
+     * Per-protocol/pool positions when the agent's portfolio payload includes
+     * them (zyfai). Omitted for agents that don't expose positions (sail).
+     */
+    positions?: OwneyPosition[];
 }
 interface OwneyBalances {
     totalBalance: string;
@@ -158,6 +93,17 @@ interface OwneyAccountApy {
     agentApy: Record<AgentId, AccountAgentApy>;
     apyByChainAndAsset: ApyByChainAndAsset;
 }
+interface AllocationAgentApy {
+    /** Account-wide weighted APY for this agent, as a decimal string. */
+    totalApy: string;
+    apyByChainAndAsset: ApyByChainAndAsset;
+}
+interface OwneyAllocationApy {
+    /** Account-wide weighted APY across all active agents, as a decimal string. */
+    totalApy: string;
+    apyByChainAndAsset: ApyByChainAndAsset;
+    agentApy: Record<AgentId, AllocationAgentApy>;
+}
 type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
 interface HistoryTransaction {
     txHashes: string[];
@@ -168,6 +114,15 @@ interface HistoryTransaction {
 interface RebalanceLog {
     fromProtocol: string;
     toProtocol: string;
+    /**
+     * Pool/vault sub-label for the source position (e.g. "USDC Core"), when the
+     * agent exposes one. Lets consumers disambiguate moves within the same
+     * protocol ("Morpho · USDC Core → Morpho · Spark USDC"). Absent when the
+     * agent only reports a bare protocol name.
+     */
+    fromPool?: string;
+    /** Pool/vault sub-label for the destination position. See {@link fromPool}. */
+    toPool?: string;
     tokenSymbol: string;
     amount: string;
     status: "success" | "failed";
@@ -195,11 +150,6 @@ interface OwneyAgentHistory {
     /** Opaque cursor for the next page. Present iff `hasMore === true`. */
     nextCursor?: string;
 }
-interface OwneyAgentStatus {
-    success: boolean;
-    strategy?: string;
-    protocols?: string[];
-}
 interface AgentUserProfile {
     address: string;
     smartWallet: string;
@@ -223,8 +173,92 @@ interface OwneyAgentApy {
 }
 interface OwneyAgentAllocation {
     agentAllocation: Record<AgentId, number>;
+    /** Per-agent positions. Empty array for agents that don't expose positions. */
+    agentPositions: Record<AgentId, OwneyPosition[]>;
 }
 
+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>;
+    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>;
+    getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
+    getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
+    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" | "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;
+};
+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;
@@ -237,6 +271,7 @@ declare class OwneySDK {
     private state;
     private apiKey;
     private zyfaiRpcUrls?;
+    private cachedSponsoredCallback;
     private initializingAgentsPromise;
     constructor(config: OwneySDKConfig);
     /**
@@ -263,6 +298,14 @@ declare class OwneySDK {
     getActiveChainId(): number | null;
     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 getDefaultSponsoredCallback;
     private getAgent;
     private getActiveAgents;
     private ensureAgentsInitialized;
@@ -352,18 +395,6 @@ declare class OwneySDK {
      * @returns {OwneyAgentHistory} `data` (up to `limit` entries), `hasMore`, `nextCursor`.
      */
     getHistory(params?: HistoryOptions): Promise<OwneyAgentHistory>;
-    /**
-     * Pause an agent's automated operations. The agent will stop rebalancing until resumed.
-     * @param agentId - The agent to pause (e.g. "zyfai")
-     * @returns OwneyAgentStatus with success flag
-     */
-    pauseAgent(agentId: AgentId): Promise<OwneyAgentStatus>;
-    /**
-     * Resume an agent's automated operations.
-     * @param agentId - The agent to resume (e.g. "zyfai")
-     * @returns OwneyAgentStatus with success flag
-     */
-    resumeAgent(agentId: AgentId): Promise<OwneyAgentStatus>;
     /**
      * Get the user's profile for a specific agent, or all agents.
      * @param agentId - Optional. Agent to query. Omit for all agents.
@@ -388,9 +419,19 @@ declare class OwneySDK {
      * @returns Object with agent names as keys and allocation percentages as values
      */
     getAgentAllocation(): Promise<OwneyAgentAllocation>;
+    /**
+     * Allocation-weighted APY from the current portfolio: each pool's APY
+     * weighted by the user's position value in it. More accurate per-user than
+     * the historical 30D APY. (ROUT-228)
+     * @param options.agentId - Optional. Scope to one agent. Omit to aggregate
+     *   positions across all active agents.
+     */
+    getAllocationApy({ agentId, }?: {
+        agentId?: AgentId;
+    }): 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" | "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" | "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" | "BALANCE_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
 declare class OwneyError extends Error {
     readonly code: OwneyErrorCode;
     readonly details?: Record<string, unknown>;
@@ -433,4 +474,4 @@ type OwneySIWXConfig = {
  */
 declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
 
-export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentHistoryPosition, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, InvalidHistoryCursorError, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAgentStatus, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneySDK, OwneySDKConfig, OwneySIWXConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions, createOwneySIWX };
+export { AccountAgentApy, AccountApyOptions, AgentApy, AgentApyDetails, AgentBalance, AgentChainIncompatibleError, AgentEarnings, AgentHistoryEntry, AgentHistoryPosition, AgentId, AgentNotFoundError, AgentSupportedAsset, AgentSupportedAssets, AgentUserProfile, AgentWithdrawResult, AgentsApyOptions, AllocationAgentApy, ApyByChainAndAsset, Asset, ConnectionState, DailyApyDays, DepositCallback, DepositOptions, HistoryAction, HistoryFilters, HistoryOptions, HistoryTransaction, IAgent, InvalidHistoryCursorError, NotConnectedError, OwneyAccountApy, OwneyAgentAllocation, OwneyAgentApy, OwneyAgentHistory, OwneyAllocationApy, OwneyBalances, OwneyDepositResult, OwneyEarnings, OwneyError, OwneyErrorCode, OwneyMultiDepositResult, OwneyPosition, OwneySDK, OwneySDKConfig, OwneySIWXConfig, OwneySupportedChainId, OwneySupportedChains, OwneySupportedTokens, OwneyToken, OwneyUserProfile, OwneyWithdrawResult, RebalanceLog, WithdrawOptions, createOwneySIWX };