@owney/sdk 0.7.32-beta.4 → 0.7.32-beta.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -363,6 +363,15 @@ interface OwneySDKConfig {
363
363
  * already-deployed app: set `globalThis.__OWNEY_DEBUG__ = true` in devtools.
364
364
  */
365
365
  debug?: boolean;
366
+ /**
367
+ * When true, the organization's pool policy is NOT applied on connect, so a
368
+ * user's own deposit-time pool selection (ROUT-569) is never overwritten by
369
+ * the org-level one on their next reconnect. Splitting and the rest of the
370
+ * org policy still apply. Turn this on in apps that expose the deposit-time
371
+ * Pools step (the spread flow); leave it off where the partner dashboard's
372
+ * pool customization is the source of truth.
373
+ */
374
+ userPoolCustomization?: boolean;
366
375
  /**
367
376
  * Absolute URL of an ERC-7677 paymaster service. When set, deposits go out as
368
377
  * an EIP-5792 `wallet_sendCalls` with `capabilities.paymasterService`, so a
@@ -418,6 +427,14 @@ interface ConnectionState {
418
427
  provider: any;
419
428
  walletAddress: `0x${string}`;
420
429
  chainId: number | null;
430
+ /**
431
+ * Reads under this state use a saved sign-in only: an agent never opens a
432
+ * wallet prompt for them and fails instead. Set by the whole-portfolio reads
433
+ * of an agent that is not active on the connection chain, and by every read
434
+ * of an agent that did not sign in this session (it failed while another
435
+ * agent signed in, or the user cancelled its sign-in).
436
+ */
437
+ promptless?: boolean;
421
438
  }
422
439
  declare const SUPPORTED_TOKENS: readonly ["USDC", "WETH"];
423
440
  declare const SUPPORTED_CHAIN_IDS: readonly [8453, 42161, 1];
@@ -426,39 +443,6 @@ type OwneySupportedChainId = (typeof SUPPORTED_CHAIN_IDS)[number];
426
443
  type OwneySupportedChains = (typeof SUPPORTED_CHAINS)[number];
427
444
  type OwneySupportedTokens = (typeof SUPPORTED_TOKENS)[number];
428
445
 
429
- /**
430
- * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
431
- * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
432
- * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
433
- * must not be normalised anywhere.
434
- *
435
- * An empty array means "no usable pools on this chain".
436
- */
437
- type OrgPoolSelection = {
438
- protocolId: string;
439
- chainId: number;
440
- pools: string[];
441
- };
442
- /**
443
- * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
444
- * narrowed appear. Optional so an older routing API, which does not return the
445
- * field, still parses; undefined and null both mean "change nothing".
446
- */
447
- type OrgPoolPolicy = {
448
- autoApproveProtocols: boolean;
449
- autoApprovePools: boolean;
450
- selections: OrgPoolSelection[];
451
- };
452
- /**
453
- * The organization's agent execution policy, or null when the partner has never
454
- * configured one — in which case the agents leave the user's profile alone.
455
- */
456
- type OrgAgentConfig = {
457
- splittingMode: "none" | "automatic" | "force";
458
- minSplits: number | null;
459
- poolPolicy?: OrgPoolPolicy | null;
460
- };
461
-
462
446
  /** Capability flag: this SDK can hand Zyfai withdrawals and deposit
463
447
  * registrations to the server, and marks such legs with evidence `serverTask`.
464
448
  * Older builds do not export this. */
@@ -497,6 +481,151 @@ type ZyfaiHandoffAnswer = {
497
481
  type: "unknown";
498
482
  };
499
483
 
484
+ /**
485
+ * One protocol's pool selection on one chain. `pools` holds Zyfai pool NAMES
486
+ * verbatim — matched case-sensitively by customizeBatch, and an unrecognised
487
+ * name makes Zyfai's rebalance engine skip the whole protocol, so these strings
488
+ * must not be normalised anywhere.
489
+ *
490
+ * An empty array means "no usable pools on this chain".
491
+ */
492
+ type OrgPoolSelection = {
493
+ protocolId: string;
494
+ chainId: number;
495
+ pools: string[];
496
+ };
497
+ /**
498
+ * The partner's protocol/pool policy (ROUT-224). Sparse — only protocols they
499
+ * narrowed appear. Optional so an older routing API, which does not return the
500
+ * field, still parses; undefined and null both mean "change nothing".
501
+ */
502
+ type OrgPoolPolicy = {
503
+ autoApproveProtocols: boolean;
504
+ autoApprovePools: boolean;
505
+ selections: OrgPoolSelection[];
506
+ };
507
+ /**
508
+ * The organization's agent execution policy, or null when the partner has never
509
+ * configured one — in which case the agents leave the user's profile alone.
510
+ */
511
+ type OrgAgentConfig = {
512
+ splittingMode: "none" | "automatic" | "force";
513
+ minSplits: number | null;
514
+ poolPolicy?: OrgPoolPolicy | null;
515
+ };
516
+
517
+ /**
518
+ * Pool policy: Owney's org-level protocol/pool policy -> Zyfai's two mismatched
519
+ * write shapes.
520
+ *
521
+ * Zyfai splits "which protocols and pools may this user's funds sit in" across
522
+ * two calls that do not share an axis:
523
+ *
524
+ * updateUserProfile({ protocols }) per ASSET, chain-agnostic
525
+ * customizeBatch([{ protocolId, per (PROTOCOL, CHAIN), asset-agnostic
526
+ * chainId, pools, autoselect }])
527
+ *
528
+ * `protocols` is an explicit ALLOW-LIST: a protocol left out of it is disabled
529
+ * for that asset, on every chain, immediately. `customizeBatch` is the opposite
530
+ * shape — one record per (protocol, chain) pair, asset-agnostic, and per
531
+ * docs.zyf.ai it "creates or updates a record for the (user, protocol, chain)
532
+ * combination"; "previous customizations for the same combination are
533
+ * overwritten".
534
+ *
535
+ * That second property is the reason this file exists rather than a single
536
+ * flat translation: customizeBatch overwrites only the combinations it is
537
+ * GIVEN. The partner's stored policy (`OrgPoolPolicy.selections`) is sparse —
538
+ * only the protocols they actually narrowed appear — but the payload we send
539
+ * must be EXHAUSTIVE over every (protocol, chain) pair Zyfai offers this user.
540
+ * If we only sent the narrowed pairs, a partner who restricts Morpho, saves,
541
+ * then later re-ticks every pool box would never be able to undo it: nothing
542
+ * in the (sparse) policy would tell us to send a record clearing it, and the
543
+ * old restrictive record would stay live on the user's profile forever.
544
+ *
545
+ * Pure functions, kept out of the agent so the mapping is testable without a
546
+ * Zyfai client. See splitting.ts for the same pattern on the other lever.
547
+ */
548
+
549
+ /** One selectable pool, with the figures the deposit-time Pools step shows. */
550
+ type AvailablePool = {
551
+ chainId: number;
552
+ token: string;
553
+ name: string;
554
+ /** combined_apy (pool + rewards), already a percent. null when absent. */
555
+ apy: number | null;
556
+ /** TVL in USD. null when absent. See ZyfCustomizationPoolInfo: `tvl` is in
557
+ * the pool's own token, `tvlUsd` is the dollar figure — only the latter is
558
+ * safe to show with a currency symbol. */
559
+ tvlUsd: number | null;
560
+ /** Per-pool deep link (e.g. the Morpho vault page). null when absent. */
561
+ link: string | null;
562
+ /**
563
+ * The pool's on-chain vault address. Set for Yieldseeker, whose pools are
564
+ * identified by vault address; unset for Zyfai, whose pools are identified
565
+ * by name.
566
+ */
567
+ address?: string;
568
+ };
569
+ /** Public Zyfai strategies used by deposit-time pool customization. */
570
+ type PoolSelectionStrategy = "aggressive" | "yieldmaxxing";
571
+ /** One asset's explicit choice for a protocol on one chain. */
572
+ type UserPoolSelection = {
573
+ asset: "USDC" | "WETH";
574
+ protocolId: string;
575
+ chainId: number;
576
+ /**
577
+ * Names enabled by the user for this asset/protocol/chain. Empty, with
578
+ * `availablePools` not empty, means the user chose none of them.
579
+ */
580
+ pools: string[];
581
+ /** Every name shown for this asset/protocol/chain in the superset catalog. */
582
+ availablePools: string[];
583
+ };
584
+ /**
585
+ * The complete saved draft for the asset/chain legs selected in the deposit.
586
+ *
587
+ * An agent whose every entry for an asset and chain has empty `pools` (with
588
+ * vaults shown) gets none of that asset's new deposits there. The agent
589
+ * remembers that "none chosen" on the provider's side, so the next Pools step
590
+ * opens with it, and money already in the agent leaves those pools too:
591
+ * Zyfai saves an empty pool list, and Yieldseeker a vault list naming none, so
592
+ * its money stays idle in the agent. Entries that showed nothing
593
+ * (`availablePools` empty) change nothing.
594
+ */
595
+ type UserPoolSelectionRequest = {
596
+ strategies: Array<{
597
+ asset: "USDC" | "WETH";
598
+ strategy: PoolSelectionStrategy;
599
+ }>;
600
+ selections: UserPoolSelection[];
601
+ };
602
+ /**
603
+ * What a user's account currently has saved (ROUT-650): each asset's strategy,
604
+ * plus the pool list of every protocol/chain pair frozen by an earlier Save.
605
+ * Pairs Zyfai still autoselects are left out, so "no entry" means "default"
606
+ * (nothing saved). A pair that is present with empty `pools` means none
607
+ * chosen: the user picked none of that pair's pools.
608
+ */
609
+ type SavedPoolSelection = {
610
+ strategies: Array<{
611
+ asset: "USDC" | "WETH";
612
+ strategy: string;
613
+ }>;
614
+ pairs: Array<{
615
+ protocolId: string;
616
+ chainId: number;
617
+ pools: string[];
618
+ }>;
619
+ };
620
+ /** One protocol with its pools for the deposit asset — what the Pools step
621
+ * renders: a protocol row that opens to a list of selectable pools. */
622
+ type PoolCatalogProtocol = {
623
+ protocolId: string;
624
+ name: string;
625
+ logo: string | null;
626
+ pools: AvailablePool[];
627
+ };
628
+
500
629
  type DepositCallback = (smartWalletAddress: string, chainId: number, amount: string) => Promise<`0x${string}`> | `0x${string}`;
501
630
  /**
502
631
  * Read access to the funding ledger, given to agents by the client so they can
@@ -520,6 +649,13 @@ type AgentFundingLedgerAccess = {
520
649
  before: Date;
521
650
  }): Promise<ProviderSnapshotSample | null>;
522
651
  };
652
+ /** What an agent did with a confirmed-deposit notice (`IAgent.depositConfirmed`). */
653
+ type DepositNotice = {
654
+ notified: true;
655
+ } | {
656
+ notified: false;
657
+ reason: string;
658
+ };
523
659
  interface IAgent {
524
660
  readonly id: string;
525
661
  readonly supportedChainIds: readonly OwneySupportedChainId[];
@@ -565,7 +701,20 @@ interface IAgent {
565
701
  beforeRequest?: () => void;
566
702
  }): Promise<ZyfaiHandoffAnswer>;
