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

package/dist/index.cjs

@@ -159,6 +159,34 @@ function rateLimitDelay(error, now = Date.now()) {
 }
 
 // src/lib/agent-reads.ts
+function rateLimitDiagnostics(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let details = {};
+  function visit(value, depth = 0) {
+    if (depth > 6 || !value || typeof value !== "object" || seen.has(value))
+      return;
+    seen.add(value);
+    const record = value;
+    for (const key2 of [
+      "rpcSource",
+      "chainId",
+      "rpcMethod",
+      "providerRequestId",
+      "statusCode"
+    ]) {
+      const candidate = record[key2];
+      if (candidate !== void 0 && details[key2] === void 0)
+        details = { ...details, [key2]: candidate };
+    }
+    for (const key2 of ["details", "cause", "response", "fields", "error"])
+      visit(record[key2], depth + 1);
+  }
+  visit(error);
+  return {
+    rpcSource: details.rpcSource ?? "agent-api",
+    ...details
+  };
+}
 var AgentReads = class {
   inFlight = /* @__PURE__ */ new Map();
   cooldowns = /* @__PURE__ */ new Map();
@@ -166,14 +194,15 @@ var AgentReads = class {
   clearInFlight() {
     this.inFlight.clear();
   }
-  limited(agentId, until) {
+  limited(agentId, until, diagnostics) {
     return new OwneyError(
       "AGENT_RATE_LIMITED",
       "Too many requests. Please wait before trying again.",
       {
         statusCode: 429,
         retryAt: until,
-        retryAfterSeconds: Math.max(0, Math.ceil((until - Date.now()) / 1e3))
+        retryAfterSeconds: Math.max(0, Math.ceil((until - Date.now()) / 1e3)),
+        ...diagnostics
       },
       agentId
     );
@@ -181,7 +210,9 @@ var AgentReads = class {
   run(agentId, key2, fetch2) {
     const cooldown = this.cooldowns.get(agentId);
     if (cooldown && cooldown.until > Date.now()) {
-      return Promise.reject(this.limited(agentId, cooldown.until));
+      return Promise.reject(
+        this.limited(agentId, cooldown.until, cooldown.diagnostics)
+      );
     }
     const requestKey = JSON.stringify([agentId, key2]);
     const existing = this.inFlight.get(requestKey);
@@ -202,8 +233,9 @@ var AgentReads = class {
           Math.min(3e4 * 2 ** (failures - 1), 3e5)
         );
         const until = Math.max(previous?.until ?? 0, Date.now() + delay);
-        this.cooldowns.set(agentId, { until, failures });
-        throw this.limited(agentId, until);
+        const diagnostics = rateLimitDiagnostics(error);
+        this.cooldowns.set(agentId, { until, failures, diagnostics });
+        throw this.limited(agentId, until, diagnostics);
       }
     ).finally(() => {
       if (this.inFlight.get(requestKey) === promise)
@@ -216,7 +248,7 @@ var AgentReads = class {
 
 // src/agents/zyfai/zyfai.agent.ts
 var import_sdk = require("@zyfai/sdk");
-var import_viem = require("viem");
+var import_viem2 = require("viem");
 var import_chains = require("viem/chains");
 
 // src/types/config.ts
@@ -1097,15 +1129,145 @@ function protocolsPolicyNeedsUpdate(current, desiredProtocols, desiredAutoSelect
   return !protocolListsEqual(current.protocols, desiredProtocols);
 }
 
+// src/lib/paid-rpc.ts
+var import_viem = require("viem");
+var PAID_RPC_RETRY_COUNT = 3;
+var PAID_RPC_RETRY_DELAY_MS = 1e3;
+function configuredRpcProxyBaseUrl(baseUrl) {
+  const configured = (baseUrl ?? "")?.trim();
+  if (!configured) {
+    throw new Error(
+      "OWNEY_ROUTING_API_BASE_URL is required for RPC proxy requests unless routingApiBaseUrl or all rpcUrls are configured."
+    );
+  }
+  return configured;
+}
+function rpcProxyUrl(chainId, apiKey, baseUrl) {
+  const url = new URL(
+    `${configuredRpcProxyBaseUrl(baseUrl).replace(/\/$/, "")}/api/v1/rpc/${chainId}`
+  );
+  if (apiKey) url.searchParams.set("apiKey", apiKey);
+  return url.toString();
+}
+function resolveRpcUrl(rpcUrls, chainId, apiKey = "", baseUrl) {
+  const url = rpcUrls?.[chainId]?.trim();
+  if (url) return url;
+  return rpcProxyUrl(chainId, apiKey, baseUrl);
+}
+function resolveRpcUrls(rpcUrls, apiKey = "", baseUrl) {
+  return {
+    1: resolveRpcUrl(rpcUrls, 1, apiKey, baseUrl),
+    8453: resolveRpcUrl(rpcUrls, 8453, apiKey, baseUrl),
+    42161: resolveRpcUrl(rpcUrls, 42161, apiKey, baseUrl)
+  };
+}
+function createPaidRpcClient(chain, rpcUrls) {
+  const url = resolveRpcUrl(
+    rpcUrls,
+    chain.id
+  );
+  return (0, import_viem.createPublicClient)({
+    chain,
+    transport: (0, import_viem.http)(url, {
+      retryCount: PAID_RPC_RETRY_COUNT,
+      retryDelay: PAID_RPC_RETRY_DELAY_MS
+    })
+  });
+}
+function headerValue(error, name) {
+  const seen = /* @__PURE__ */ new Set();
+  let value;
+  function visit(candidate, depth = 0) {
+    if (value || depth > 6 || !candidate || typeof candidate !== "object")
+      return;
+    if (seen.has(candidate)) return;
+    seen.add(candidate);
+    const record = candidate;
+    const headers = record.headers;
+    let found;
+    if (typeof headers?.get === "function") {
+      found = headers.get(name);
+    } else {
+      const headerRecord = headers;
+      found = headerRecord?.[name] ?? headerRecord?.[name.toLowerCase()];
+    }
+    if (typeof found === "string" && found) {
+      value = found;
+      return;
+    }
+    for (const key2 of ["cause", "details", "response", "error"])
+      visit(record[key2], depth + 1);
+  }
+  visit(error);
+  return value;
+}
+function statusCode(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let status;
+  function visit(candidate, depth = 0) {
+    if (status || depth > 6 || !candidate || typeof candidate !== "object")
+      return;
+    if (seen.has(candidate)) return;
+    seen.add(candidate);
+    const record = candidate;
+    for (const key2 of ["status", "statusCode"]) {
+      const parsed = Number(record[key2]);
+      if (Number.isInteger(parsed) && parsed >= 100 && parsed <= 599) {
+        status = parsed;
+        return;
+      }
+    }
+    for (const key2 of ["cause", "details", "response", "error"])
+      visit(record[key2], depth + 1);
+  }
+  visit(error);
+  return status;
+}
+function paidRpcError(error, chainId, rpcMethod, agentId) {
+  const delay = rateLimitDelay(error);
+  const providerRequestId = headerValue(error, "x-alchemy-request-id") ?? headerValue(error, "x-request-id");
+  if (delay === void 0) {
+    return new OwneyError(
+      "AGENT_API_ERROR",
+      "The blockchain RPC request failed.",
+      {
+        rpcSource: "paid-rpc",
+        chainId,
+        rpcMethod,
+        ...statusCode(error) ? { statusCode: statusCode(error) } : {},
+        ...providerRequestId ? { providerRequestId } : {}
+      },
+      agentId
+    );
+  }
+  const retryAt = Date.now() + delay;
+  return new OwneyError(
+    "AGENT_RATE_LIMITED",
+    "The blockchain RPC is rate limited. Please wait before trying again.",
+    {
+      rpcSource: "paid-rpc",
+      chainId,
+      rpcMethod,
+      statusCode: 429,
+      retryAt,
+      retryAfterSeconds: Math.max(0, Math.ceil(delay / 1e3)),
+      ...providerRequestId ? { providerRequestId } : {}
+    },
+    agentId
+  );
+}
+async function withPaidRpcDiagnostics(operation, chainId, rpcMethod, agentId) {
+  try {
+    return await operation();
+  } catch (error) {
+    throw paidRpcError(error, chainId, rpcMethod, agentId);
+  }
+}
+
 // src/agents/zyfai/zyfai.agent.ts
-var ERC7579_IS_MODULE_INSTALLED_ABI = (0, import_viem.parseAbi)([
+var ERC7579_IS_MODULE_INSTALLED_ABI = (0, import_viem2.parseAbi)([
   "function isModuleInstalled(uint256 moduleTypeId, address module, bytes additionalContext) view returns (bool)"
 ]);
-var DEFAULT_ZYFAI_RPC_URLS = {
-  8453: "https://base-mainnet.g.alchemy.com/v2/ZWyVU-9XfS3z8Rn-xkq7V",
-  42161: "https://arb-mainnet.g.alchemy.com/v2/ZWyVU-9XfS3z8Rn-xkq7V",
-  1: "https://eth-mainnet.g.alchemy.com/v2/ZWyVU-9XfS3z8Rn-xkq7V"
-};
 var WETH_ADDRESS_BY_CHAIN = {
   8453: "0x4200000000000000000000000000000000000006",
   42161: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
@@ -1171,7 +1333,7 @@ var ZyfaiAgent = class _ZyfaiAgent {
   earningsSnapshot = null;
   earningsGeneration = 0;
   constructor(apiKey, rpcUrls, referralSource) {
-    this.rpcUrls = rpcUrls ?? DEFAULT_ZYFAI_RPC_URLS;
+    this.rpcUrls = resolveRpcUrls(rpcUrls);
     this.sdk = new import_sdk.ZyfaiSDK({
       apiKey,
       rpcUrls: this.rpcUrls,
@@ -1185,10 +1347,10 @@ var ZyfaiAgent = class _ZyfaiAgent {
   getPublicClient(chainId) {
     const cached = this.publicClients.get(chainId);
     if (cached) return cached;
-    const client = (0, import_viem.createPublicClient)({
-      chain: VIEM_CHAIN[chainId],
-      transport: (0, import_viem.http)(this.rpcUrls[chainId])
-    });
+    const client = createPaidRpcClient(
+      VIEM_CHAIN[chainId],
+      this.rpcUrls
+    );
     this.publicClients.set(chainId, client);
     return client;
   }
@@ -2156,7 +2318,7 @@ var ZyfaiAgent = class _ZyfaiAgent {
 };
 
 // src/agents/yieldseeker/yieldseeker.agent.ts
-var import_viem6 = require("viem");
+var import_viem7 = require("viem");
 var import_chains3 = require("viem/chains");
 
 // src/lib/chain-guard.ts
@@ -2195,7 +2357,7 @@ async function ensureWalletOnChain(pub, wallet, expected) {
 }
 
 // src/lib/transfer-auth.ts
-var import_viem2 = require("viem");
+var import_viem3 = require("viem");
 
 // src/lib/sponsor-client.ts
 var ROUTING_API_BASE_URL = "https://owney-routing-api-243946518160.europe-west4.run.app";
@@ -2311,13 +2473,14 @@ async function postSponsorBatchTransfer(input) {
 }
 
 // src/lib/permit2.ts
-var import_viem3 = require("viem");
+var import_viem4 = require("viem");
 var PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+var MAX_UINT256 = 2n ** 256n - 1n;
 function permit2ApprovalAmount(requiredAmount) {
   if (requiredAmount <= 0n) {
     throw new Error("Permit2 approval requires a positive deposit amount");
   }
-  return requiredAmount;
+  return MAX_UINT256;
 }
 var ERC20_ALLOWANCE_ABI = [
   {
@@ -2351,14 +2514,15 @@ var ERC20_ALLOWANCE_ABI = [
 function randomPermit2Nonce() {
   const bytes = new Uint8Array(32);
   globalThis.crypto.getRandomValues(bytes);
-  return BigInt((0, import_viem3.bytesToHex)(bytes));
+  return BigInt((0, import_viem4.bytesToHex)(bytes));
 }
-async function readPermit2Allowance(publicClient, token, owner) {
+async function readPermit2Allowance(publicClient, token, owner, blockNumber) {
   return publicClient.readContract({
     address: token,
     abi: ERC20_ALLOWANCE_ABI,
     functionName: "allowance",
-    args: [owner, PERMIT2_ADDRESS]
+    args: [owner, PERMIT2_ADDRESS],
+    ...blockNumber === void 0 ? {} : { blockNumber }
   });
 }
 async function readErc20Balance(publicClient, token, owner) {
@@ -2393,7 +2557,7 @@ function makeVerificationAwareDepositCallback(implementation) {
 
 // src/agents/yieldseeker/yieldseeker.auth.ts
 var import_siwe = require("siwe");
-var import_viem4 = require("viem");
+var import_viem5 = require("viem");
 var import_chains2 = require("viem/chains");
 
 // src/agents/yieldseeker/yieldseeker.auth-cache.ts
@@ -2506,7 +2670,7 @@ function createYieldseekerSiweMessage(address, chainId, dependencies = {}) {
   return new import_siwe.SiweMessage({
     scheme: url.protocol.slice(0, -1),
     domain: url.host,
-    address: (0, import_viem4.getAddress)(address),
+    address: (0, import_viem5.getAddress)(address),
     uri: url.origin,
     version: "1",
     chainId,
@@ -2592,15 +2756,15 @@ var YieldseekerAuth = class {
     clearYieldseekerSession(state.walletAddress, chainId);
   }
   async sign(state, chainId) {
-    const account = (0, import_viem4.getAddress)(state.walletAddress);
-    const publicClient = (0, import_viem4.createPublicClient)({
+    const account = (0, import_viem5.getAddress)(state.walletAddress);
+    const publicClient = (0, import_viem5.createPublicClient)({
       chain: import_chains2.base,
-      transport: (0, import_viem4.custom)(state.provider)
+      transport: (0, import_viem5.custom)(state.provider)
     });
-    const walletClient = (0, import_viem4.createWalletClient)({
+    const walletClient = (0, import_viem5.createWalletClient)({
       account,
       chain: import_chains2.base,
-      transport: (0, import_viem4.custom)(state.provider)
+      transport: (0, import_viem5.custom)(state.provider)
     });
     await ensureWalletOnChain(
       publicClient,
@@ -2741,10 +2905,11 @@ var YieldseekerApiClient = class {
       const payload = await response.json().catch(() => null);
       if (!response.ok) {
         const error = providerError(payload, `HTTP_${response.status}`);
+        const retryAfter = response.headers.get("Retry-After");
         throw new YieldseekerApiError(
           response.status,
           error.code,
-          error.fields
+          retryAfter ? { ...error.fields, headers: { "Retry-After": retryAfter } } : error.fields
         );
       }
       if (payload && typeof payload === "object" && payload.success === true && "data" in payload) {
@@ -2766,7 +2931,7 @@ var YieldseekerApiClient = class {
 };
 
 // src/agents/yieldseeker/yieldseeker.mapper.ts
-var import_viem5 = require("viem");
+var import_viem6 = require("viem");
 
 // src/lib/helpers/snapshot-apy.ts
 var DAY_MS = 864e5;
@@ -2833,10 +2998,10 @@ function raw(value, endpoint) {
   return BigInt(value);
 }
 function decimal(value, decimals, endpoint) {
-  return (0, import_viem5.formatUnits)(raw(value, endpoint), decimals);
+  return (0, import_viem6.formatUnits)(raw(value, endpoint), decimals);
 }
 function usd(rawAmount, decimals, price) {
-  return Number((0, import_viem5.formatUnits)(rawAmount, decimals)) * price;
+  return Number((0, import_viem6.formatUnits)(rawAmount, decimals)) * price;
 }
 function percent(value) {
   const result = Number(value);
@@ -2862,7 +3027,7 @@ function assetAddressValue(record, address) {
 }
 function position(value, asset, baseAssetDecimals) {
   const option = value?.yieldOption;
-  if (!option || typeof option.provider !== "string" || typeof option.name !== "string" || typeof option.address !== "string" || !(0, import_viem5.isAddress)(option.address)) {
+  if (!option || typeof option.provider !== "string" || typeof option.name !== "string" || typeof option.address !== "string" || !(0, import_viem6.isAddress)(option.address)) {
     return invalid("yield positions", "missing vault metadata");
   }
   return {
@@ -2875,13 +3040,14 @@ function position(value, asset, baseAssetDecimals) {
     // differ from the underlying asset. Yieldseeker already converts it to
     // underlying base-asset units in `assetsBase`; pair that value with the
     // snapshot's corresponding `baseAssetDecimals` for display. Keep the raw
-    // share quantity separately because withdraw-from-position expects it.
+    // share quantity separate from the withdrawable underlying asset amount.
     amount: decimal(
       value.assetsBase,
       baseAssetDecimals,
       "yield positions"
     ),
     amountRaw: String(value.assetsRaw),
+    withdrawableAmountRaw: String(value.withdrawableAssetsRaw),
     apy: percent(option.riskAdjustedApy),
     tvl: Number(option.totalDepositsUsd),
     liquidity: Number(option.withdrawableDepositsUsd)
@@ -2943,7 +3109,7 @@ function mapYieldseekerEarnings(contexts) {
       chain: "BASE",
       chainId: 8453,
       asset: context.asset,
-      amount: (0, import_viem5.formatUnits)(amount, context.snapshot.baseAssetDecimals)
+      amount: (0, import_viem6.formatUnits)(amount, context.snapshot.baseAssetDecimals)
     });
     lifetimeEarnings += usd(
       amount,
@@ -3206,10 +3372,18 @@ function mapYieldseekerAgentApy(options, days) {
 
 // src/agents/yieldseeker/yieldseeker.agent.ts
 var OWNEY_AGENT_NAME = "owney";
+var OWNEY_AGENT_RULE_PRESET = "explorative";
 var YIELDSEEKER_USERNAME_PREFIX = "owney_";
 var YIELDSEEKER_USERNAME_RANDOM_LENGTH = 14;
 var YIELDSEEKER_USERNAME_CREATE_ATTEMPTS = 3;
 var YIELDSEEKER_YIELD_OPTIONS_CACHE_MS = 6e4;
+var YIELDSEEKER_AGENT_LIST_CACHE_MS = 12e4;
+var YIELDSEEKER_PORTFOLIO_CACHE_MS = 12e4;
+var YIELDSEEKER_SETTLEMENT_CACHE_MS = 5e3;
+var YIELDSEEKER_SETTLEMENT_ACTIVITY_CACHE_MS = 15e3;
+var YIELDSEEKER_READ_FAILURE_COOLDOWN_MS = 6e4;
+var YIELDSEEKER_SETTLEMENT_WINDOW_MS = 5 * 6e4;
+var YIELDSEEKER_ACTIVITY_CACHE_MS = 6e4;
 function generateYieldseekerUsername() {
   const suffix = globalThis.crypto.randomUUID().replaceAll("-", "").slice(0, YIELDSEEKER_USERNAME_RANDOM_LENGTH).toLowerCase();
   return `${YIELDSEEKER_USERNAME_PREFIX}${suffix}`;
@@ -3253,6 +3427,7 @@ function query(params) {
 var YieldseekerAgent = class {
   id = "yieldseeker";
   balanceComposition = "tokens-plus-positions";
+  withdrawalRequiresWalletApproval = true;
   supportedChainIds = [8453];
   supportedAssets = [
     {
@@ -3266,11 +3441,26 @@ var YieldseekerAgent = class {
   ];
   api;
   auth;
+  rpcUrls;
+  receiptClient;
   transactionExecutor;
   unwindReceiptWaiter;
   agentContexts = /* @__PURE__ */ new Map();
   users = /* @__PURE__ */ new Map();
   pendingAgents = /* @__PURE__ */ new Map();
+  pendingWalletContexts = /* @__PURE__ */ new Map();
+  readCache = /* @__PURE__ */ new Map();
+  pendingReads = /* @__PURE__ */ new Map();
+  readGeneration = 0;
+  portfolioVersions = /* @__PURE__ */ new Map();
+  snapshotFailures = /* @__PURE__ */ new Map();
+  standardReadFailures = /* @__PURE__ */ new Map();
+  reconcileUntil = /* @__PURE__ */ new Map();
+  activityRefreshUntil = /* @__PURE__ */ new Map();
+  // null means a confirmed movement has no reliable baseline. Do not guess
+  // settlement; keep slow reconciliation after the fast window expires.
+  snapshotMovements = /* @__PURE__ */ new Map();
+  movementEpochs = /* @__PURE__ */ new Map();
   yieldOptions = /* @__PURE__ */ new Map();
   pendingYieldOptions = /* @__PURE__ */ new Map();
   constructor(owneyApiKey, options = {}) {
@@ -3280,10 +3470,16 @@ var YieldseekerAgent = class {
       options.fetchFn
     );
     this.auth = new YieldseekerAuth(options.auth);
+    this.rpcUrls = options.rpcUrls;
     this.transactionExecutor = options.transactionExecutor;
     this.unwindReceiptWaiter = options.unwindReceiptWaiter;
   }
+  getReceiptClient() {
+    this.receiptClient ??= createPaidRpcClient(import_chains3.base, this.rpcUrls);
+    return this.receiptClient;
+  }
   async disconnect() {
+    this.readGeneration += 1;
     this.auth.clear();
     for (const key2 of this.users.keys()) {
       const [walletAddress, chainId] = key2.split(":");
@@ -3292,6 +3488,16 @@ var YieldseekerAgent = class {
     this.users.clear();
     this.agentContexts.clear();
     this.pendingAgents.clear();
+    this.pendingWalletContexts.clear();
+    this.readCache.clear();
+    this.pendingReads.clear();
+    this.portfolioVersions.clear();
+    this.snapshotFailures.clear();
+    this.standardReadFailures.clear();
+    this.reconcileUntil.clear();
+    this.activityRefreshUntil.clear();
+    this.snapshotMovements.clear();
+    this.movementEpochs.clear();
   }
   async activateAgent(state, chainId, asset) {
     this.assertChain(chainId);
@@ -3311,41 +3517,37 @@ var YieldseekerAgent = class {
       );
     }
     const context = await this.ensureAgent(state, chainId, asset);
+    const generation = this.readGeneration;
+    const movement = this.snapshotMovement(state, chainId, context, BigInt(amount));
     let txHash;
-    try {
-      if (depositCallback) {
-        provideDepositVerificationContext(depositCallback, {
-          agentId: "yieldseeker",
-          signature: await this.auth.getToken(state, chainId),
-          userId: context.user.userId,
-          yieldseekerAgentId: context.agent.agentId
-        });
-        txHash = await depositCallback(
-          context.wallet.walletAddress,
-          chainId,
-          amount
-        );
-        await this.waitForReceipt(state, chainId, txHash);
-      } else {
-        txHash = await this.submitTransaction(state, chainId, {
-          from: (0, import_viem6.getAddress)(state.walletAddress),
-          to: YIELDSEEKER_ASSET_METADATA[asset].address,
-          data: (0, import_viem6.encodeFunctionData)({
-            abi: import_viem6.erc20Abi,
-            functionName: "transfer",
-            args: [(0, import_viem6.getAddress)(context.wallet.walletAddress), BigInt(amount)]
-          }),
-          value: "0",
-          chainId
-        });
-      }
-    } finally {
-      await this.refreshSnapshotAfterMovement(
-        state,
+    if (depositCallback) {
+      provideDepositVerificationContext(depositCallback, {
+        agentId: "yieldseeker",
+        signature: await this.auth.getToken(state, chainId),
+        userId: context.user.userId,
+        yieldseekerAgentId: context.agent.agentId
+      });
+      txHash = await depositCallback(
+        context.wallet.walletAddress,
         chainId,
-        context,
-        "deposit"
+        amount
       );
+      await this.waitForReceipt(state, chainId, txHash);
+    } else {
+      txHash = await this.submitTransaction(state, chainId, {
+        from: (0, import_viem7.getAddress)(state.walletAddress),
+        to: YIELDSEEKER_ASSET_METADATA[asset].address,
+        data: (0, import_viem7.encodeFunctionData)({
+          abi: import_viem7.erc20Abi,
+          functionName: "transfer",
+          args: [(0, import_viem7.getAddress)(context.wallet.walletAddress), BigInt(amount)]
+        }),
+        value: "0",
+        chainId
+      });
+    }
+    if (this.readGeneration === generation) {
+      void this.refreshSnapshotAfterMovement(state, chainId, context, "deposit", movement);
     }
     return {
       txHash,
@@ -3373,6 +3575,9 @@ var YieldseekerAgent = class {
         this.id
       );
     }
+    const generation = this.readGeneration;
+    let confirmedMovement = false;
+    let settlement = null;
     try {
       const portfolio = await this.loadPortfolioContext(
         state,
@@ -3390,6 +3595,7 @@ var YieldseekerAgent = class {
       );
       const totalAvailable = idle + deployed;
       const requested = amount === void 0 ? totalAvailable : BigInt(amount);
+      const plannedMovement = this.snapshotMovement(state, chainId, context, -requested);
       if (requested > totalAvailable) {
         throw new OwneyError(
           "WITHDRAW_INSUFFICIENT_BALANCE",
@@ -3425,6 +3631,7 @@ var YieldseekerAgent = class {
           throw this.invalidResponse("position withdrawal");
         }
         await this.waitForReceipt(state, chainId, response.transactionHash);
+        confirmedMovement = true;
         remaining -= assetsRaw;
       }
       if (remaining > 0n) {
@@ -3433,15 +3640,15 @@ var YieldseekerAgent = class {
           remaining: remaining.toString()
         });
       }
-      const account = (0, import_viem6.getAddress)(state.walletAddress);
+      const account = (0, import_viem7.getAddress)(state.walletAddress);
       const txHash = await this.submitTransaction(state, chainId, {
         from: account,
-        to: (0, import_viem6.getAddress)(context.wallet.walletAddress),
-        data: amount === void 0 ? (0, import_viem6.encodeFunctionData)({
+        to: (0, import_viem7.getAddress)(context.wallet.walletAddress),
+        data: amount === void 0 ? (0, import_viem7.encodeFunctionData)({
           abi: YIELDSEEKER_AGENT_WALLET_ABI,
           functionName: "withdrawAllAssetToUser",
           args: [account, metadata.address]
-        }) : (0, import_viem6.encodeFunctionData)({
+        }) : (0, import_viem7.encodeFunctionData)({
           abi: YIELDSEEKER_AGENT_WALLET_ABI,
           functionName: "withdrawAssetToUser",
           args: [account, metadata.address, requested]
@@ -3449,18 +3656,23 @@ var YieldseekerAgent = class {
         value: "0",
         chainId
       });
+      confirmedMovement = true;
+      settlement = plannedMovement;
       return {
         txHash,
         type: amount === void 0 ? "full" : "partial",
         amount: requested.toString()
       };
     } finally {
-      await this.refreshSnapshotAfterMovement(
-        state,
-        chainId,
-        context,
-        "withdrawal"
-      );
+      if (confirmedMovement && this.readGeneration === generation) {
+        void this.refreshSnapshotAfterMovement(
+          state,
+          chainId,
+          context,
+          "withdrawal",
+          settlement
+        );
+      }
     }
   }
   async getBalances(state, chainId) {
@@ -3485,7 +3697,7 @@ var YieldseekerAgent = class {
     this.assertChain(chainId);
     const asset = options?.tokenSymbol?.toUpperCase();
     if (asset !== void 0) this.assertAsset(asset);
-    const contexts = await this.loadPortfolio(state, chainId, {
+    const contexts = await this.loadActivityPortfolio(state, chainId, {
       ...asset ? { asset } : {},
       historic: true,
       actions: true
@@ -3497,7 +3709,7 @@ var YieldseekerAgent = class {
     );
     const vaultAddresses = new Set(
       catalog.flat().filter(
-        (yieldOption) => yieldOption.chainId === chainId && (0, import_viem6.isAddress)(yieldOption.address)
+        (yieldOption) => yieldOption.chainId === chainId && (0, import_viem7.isAddress)(yieldOption.address)
       ).map((yieldOption) => yieldOption.address.toLowerCase())
     );
     return mapYieldseekerHistory(contexts, {
@@ -3512,7 +3724,7 @@ var YieldseekerAgent = class {
     this.assertChain(chainId);
     return mapYieldseekerProfile(
       state.walletAddress,
-      await this.loadPortfolio(state, chainId, {})
+      await this.loadActivityPortfolio(state, chainId, {})
     );
   }
   async getAgentApy(days, options) {
@@ -3554,6 +3766,95 @@ var YieldseekerAgent = class {
   contextKey(state, chainId, asset) {
     return `${this.userKey(state, chainId)}:${asset}`;
   }
+  assertSession(generation, chainId, asset) {
+    if (this.readGeneration !== generation) {
+      throw new OwneyError(
+        "NOT_CONNECTED",
+        "Wallet session changed during the Yieldseeker request.",
+        { rpcSource: "agent-api", chainId, ...asset ? { asset } : {} },
+        this.id
+      );
+    }
+  }
+  cachedRead(key2, ttlMs, read2) {
+    const cached = this.readCache.get(key2);
+    if (cached && cached.expiresAt > Date.now()) {
+      return Promise.resolve(cached.value);
+    }
+    const pending = this.pendingReads.get(key2);
+    if (pending) return pending;
+    const generation = this.readGeneration;
+    const request = Promise.resolve().then(read2).then((value) => {
+      if (this.readGeneration === generation && this.pendingReads.get(key2) === request) {
+        this.readCache.set(key2, {
+          expiresAt: Date.now() + ttlMs,
+          value
+        });
+      }
+      return value;
+    }).finally(() => {
+      if (this.pendingReads.get(key2) === request) {
+        this.pendingReads.delete(key2);
+      }
+    });
+    this.pendingReads.set(key2, request);
+    return request;
+  }
+  agentListKey(state, chainId) {
+    return `agents:${this.userKey(state, chainId)}`;
+  }
+  async listAgents(state, chainId, user) {
+    const response = await this.cachedRead(
+      this.agentListKey(state, chainId),
+      YIELDSEEKER_AGENT_LIST_CACHE_MS,
+      async () => {
+        const response2 = await this.walletRequest(
+          state,
+          chainId,
+          `/users/${user.userId}/agents`
+        );
+        if (!Array.isArray(response2?.agents)) {
+          throw this.invalidResponse("agent list");
+        }
+        return response2;
+      }
+    );
+    return response.agents;
+  }
+  async contextForAgent(state, chainId, user, agent, asset) {
+    const key2 = this.contextKey(state, chainId, asset);
+    const cached = this.agentContexts.get(key2);
+    if (cached?.agent.agentId === agent.agentId) return cached;
+    const pending = this.pendingWalletContexts.get(key2);
+    if (pending) return pending;
+    const generation = this.readGeneration;
+    const request = this.walletRequest(
+      state,
+      chainId,
+      `/users/${user.userId}/agents/${agent.agentId}/wallet`
+    ).then((walletResponse) => {
+      this.assertSession(generation, chainId, asset);
+      if (!walletResponse?.agentWallet || !(0, import_viem7.isAddress)(walletResponse.agentWallet.walletAddress)) {
+        throw this.invalidResponse("agent wallet");
+      }
+      const context = {
+        user,
+        agent,
+        wallet: walletResponse.agentWallet,
+        asset
+      };
+      this.agentContexts.set(key2, context);
+      return context;
+    });
+    this.pendingWalletContexts.set(key2, request);
+    try {
+      return await request;
+    } finally {
+      if (this.pendingWalletContexts.get(key2) === request) {
+        this.pendingWalletContexts.delete(key2);
+      }
+    }
+  }
   async resolveUser(state, chainId) {
     const key2 = this.userKey(state, chainId);
     const inMemory = this.users.get(key2);
@@ -3563,7 +3864,8 @@ var YieldseekerAgent = class {
       this.users.set(key2, persisted);
       return persisted;
     }
-    const walletAddress = (0, import_viem6.getAddress)(state.walletAddress);
+    const walletAddress = (0, import_viem7.getAddress)(state.walletAddress);
+    const generation = this.readGeneration;
     let user = null;
     try {
       const login = await this.providerRequest(
@@ -3610,6 +3912,7 @@ var YieldseekerAgent = class {
     if (!user || !/^[a-zA-Z0-9_-]{1,128}$/.test(user.userId)) {
       throw this.invalidResponse("wallet identity");
     }
+    this.assertSession(generation, chainId);
     const resolved = { userId: user.userId };
     this.users.set(key2, resolved);
     writeYieldseekerIdentity(state.walletAddress, chainId, resolved.userId);
@@ -3625,10 +3928,13 @@ var YieldseekerAgent = class {
     if (cached) return cached;
     const pending = this.pendingAgents.get(key2);
     if (pending) return pending;
+    const generation = this.readGeneration;
     const request = this.resolveAgent(state, chainId, asset, true).then(
       async (context) => {
+        this.assertSession(generation, chainId, asset);
         if (!context) throw this.invalidResponse("agent creation");
         await this.deployAgent(state, chainId, context);
+        this.assertSession(generation, chainId, asset);
         this.agentContexts.set(key2, context);
         return context;
       }
@@ -3637,29 +3943,27 @@ var YieldseekerAgent = class {
     try {
       return await request;
     } finally {
-      this.pendingAgents.delete(key2);
+      if (this.pendingAgents.get(key2) === request) this.pendingAgents.delete(key2);
     }
   }
   async findAgent(state, chainId, asset) {
     const key2 = this.contextKey(state, chainId, asset);
     const cached = this.agentContexts.get(key2);
     if (cached) return cached;
+    const generation = this.readGeneration;
     const context = await this.resolveAgent(state, chainId, asset, false);
+    this.assertSession(generation, chainId, asset);
     if (context) this.agentContexts.set(key2, context);
     return context;
   }
   async resolveAgent(state, chainId, asset, createIfMissing) {
+    const generation = this.readGeneration;
     const user = await this.resolveUser(state, chainId);
-    const response = await this.walletRequest(
-      state,
-      chainId,
-      `/users/${user.userId}/agents`
-    );
-    if (!Array.isArray(response?.agents)) {
-      throw this.invalidResponse("agent list");
-    }
+    this.assertSession(generation, chainId, asset);
+    const agents = await this.listAgents(state, chainId, user);
+    this.assertSession(generation, chainId, asset);
     const metadata = YIELDSEEKER_ASSET_METADATA[asset];
-    let agent = response.agents.find(
+    let agent = agents.find(
       (candidate) => this.isOwneyAgent(candidate) && candidate.chainId === chainId && candidate.type === "vault" && candidate.assetAddress.toLowerCase() === metadata.address.toLowerCase()
     );
     if (!agent && createIfMissing) {
@@ -3675,99 +3979,254 @@ var YieldseekerAgent = class {
             chainId,
             assetAddress: metadata.address,
             type: "vault",
-            rulePreset: null
+            rulePreset: OWNEY_AGENT_RULE_PRESET
           }
         }
       );
+      this.assertSession(generation, chainId, asset);
       agent = created?.agent;
+      if (agent) {
+        this.readCache.set(this.agentListKey(state, chainId), {
+          expiresAt: Date.now() + YIELDSEEKER_AGENT_LIST_CACHE_MS,
+          value: {
+            agents: [...agents, agent]
+          }
+        });
+      }
     }
     if (!agent) return null;
     this.assertAgent(agent);
-    const walletResponse = await this.walletRequest(
-      state,
-      chainId,
-      `/users/${user.userId}/agents/${agent.agentId}/wallet`
-    );
-    if (!walletResponse?.agentWallet || !(0, import_viem6.isAddress)(walletResponse.agentWallet.walletAddress)) {
-      throw this.invalidResponse("agent wallet");
-    }
-    return { user, agent, wallet: walletResponse.agentWallet, asset };
+    return this.contextForAgent(state, chainId, user, agent, asset);
   }
   async loadPortfolio(state, chainId, options) {
-    const user = await this.resolveUser(state, chainId);
-    const response = await this.walletRequest(
-      state,
-      chainId,
-      `/users/${user.userId}/agents`
+    const contexts = await this.resolvePortfolioContexts(state, chainId, options.asset);
+    return Promise.all(
+      contexts.map(
+        (context) => this.loadPortfolioContext(state, chainId, context, options)
+      )
     );
-    if (!Array.isArray(response?.agents)) {
-      throw this.invalidResponse("agent list");
-    }
+  }
+  async loadActivityPortfolio(state, chainId, options) {
+    const contexts = await this.resolvePortfolioContexts(state, chainId, options.asset);
+    return Promise.all(
+      contexts.map(
+        (context) => this.loadActivityContext(state, chainId, context, options)
+      )
+    );
+  }
+  async resolvePortfolioContexts(state, chainId, assetFilter) {
+    const generation = this.readGeneration;
+    const user = await this.resolveUser(state, chainId);
+    this.assertSession(generation, chainId);
+    const agents = await this.listAgents(state, chainId, user);
+    this.assertSession(generation, chainId);
     const contexts = [];
-    for (const agent of response.agents) {
+    for (const agent of agents) {
       const asset = this.assetForAgent(agent);
-      if (!this.isOwneyAgent(agent) || !asset || agent.chainId !== chainId || agent.type !== "vault" || options.asset && options.asset !== asset) {
+      if (!this.isOwneyAgent(agent) || !asset || agent.chainId !== chainId || agent.type !== "vault" || assetFilter && assetFilter !== asset) {
         continue;
       }
       this.assertAgent(agent);
-      const walletResponse = await this.walletRequest(
-        state,
-        chainId,
-        `/users/${user.userId}/agents/${agent.agentId}/wallet`
-      );
-      if (!walletResponse?.agentWallet || !(0, import_viem6.isAddress)(walletResponse.agentWallet.walletAddress)) {
-        throw this.invalidResponse("agent wallet");
-      }
-      const context = {
-        user,
-        agent,
-        wallet: walletResponse.agentWallet,
-        asset
+      contexts.push(this.contextForAgent(state, chainId, user, agent, asset));
+    }
+    const resolvedContexts = await Promise.all(contexts);
+    this.assertSession(generation, chainId);
+    return resolvedContexts;
+  }
+  portfolioVersion(contextKey) {
+    return this.portfolioVersions.get(contextKey) ?? 0;
+  }
+  portfolioCacheMs(contextKey) {
+    return (this.reconcileUntil.get(contextKey) ?? 0) > Date.now() ? YIELDSEEKER_SETTLEMENT_CACHE_MS : YIELDSEEKER_PORTFOLIO_CACHE_MS;
+  }
+  snapshotMovement(state, chainId, context, delta) {
+    const key2 = this.contextKey(state, chainId, context.asset);
+    const previous = this.snapshotMovements.get(key2);
+    if (this.snapshotMovements.has(key2)) {
+      if (!previous || previous.delta > 0n !== delta > 0n) return null;
+      return {
+        ...previous,
+        epoch: this.movementEpochs.get(key2) ?? 0,
+        delta: previous.delta + delta,
+        expectedBalance: previous.expectedBalance + delta,
+        expectedNetDeposits: previous.expectedNetDeposits + delta
       };
-      this.agentContexts.set(this.contextKey(state, chainId, asset), context);
-      contexts.push(context);
     }
-    return Promise.all(
-      contexts.map(
-        (context) => this.loadPortfolioContext(state, chainId, context, options)
-      )
-    );
+    const cached = this.readCache.get(`snapshot:${key2}`);
+    if (!cached || cached.expiresAt <= Date.now()) return null;
+    const snapshot = cached.value.agentSnapshot;
+    if (snapshot.baseAssetDecimals !== YIELDSEEKER_ASSET_METADATA[context.asset].decimals) return null;
+    if (!/^-?\d+$/.test(snapshot.netDepositsBase) || !/^\d+$/.test(snapshot.totalValueBase)) return null;
+    return {
+      epoch: this.movementEpochs.get(key2) ?? 0,
+      delta,
+      decimals: snapshot.baseAssetDecimals,
+      expectedBalance: BigInt(snapshot.totalValueBase) + delta,
+      expectedNetDeposits: BigInt(snapshot.netDepositsBase) + delta
+    };
+  }
+  advancePortfolioVersion(contextKey) {
+    const version = this.portfolioVersion(contextKey) + 1;
+    this.portfolioVersions.set(contextKey, version);
+    this.snapshotFailures.delete(contextKey);
+    for (const kind of ["snapshot", "positions", "historic", "actions"]) {
+      const key2 = `${kind}:${contextKey}`;
+      this.readCache.delete(key2);
+      this.pendingReads.delete(key2);
+    }
+    return version;
+  }
+  requestPortfolioSnapshot(state, chainId, context, contextKey, version, generation, forceRefresh = false) {
+    return this.walletRequest(
+      state,
+      chainId,
+      `${this.agentPath(context, "snapshot")}${query(forceRefresh ? { shouldForceRefresh: true } : { shouldOnlyUseRecentValue: true, shouldAllowStaleOnError: true })}`
+    ).then((response) => {
+      if (!response?.agentSnapshot) {
+        throw this.invalidResponse("agent snapshot");
+      }
+      if (this.readGeneration === generation && this.portfolioVersion(contextKey) === version) {
+        this.snapshotFailures.delete(contextKey);
+        const movement = this.snapshotMovements.get(contextKey);
+        const snapshot = response.agentSnapshot;
+        if (movement && snapshot.baseAssetDecimals === movement.decimals && /^-?\d+$/.test(snapshot.netDepositsBase) && /^\d+$/.test(snapshot.totalValueBase)) {
+          const balance = BigInt(snapshot.totalValueBase);
+          const netDeposits = BigInt(snapshot.netDepositsBase);
+          const reconciled = movement.delta > 0n ? balance >= movement.expectedBalance && netDeposits >= movement.expectedNetDeposits : balance <= movement.expectedBalance && netDeposits <= movement.expectedNetDeposits;
+          if (reconciled) {
+            this.snapshotMovements.delete(contextKey);
+            this.reconcileUntil.delete(contextKey);
+          }
+        }
+      }
+      return response;
+    }).catch((error) => {
+      if (this.readGeneration === generation && this.portfolioVersion(contextKey) === version) {
+        this.snapshotFailures.set(contextKey, {
+          retryAt: Date.now() + Math.max(YIELDSEEKER_READ_FAILURE_COOLDOWN_MS, rateLimitDelay(error) ?? 0),
+          error
+        });
+      }
+      throw error;
+    });
+  }
+  portfolioSnapshot(state, chainId, context, contextKey) {
+    const key2 = `snapshot:${contextKey}`;
+    const cached = this.readCache.get(key2);
+    if ((!cached || cached.expiresAt <= Date.now()) && !this.pendingReads.has(key2)) {
+      const failure = this.snapshotFailures.get(contextKey);
+      if (failure && failure.retryAt > Date.now()) throw failure.error;
+      this.advancePortfolioVersion(contextKey);
+    }
+    const version = this.portfolioVersion(contextKey);
+    const generation = this.readGeneration;
+    return {
+      version,
+      read: this.cachedRead(key2, this.portfolioCacheMs(contextKey), () => (
+        // Force only during the bounded post-transaction window. Keep unknown
+        // or unreconciled movements for verification, but do not let them turn
+        // routine polling into forced refreshes indefinitely.
+        this.requestPortfolioSnapshot(
+          state,
+          chainId,
+          context,
+          contextKey,
+          version,
+          generation,
+          this.snapshotMovements.has(contextKey) && (this.reconcileUntil.get(contextKey) ?? 0) > Date.now()
+        )
+      ))
+    };
   }
   async loadPortfolioContext(state, chainId, context, options = {}) {
-    const [snapshot, positions, historic, actions] = await Promise.all([
-      this.walletRequest(
-        state,
-        chainId,
-        `${this.agentPath(context, "snapshot")}${query({
-          shouldOnlyUseRecentValue: true,
-          shouldAllowStaleOnError: true
-        })}`
-      ),
-      this.walletRequest(
-        state,
-        chainId,
-        this.agentPath(context, "yield-positions")
+    const contextKey = this.contextKey(state, chainId, context.asset);
+    const generation = this.readGeneration;
+    const assertSession = () => this.assertSession(generation, chainId, context.asset);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const { version, read: read2 } = this.portfolioSnapshot(state, chainId, context, contextKey);
+      const parts = this.loadPortfolioParts(state, chainId, context, options, contextKey);
+      try {
+        const [snapshot, portfolioParts] = await Promise.all([read2, parts]);
+        assertSession();
+        if (this.portfolioVersion(contextKey) !== version) continue;
+        return {
+          ...context,
+          snapshot: snapshot.agentSnapshot,
+          ...portfolioParts
+        };
+      } catch (error) {
+        assertSession();
+        if (this.portfolioVersion(contextKey) !== version) continue;
+        throw error;
+      }
+    }
+    throw new OwneyError(
+      "AGENT_API_ERROR",
+      "Yieldseeker portfolio changed during the read. Please retry.",
+      { rpcSource: "agent-api", chainId, asset: context.asset },
+      this.id
+    );
+  }
+  async loadActivityContext(state, chainId, context, options) {
+    const contextKey = this.contextKey(state, chainId, context.asset);
+    const generation = this.readGeneration;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const version = this.portfolioVersion(contextKey);
+      try {
+        const parts = await this.loadPortfolioParts(state, chainId, context, options, contextKey);
+        this.assertSession(generation, chainId, context.asset);
+        if (this.portfolioVersion(contextKey) !== version) continue;
+        return { ...context, ...parts };
+      } catch (error) {
+        this.assertSession(generation, chainId, context.asset);
+        if (this.portfolioVersion(contextKey) !== version) continue;
+        throw error;
+      }
+    }
+    throw new OwneyError(
+      "AGENT_API_ERROR",
+      "Yieldseeker activity changed during the read. Please retry.",
+      { rpcSource: "agent-api", chainId, asset: context.asset },
+      this.id
+    );
+  }
+  async loadPortfolioParts(state, chainId, context, options, contextKey) {
+    const [positions, historic, actions] = await Promise.all([
+      this.cachedRead(
+        `positions:${contextKey}`,
+        this.portfolioCacheMs(contextKey),
+        async () => {
+          const response = await this.walletRequest(
+            state,
+            chainId,
+            this.agentPath(context, "yield-positions")
+          );
+          if (!Array.isArray(response?.yieldPositions)) {
+            throw this.invalidResponse("yield positions");
+          }
+          return response;
+        }
       ),
-      options.historic ? this.walletRequest(
-        state,
-        chainId,
-        this.agentPath(context, "wallet/historic-position")
+      options.historic ? this.cachedRead(
+        `historic:${contextKey}`,
+        (this.activityRefreshUntil.get(contextKey) ?? 0) > Date.now() ? YIELDSEEKER_SETTLEMENT_ACTIVITY_CACHE_MS : YIELDSEEKER_ACTIVITY_CACHE_MS,
+        () => this.walletRequest(
+          state,
+          chainId,
+          this.agentPath(context, "wallet/historic-position")
+        )
       ) : Promise.resolve(void 0),
-      options.actions ? this.walletRequest(
-        state,
-        chainId,
-        this.agentPath(context, "actions")
+      options.actions ? this.cachedRead(
+        `actions:${contextKey}`,
+        (this.activityRefreshUntil.get(contextKey) ?? 0) > Date.now() ? YIELDSEEKER_SETTLEMENT_ACTIVITY_CACHE_MS : YIELDSEEKER_ACTIVITY_CACHE_MS,
+        () => this.walletRequest(
+          state,
+          chainId,
+          this.agentPath(context, "actions")
+        )
       ) : Promise.resolve(void 0)
     ]);
-    if (!snapshot?.agentSnapshot) {
-      throw this.invalidResponse("agent snapshot");
-    }
-    if (!Array.isArray(positions?.yieldPositions)) {
-      throw this.invalidResponse("yield positions");
-    }
     return {
-      ...context,
-      snapshot: snapshot.agentSnapshot,
       positions: positions.yieldPositions,
       ...historic?.position ? { historic: historic.position } : {},
       ...actions?.actions ? { actions: actions.actions } : {}
@@ -3782,25 +4241,28 @@ var YieldseekerAgent = class {
       this.agentPath(context, "deploy"),
       { method: "POST", body: {} }
     );
-    if (!deployed?.agentWallet || !(0, import_viem6.isAddress)(deployed.agentWallet.walletAddress) || deployed.agentWallet.walletAddress.toLowerCase() !== walletAddress) {
+    if (!deployed?.agentWallet || !(0, import_viem7.isAddress)(deployed.agentWallet.walletAddress) || deployed.agentWallet.walletAddress.toLowerCase() !== walletAddress) {
       throw this.invalidResponse("agent deployment", {
         reason: "Deploy did not return the expected Agent Wallet."
       });
     }
     context.wallet = deployed.agentWallet;
   }
-  async refreshSnapshotAfterMovement(state, chainId, context, movement) {
+  async refreshSnapshotAfterMovement(state, chainId, context, movement, settlement) {
+    const contextKey = this.contextKey(state, chainId, context.asset);
+    this.reconcileUntil.set(contextKey, Date.now() + YIELDSEEKER_SETTLEMENT_WINDOW_MS);
+    this.activityRefreshUntil.set(contextKey, Date.now() + YIELDSEEKER_SETTLEMENT_WINDOW_MS);
+    const epoch = this.movementEpochs.get(contextKey) ?? 0;
+    this.snapshotMovements.set(contextKey, settlement?.epoch === epoch ? settlement : null);
+    this.movementEpochs.set(contextKey, epoch + 1);
+    const version = this.advancePortfolioVersion(contextKey);
+    const generation = this.readGeneration;
     try {
-      const response = await this.walletRequest(
-        state,
-        chainId,
-        `${this.agentPath(context, "snapshot")}${query({
-          shouldForceRefresh: true
-        })}`
+      await this.cachedRead(
+        `snapshot:${contextKey}`,
+        YIELDSEEKER_SETTLEMENT_CACHE_MS,
+        () => this.requestPortfolioSnapshot(state, chainId, context, contextKey, version, generation, true)
       );
-      if (!response?.agentSnapshot) {
-        throw this.invalidResponse("agent snapshot refresh");
-      }
     } catch (error) {
       console.warn(
         `[owney-sdk] Yieldseeker ${movement} snapshot refresh failed:`,
@@ -3812,10 +4274,26 @@ var YieldseekerAgent = class {
     return `/users/${context.user.userId}/agents/${context.agent.agentId}/${suffix}`;
   }
   async walletRequest(state, chainId, path, options = {}) {
+    const read2 = (options.method ?? "GET") === "GET";
+    const userKey = this.userKey(state, chainId);
+    if (read2) {
+      const failure = this.standardReadFailures.get(userKey);
+      if (failure && failure.retryAt > Date.now()) throw failure.error;
+      if (failure) this.standardReadFailures.delete(userKey);
+    }
+    const generation = this.readGeneration;
     try {
       return await this.providerRequest(state, chainId, path, options);
     } catch (error) {
-      throw this.mapApiError(error);
+      const mapped = this.mapApiError(error);
+      const delay = read2 ? rateLimitDelay(mapped) : void 0;
+      if (delay !== void 0 && this.readGeneration === generation) {
+        this.standardReadFailures.set(userKey, {
+          retryAt: Date.now() + Math.max(YIELDSEEKER_READ_FAILURE_COOLDOWN_MS, delay),
+          error: mapped
+        });
+      }
+      throw mapped;
     }
   }
   async providerRequest(state, chainId, path, options = {}) {
@@ -3856,6 +4334,7 @@ var YieldseekerAgent = class {
       code,
       `Yieldseeker request failed: ${error.providerCode}.`,
       {
+        rpcSource: "agent-api",
         statusCode: error.status,
         providerCode: error.providerCode,
         ...error.responseFields ? { fields: error.responseFields } : {}
@@ -3868,32 +4347,37 @@ var YieldseekerAgent = class {
       return this.transactionExecutor(state, chainId, transaction);
     }
     this.assertTransaction(transaction, state, chainId);
-    const account = (0, import_viem6.getAddress)(state.walletAddress);
-    const walletClient = (0, import_viem6.createWalletClient)({
+    const account = (0, import_viem7.getAddress)(state.walletAddress);
+    const walletClient = (0, import_viem7.createWalletClient)({
       account,
       chain: import_chains3.base,
-      transport: (0, import_viem6.custom)(state.provider)
+      transport: (0, import_viem7.custom)(state.provider)
     });
-    const publicClient = (0, import_viem6.createPublicClient)({
+    const walletChainClient = (0, import_viem7.createPublicClient)({
       chain: import_chains3.base,
-      transport: (0, import_viem6.custom)(state.provider)
+      transport: (0, import_viem7.custom)(state.provider)
     });
     await ensureWalletOnChain(
-      publicClient,
+      walletChainClient,
       walletClient,
       8453
     );
     const hash = await walletClient.sendTransaction({
       account,
       chain: import_chains3.base,
-      to: (0, import_viem6.getAddress)(transaction.to),
+      to: (0, import_viem7.getAddress)(transaction.to),
       data: transaction.data,
       value: BigInt(transaction.value)
     });
-    const receipt = await publicClient.waitForTransactionReceipt({
-      hash,
-      confirmations: 1
-    });
+    const receipt = await withPaidRpcDiagnostics(
+      () => this.getReceiptClient().waitForTransactionReceipt({
+        hash,
+        confirmations: 1
+      }),
+      8453,
+      "eth_getTransactionReceipt",
+      this.id
+    );
     if (receipt.status !== "success") {
       throw new OwneyError(
         "AGENT_TRANSACTION_REVERTED",
@@ -3909,14 +4393,15 @@ var YieldseekerAgent = class {
       await this.unwindReceiptWaiter(state, chainId, transactionHash);
       return;
     }
-    const publicClient = (0, import_viem6.createPublicClient)({
-      chain: import_chains3.base,
-      transport: (0, import_viem6.custom)(state.provider)
-    });
-    const receipt = await publicClient.waitForTransactionReceipt({
-      hash: transactionHash,
-      confirmations: 1
-    });
+    const receipt = await withPaidRpcDiagnostics(
+      () => this.getReceiptClient().waitForTransactionReceipt({
+        hash: transactionHash,
+        confirmations: 1
+      }),
+      8453,
+      "eth_getTransactionReceipt",
+      this.id
+    );
     if (receipt.status !== "success") {
       throw new OwneyError(
         "AGENT_TRANSACTION_REVERTED",
@@ -3927,12 +4412,12 @@ var YieldseekerAgent = class {
     }
   }
   assertTransaction(transaction, state, chainId) {
-    if (!transaction || typeof transaction.from !== "string" || !(0, import_viem6.isAddress)(transaction.from) || typeof transaction.to !== "string" || !(0, import_viem6.isAddress)(transaction.to) || typeof transaction.data !== "string" || !/^0x[a-fA-F0-9]*$/.test(transaction.data) || typeof transaction.value !== "string" || !/^[0-9]+$/.test(transaction.value) || transaction.chainId !== chainId || (0, import_viem6.getAddress)(transaction.from) !== (0, import_viem6.getAddress)(state.walletAddress)) {
+    if (!transaction || typeof transaction.from !== "string" || !(0, import_viem7.isAddress)(transaction.from) || typeof transaction.to !== "string" || !(0, import_viem7.isAddress)(transaction.to) || typeof transaction.data !== "string" || !/^0x[a-fA-F0-9]*$/.test(transaction.data) || typeof transaction.value !== "string" || !/^[0-9]+$/.test(transaction.value) || transaction.chainId !== chainId || (0, import_viem7.getAddress)(transaction.from) !== (0, import_viem7.getAddress)(state.walletAddress)) {
       throw this.invalidResponse("transaction");
     }
   }
   assertAgent(agent) {
-    if (typeof agent.agentId !== "string" || typeof agent.assetAddress !== "string" || !(0, import_viem6.isAddress)(agent.assetAddress) || agent.chainId !== 8453) {
+    if (typeof agent.agentId !== "string" || typeof agent.assetAddress !== "string" || !(0, import_viem7.isAddress)(agent.assetAddress) || agent.chainId !== 8453) {
       throw this.invalidResponse("agent");
     }
   }
@@ -4085,7 +4570,7 @@ async function withFailureReporting(apiKey, agentType, fn, baseUrl) {
 }
 
 // src/lib/helpers/withdraw-helper.ts
-var import_viem7 = require("viem");
+var import_viem8 = require("viem");
 function projectAgentBalancesForAsset(agents, aggregated, chainId, asset, decimals) {
   const target = asset.toUpperCase();
   return agents.map((agent) => {
@@ -4093,7 +4578,7 @@ function projectAgentBalancesForAsset(agents, aggregated, chainId, asset, decima
     const tokenBalance = agentBalance?.tokens.find(
       (t) => t.chainId === chainId && t.asset.toUpperCase() === target
     );
-    let balance = tokenBalance ? (0, import_viem7.parseUnits)(tokenBalance.amount, decimals) : 0n;
+    let balance = tokenBalance ? (0, import_viem8.parseUnits)(tokenBalance.amount, decimals) : 0n;
     if (agent.balanceComposition === "tokens-plus-positions") {
       const chainNameById = {
         1: "ETHEREUM",
@@ -4105,16 +4590,16 @@ function projectAgentBalancesForAsset(agents, aggregated, chainId, asset, decima
         const positionChain = position2.chain.trim().toUpperCase();
         const matchesChain = positionChain === String(chainId) || targetChain !== void 0 && positionChain === targetChain;
         if (!matchesChain || position2.asset.toUpperCase() !== target) continue;
-        if (position2.amountRaw !== void 0) {
-          try {
-            balance += BigInt(position2.amountRaw);
-            continue;
-          } catch {
-          }
-        }
-        balance += (0, import_viem7.parseUnits)(position2.amount, decimals);
+        balance += position2.withdrawableAmountRaw !== void 0 ? BigInt(position2.withdrawableAmountRaw) : (0, import_viem8.parseUnits)(position2.amount, decimals);
       }
     }
+    const assetTotal = agentBalance?.assetBalances?.find(
+      (t) => t.chainId === chainId && t.asset.toUpperCase() === target
+    );
+    if (assetTotal) {
+      const total = (0, import_viem8.parseUnits)(assetTotal.amount, decimals);
+      if (total < balance) balance = total > 0n ? total : 0n;
+    }
     return { agent, balance };
   });
 }
@@ -4271,15 +4756,50 @@ function aggregateApyByChainAndAsset(agentApys, agentBalances) {
 }
 
 // src/client.ts
-var import_viem11 = require("viem");
+var import_viem12 = require("viem");
 var import_chains4 = require("viem/chains");
 
 // src/lib/sponsored-token-batch.ts
-var import_viem9 = require("viem");
+var import_viem10 = require("viem");
 
 // src/lib/permit2-batch.ts
-var import_viem8 = require("viem");
+var import_viem9 = require("viem");
 var BATCH_PERMIT2_ADDRESS = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
+var BASE_USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+var MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
+var ERC2612_PERMIT_TYPES = {
+  Permit: [
+    { name: "owner", type: "address" },
+    { name: "spender", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" }
+  ]
+};
+var ERC2612_READ_ABI = (0, import_viem9.parseAbi)([
+  "function name() view returns (string)",
+  "function version() view returns (string)",
+  "function nonces(address owner) view returns (uint256)"
+]);
+function erc2612TypedData(input) {
+  return {
+    domain: {
+      name: input.permit.tokenName,
+      version: input.permit.tokenVersion,
+      chainId: input.chainId,
+      verifyingContract: input.token
+    },
+    types: ERC2612_PERMIT_TYPES,
+    primaryType: "Permit",
+    message: {
+      owner: input.owner,
+      spender: BATCH_PERMIT2_ADDRESS,
+      value: BigInt(input.permit.value),
+      nonce: BigInt(input.permit.nonce),
+      deadline: BigInt(input.permit.deadline)
+    }
+  };
+}
 var PERMIT_BATCH_TYPES = {
   PermitBatchWitnessTransferFrom: [
     { name: "permitted", type: "TokenPermissions[]" },
@@ -4294,7 +4814,7 @@ var PERMIT_BATCH_TYPES = {
     { name: "amount", type: "uint256" }
   ]
 };
-var PERMIT2_BATCH_ABI = (0, import_viem8.parseAbi)([
+var PERMIT2_BATCH_ABI = (0, import_viem9.parseAbi)([
   "struct TokenPermissions { address token; uint256 amount; }",
   "struct PermitBatchTransferFrom { TokenPermissions[] permitted; uint256 nonce; uint256 deadline; }",
   "struct SignatureTransferDetails { address to; uint256 requestedAmount; }",
@@ -4353,7 +4873,7 @@ function clear(key2) {
   else window.localStorage.removeItem(key2);
 }
 function sponsorTokenBatch(i) {
-  const key2 = `owney.token-batch.v1:${(0, import_viem9.keccak256)((0, import_viem9.toBytes)(i.apiKey))}:${i.baseUrl ?? "default"}:${i.chainId}:${i.owner.toLowerCase()}:${i.token.toLowerCase()}`;
+  const key2 = `owney.token-batch.v1:${(0, import_viem10.keccak256)((0, import_viem10.toBytes)(i.apiKey))}:${i.baseUrl ?? "default"}:${i.chainId}:${i.owner.toLowerCase()}:${i.token.toLowerCase()}`;
   const plan = planOf(i.transfers);
   const active = inflight.get(key2);
   if (active) {
@@ -4384,7 +4904,7 @@ async function execute(i, key2, plan) {
           baseUrl: i.baseUrl,
           body
         });
-        if (!prepared.serializedTransaction || (0, import_viem9.keccak256)(prepared.serializedTransaction) !== prepared.txHash)
+        if (!prepared.serializedTransaction || (0, import_viem10.keccak256)(prepared.serializedTransaction) !== prepared.txHash)
           throw new Error(
             "Sponsorship API did not return a valid prepared transaction."
           );
@@ -4399,7 +4919,7 @@ async function execute(i, key2, plan) {
         baseUrl: i.baseUrl,
         body
       });
-      if (result.txHash !== (0, import_viem9.keccak256)(body.serializedTransaction))
+      if (result.txHash !== (0, import_viem10.keccak256)(body.serializedTransaction))
         throw new Error(
           "Sponsorship receipt does not match the pending transaction."
         );
@@ -4414,7 +4934,7 @@ async function execute(i, key2, plan) {
   const saved = read(key2);
   if (saved) {
     const previous = JSON.parse(saved);
-    if (previous.chainId !== i.chainId || !(0, import_viem9.isAddressEqual)(previous.from, i.owner) || !(0, import_viem9.isAddressEqual)(previous.token, i.token) || planOf(previous.transfers) !== plan)
+    if (previous.chainId !== i.chainId || !(0, import_viem10.isAddressEqual)(previous.from, i.owner) || !(0, import_viem10.isAddressEqual)(previous.token, i.token) || planOf(previous.transfers) !== plan)
       throw new Error(
         "Retry the previous token deposit and agent split first to reconcile its status."
       );
@@ -4431,28 +4951,67 @@ async function execute(i, key2, plan) {
       "DEPOSIT_INSUFFICIENT_BALANCE",
       "Insufficient token balance for this deposit."
     );
-  if (allowance < total)
+  if (allowance < total && (i.chainId !== 8453 || !(0, import_viem10.isAddressEqual)(i.token, BASE_USDC_ADDRESS)))
     throw new OwneyError(
       "PERMIT2_APPROVAL_REQUIRED",
       "token deposits need a one-time Permit2 approval."
     );
-  const relayer = await getSponsorRelayerAddress({
+  const now = (await i.pub.getBlock()).timestamp;
+  let erc2612Permit;
+  if (allowance < total) {
+    const [tokenName, tokenVersion, permitNonce] = await Promise.all([
+      i.pub.readContract({
+        address: i.token,
+        abi: ERC2612_READ_ABI,
+        functionName: "name"
+      }),
+      i.pub.readContract({
+        address: i.token,
+        abi: ERC2612_READ_ABI,
+        functionName: "version"
+      }),
+      i.pub.readContract({
+        address: i.token,
+        abi: ERC2612_READ_ABI,
+        functionName: "nonces",
+        args: [i.owner]
+      })
+    ]);
+    const unsignedPermit = {
+      value: MAX_UINT256.toString(),
+      nonce: permitNonce.toString(),
+      deadline: (now + 900n).toString(),
+      tokenName,
+      tokenVersion
+    };
+    const signature2 = await i.wallet.signTypedData({
+      account: i.owner,
+      ...erc2612TypedData({
+        chainId: 8453,
+        token: i.token,
+        owner: i.owner,
+        permit: unsignedPermit
+      })
+    });
+    erc2612Permit = { ...unsignedPermit, signature: signature2 };
+  }
+  const spender = erc2612Permit ? MULTICALL3_ADDRESS : await getSponsorRelayerAddress({
     apiKey: i.apiKey,
     baseUrl: i.baseUrl,
     chainId: i.chainId
   });
-  const now = (await i.pub.getBlock()).timestamp;
   const unsigned = {
     chainId: i.chainId,
     token: i.token,
     from: i.owner,
     transfers: i.transfers,
     nonce: randomPermit2Nonce().toString(),
-    deadline: (now + 900n).toString()
+    deadline: (now + 900n).toString(),
+    ...erc2612Permit ? { erc2612Permit } : {}
   };
   const signature = await i.wallet.signTypedData({
     account: i.owner,
-    ...batchTypedData(unsigned, relayer)
+    ...batchTypedData(unsigned, spender)
   });
   i.onApproved?.();
   return send({ ...unsigned, signature });
@@ -4472,8 +5031,8 @@ function makeSponsoredTokenCallback(deps) {
         "CHAIN_UNSUPPORTED",
         `No sponsored token configured for chain ${chainId}`
       );
-    const pub = deps.getPublicClient(chainId), wallet = deps.getWalletClient(chainId);
-    await ensureWalletOnChain(pub, wallet, chainId);
+    const pub = deps.getPublicClient(chainId), walletChain = deps.getWalletChainClient?.(chainId) ?? pub, wallet = deps.getWalletClient(chainId);
+    await ensureWalletOnChain(walletChain, wallet, chainId);
     return sponsorTokenBatch({
       apiKey: deps.apiKey,
       baseUrl: deps.baseUrl,
@@ -4569,7 +5128,7 @@ async function runAgentDepositBatch(chainId, legs, transfer) {
 }
 
 // src/lib/sponsored-calls-deposit.ts
-var import_viem10 = require("viem");
+var import_viem11 = require("viem");
 var DEFAULT_POLL_INTERVAL_MS = 1500;
 var DEFAULT_MAX_POLLS = 30;
 async function paymasterSupported(provider, owner, chainId) {
@@ -4577,7 +5136,7 @@ async function paymasterSupported(provider, owner, chainId) {
     method: "wallet_getCapabilities",
     params: [owner]
   });
-  const forChain = caps?.[(0, import_viem10.toHex)(chainId)] ?? caps?.[String(chainId)];
+  const forChain = caps?.[(0, import_viem11.toHex)(chainId)] ?? caps?.[String(chainId)];
   return Boolean(forChain?.paymasterService?.supported);
 }
 function makeSponsoredCallsCallback(deps) {
@@ -4614,8 +5173,8 @@ function makeSponsoredCallsCallback(deps) {
     const calls = transfers.map((transfer) => ({
       to: token,
       value: "0x0",
-      data: (0, import_viem10.encodeFunctionData)({
-        abi: import_viem10.erc20Abi,
+      data: (0, import_viem11.encodeFunctionData)({
+        abi: import_viem11.erc20Abi,
         functionName: "transfer",
         args: [transfer.to, BigInt(transfer.amount)]
       })
@@ -4653,7 +5212,7 @@ function makeSponsoredCallsCallback(deps) {
         {
           version: "2.0.0",
           from: deps.ownerAddress,
-          chainId: (0, import_viem10.toHex)(chainId),
+          chainId: (0, import_viem11.toHex)(chainId),
           atomicRequired: transfers.length > 1,
           calls,
           capabilities: {
@@ -4713,6 +5272,8 @@ function makeSponsoredCallsCallback(deps) {
 }
 
 // src/client.ts
+var PERMIT2_ALLOWANCE_VERIFY_ATTEMPTS = 6;
+var PERMIT2_ALLOWANCE_VERIFY_DELAY_MS = 250;
 function encodeMultiAgentCursor(map) {
   return Buffer.from(JSON.stringify(map), "utf8").toString("base64");
 }
@@ -4773,6 +5334,7 @@ var OwneySDK = class {
   // leave every user's agent profile alone.
   orgAgentConfig;
   orgAgentConfigPromise = null;
+  rpcUrls;
   zyfaiRpcUrls;
   yieldseekerApiBaseUrl;
   yieldseekerSiweOrigin;
@@ -4797,7 +5359,12 @@ var OwneySDK = class {
   constructor(config) {
     this.apiKey = config.apiKey;
     if (config.debug) setOwneyDebug(true);
-    this.zyfaiRpcUrls = config.zyfaiRpcUrls;
+    this.rpcUrls = resolveRpcUrls(
+      config.rpcUrls,
+      config.apiKey,
+      config.routingApiBaseUrl
+    );
+    this.zyfaiRpcUrls = config.rpcUrls ? void 0 : config.zyfaiRpcUrls;
     this.yieldseekerApiBaseUrl = config.yieldseekerApiBaseUrl;
     this.yieldseekerSiweOrigin = config.yieldseekerSiweOrigin;
     this.routingApiBaseUrl = config.routingApiBaseUrl;
@@ -4887,6 +5454,9 @@ var OwneySDK = class {
     }
     return this.state.provider;
   }
+  getPaidRpcClient(chainId) {
+    return createPaidRpcClient(VIEM_CHAIN2[chainId], this.rpcUrls);
+  }
   /** Builds the default USDC batch callback for the connected wallet. */
   getDefaultSponsoredCallback(onApproved) {
     if (!onApproved && this.cachedSponsoredCallback)
@@ -4902,14 +5472,15 @@ var OwneySDK = class {
       // Casts work around viem's chain-narrowed Client vs the generic
       // PublicClient/WalletClient param types — structurally identical at
       // runtime, but the two share a name TS treats as unrelated.
-      getPublicClient: (cid) => (0, import_viem11.createPublicClient)({
+      getPublicClient: (cid) => this.getPaidRpcClient(cid),
+      getWalletChainClient: (cid) => (0, import_viem12.createPublicClient)({
         chain: VIEM_CHAIN2[cid],
-        transport: (0, import_viem11.custom)(provider)
+        transport: (0, import_viem12.custom)(provider)
       }),
-      getWalletClient: (cid) => (0, import_viem11.createWalletClient)({
+      getWalletClient: (cid) => (0, import_viem12.createWalletClient)({
         account: owner,
         chain: VIEM_CHAIN2[cid],
-        transport: (0, import_viem11.custom)(provider)
+        transport: (0, import_viem12.custom)(provider)
       })
     });
     if (!onApproved) this.cachedSponsoredCallback = callback;
@@ -4952,14 +5523,15 @@ var OwneySDK = class {
       // Casts work around viem's chain-narrowed Client vs the generic
       // PublicClient/WalletClient param types — structurally identical at
       // runtime, but the two share a name TS treats as unrelated.
-      getPublicClient: (cid) => (0, import_viem11.createPublicClient)({
+      getPublicClient: (cid) => this.getPaidRpcClient(cid),
+      getWalletChainClient: (cid) => (0, import_viem12.createPublicClient)({
         chain: VIEM_CHAIN2[cid],
-        transport: (0, import_viem11.custom)(provider)
+        transport: (0, import_viem12.custom)(provider)
       }),
-      getWalletClient: (cid) => (0, import_viem11.createWalletClient)({
+      getWalletClient: (cid) => (0, import_viem12.createWalletClient)({
         account: owner,
         chain: VIEM_CHAIN2[cid],
-        transport: (0, import_viem11.custom)(provider)
+        transport: (0, import_viem12.custom)(provider)
       })
     });
     if (!onApproved) this.cachedWethSponsoredCallback = callback;
@@ -5065,12 +5637,21 @@ var OwneySDK = class {
   createAgent(agentId, key2) {
     if (agentId === "zyfai") {
       if (!key2) return null;
-      return new ZyfaiAgent(key2, this.zyfaiRpcUrls, this.referralSource);
+      return new ZyfaiAgent(
+        key2,
+        this.zyfaiRpcUrls ? resolveRpcUrls(
+          this.zyfaiRpcUrls,
+          this.apiKey,
+          this.routingApiBaseUrl
+        ) : this.rpcUrls,
+        this.referralSource
+      );
     }
     if (agentId === "yieldseeker") {
       return new YieldseekerAgent(this.apiKey, {
         auth: { origin: this.yieldseekerSiweOrigin },
-        baseUrl: this.yieldseekerApiBaseUrl ?? getYieldseekerProxyBaseUrl(this.routingApiBaseUrl)
+        baseUrl: this.yieldseekerApiBaseUrl ?? getYieldseekerProxyBaseUrl(this.routingApiBaseUrl),
+        rpcUrls: this.rpcUrls
       });
     }
     return null;
@@ -5361,7 +5942,8 @@ var OwneySDK = class {
             );
             await this.approvePermit2(
               asset,
-              requiredAmount
+              requiredAmount,
+              cid
             );
             return batchTransfer(cid, transfers);
           }
@@ -5405,10 +5987,12 @@ var OwneySDK = class {
    * 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
-   *    token deposit, this is the wallet's first Permit2 deposit for that token. 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.
@@ -5451,7 +6035,8 @@ var OwneySDK = class {
           );
           await this.approvePermit2(
             asset,
-            BigInt(amount)
+            BigInt(amount),
+            chainId
           );
           continue;
         }
@@ -5598,6 +6183,32 @@ var OwneySDK = class {
     }
     return eligible;
   }
+  /**
+   * 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.
+   */
+  orderAgentsForWithdrawal(agents) {
+    return agents.map((agent, index) => ({ agent, index })).sort((left, right) => {
+      const approvalOrder = Number(Boolean(right.agent.withdrawalRequiresWalletApproval)) - Number(Boolean(left.agent.withdrawalRequiresWalletApproval));
+      return approvalOrder || left.index - right.index;
+    }).map(({ agent }) => agent);
+  }
+  isUserRejectedWithdrawal(error) {
+    let current = error;
+    const seen = /* @__PURE__ */ new Set();
+    while (current && typeof current === "object" && !seen.has(current)) {
+      seen.add(current);
+      const candidate = current;
+      if (candidate.code === 4001 || candidate.code === "4001") return true;
+      const message = [candidate.message, candidate.shortMessage].filter((value) => typeof value === "string").join(" ");
+      if (/user (?:rejected|denied)|rejected by user/i.test(message)) {
+        return true;
+      }
+      current = candidate.cause;
+    }
+    return false;
+  }
   // --- Fund operations ---
   /**
    * Withdraw funds from a specific agent, or all agents that support the active chain+asset if agentId is omitted.
@@ -5609,7 +6220,14 @@ var OwneySDK = class {
    * @returns {AgentWithdrawResult} for a single agent, or {OwneyWithdrawResult} with per-agent results
    */
   async withdraw(options) {
-    const { asset, amount, agentId } = options;
+    const { asset, amount, agentId, onAgentResult } = options;
+    const notifyAgentResult = (id, result) => {
+      try {
+        onAgentResult?.(id, result);
+      } catch (error) {
+        console.warn("Withdrawal result observer failed:", error);
+      }
+    };
     const state = this.requireState();
     const chainId = this.requireChainId();
     const token = asset;
@@ -5625,21 +6243,26 @@ var OwneySDK = class {
     if (agentId) {
       const agent = this.getAgent(agentId);
       this.validateAssetSupport(agent, chainId, asset);
-      return withFailureReporting(
+      const result = await withFailureReporting(
         this.apiKey,
         agent.id,
         () => agent.withdraw(state, chainId, token, amount),
         this.routingApiBaseUrl
       );
+      notifyAgentResult(agent.id, result);
+      return result;
     }
     const eligibleAgents = this.getEligibleAgents(chainId, asset);
+    const withdrawalAgents = this.orderAgentsForWithdrawal(eligibleAgents);
     if (!amount) {
       const results2 = {};
       const agentErrors2 = {};
-      for (const agent of eligibleAgents) {
+      for (const agent of withdrawalAgents) {
         try {
           results2[agent.id] = await agent.withdraw(state, chainId, token);
+          notifyAgentResult(agent.id, results2[agent.id]);
         } catch (err) {
+          if (this.isUserRejectedWithdrawal(err)) throw err;
           console.error(`withdraw failed for agent "${agent.id}":`, err);
           agentErrors2[agent.id] = err instanceof Error ? err.message : String(err);
           const code = err instanceof OwneyError ? err.code : "SDK_AGENT_FAILURE";
@@ -5720,12 +6343,13 @@ var OwneySDK = class {
       planned: 0n
     }));
     const plans = [...disabledPlans, ...enabledPlans];
+    const orderedPlans = this.orderAgentsForWithdrawal(plans.map((p) => p.agent)).map((agent) => plans.find((plan) => plan.agent === agent));
     const results = {};
     const agentErrors = {
       ...aggregated.agentErrors ?? {}
     };
-    for (let i = 0; i < plans.length; i++) {
-      const p = plans[i];
+    for (let i = 0; i < orderedPlans.length; i++) {
+      const p = orderedPlans[i];
       if (p.planned === 0n) continue;
       try {
         results[p.agent.id] = await p.agent.withdraw(
@@ -5734,7 +6358,9 @@ var OwneySDK = class {
           token,
           p.planned.toString()
         );
+        notifyAgentResult(p.agent.id, results[p.agent.id]);
       } catch (err) {
+        if (this.isUserRejectedWithdrawal(err)) throw err;
         console.error(`withdraw failed for agent "${p.agent.id}":`, err);
         agentErrors[p.agent.id] = err instanceof Error ? err.message : String(err);
         const code = err instanceof OwneyError ? err.code : "SDK_AGENT_FAILURE";
@@ -5746,7 +6372,7 @@ var OwneySDK = class {
         );
         const failedAmount = p.planned;
         p.planned = 0n;
-        redistributeShare(plans, i, failedAmount);
+        redistributeShare(orderedPlans, i, failedAmount);
       }
     }
     if (Object.keys(results).length === 0) {
@@ -5856,23 +6482,11 @@ var OwneySDK = class {
       const agent = this.getAgent(agentId);
       return this.readAgent(agent, "earnings", () => agent.getEarnings(state, chainId));
     }
-    let totalEarnings = 0;
-    const results = {};
     const entries = [...this.getActiveAgents().entries()];
-    const earningsResults = await Promise.all(
-      entries.map(async ([id, agent]) => {
-        const e = await this.readAgent(agent, "earnings", () => agent.getEarnings(state, chainId));
-        return [id, e];
-      })
+    return this.aggregateEarnings(
+      entries,
+      (agent) => this.readAgent(agent, "earnings", () => agent.getEarnings(state, chainId))
     );
-    for (const [id, e] of earningsResults) {
-      results[id] = e;
-      totalEarnings += Number(e.lifetimeEarnings);
-    }
-    return {
-      totalEarnings: String(totalEarnings),
-      agentEarnings: results
-    };
   }
   /**
    * Return refreshed earnings while letting each agent own its refresh policy.
@@ -5887,18 +6501,42 @@ var OwneySDK = class {
       () => agent.refreshEarnings?.(state, chainId) ?? agent.getEarnings(state, chainId)
     );
     if (agentId) return refreshAgent(this.getAgent(agentId));
-    let totalEarnings = 0;
+    return this.aggregateEarnings([...this.getActiveAgents().entries()], refreshAgent);
+  }
+  async aggregateEarnings(entries, read2) {
+    const settled = await Promise.allSettled(entries.map(([, agent]) => read2(agent)));
     const agentEarnings = {};
-    const refreshed = await Promise.all(
-      [...this.getActiveAgents().entries()].map(
-        async ([id, agent]) => [id, await refreshAgent(agent)]
-      )
-    );
-    for (const [id, earnings] of refreshed) {
-      agentEarnings[id] = earnings;
-      totalEarnings += Number(earnings.lifetimeEarnings);
+    const agentErrors = {};
+    const agentRetryAt = {};
+    const failures = [];
+    let totalEarnings = 0;
+    for (let i = 0; i < settled.length; i++) {
+      const [id] = entries[i];
+      const result = settled[i];
+      if (result.status === "fulfilled") {
+        agentEarnings[id] = result.value;
+        totalEarnings += Number(result.value.lifetimeEarnings);
+        continue;
+      }
+      const reason = result.reason;
+      failures.push(reason);
+      const retryDelay = rateLimitDelay(reason);
+      if (retryDelay !== void 0) agentRetryAt[id] = Date.now() + retryDelay;
+      agentErrors[id] = reason instanceof Error ? reason.message : String(reason);
+      console.error(`[owney-sdk] Earnings fetch failed for agent "${id}":`, reason);
+    }
+    if (entries.length > 0 && Object.keys(agentEarnings).length === 0) {
+      throw new OwneyError(
+        "EARNINGS_ALL_FAILED",
+        "Failed to fetch earnings for all active agents.",
+        { agentErrors, failures }
+      );
     }
-    return { totalEarnings: String(totalEarnings), agentEarnings };
+    return {
+      totalEarnings: String(totalEarnings),
+      agentEarnings,
+      ...Object.keys(agentErrors).length > 0 ? { agentErrors, agentRetryAt } : {}
+    };
   }
   /**
    * Get the weighted APY for the user's account over a time period.
@@ -6172,16 +6810,18 @@ var OwneySDK = class {
   }
   /**
    * User-paid approval of Permit2 on the selected token for the active chain.
-   * Approves exactly the pending deposit amount. Another approval is required
-   * for a later deposit once this allowance has been consumed. Resolves after
-   * one confirmation so the subsequent deposit attempt sees the new allowance.
+   * 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.
    */
-  async approvePermit2(asset = "WETH", requiredAmount = 0n) {
+  async approvePermit2(asset = "WETH", requiredAmount = 0n, expectedChainId) {
     const state = this.requireState();
-    const chainId = this.requireChainId();
+    const chainId = expectedChainId ?? this.requireChainId();
     this.getEligibleAgents(chainId, asset, { excludeDisabled: true });
     const token = sponsoredTokensFor(asset)[chainId];
     if (!token) {
@@ -6191,16 +6831,18 @@ var OwneySDK = class {
       );
     }
     const provider = this.requireConnectedProvider();
-    const publicClient = (0, import_viem11.createPublicClient)({
+    const walletChainClient = (0, import_viem12.createPublicClient)({
       chain: VIEM_CHAIN2[chainId],
-      transport: (0, import_viem11.custom)(provider)
+      transport: (0, import_viem12.custom)(provider)
     });
+    const publicClient = this.getPaidRpcClient(chainId);
     const approvalAmount = permit2ApprovalAmount(requiredAmount);
-    const wallet = (0, import_viem11.createWalletClient)({
+    const wallet = (0, import_viem12.createWalletClient)({
       account: state.walletAddress,
       chain: VIEM_CHAIN2[chainId],
-      transport: (0, import_viem11.custom)(provider)
+      transport: (0, import_viem12.custom)(provider)
     });
+    await ensureWalletOnChain(walletChainClient, wallet, chainId);
     const hash = await wallet.writeContract({
       address: token,
       abi: ERC20_ALLOWANCE_ABI,
@@ -6209,14 +6851,53 @@ var OwneySDK = class {
       account: state.walletAddress,
       chain: VIEM_CHAIN2[chainId]
     });
-    const receipt = await publicClient.waitForTransactionReceipt({
-      hash,
-      confirmations: 1
-    });
+    const receipt = await withPaidRpcDiagnostics(
+      () => publicClient.waitForTransactionReceipt({
+        hash,
+        confirmations: 1
+      }),
+      chainId,
+      "eth_getTransactionReceipt"
+    );
     if (receipt.status !== "success") {
       throw new Error(`Permit2 approval reverted (tx ${hash})`);
     }
-    return hash;
+    let observedAllowance = 0n;
+    let verificationError;
+    for (let attempt = 0; attempt < PERMIT2_ALLOWANCE_VERIFY_ATTEMPTS; attempt += 1) {
+      try {
+        observedAllowance = await readPermit2Allowance(
+          publicClient,
+          token,
+          state.walletAddress,
+          attempt === 0 ? receipt.blockNumber : void 0
+        );
+        verificationError = void 0;
+        if (observedAllowance >= requiredAmount) return hash;
+      } catch (error) {
+        verificationError = error;
+      }
+      if (attempt + 1 < PERMIT2_ALLOWANCE_VERIFY_ATTEMPTS) {
+        await new Promise(
+          (resolve) => setTimeout(resolve, PERMIT2_ALLOWANCE_VERIFY_DELAY_MS)
+        );
+      }
+    }
+    throw new OwneyError(
+      "PERMIT2_APPROVAL_REQUIRED",
+      "Permit2 approval was confirmed, but the required token allowance was not observable.",
+      {
+        approvalConfirmed: true,
+        approvalTxHash: hash,
+        owner: state.walletAddress,
+        token,
+        spender: PERMIT2_ADDRESS,
+        chainId,
+        requiredAmount: requiredAmount.toString(),
+        observedAllowance: observedAllowance.toString(),
+        ...verificationError instanceof Error ? { verificationError: verificationError.message } : {}
+      }
+    );
   }
   // --- Discovery (no wallet required) ---
   /**
@@ -6321,7 +7002,7 @@ var OwneySDK = class {
 };
 
 // src/agents/zyfai/zyfai.siwx.ts
-var import_viem12 = require("viem");
+var import_viem13 = require("viem");
 var import_siwe2 = require("siwe");
 var import_sdk2 = require("@zyfai/sdk");
 
@@ -6448,7 +7129,7 @@ function buildSIWXConfig(deps) {
       issuedAt,
       toString() {
         return new import_siwe2.SiweMessage({
-          address: (0, import_viem12.getAddress)(accountAddress),
+          address: (0, import_viem13.getAddress)(accountAddress),
           chainId: numericChainId(chainId),
           domain,
           uri,