567
703
  disconnect(): Promise<void>;
704
+ /**
705
+ * Ready the user's account for every asset the agent supports on `chainId`,
706
+ * `asset` first. A failure the provider says will not go away (the user can
707
+ * never have this agent) carries `details.permanent: true`, and the client
708
+ * then refuses the whole connect (`AGENT_ACTIVATION_BLOCKED`).
709
+ */
568
710
  activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
711
+ /**
712
+ * True when the provider reported this session that the user cannot have an
713
+ * agent for this chain and asset (Yieldseeker's active-agent limit). Callers
714
+ * leave the slot out of deposits. Optional: an agent without such a limit
715
+ * omits it.
716
+ */
717
+ isSlotUnavailable?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): boolean;
569
718
  /**
570
719
  * Apply the organization's agent policy to this user's account.
571
720
  *
@@ -579,6 +728,35 @@ interface IAgent {
579
728
  * unchanged rather than break the connect.
580
729
  */
581
730
  applyOrgPolicy?(state: ConnectionState, chainId: number, policy: OrgAgentConfig): Promise<void>;
731
+ /**
732
+ * The deposit-time pool catalogue for one asset and strategy: protocols with
733
+ * their selectable pools and figures. Optional — an agent with no pool
734
+ * customization omits it. (ROUT-569)
735
+ */
736
+ getPoolCatalog?(params: {
737
+ asset: string;
738
+ strategy: "conservative" | "aggressive" | "yieldmaxxing";
739
+ }): Promise<PoolCatalogProtocol[]>;
740
+ /**
741
+ * Apply a user's own pool selection to their account, driven by the
742
+ * deposit-time Pools step. Optional. A failure throws, and the caller
743
+ * must not start the deposit.
744
+ * `state` is the client's connection, or undefined when there is none; an
745
+ * agent that signs in per call (Yieldseeker) needs it, and one that is
746
+ * already connected (Zyfai) ignores it. (ROUT-569)
747
+ */
748
+ setPoolSelection?(selection: UserPoolSelectionRequest, state?: ConnectionState): Promise<void>;
749
+ /**
750
+ * Read back what `setPoolSelection` saved, for the pairs and assets given,
751
+ * so the Pools step can open on the user's own choices. Optional. (ROUT-650)
752
+ */
753
+ getPoolSelection?(state: ConnectionState, chainId: number, params: {
754
+ pairs: Array<{
755
+ protocolId: string;
756
+ chainId: number;
757
+ }>;
758
+ assets: Array<"USDC" | "WETH">;
759
+ }): Promise<SavedPoolSelection>;
582
760
  deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>,
583
761
  /** `operationId`: the funding ledger operation. Zyfai hands the deposit's
584
762
  * registration to the server with it (only agents with
@@ -600,6 +778,14 @@ interface IAgent {
600
778
  verifyWithdrawalCompletion?(state: ConnectionState, evidence: FundingEvidence): Promise<WithdrawalCompletion>;
601
779
  /** A newly observed pool allocation invalidates this asset's portfolio cache only. */
602
780
  invalidateAllocationRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
781
+ /**
782
+ * A deposit into this agent just confirmed on-chain. An agent whose provider
783
+ * can act on a deposit at once tells it here (Yieldseeker then allocates it
784
+ * instead of waiting for its next scheduled check). The client calls it once
785
+ * per confirmed transfer, in the background: it must never prompt the wallet
786
+ * and never throw. Agents without it rely on their provider's own discovery.
787
+ */
788
+ depositConfirmed?(state: ConnectionState, chainId: number, evidence: FundingEvidence): Promise<DepositNotice>;
603
789
  /** Invalidate only the confirmed asset. This hook must not sign or submit transactions. */
604
790
  invalidateFundingRead?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
605
791
  /** End accelerated balance reads only for the exact snapshot the caller displayed. */
@@ -617,6 +803,13 @@ interface IAgent {
617
803
  /** Optional positive proof for a repeat deposit; unknown must fall back to portfolio validation. */
618
804
  hasExistingDepositFunds?(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
619
805
  getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
806
+ /**
807
+ * Whether this wallet can be read on `chainId` from a saved sign-in, with no
808
+ * wallet prompt. Lets the whole-portfolio reads include an agent that does
809
+ * not run on the connection chain (Yieldseeker on Base while the wallet is
810
+ * on Arbitrum); agents without it are read only while active.
811
+ */
812
+ hasReadSession?(state: ConnectionState, chainId: number): boolean;
620
813
  getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
621
814
  /** Funding-ledger read access for earnings holds. Optional; without it an agent behaves as before. */
622
815
  setFundingLedgerAccess?(access: AgentFundingLedgerAccess | undefined): void;
@@ -635,7 +828,14 @@ interface IAgent {
635
828
  * Optional asset symbol ("USDC" / "WETH") scoping the daily series to a
636
829
  * single asset on the chain. Agents without per-asset positions ignore it.
637
830
  */
638
- tokenSymbol?: string): Promise<AccountAgentApy>;
831
+ tokenSymbol?: string,
832
+ /**
833
+ * Chain the series is scoped to, when that differs from the chain the
834
+ * connection is on. `null` spans every chain the wallet held (ROUT-479);
835
+ * omitted means `chainId`. Kept apart from `chainId` because that one
836
+ * still resolves the wallet and must stay a real, connected chain.
837
+ */
838
+ scopeChainId?: number | null): Promise<AccountAgentApy>;
639
839
  /**
640
840
  * Daily cumulative earnings in token units, scoped to a chain/asset, using
641
841
  * the provider's earnings basis. Include an opening snapshot when available
@@ -682,11 +882,27 @@ type AvailableAgent = {
682
882
  supportedChainIds: readonly number[];
683
883
  supportedAssets: readonly AgentSupportedAssets[];
684
884
  };
885
+ type ActivateAgentOptions = {
886
+ /** Limits agent setup to what this asset needs. Omit for every asset. */
887
+ asset?: OwneySupportedTokens;
888
+ /**
889
+ * Called once the chain and agents are registered, before any agent signs in
890
+ * or runs its setup. From then on reads such as `getBalances` are safe to
891
+ * start: each agent's reads wait on that agent's own sign-in, so they share
892
+ * the activation's one wallet prompt instead of waiting for all of setup.
893
+ */
894
+ onAgentsSelected?: () => void;
895
+ };
685
896
  type AvailableAgentsOptions = {
686
897
  chainId?: number;
687
898
  asset?: Asset;
688
- /** Disabled agents are omitted by default because they cannot accept funds. */
899
+ /** Disabled agents are omitted by default because they cannot accept funds.
900
+ * Listing them also lists unavailable agents: both may still hold funds. */
689
901
  includeDisabled?: boolean;
902
+ /** Agents unavailable on `chainId` and `asset` this session are omitted by
903
+ * default because they get no deposits: their provider has no agent for the
904
+ * slot. See `OwneySDK.getUnavailableAgentIds`. */
905
+ includeUnavailable?: boolean;
690
906
  };
691
907
  /**
692
908
  * A lookback window for any "last N days" read — the APY series, the daily
@@ -717,6 +933,15 @@ type HistoryOptions = {
717
933
  chainId?: number;
718
934
  agentId?: AgentId;
719
935
  filters?: HistoryFilters;
936
+ /**
937
+ * Chains to read, instead of the one `activateAgent` last set (ROUT-479).
938
+ *
939
+ * Each chain pages independently and the results merge into one
940
+ * chronological list, with every entry stamped with the chain it came from.
941
+ * Omit for the single-chain behaviour, which stays the default: fanning out
942
+ * by default would multiply every existing caller's request count.
943
+ */
944
+ chainIds?: OwneySupportedChainId[];
720
945
  };
721
946
  type WithdrawOptions = {
722
947
  /** Internal orchestration observation deadline; never retries a send. */
@@ -741,6 +966,12 @@ type WithdrawOptions = {
741
966
  * their own so the app record and the ledger share one reference. It is also
742
967
  * the withdrawal reservation's operationId. */
743
968
  operationId?: string;
969
+ /**
970
+ * Groups this withdrawal with the others started by one user action (a
971
+ * "withdraw all" sends one per asset). A UUID, recorded on the funding
972
+ * ledger's operation; a value that is not a UUID is ignored.
973
+ */
974
+ batchId?: string;
744
975
  /**
745
976
  * Cross-device withdrawal reservation options.
746
977
  * - `override`: the `reference` from an overridable `RESERVED_ELSEWHERE`
@@ -750,6 +981,11 @@ type WithdrawOptions = {
750
981
  * this SDK still has that operation's holder token; otherwise ignored.
751
982
  */
752
983
  reservation?: WithdrawalReservationOptions;
984
+ /**
985
+ * Chain to withdraw from. Defaults to the chain `activateAgent` last set.
986
+ * See `DepositOptions.chainId` — the same rules apply.
987
+ */
988
+ chainId?: number;
753
989
  };
754
990
  /** `WithdrawOptions.reservation`: see there. */
755
991
  type WithdrawalReservationOptions = {
@@ -759,6 +995,18 @@ type WithdrawalReservationOptions = {
759
995
  type AccountApyOptions = {
760
996
  agentId?: AgentId;
761
997
  days: LookbackDays;
998
+ /**
999
+ * Chain to scope the daily series to, instead of the one `activateAgent`
1000
+ * last set (ROUT-479).
1001
+ *
1002
+ * `"all"` blends every chain the wallet held that day, which is what the
1003
+ * chart's "All chains" filter asks for. Unlike the history and earnings
1004
+ * reads this needs no fan-out: the provider's daily-APY payload is already
1005
+ * wallet-wide and names each position's chain, so the scope is a filter over
1006
+ * one response rather than several calls. Omit for the active chain, which
1007
+ * stays the default.
1008
+ */
1009
+ chainId?: OwneySupportedChainId | "all";
762
1010
  /**
763
1011
  * Optional asset symbol (e.g. "USDC", "WETH") to scope the daily APY series
764
1012
  * to a specific asset on the active chain. Without it the series blends every
@@ -776,6 +1024,14 @@ type AccountApyOptions = {
776
1024
  type DailyEarningsOptions = {
777
1025
  agentId?: AgentId;
778
1026
  days: LookbackDays;
1027
+ /**
1028
+ * Chains to read, instead of the one `activateAgent` last set (ROUT-479).
1029
+ *
1030
+ * The same asset is summed across them — USDC on Base and USDC on Arbitrum
1031
+ * are the same unit. Different assets stay apart, as they already do within
1032
+ * one chain. Omit for the single-chain behaviour, which stays the default.
1033
+ */
1034
+ chainIds?: OwneySupportedChainId[];
779
1035
  /**
780
1036
  * Optional asset symbol (e.g. "USDC", "WETH") scoping the series to one
781
1037
  * asset on the active chain.
@@ -818,10 +1074,39 @@ type DepositOptions = {
818
1074
  asset: Asset;
819
1075
  depositCallback?: DepositCallback;
820
1076
  agentId?: AgentId;
1077
+ /**
1078
+ * Agents that must receive nothing from this deposit. The rest split the
1079
+ * whole amount, and only their minimums apply; an excluded agent is not read,
1080
+ * not prioritized as unfunded and not reported on.
1081
+ *
1082
+ * Throws `ALL_AGENTS_EXCLUDED` (before anything is read or sent) when no
1083
+ * agent is left, or when `agentId` itself is listed. Unknown ids are ignored.
1084
+ * Ignored by `resumeTxHash` and `resumeSavedBatch`: a signed batch is already
1085
+ * committed to its wallets and must be finished as signed.
1086
+ */
1087
+ excludeAgentIds?: AgentId[];
821
1088
  onApproved?: () => void;
822
1089
  /** Funding ledger reference (a UUID). Defaults to a new random UUID; apps pass
823
1090
  * their own so the app record and the ledger share one reference. */
824
1091
  operationId?: string;
1092
+ /**
1093
+ * Groups this deposit with the others started by one user action (a spread
1094
+ * deposit sends one per position). A UUID, recorded on the funding ledger's
1095
+ * operation; a value that is not a UUID is ignored.
1096
+ */
1097
+ batchId?: string;
1098
+ /**
1099
+ * Chain to deposit on. Defaults to the chain `activateAgent` last set, so
1100
+ * omitting it behaves exactly as before.
1101
+ *
1102
+ * Pass it to fund several chains in a row without re-activating between
1103
+ * them (ROUT-245's spread strategies). It selects the target; it does not
1104
+ * replace activation, which is what populates `activeAgents`, and it does
1105
+ * not remove the wallet's network switch — the default deposit callbacks
1106
+ * still put the wallet on this chain before signing, since a deposit
1107
+ * signature is EIP-712 with the chain in its domain.
1108
+ */
1109
+ chainId?: number;
825
1110
  };
826
1111
 
827
1112
  type FundingStage = "pending" | "confirmed" | "unknown" | "failed" | "not-applicable";
@@ -1154,6 +1439,25 @@ type OwneyRecentAsyncWithdrawal = {
1154
1439
  chainId: number;
1155
1440
  asset: string;
1156
1441
  };
1442
+ /**
1443
+ * One position drained by `withdrawAll()` — a chain and asset pair.
1444
+ *
1445
+ * Carries either a result or an error, never both: a leg that failed while
1446
+ * others succeeded is the normal case, not an exception, and the caller needs
1447
+ * to name the ones that did not arrive.
1448
+ */
1449
+ interface OwneyWithdrawAllLeg {
1450
+ chainId: OwneySupportedChainId;
1451
+ asset: OwneySupportedTokens;
1452
+ /** What the position held when the sweep started. */
1453
+ amount: string;
1454
+ result?: OwneyWithdrawResult | AgentWithdrawResult;
1455
+ error?: string;
1456
+ }
1457
+ interface OwneyWithdrawAllResult {
1458
+ /** Every position attempted, in the order it was attempted. */
1459
+ legs: OwneyWithdrawAllLeg[];
1460
+ }
1157
1461
  interface OwneyBalances {
1158
1462
  totalBalance: string;
1159
1463
  /** Asset that `totalBalance` is denominated in. Currently always `"usdc"`. */
@@ -1182,17 +1486,61 @@ interface OwneyEarnings {
1182
1486
  agentRetryAt?: Partial<Record<AgentId, number>>;
1183
1487
  }
1184
1488
  type ApyByChainAndAsset = Partial<Record<OwneySupportedChainId, Partial<Record<OwneySupportedTokens, number>>>>;
1489
+ /** One external reward program contributing percentage points to a day. */
1490
+ interface ApyIncentive {
1491
+ source: "merkl";
1492
+ agentId: AgentId;
1493
+ opportunityId: string;
1494
+ /** All on-chain campaigns represented by the opportunity APR that day. */
1495
+ campaignIds: string[];
1496
+ /** Source APR before portfolio weighting, expressed as a percentage. */
1497
+ apr: number;
1498
+ /** Percentage points to add to this point's native/provider `apy`. */
1499
+ apyContribution: number;
1500
+ }
1185
1501
  /** A single day's net APY for the connected account, as a percentage number. */
1186
1502
  interface ApyHistoryPoint {
1187
1503
  /** ISO date string for the day, e.g. "2026-06-20". */
1188
1504
  date: string;
1189
- /** Net (after-fee) weighted APY for that day, summed across tokens. */
1505
+ /** Native/provider net APY. External incentives are deliberately excluded. */
1190
1506
  apy: number;
1191
1507
  /** Balance on this date, in the explicitly named unit; never today's balance. */
1192
1508
  historicalBalance?: {
1193
1509
  amount: number;
1194
1510
  unit: string;
1195
1511
  };
1512
+ /** Best-effort external rewards. Absent when none apply or cannot be read. */
1513
+ incentives?: ApyIncentive[];
1514
+ }
1515
+ /**
1516
+ * What the APY chart's chain/asset menus are allowed to offer, and how far
1517
+ * back each option reaches (ROUT-479).
1518
+ *
1519
+ * An option only earns a place if some day in the window held a real position
1520
+ * on it — a balance and a rate. Listing anything else would offer a filter
1521
+ * that draws a blank chart. `days` is what the menu prints beside each row,
1522
+ * and the legs genuinely differ: a wallet can hold USDC for a fortnight and
1523
+ * WETH for three days.
1524
+ */
1525
+ interface ApyCoverage {
1526
+ chains: {
1527
+ chainId: number;
1528
+ days: number;
1529
+ }[];
1530
+ /** Legs whose `tokenSymbol` the provider left unset are absent — they cannot
1531
+ * be named, so they cannot be picked. Their chain still counts. */
1532
+ assets: {
1533
+ asset: string;
1534
+ days: number;
1535
+ }[];
1536
+ /** Each asset on each chain, for a menu that offers the two together
1537
+ * (ROUT-647). The lists above cannot say this: USDC on Base and WETH on
1538
+ * Arbitrum put both chains and both assets in them, and no WETH on Base. */
1539
+ pairs: {
1540
+ chainId: number;
1541
+ asset: string;
1542
+ days: number;
1543
+ }[];
1196
1544
  }
1197
1545
  interface AccountAgentApy {
1198
1546
  walletAddress: string;
@@ -1204,6 +1552,8 @@ interface AccountAgentApy {
1204
1552
  * date. Empty when the provider returns no daily history.
1205
1553
  */
1206
1554
  history?: ApyHistoryPoint[];
1555
+ /** Which chains/assets this history can be filtered down to. */
1556
+ coverage?: ApyCoverage;
1207
1557
  }
1208
1558
  interface OwneyAccountApy {
1209
1559
  totalApy: string;
@@ -1277,12 +1627,28 @@ interface AgentHistoryEntry {
1277
1627
  id?: string;
1278
1628
  agent: AgentId;
1279
1629
  action: HistoryAction;
1630
+ /**
1631
+ * Chain this entry came from, stamped by the history fan-out (ROUT-479).
1632
+ *
1633
+ * Absent on a single-chain read, where the caller already knows the chain.
1634
+ * The entry has no chain of its own otherwise: `transactions[].chainId` is
1635
+ * optional and missing whenever the indexer has not attached the transfer,
1636
+ * so a row cannot be labelled from it reliably.
1637
+ */
1638
+ chainId?: OwneySupportedChainId;
1280
1639
  date: string;
1281
1640
  oldApy: string | null;
1282
1641
  newApy: string | null;
1283
1642
  transactions: HistoryTransaction[];
1284
1643
  rebalanceLog: RebalanceLog[];
1285
1644
  positions?: AgentHistoryPosition[];
1645
+ /**
1646
+ * Set on a `Withdraw` that was only requested from an async vault
1647
+ * (ROUT-624). The vault pays out in batches later, so the funds have not
1648
+ * reached the wallet yet and `transactions[0].amount` is the amount
1649
+ * requested.
1650
+ */
1651
+ asyncRequest?: true;
1286
1652
  }
1287
1653
  interface OwneyAgentHistory {
1288
1654
  agentErrors?: Partial<Record<AgentId, string>>;
@@ -1404,7 +1770,7 @@ type WithdrawalPayoutScan = {
1404
1770
  caughtUp: boolean;
1405
1771
  };
1406
1772
 
1407
- type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "AGENT_ACTIVATION_PARTIAL_FAILURE" | "YIELDSEEKER_AGENT_MISSING" | "YIELDSEEKER_WALLET_UNVERIFIED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_IN_PROGRESS" | "DEPOSIT_CHECKPOINT_FAILED" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_INVALID_AMOUNT" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "WITHDRAW_IN_PROGRESS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_BALANCE_UNAVAILABLE" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_UNCONFIRMED" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_SWAP_INCOMPLETE" | "WITHDRAW_FAILED" | "WITHDRAW_INVALID_AMOUNT" | "WITHDRAW_RESERVATION_UNAVAILABLE" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "AGENT_API_ERROR" | "AGENT_AUTH_FAILED" | "AGENT_INVALID_RESPONSE" | "AGENT_TIMEOUT" | "AGENT_TRANSACTION_REVERTED" | "AGENT_APY_PERIOD_UNSUPPORTED" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "EARNINGS_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "VALIDATION_INVALID_DAYS";
1773
+ type OwneyErrorCode = "NOT_CONNECTED" | "NO_ACTIVE_CHAIN" | "WALLET_NO_ACCOUNTS" | "WALLET_ADDRESS_REQUIRED" | "WALLET_NOT_DEPLOYED" | "AGENT_NOT_FOUND" | "AGENT_CHAIN_INCOMPATIBLE" | "AGENT_EMPTY_LIST" | "AGENT_DISABLED" | "AGENT_ACTIVATION_PARTIAL_FAILURE" | "AGENT_ACTIVATION_BLOCKED" | "YIELDSEEKER_AGENT_MISSING" | "YIELDSEEKER_AGENT_CLOSED" | "YIELDSEEKER_SLOT_UNAVAILABLE" | "YIELDSEEKER_WALLET_UNVERIFIED" | "CHAIN_UNSUPPORTED" | "CHAIN_NO_COMPATIBLE_AGENTS" | "CHAIN_MISMATCH" | "ASSET_UNSUPPORTED" | "ASSET_NO_COMPATIBLE_AGENTS" | "DEPOSIT_BALANCE_UNAVAILABLE" | "DEPOSIT_PARTIAL_FAILURE" | "DEPOSIT_IN_PROGRESS" | "DEPOSIT_CHECKPOINT_FAILED" | "DEPOSIT_AMOUNT_BELOW_MINIMUM" | "DEPOSIT_INVALID_AMOUNT" | "DEPOSIT_CALLBACK_REQUIRED" | "DEPOSIT_CALLBACK_INVALID" | "DEPOSIT_NO_PERMITTED_TOKENS" | "DEPOSIT_INSUFFICIENT_BALANCE" | "ALL_AGENTS_EXCLUDED" | "WITHDRAW_IN_PROGRESS" | "WITHDRAW_NO_PERMITTED_TOKENS" | "WITHDRAW_BALANCE_UNAVAILABLE" | "WITHDRAW_INSUFFICIENT_BALANCE" | "WITHDRAW_ALL_FAILED" | "WITHDRAW_UNCONFIRMED" | "WITHDRAW_NOTHING_TO_WITHDRAW" | "WITHDRAW_PARTIAL_FAILURE" | "WITHDRAW_SWAP_INCOMPLETE" | "WITHDRAW_FAILED" | "WITHDRAW_INVALID_AMOUNT" | "WITHDRAW_RESERVATION_UNAVAILABLE" | "AGENT_RATE_LIMITED" | "API_ROUTING_ERROR" | "API_ROUTING_FAILED" | "API_NO_AGENTS" | "AGENT_API_ERROR" | "AGENT_AUTH_FAILED" | "AGENT_INVALID_RESPONSE" | "AGENT_TIMEOUT" | "AGENT_TRANSACTION_REVERTED" | "AGENT_APY_PERIOD_UNSUPPORTED" | "SPONSOR_REQUEST_FAILED" | "PERMIT2_APPROVAL_REQUIRED" | "SPONSORED_CALLS_UNSUPPORTED" | "SPONSORED_CALLS_NO_ID" | "SPONSORED_CALLS_NO_RECEIPT" | "SWAP_DISABLED" | "SWAP_RATE_LIMITED" | "SWAP_REQUEST_FAILED" | "SWAP_QUOTE_FAILED" | "SWAP_UNSUPPORTED_PAIR" | "SWAP_APPROVAL_REQUIRED" | "SWAP_BELOW_DEPOSIT_MINIMUM" | "SWAP_DEPOSIT_PENDING" | "SWAP_WALLET_PROMPT_TIMEOUT" | "SWAP_INSUFFICIENT_GAS" | "SWAP_NATIVE_UNSUPPORTED" | "SWAP_ORDER_EXPIRED" | "SWAP_ORDER_REFUNDED" | "SWAP_ORDER_CANCELLED" | "SWAP_ORDER_NOT_FOUND" | "WITHDRAW_ARRIVAL_TIMEOUT" | "WITHDRAW_SWAP_FAILED" | "BALANCE_ALL_FAILED" | "EARNINGS_ALL_FAILED" | "ALLOCATION_ALL_FAILED" | "POOL_CATALOG_UNSUPPORTED" | "POOL_SELECTION_UNSUPPORTED" | "POOL_SELECTION_NOT_APPLIED" | "POOL_SELECTION_RULE_LIMIT" | "VALIDATION_INVALID_DAYS";
1408
1774
  declare class OwneyError extends Error {
1409
1775
  readonly code: OwneyErrorCode;
1410
1776
  readonly details?: Record<string, unknown>;
@@ -1457,6 +1823,12 @@ type WithdrawSwapRecord = {
1457
1823
  * is continued or rechecked. Absent on records written by an older SDK.
1458
1824
  */
1459
1825
  operationId?: string;
1826
+ /**
1827
+ * The batch this withdrawal belongs to (see `WithdrawOptions.batchId`), kept
1828
+ * so a continuation or recheck reports into the same batch. Absent when the
1829
+ * withdrawal was not part of one.
1830
+ */
1831
+ batchId?: string;
1460
1832
  recovery?: WithdrawalSwapRecovery;
1461
1833
  spent?: string;
1462
1834
  dismissed?: boolean;
@@ -1551,6 +1923,11 @@ type PendingDeposit = {
1551
1923
  * it. Absent on records written by an older SDK.
1552
1924
  */
1553
1925
  operationId?: string;
1926
+ /**
1927
+ * The user action's batch (see `DepositOptions.batchId`), so finishing the
1928
+ * deposit later reports under it. Absent when the swap had none.
1929
+ */
1930
+ batchId?: string;
1554
1931
  };
1555
1932
  /** Every record, dismissed ones included, newest first. Sweeps as it goes. */
1556
1933
  declare function listPendingDeposits(now?: number): PendingDeposit[];
@@ -1564,6 +1941,14 @@ declare class OwneySDK {
1564
1941
  * withdraw, but they are excluded from new deposits / activations.
1565
1942
  */
1566
1943
  private disabledAgents;
1944
+ /**
1945
+ * Agents whose sign-in the user cancelled this session (the wallet rejected
1946
+ * the prompt), keyed by chain. Until the app ends the session they are read
1947
+ * from a saved sign-in only (`readStateFor`), so no read reopens the prompt
1948
+ * the user cancelled. A later successful activation of the agent removes
1949
+ * it, and `disconnect()` or a different wallet's `connect()` clears the map.
1950
+ */
1951
+ private declinedSignIns;
1567
1952
  private state;
1568
1953
  private connectionRevision;
1569
1954
  private disconnectingAgents;
@@ -1574,6 +1959,7 @@ declare class OwneySDK {
1574
1959
  private zyfaiRpcUrls?;
1575
1960
  private yieldseekerApiBaseUrl?;
1576
1961
  private yieldseekerSiweOrigin?;
1962
+ private userPoolCustomization;
1577
1963
  private routingApiBaseUrl?;
1578
1964
  private referralSource?;
1579
1965
  private readonly ledger;
@@ -1594,6 +1980,8 @@ declare class OwneySDK {
1594
1980
  * session started: true when it armed the refresh, false when its deadline
1595
1981
  * had passed (it only dropped the cache and forced one snapshot read). */
1596
1982
  private readonly recoveredFundingReads;
1983
+ /** Confirmed deposits already announced to their agent (`depositConfirmed`), bounded. */
1984
+ private readonly announcedDeposits;
1597
1985
  private fundingBalanceChecks;
1598
1986
  private readonly activationChecks;
1599
1987
  private readonly withdrawalSubmissions;
@@ -1669,6 +2057,33 @@ declare class OwneySDK {
1669
2057
  private clearConnectionState;
1670
2058
  private disconnectAgents;
1671
2059
  private isAgentDisabled;
2060
+ /**
2061
+ * True when `id` takes no new deposits on this chain and asset this
2062
+ * session: its adapter reports no agent for the slot.
2063
+ */
2064
+ private isAgentUnavailable;
2065
+ /**
2066
+ * The agents that take no new deposits on this chain and asset this
2067
+ * session, so the app can show them as unavailable: each agent whose
2068
+ * provider has no agent for this slot. They stay withdrawable.
2069
+ */
2070
+ getUnavailableAgentIds(chainId: number, asset?: string): AgentId[];
2071
+ /**
2072
+ * The adapter reports no agent for this chain and asset this session (see
2073
+ * `IAgent.isSlotUnavailable`): there is nothing there to withdraw, so a
2074
+ * withdrawal without an explicit agent leaves it out instead of failing its
2075
+ * leg.
2076
+ */
2077
+ private hasNoAgentForSlot;
2078
+ /**
2079
+ * The state an agent's reads use. An agent whose sign-in the user cancelled
2080
+ * on the connection chain this session is read from a saved sign-in only,
2081
+ * as `offChainPortfolioAgents` reads: a read that would need a wallet
2082
+ * prompt fails for that agent instead of reopening the prompt the user
2083
+ * cancelled. A later successful activation of the agent, or `disconnect()`,
2084
+ * lifts it.
2085
+ */
2086
+ private readStateFor;
1672
2087
  /**
1673
2088
  * Check if the SDK has an active connection state.
1674
2089
  * @returns `true` if `connect()` has been called and `disconnect()` has not
@@ -1713,6 +2128,18 @@ declare class OwneySDK {
1713
2128
  private getAgent;
1714
2129
  getActiveAgentIds(): AgentId[];
1715
2130
  private getActiveAgents;
2131
+ /**
2132
+ * Agents that do not run on the connection chain but can be read on their
2133
+ * own from a saved sign-in: Yieldseeker, Base-only, while the wallet sits on
2134
+ * Arbitrum or Ethereum. The whole-portfolio reads (ROUT-479) add them, under
2135
+ * a promptless state; with no saved sign-in they are left out, as before.
2136
+ */
2137
+ private offChainPortfolioAgents;
2138
+ /** Every agent a whole-portfolio read covers: the active ones on the
2139
+ * connection chain, then the off-chain ones on their own chain. */
2140
+ private portfolioReads;
2141
+ /** The active agents, each with the state its reads use (`readStateFor`). */
2142
+ private activeReads;
1716
2143
  /**
1717
2144
  * Read the org's agent policy once and reuse it. fetchOrgAgentConfig never
1718
2145
  * throws — it degrades to null — so this cannot break activation.
@@ -1743,8 +2170,17 @@ declare class OwneySDK {
1743
2170
  * that support the given chainId (incompatible agents are silently skipped).
1744
2171
  * If provided, ALL specified agents must support the chainId or the call
1745
2172
  * throws before activating any agent.
1746
- */
1747
- activateAgent(chainId: number, agentId?: AgentId[], asset?: OwneySupportedTokens): Promise<void>;
2173
+ * @param options - Optional. `asset` limits setup to that asset;
2174
+ * `onAgentsSelected` fires once reads can start.
2175
+ * @throws Activation stops at the first agent that fails, and the caller
2176
+ * should end the session. `AGENT_ACTIVATION_PARTIAL_FAILURE` when an
2177
+ * earlier agent activated; `walletRejected` in its details means the user
2178
+ * rejected a signature. `AGENT_ACTIVATION_BLOCKED` when the agent can
2179
+ * never be readied (`details.permanent`). Otherwise the agent's own error
2180
+ * is thrown as is. Until it signs in, an agent whose signature the user
2181
+ * rejected is read from a saved sign-in only and opens no prompt.
2182
+ */
2183
+ activateAgent(chainId: number, agentId?: AgentId[], options?: ActivateAgentOptions): Promise<void>;
1748
2184
  private assertActivationSession;
1749
2185
  /**
1750
2186
  * Activate agents ONE AT A TIME, each followed by its org policy.
@@ -1759,9 +2195,13 @@ declare class OwneySDK {
1759
2195
  * Serializing costs no real wall-clock: the user can only approve one prompt
1760
2196
  * at a time anyway.
1761
2197
  *
1762
- * Stop at the first failure so a canceled sign-in does not open another
1763
- * agent's wallet prompt. Report any earlier successes for diagnostics; the
1764
- * app discards the session when the complete sign-in does not succeed.
2198
+ * Stop at the first failure (2026-11-06): a connect needs every agent, so
2199
+ * no later agent's wallet prompt opens for a sign-in that already failed.
2200
+ * When an earlier agent activated, the partial failure reports it, and
2201
+ * `walletRejected` tells the app the user canceled; the app ends the
2202
+ * session either way. When none activated, the agent's own error is thrown.
2203
+ * A failure the provider marks `permanent` is thrown as
2204
+ * `AGENT_ACTIVATION_BLOCKED`.
1765
2205
  */
1766
2206
  private activateAgentsInTurn;
1767
2207
  /**
@@ -1776,6 +2216,10 @@ declare class OwneySDK {
1776
2216
  * all shares into one signature; custom callbacks still run once per agent.
1777
2217
  * @param options.agentId - Optional explicit target. Otherwise split equally,
1778
2218
  * or fund remaining agents when a recovery deposit cannot meet every minimum.
2219
+ * @param options.excludeAgentIds - Agents that must receive nothing. The rest
2220
+ * split the whole amount under their own minimums. Throws
2221
+ * `ALL_AGENTS_EXCLUDED` when none is left or `agentId` is listed. Ignored
2222
+ * when resuming a signed batch.
1779
2223
  * @returns {OwneyDepositResult} for a single agent, or {OwneyMultiDepositResult} with per-agent results
1780
2224
  */
1781
2225
  deposit(options: DepositOptions): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
@@ -1807,6 +2251,13 @@ declare class OwneySDK {
1807
2251
  * doesn't force a retry of sibling agents in a multi-agent split.
1808
2252
  */
1809
2253
  private depositWithFallback;
2254
+ /**
2255
+ * Refuses a new deposit that `excludeAgentIds` leaves with nobody to fund:
2256
+ * the explicit `agentId` is listed, or every agent that can take this asset
2257
+ * on this chain (and is not disabled) is. A no-op without a list, so a deposit
2258
+ * without exclusions is exactly as it was. Reads no provider.
2259
+ */
2260
+ private assertDepositAgentsRemain;
1810
2261
  private getMinDepositAmount;
1811
2262
  private splitDepositAmount;
1812
2263
  private formatAgentName;
@@ -1818,7 +2269,30 @@ declare class OwneySDK {
1818
2269
  * false, so the minimum is enforced as today.
1819
2270
  */
1820
2271
  private hasExistingBalance;
2272
+ /**
2273
+ * Guard an explicitly requested chain against one agent's own list.
2274
+ *
2275
+ * Only reachable when the caller passes `chainId` — the activated chain has
2276
+ * already been checked by `activateAgent`. Kept separate from
2277
+ * `validateAssetSupport` so "this agent is not on Ethereum" does not arrive
2278
+ * worded as "this agent does not support USDC".
2279
+ */
2280
+ private validateChainSupport;
2281
+ /**
2282
+ * Guard an explicitly requested chain before a fan-out.
2283
+ *
2284
+ * Without this the split simply produces no agents, and the caller is told
2285
+ * their amount "cannot activate every eligible agent" against a combined
2286
+ * minimum of 0 — an error about the amount when the chain is at fault.
2287
+ */
2288
+ private validateChainHasAgents;
1821
2289
  private validateAssetSupport;
2290
+ /**
2291
+ * The agents that support this asset on this chain. `excludeDisabled` is for
2292
+ * new deposits: it also leaves out the agents unavailable for this slot this
2293
+ * session (see `getUnavailableAgentIds`). Without it, withdrawals and deposit
2294
+ * recovery still see every agent that may hold funds.
2295
+ */
1822
2296
  private getEligibleAgents;
1823
2297
  /**
1824
2298
  * Run owner-approved withdrawals before relayer-only withdrawals. Wallet
@@ -1826,6 +2300,11 @@ declare class OwneySDK {
1826
2300
  * operation, so no relayer leg should commit before it has completed.
1827
2301
  */
1828
2302
  private orderAgentsForWithdrawal;
2303
+ /**
2304
+ * The user cancelled a wallet prompt, for any agent: see isWalletRejection.
2305
+ * That includes an agent error that kept the rejection only as text in
2306
+ * `details.cause`.
2307
+ */
1829
2308
  private isUserRejectedWithdrawal;
1830
2309
  private captureReadScope;
1831
2310
  /** Revalidate a saved transfer against the authenticated account and actual receipt. */
@@ -1834,6 +2313,14 @@ declare class OwneySDK {
1834
2313
  refreshBalance?: boolean;
1835
2314
  requireAmountMatch?: boolean;
1836
2315
  }): Promise<FundingEvidence>;
2316
+ /**
2317
+ * Tells the agent, once per confirmed deposit transfer, that its deposit
2318
+ * landed (`IAgent.depositConfirmed`), and records the outcome on the
2319
+ * deposit's ledger operation when there is one. In the background: never
2320
+ * throws and never delays the deposit. A missed notice only leaves the
2321
+ * provider on its own schedule.
2322
+ */
2323
+ private announceDepositConfirmed;
1837
2324
  private noteFundingRefresh;
1838
2325
  /**
1839
2326
  * Re-arms an agent's balance refresh after a confirmed deposit or withdrawal
@@ -1970,6 +2457,18 @@ declare class OwneySDK {
1970
2457
  * would strand funds we might have been able to move.
1971
2458
  */
1972
2459
  /** ERC20 balance of the connected wallet, read through the wallet's own node. */
2460
+ /**
2461
+ * A read client pinned to `chainId`, over HTTP rather than the wallet.
2462
+ *
2463
+ * The swap rail has read this way from the start, and the reason is written
2464
+ * out at `buildSwapDeps`: a provider-backed client reads from whatever chain
2465
+ * the WALLET is on, which after a cross-chain swap is the source chain, not
2466
+ * the one the funds landed on. The deposit's own reads did not, so a Permit2
2467
+ * check for WETH on Arbitrum went to Base — where that address is not a
2468
+ * contract at all, so viem got "0x" back and threw "The contract function
2469
+ * 'allowance' returned no data".
2470
+ */
2471
+ private chainReader;
1973
2472
  private readTokenBalance;
1974
2473
  /** How much of `token` the wallet has already approved Permit2 to move. */
1975
2474
  private readTokenPermit2Allowance;
@@ -1981,12 +2480,36 @@ declare class OwneySDK {
1981
2480
  * wallet calls also cover approval without spending the received tokens.
1982
2481
  */
1983
2482
  private settleSwapDepositAmount;
2483
+ /**
2484
+ * Deposit a swap's output, retrying once at the balance the deposit saw.
2485
+ *
2486
+ * `settleSwapDepositAmount` approves and THEN reads, but the read and the
2487
+ * deposit's own pre-check can disagree: the approval is confirmed through
2488
+ * the wallet's node, the read goes to a pinned RPC, and gas paid in WETH
2489
+ * (MetaMask offers this to a wallet with no ETH) can land after either.
2490
+ * ROUT-618 failed that way with the settle step in place.
2491
+ *
2492
+ * The pre-check reports the balance it saw, and that is the authority, so
2493
+ * a shortfall is retried once at that figure. Only a small one: a node that
2494
+ * has not caught up can read near zero, and depositing that would leave the
2495
+ * rest of the swap stranded behind a "success".
2496
+ */
2497
+ private depositSwapOutput;
1984
2498
  private walletSeesBalance;
1985
2499
  /**
1986
2500
  * Runs a quoted swap. A named seam rather than an inline `executeSwap` call
1987
2501
  * so the deposit half of `swapAndDeposit` can be exercised on its own.
1988
2502
  */
1989
2503
  private runSwap;
2504
+ /**
2505
+ * Throws SWAP_INSUFFICIENT_GAS when the wallet cannot pay for this swap.
2506
+ *
2507
+ * Only the classic rail is ever refused: it is the one where the user sends
2508
+ * the transactions. Call it on a preview quote to warn BEFORE a withdrawal
2509
+ * moves anything — `withdrawAndSwap` repeats it on its own quote, but by
2510
+ * then the funds have already left the agent (ROUT-622).
2511
+ */
2512
+ checkSwapGas(quote: SwapQuote): Promise<void>;
1990
2513
  /**
1991
2514
  * The half of the swap deps that only ever talks to the routing API.
1992
2515
  *
@@ -2033,8 +2556,19 @@ declare class OwneySDK {
2033
2556
  * second half of `swapAndDeposit` on its own. Cleared only once the deposit
2034
2557
  * has actually gone through — a failure here leaves the record in place so it
2035
2558
  * can be offered again rather than silently dropped.
2559
+ *
2560
+ * The record does not remember `excludeAgentIds`, on purpose: the caller must
2561
+ * pass the CURRENT list, because the user's choice may have changed since the
2562
+ * swap (a deposit reads it fresh each time). Without it, a record with no
2563
+ * `agentId` splits across every eligible agent. When the list leaves nobody to
2564
+ * fund (or names the record's own agent) it throws `ALL_AGENTS_EXCLUDED`
2565
+ * before the wallet is touched and keeps the record.
2566
+ *
2567
+ * @param options.excludeAgentIds - See `DepositOptions.excludeAgentIds`.
2036
2568
  */
2037
- completePendingDeposit(id: string): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
2569
+ completePendingDeposit(id: string, options?: {
2570
+ excludeAgentIds?: AgentId[];
2571
+ }): Promise<OwneyDepositResult | OwneyMultiDepositResult>;
2038
2572
  /**
2039
2573
  * Pick up cross-chain swaps a previous session left in flight.
2040
2574
  *
@@ -2171,6 +2705,13 @@ declare class OwneySDK {
2171
2705
  symbol: string;
2172
2706
  };
2173
2707
  agentId?: AgentId;
2708
+ /**
2709
+ * Agents the deposit must not fund (see `DepositOptions.excludeAgentIds`).
2710
+ * Checked before the quote, so a swap that could not end in a deposit never
2711
+ * starts. Not stored on a pending deposit: whoever finishes one later
2712
+ * passes the then-current list to `completePendingDeposit(id, options)`.
2713
+ */
2714
+ excludeAgentIds?: AgentId[];
2174
2715
  /** Percent, classic rail only. Fusion+ prices through its auction. */
2175
2716
  slippage?: number;
2176
2717
  onSwapProgress?: (stage: SwapStage) => void;
@@ -2182,6 +2723,9 @@ declare class OwneySDK {
2182
2723
  assertCurrent?: () => void;
2183
2724
  /** Funding-ledger reference for this swap and its deposit. Generated when omitted. */
2184
2725
  operationId?: string;
2726
+ /** Groups this swap and deposit with the others started by one user action
2727
+ * (see `DepositOptions.batchId`). Saved on the pending deposit record. */
2728
+ batchId?: string;
2185
2729
  }): Promise<{
2186
2730
  swap: {
2187
2731
  received: string;
@@ -2297,6 +2841,12 @@ declare class OwneySDK {
2297
2841
  * omitted; a continuation reuses the one saved on its record.
2298
2842
  */
2299
2843
  operationId?: string;
2844
+ /**
2845
+ * Groups this withdrawal with the others started by one user action (see
2846
+ * `WithdrawOptions.batchId`). Saved on the record, so a continuation
2847
+ * reports into the same batch.
2848
+ */
2849
+ batchId?: string;
2300
2850
  }): Promise<{
2301
2851
  withdraw: OwneyWithdrawResult | AgentWithdrawResult;
2302
2852
  /** What actually arrived in the wallet, smallest unit of the agent's asset. */
@@ -2386,10 +2936,24 @@ declare class OwneySDK {
2386
2936
  * @param agentId - Optional. Agent to query. Omit for aggregated balances.
2387
2937
  * @returns {AgentBalance} for a single agent, or {OwneyBalances} with totalBalance and per-agent breakdown
2388
2938
  */
2939
+ /**
2940
+ * Withdraw every position the wallet holds, across chains and assets.
2941
+ *
2942
+ * `withdraw()` drains one asset on one chain, so this is N of those. It
2943
+ * deliberately does not stop at the first failure: the funds in the other
2944
+ * positions are just as withdrawable, and someone who asked for everything
2945
+ * is better served by three of four than by none. Each leg reports its own
2946
+ * outcome so the caller can name the ones that did not arrive; only a total
2947
+ * failure throws.
2948
+ *
2949
+ * @returns {OwneyWithdrawAllResult} one leg per position attempted.
2950
+ */
2951
+ withdrawAll(): Promise<OwneyWithdrawAllResult>;
2389
2952
  getBalances(agentId?: AgentId, options?: {
2390
2953
  chainId?: number;
2391
2954
  asset?: OwneySupportedTokens;
2392
2955
  }): Promise<OwneyBalances | AgentBalance>;
2956
+ private readBalances;
2393
2957
  /** Preserve failure objects for withdrawal recovery without changing public balance results. */
2394
2958
  private readAggregatedBalances;
2395
2959
  /**
@@ -2421,8 +2985,47 @@ declare class OwneySDK {
2421
2985
  * subtract from the total. Without an agentId the series is the sum of the
2422
2986
  * agents that answered.
2423
2987
  */
2424
- getDailyEarnings({ agentId, days, tokenSymbol, }: DailyEarningsOptions): Promise<AccountDailyEarnings>;
2425
- getAccountApy({ agentId, days, tokenSymbol, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
2988
+ getDailyEarnings({ agentId, days, tokenSymbol, chainIds, }: DailyEarningsOptions): Promise<AccountDailyEarnings>;
2989
+ /**
2990
+ * The deposit-time pool catalogue (ROUT-569): every protocol with its
2991
+ * selectable pools (name, APY, TVL, link) for `asset` under `strategy`.
2992
+ * Defaults to the zyfai agent, the only one with pool customization today.
2993
+ */
2994
+ getPoolCatalog(params: {
2995
+ asset: OwneySupportedTokens;
2996
+ strategy: "conservative" | "aggressive" | "yieldmaxxing";
2997
+ agentId?: AgentId;
2998
+ }): Promise<PoolCatalogProtocol[]>;
2999
+ /**
3000
+ * Apply a user's deposit-time pool selection to their account (ROUT-569).
3001
+ * The request carries explicit pool choices plus the resulting strategy for
3002
+ * each asset reviewed in the deposit flow.
3003
+ */
3004
+ setPoolSelection(params: {
3005
+ selection: UserPoolSelectionRequest;
3006
+ agentId?: AgentId;
3007
+ }): Promise<void>;
3008
+ /**
3009
+ * The pool selection saved on the user's account (ROUT-650), so the Pools
3010
+ * step can show what applies now rather than the defaults. `pairs` and
3011
+ * `assets` say which protocol/chain lists and strategies to read.
3012
+ */
3013
+ getPoolSelection(params: {
3014
+ pairs: Array<{
3015
+ protocolId: string;
3016
+ chainId: number;
3017
+ }>;
3018
+ assets: Array<"USDC" | "WETH">;
3019
+ agentId?: AgentId;
3020
+ }): Promise<SavedPoolSelection>;
3021
+ /**
3022
+ * The agents a person can customize pools for: registered, enabled, and
3023
+ * able to list a pool catalogue. Waits for agent initialization, so an agent
3024
+ * the organization disabled is known and left out.
3025
+ */
3026
+ getPoolCustomizationAgents(): Promise<AgentId[]>;
3027
+ getAccountApy({ agentId, days, tokenSymbol, chainId: scope, }: AccountApyOptions): Promise<OwneyAccountApy | AccountAgentApy>;
3028
+ private enrichApyHistory;
2426
3029
  /**
2427
3030
  * Get transaction history for a specific agent, or all agents.
2428
3031
  *
@@ -2568,6 +3171,11 @@ declare class YieldseekerAgent implements IAgent {
2568
3171
  private readonly agentAccountReads;
2569
3172
  private readonly reportedAccounts;
2570
3173
  private readonly missingSlots;
3174
+ private readonly rethrownSlotFailures;
3175
+ private readonly closedSlots;
3176
+ private readonly pendingReopens;
3177
+ private readonly unavailableSlots;
3178
+ private readonly pendingReactivates;
2571
3179
  private readonly freshListReads;
2572
3180
  private readonly knownContextKeys;
2573
3181
  private readonly pendingSlotInvalidations;
@@ -2612,6 +3220,7 @@ declare class YieldseekerAgent implements IAgent {
2612
3220
  private ledgerBudgetMs;
2613
3221
  /** slotKey -> the last successful ledger rows and when they arrived. */
2614
3222
  private readonly lastLedgerRows;
3223
+ /** Keyed by `vaultOptionsKey`: each asset's usable list and its full list are cached apart. */
2615
3224
  private readonly vaultOptions;
2616
3225
  private readonly pendingVaultOptions;
2617
3226
  private readonly assetApyStats;
@@ -2622,6 +3231,32 @@ declare class YieldseekerAgent implements IAgent {
2622
3231
  getWalletStatus(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, useCachedV2?: boolean): Promise<YieldseekerWalletStatus | null>;
2623
3232
  /** Reads (or reuses the 15-minute verified V2 hint for) this exact context's wallet. */
2624
3233
  private readWalletStatus;
3234
+ /**
3235
+ * Deposits go only to an agent Yieldseeker still has open. The session caches
3236
+ * the selected agent, so a tab left open can hold one Yieldseeker has since
3237
+ * closed (deactivated). This reads the agent wallet fresh from Yieldseeker,
3238
+ * bypassing the cached wallet contexts, and:
3239
+ * - open, same wallet address: returns the context to deposit with;
3240
+ * - closed (`deactivatedDate` set): reactivates it, re-reads the wallet, and
3241
+ * continues only when it is now open with the same address. Only the
3242
+ * verified record's agent is reopened: any other closed agent (a
3243
+ * superseded-wallet match, or a named agent with no verified record, also
3244
+ * when the accounts could not be read) refuses without a request;
3245
+ * - anything else refuses with nothing sent, before any progress event,
3246
+ * signature or callback. Every refusal carries `notSubmitted` and
3247
+ * `safeToFallback: false`, so no paid fallback runs.
3248
+ * A slot recorded unavailable (the active-agent limit) refuses at once with
3249
+ * no request. The reactivate goes through reactivateSlot, which shares one
3250
+ * request per slot and remembers a failure for the list-cache window, so
3251
+ * repeated deposits do not repeat it. A failed wallet read fails closed
3252
+ * (YIELDSEEKER_WALLET_UNVERIFIED, reason UNAVAILABLE), like the on-chain
3253
+ * gate. A reactivate that fails keeps its error code
3254
+ * (YIELDSEEKER_AGENT_CLOSED, or the mapped API error for a transient
3255
+ * failure). At the limit the slot is also recorded unavailable for the
3256
+ * session (see isSlotUnavailable). Session changes keep their own
3257
+ * NOT_CONNECTED error.
3258
+ */
3259
+ private assertAgentOpen;
2625
3260
  /**
2626
3261
  * Deposits go only to a wallet whose identity is verified on chain (factory
2627
3262
  * mapping, owner, base asset, FACTORY). The API key is public, so the wallet
@@ -2638,7 +3273,20 @@ declare class YieldseekerAgent implements IAgent {
2638
3273
  status: YieldseekerWalletStatus;
2639
3274
  }>;
2640
3275
  disconnect(): Promise<void>;
3276
+ /**
3277
+ * Ready every asset's agent, `asset` first: a missing one is created and a
3278
+ * closed one reopened (2026-11-06). A slot Yieldseeker will never let the
3279
+ * user have (the agent limit, closed for good, missing with no way to
3280
+ * reopen) is rethrown with `details.permanent`, which refuses the connect.
3281
+ * A temporary failure (an API error or timeout) on another asset does not:
3282
+ * that slot answers again where it is needed. On the selected asset every
3283
+ * failure is thrown as before, without readying the rest, so a failed
3284
+ * sign-in never opens a second prompt.
3285
+ */
2641
3286
  activateAgent(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<void>;
3287
+ /** The same failure, marked as one that will not go away this session. */
3288
+ private permanentFailure;
3289
+ isSlotUnavailable(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): boolean;
2642
3290
  deposit(state: ConnectionState, chainId: number, amount: string, asset: OwneySupportedTokens, depositCallback?: DepositCallback, onProgress?: FundingProgress, onBeforeSubmission?: (evidence: FundingEvidence) => void | Promise<void>): Promise<OwneyDepositResult>;
2643
3291
  withdraw(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, amount?: string, onProgress?: FundingProgress, gasMode?: "auto" | "sponsored" | "paid", onBeforeSubmission?: FundingProgress, assertOperation?: () => void, submission?: {
2644
3292
  operationId?: string;
@@ -2659,22 +3307,131 @@ declare class YieldseekerAgent implements IAgent {
2659
3307
  private withdrawalVaultHints;
2660
3308
  private readWithdrawalPositions;
2661
3309
  private resolveWithdrawalLiquidity;
3310
+ hasReadSession(state: ConnectionState, chainId: number): boolean;
2662
3311
  getBalances(state: ConnectionState, chainId: number, asset?: OwneySupportedTokens): Promise<AgentBalance>;
2663
3312
  verifyWithdrawalBalance(state: ConnectionState, evidence: FundingEvidence, balance: AgentBalance): Promise<AssetReadMetadata | undefined>;
2664
3313
  invalidateAllocationRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): void;
2665
3314
  invalidateFundingRead(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, refreshUntil?: number, txHash?: string): void;
2666
3315
  endFundingBalanceRefresh(state: ConnectionState, chainId: number, asset: OwneySupportedTokens, read: AssetReadMetadata): boolean;
3316
+ /**
3317
+ * Tells Yieldseeker a deposit landed (`deposit-made`), so the agent allocates
3318
+ * it now instead of on its next 30-minute check. Yieldseeker decides whether
3319
+ * anything moves (the funding minimum, a deployed agent, no manual
3320
+ * withdrawal in the last hour). Uses the agent this session already knows
3321
+ * for the asset and the saved sign-in only: never prompts, never retries,
3322
+ * never throws.
3323
+ */
3324
+ depositConfirmed(state: ConnectionState, chainId: number, evidence: FundingEvidence): Promise<DepositNotice>;
2667
3325
  getFundingWallet(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<string>;
2668
3326
  hasExistingDepositFunds(state: ConnectionState, chainId: number, asset: OwneySupportedTokens): Promise<true | undefined>;
2669
3327
  getEarnings(state: ConnectionState, chainId: number): Promise<AgentEarnings>;
2670
- getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, tokenSymbol?: string): Promise<AccountAgentApy>;
3328
+ getAccountApy(state: ConnectionState, chainId: number, days: DailyApyDays, tokenSymbol?: string,
3329
+ /** The chart's chain filter (ROUT-479); null is every chain. */
3330
+ scopeChainId?: number | null): Promise<AccountAgentApy>;
2671
3331
  getDailyEarnings(state: ConnectionState, chainId: number, days: LookbackDays, tokenSymbol?: string): Promise<AccountDailyEarnings>;
2672
3332
  getHistory(state: ConnectionState, chainId: number, options?: HistoryFilters): Promise<OwneyAgentHistory>;
2673
3333
  getUserProfile(state: ConnectionState, chainId: number): Promise<AgentUserProfile>;
2674
3334
  getAgentApy(days: DailyApyDays, options?: AgentApyOptions): Promise<AgentApy>;
2675
3335
  supportsAgentApyPeriod(days: DailyApyDays): boolean;
2676
3336
  private loadAssetApyStats;
3337
+ /**
3338
+ * The deposit-time Pools step's catalogue: every vault Yieldseeker lists
3339
+ * for a new agent on `asset` on Base, grouped by provider (the provider is
3340
+ * both `protocolId` and `name`). Nothing is filtered on our side, on
3341
+ * liquidity, size or provider. `strategy` is accepted for the IAgent
3342
+ * contract and ignored.
3343
+ */
3344
+ getPoolCatalog(params: {
3345
+ asset: string;
3346
+ strategy?: "conservative" | "aggressive" | "yieldmaxxing";
3347
+ }): Promise<PoolCatalogProtocol[]>;
3348
+ /**
3349
+ * The asset's vaults on Base. By default only those a new agent can use:
3350
+ * Yieldseeker leaves out the ones it has disabled (40acres and Moonwell
3351
+ * among them), gated or can't use, so the picker follows its list
3352
+ * (2026-11-04). `includeUnavailable` adds those back, for anything about
3353
+ * money an agent may still hold in one: withdrawals and activity.
3354
+ */
2677
3355
  private loadVaultOptions;
3356
+ /**
3357
+ * Save the user's Yieldseeker picks as the agent's managed vault list, then
3358
+ * read the rules back before any money moves. Each asset has its own agent,
3359
+ * so each is saved on its own. `pools` and `availablePools` hold vault
3360
+ * addresses.
3361
+ *
3362
+ * - Only Base entries are ours. An asset with no picks whose entries showed
3363
+ * no vault is skipped and nothing is sent.
3364
+ * - Some vaults picked: the managed list names them. Saving it again
3365
+ * replaces it, so there is only ever one.
3366
+ * - None picked (vaults shown): the managed list names no vault, and the
3367
+ * rules must read back as an empty allow-list. Yieldseeker then keeps the
3368
+ * agent's money out of every vault, as Zyfai does with an empty pool list,
3369
+ * and the next Pools step reads "none". Only an agent that already exists
3370
+ * is written: one is never created just to hold "none".
3371
+ * - Every vault picked: the managed list is deleted, and no allow-list may
3372
+ * remain, so vaults Yieldseeker adds later are allowed too.
3373
+ * - A free-text allow-list we saved before the managed list existed is
3374
+ * deleted once the new state is written. A failed delete does not fail the
3375
+ * save; it is debug-logged, and the read-back decides.
3376
+ * - A read-back that differs puts the previous managed list back (or deletes
3377
+ * the one just created) and throws POOL_SELECTION_NOT_APPLIED. If putting
3378
+ * it back fails too, that is still the error thrown. An old free-text list
3379
+ * already deleted is not put back.
3380
+ * - An agent already holding the most active memories, none of them ours,
3381
+ * throws POOL_SELECTION_RULE_LIMIT before anything is written.
3382
+ *
3383
+ * Always Base, whichever chain the wallet is connected on.
3384
+ */
3385
+ setPoolSelection(selection: UserPoolSelectionRequest, state?: ConnectionState): Promise<void>;
3386
+ private savePoolPicks;
3387
+ /**
3388
+ * Delete the free-text allow-lists we saved before the managed list existed.
3389
+ * Never throws: a list left behind is caught by the read-back. Logs no
3390
+ * sign-in token.
3391
+ */
3392
+ private deleteLegacyPoolMemories;
3393
+ /**
3394
+ * `<address> (<name>)` for each pick, under the prefix. An unnamed address
3395
+ * has no brackets. No picks names no vault.
3396
+ */
3397
+ private poolMemoryContent;
3398
+ /** Undo a failed save of the managed list. Never throws: the caller reports the save's own failure. */
3399
+ private restorePoolMemory;
3400
+ /**
3401
+ * What the user's Yieldseeker agents currently allow, as `SavedPoolSelection`
3402
+ * pairs: the allowed vault addresses under the provider each belongs to, for
3403
+ * the vaults a new agent can use. An agent with no allow-list adds nothing,
3404
+ * and no pairs at all means every shown vault is on. Reads never create an
3405
+ * agent, and always read Base. A read that fails throws, because "no
3406
+ * allow-list" would wrongly mean "everything".
3407
+ *
3408
+ * An allow-list naming none of the listed vaults (the saved "none", or vaults
3409
+ * Yieldseeker has since stopped listing) leaves the agent nowhere to go, so
3410
+ * it reports none chosen for its asset: a pair with empty `pools` for every
3411
+ * provider listing vaults for it. With no vault listed at all there is
3412
+ * nothing to name that by, and it throws: the rules still restrict the agent.
3413
+ *
3414
+ * `pairs` is accepted for the contract but does not trim the answer: cutting
3415
+ * a real allow-list down to the pairs asked about could leave none, and none
3416
+ * reads as every vault on.
3417
+ */
3418
+ getPoolSelection(state: ConnectionState, _chainId: number, params: {
3419
+ pairs: Array<{
3420
+ protocolId: string;
3421
+ chainId: number;
3422
+ }>;
3423
+ assets: Array<"USDC" | "WETH">;
3424
+ }): Promise<SavedPoolSelection>;
3425
+ /**
3426
+ * The allow-list in the agent's rules: every `allowedVaultAddresses` on an
3427
+ * `ignored_vault` user rule. Undefined when no rule has one, which allows
3428
+ * every vault; an empty list allows none. A response that does not have the
3429
+ * expected shape throws rather than reading as no allow-list.
3430
+ */
3431
+ private readAllowList;
3432
+ private listMemories;
3433
+ /** A memory call for an agent, on Base whichever chain the wallet is on. */
3434
+ private memoryRequest;
2678
3435
  private userKey;
2679
3436
  /** One deposit/withdraw slot: owner, chain and asset. */
2680
3437
  private slotKey;
@@ -2714,23 +3471,81 @@ declare class YieldseekerAgent implements IAgent {
2714
3471
  * highest-priority set of `priorities` (index 0 first). Hinted agentIds are
2715
3472
  * resolved first and a hinted top-priority match ends the search; then other
2716
3473
  * listed agents, at most YIELDSEEKER_WALLET_MATCH_LIMIT wallets in total.
3474
+ * A candidate whose wallet shows it closed (deactivated) never ranks, and its
3475
+ * agentId is added to `closed`.
2717
3476
  */
2718
3477
  private agentWithWallet;
2719
3478
  /**
2720
3479
  * chooseAgent, re-reading a cached list once (bypassing its cache) when the
2721
- * verified agent is missing. A slot still missing after that re-read is
2722
- * remembered for the list cache window, so later reads fail from the cached
2723
- * list without another re-read.
3480
+ * verified agent is missing. Still missing, Yieldseeker may have closed
3481
+ * (deactivated) it: the verified record's agent is reactivated and selected
3482
+ * from a fresh list, by the verified wallet only (never created). A slot
3483
+ * that still fails is remembered with its error for the list cache window,
3484
+ * so later reads fail without another re-read or reactivate. A slot
3485
+ * Yieldseeker will not reopen because of its active-agent limit throws
3486
+ * YIELDSEEKER_SLOT_UNAVAILABLE, here and for the rest of the session, with
3487
+ * no request.
2724
3488
  */
2725
3489
  private chooseAgentRefreshing;
2726
- private isSlotMissing;
3490
+ private throwIfSlotUnavailable;
3491
+ /**
3492
+ * Rethrow the error a slot's lookup failed with while the slot is still
3493
+ * marked, or for the session when Yieldseeker will never reopen its agent.
3494
+ * A remembered rate limit is rethrown with the time left on its marker as
3495
+ * its retry delay (`retryAfterSeconds`): no new attempt is made before then,
3496
+ * so a caller that waits it out retries once instead of every few seconds.
3497
+ */
3498
+ private throwIfSlotMissing;
3499
+ /**
3500
+ * Remember a slot's failed lookup or reactivate for the list-cache window.
3501
+ * A sign-in failure is not remembered (the wallet's rejection,
3502
+ * AGENT_AUTH_FAILED, NOT_CONNECTED): it says nothing about the slot, and
3503
+ * remembered it would refuse the next sign-in, even one the user starts,
3504
+ * with no request for the whole window.
3505
+ */
3506
+ private rememberMissingSlot;
3507
+ /**
3508
+ * Reactivate the slot's verified agent, then read the list bypassing its
3509
+ * cache, with a read sent after the reactivate answered. Concurrent lookups
3510
+ * of one slot share one reopen. Resolves to the fresh list. At the
3511
+ * active-agent limit the slot is recorded unavailable and this throws
3512
+ * YIELDSEEKER_SLOT_UNAVAILABLE.
3513
+ */
3514
+ private reopenAgent;
3515
+ /**
3516
+ * The one way to reactivate a slot's agent, for the slot lookup (reopenAgent)
3517
+ * and the pre-deposit check (assertAgentOpen), so a slot costs at most one
3518
+ * reactivate per list-cache window:
3519
+ * - a slot recorded unavailable (the limit) answers "limit" with no request;
3520
+ * - concurrent callers share one request;
3521
+ * - a failed reactivate (closed code, rate limit, timeout, 5xx...) is
3522
+ * remembered as the slot's failure for the list-cache window (missingSlots)
3523
+ * and rethrown to later callers with no request; a closed code
3524
+ * (closedSlots) for the session; a sign-in failure is not remembered;
3525
+ * - the limit is recorded in unavailableSlots only while the session is
3526
+ * unchanged, so a disconnect during the request is not undone by its late
3527
+ * answer.
3528
+ */
3529
+ private reactivateSlot;
3530
+ /**
3531
+ * Ask Yieldseeker to reopen a closed (deactivated) agent, with the user's
3532
+ * Yieldseeker sign-in. AGENT_NOT_DEACTIVATED (already open, e.g. reopened
3533
+ * by another tab) counts as reopened; the active-agent limit is an outcome,
3534
+ * not an error. An agent that cannot come back throws
3535
+ * YIELDSEEKER_AGENT_CLOSED; any other failure (rate limit, timeout, network,
3536
+ * 5xx, an unknown code) throws the mapped API error.
3537
+ */
3538
+ private reactivateAgent;
3539
+ /** Drop the cached and in-flight wallet contexts of one agent, in every slot. */
3540
+ private forgetAgentWallet;
2727
3541
  /**
2728
3542
  * The agent that serves deposits and withdrawals for a slot (Ruling 23):
2729
3543
  * 1. the listed fitting agent whose wallet is the verified account's wallet,
2730
3544
  * whatever its name; the stored agentId is only a hint;
2731
3545
  * 2. else a listed fitting agent whose wallet is a superseded account's wallet;
2732
3546
  * 3. else the fitting agent named "owney" (first use, migration, or a
2733
- * verified wallet that is not a fitting listed agent);
3547
+ * verified wallet that is not a fitting listed agent), unless step 1/2
3548
+ * read its wallet and it is closed (deactivated): that agent is not listed;
2734
3549
  * 4. else, with a verified account, throw YIELDSEEKER_AGENT_MISSING (never
2735
3550
  * create); without one, undefined (the caller may create).
2736
3551
  * Steps 1 and 2 share one search of at most YIELDSEEKER_WALLET_MATCH_LIMIT
@@ -2740,6 +3555,19 @@ declare class YieldseekerAgent implements IAgent {
2740
3555
  private chooseAgent;
2741
3556
  private isAgentMissing;
2742
3557
  private agentMissing;
3558
+ private slotUnavailable;
3559
+ /** The slot has no usable agent: missing, at Yieldseeker's agent limit, or closed for good. */
3560
+ private isSlotEmpty;
3561
+ /**
3562
+ * The slot's lookup failed through the missing-agent / reopen path and was
3563
+ * remembered with this very error, even a transient one (429, 5xx, timeout),
3564
+ * or with the copy of it a remembered rate limit is rethrown as. Compares
3565
+ * the remembered error, not its expiry, so it holds however long the rest
3566
+ * of the read takes.
3567
+ */
3568
+ private isMarkedSlotFailure;
3569
+ /** providerCode is absent when Yieldseeker named none (the agent stayed closed after a reopen). */
3570
+ private agentClosed;
2743
3571
  /**
2744
3572
  * Fire-and-forget: record which agent serves this slot. Never awaited on the
2745
3573
  * funds path and never throws; once per agent wallet and deployment state
@@ -2844,6 +3672,14 @@ declare class YieldseekerAgent implements IAgent {
2844
3672
  private agentPath;
2845
3673
  private walletRequest;
2846
3674
  private providerRequest;
3675
+ /**
3676
+ * mapApiError for a request that may have opened the Yieldseeker sign-in
3677
+ * prompt (providerRequest signs when no sign-in is saved, and again when
3678
+ * Yieldseeker refuses one). The wallet's rejection, the user cancelling that
3679
+ * prompt, is returned unchanged: the client and the app must see the user's
3680
+ * cancel (no further prompt, no retry), never a provider failure.
3681
+ */
3682
+ private mapRequestFailure;
2847
3683
  private mapApiError;
2848
3684
  private submitTransaction;
2849
3685
  private waitForReceipt;
@@ -2899,6 +3735,23 @@ type OwneySIWXConfig = {
2899
3735
  */
2900
3736
  declare function createOwneySIWX(config: OwneySIWXConfig): SIWXConfig;
2901
3737
 
3738
+ /**
3739
+ * Ask the wallet ITSELF to switch networks, over WalletConnect.
3740
+ *
3741
+ * WalletConnect's provider answers `wallet_switchEthereumChain` locally when
3742
+ * the chain was approved at connect time: it moves its own default chain and
3743
+ * reports success without telling the wallet. MetaMask mobile then stays on
3744
+ * its network, keeps reporting it, and every guard downstream fails with
3745
+ * CHAIN_MISMATCH — after a swap, with the user's funds already moved (ROUT-727).
3746
+ * Sending the request through the session client reaches the wallet, which
3747
+ * shows a real "switch network" prompt; the client also deep-links the wallet
3748
+ * app open on mobile.
3749
+ *
3750
+ * Returns false when `provider` is not a WalletConnect session, so the caller
3751
+ * can fall back to an ordinary switch.
3752
+ */
3753
+ declare function switchWalletConnectChain(provider: unknown, chainId: number, timeoutMs?: number): Promise<boolean>;
3754
+
2902
3755
  /**
2903
3756
  * Persists cross-chain swap secrets so an in-flight order survives a reload.
2904
3757
  *
@@ -2940,6 +3793,8 @@ type StoredOrder = {
2940
3793
  chainId: number;
2941
3794
  agentId?: string;
2942
3795
  operationId?: string;
3796
+ /** The user action's batch (see `DepositOptions.batchId`), carried to the recorded pending deposit. */
3797
+ batchId?: string;
2943
3798
  };
2944
3799
  /**
2945
3800
  * Our routing API accepted these secrets (part 5's opt-in handoff) and
@@ -3028,4 +3883,4 @@ declare const YIELDSEEKER_WITHDRAW_SERVER_SUBMIT: 1;
3028
3883
  * Older builds do not export this. */
3029
3884
  declare const FUNDING_DEPOSIT_RECOVERY_REPORT: 1;
3030
3885
 
3031
- export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentFundingLedgerAccess, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyHistoryPoint, type Asset, type AssetDailyEarnings, type AssetReadMetadata, type AvailableAgent, type AvailableAgentsOptions, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositAuthorizationReference, type DepositCallback, type DepositOptions, type DepositReplacementValidation, FUNDING_DEPOSIT_RECOVERY_REPORT, FUSION_SECRET_SERVER_PUBLISH, type FundingEvidence, type FundingOperationKind, type FundingOperationLeg, type FundingOperationRow, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LedgerLegReport, type LookbackDays, NotConnectedError, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawResult, type PendingDeposit, type ProviderSnapshotSample, type RebalanceLog, type ReservationAgent, type ReservationReleaseReason, type RpcUrlsConfig, SDK_VERSION, SPONSORED_DEPOSIT_SERVER_BROADCAST, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type UnsignedUserOperationEvidence, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, type WithdrawalCompletion, type WithdrawalCompletionContext, type WithdrawalPayoutCandidate, type WithdrawalPayoutScan, type WithdrawalReservationConflict, type WithdrawalReservationMode, type WithdrawalReservationOptions, type WithdrawalSwapRecovery, YIELDSEEKER_WITHDRAW_SERVER_SUBMIT, YieldseekerAgent, type YieldseekerWalletStatus, ZYFAI_REGISTRATION_NOT_SENT_CODES, ZYFAI_SERVER_TASKS, ZYFAI_WITHDRAWAL_NOT_SENT_CODES, ZYFAI_WITHDRAW_DISPATCH_CHECKPOINT, type ZyfaiDepositPlacement, type ZyfaiRpcUrlsConfig, type ZyfaiWithdrawalLifecycle, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, updateWithdrawSwap };
3886
+ export { type AccountAgentApy, type AccountApyOptions, type AccountDailyEarnings, type ActivateAgentOptions, type AgentApy, type AgentApyDetails, type AgentBalance, AgentChainIncompatibleError, type AgentEarnings, type AgentFundingLedgerAccess, type AgentHistoryEntry, type AgentHistoryPosition, type AgentId, AgentNotFoundError, type AgentSupportedAsset, type AgentSupportedAssets, type AgentUserProfile, type AgentWithdrawResult, type AgentsApyOptions, type AllocationAgentApy, type AllocationApyOptions, type ApyByChainAndAsset, type ApyCoverage, type ApyHistoryPoint, type ApyIncentive, type Asset, type AssetDailyEarnings, type AssetReadMetadata, type AvailableAgent, type AvailableAgentsOptions, type AvailablePool, type ConnectionState, type DailyApyDays, type DailyEarningsOptions, type DailyEarningsPoint, type DepositAuthorizationReference, type DepositCallback, type DepositOptions, type DepositReplacementValidation, FUNDING_DEPOSIT_RECOVERY_REPORT, FUSION_SECRET_SERVER_PUBLISH, type FundingEvidence, type FundingOperationKind, type FundingOperationLeg, type FundingOperationRow, type FundingProgress, type FundingStage, type HistoryAction, type HistoryFilters, type HistoryOptions, type HistoryTransaction, type IAgent, InvalidHistoryCursorError, type LedgerLegReport, type LookbackDays, NotConnectedError, type OrgPoolPolicy, type OrgPoolSelection, type OwneyAccountApy, type OwneyAgentApy, type OwneyAgentHistory, type OwneyAllocationApy, type OwneyBalances, type OwneyDepositResult, type OwneyEarnings, OwneyError, type OwneyErrorCode, type OwneyMultiDepositResult, type OwneyPosition, OwneySDK, type OwneySDKConfig, type OwneySIWXConfig, type OwneySupportedChainId, type OwneySupportedChains, type OwneySupportedTokens, type OwneyToken, type OwneyUserProfile, type OwneyWithdrawAllLeg, type OwneyWithdrawAllResult, type OwneyWithdrawResult, type PendingDeposit, type PoolCatalogProtocol, type PoolSelectionStrategy, type ProviderSnapshotSample, type RebalanceLog, type ReservationAgent, type ReservationReleaseReason, type RpcUrlsConfig, SDK_VERSION, SPONSORED_DEPOSIT_SERVER_BROADCAST, type SavedPoolSelection, type SwapChainTokens, type SwapDirection, type SwapOrderStatus, type SwapQuote, type SwapQuoteParams, type SwapRail, type SwapStage, type SwapTokenInfo, type SwapTokenSearchResult, type UnsignedUserOperationEvidence, type UserPoolSelection, type UserPoolSelectionRequest, type WithdrawOptions, type WithdrawSwapRecord, type WithdrawSwapStatus, type WithdrawalCompletion, type WithdrawalCompletionContext, type WithdrawalPayoutCandidate, type WithdrawalPayoutScan, type WithdrawalReservationConflict, type WithdrawalReservationMode, type WithdrawalReservationOptions, type WithdrawalSwapRecovery, YIELDSEEKER_WITHDRAW_SERVER_SUBMIT, YieldseekerAgent, type YieldseekerWalletStatus, ZYFAI_REGISTRATION_NOT_SENT_CODES, ZYFAI_SERVER_TASKS, ZYFAI_WITHDRAWAL_NOT_SENT_CODES, ZYFAI_WITHDRAW_DISPATCH_CHECKPOINT, type ZyfaiDepositPlacement, type ZyfaiRpcUrlsConfig, type ZyfaiWithdrawalLifecycle, clearWithdrawSwap, createOwneySIWX, listPendingDeposits, listOrders as listPendingSwaps, listWithdrawSwaps, saveWithdrawSwap, setOwneyDebug, subscribeWithdrawSwaps, switchWalletConnectChain, updateWithdrawSwap };