@owney/sdk 0.2.7 → 0.2.9

package/README.md

@@ -32,9 +32,10 @@ const balances = await sdk.getBalances();
 
 Create a new SDK instance.
 
-| Param | Type | Description |
-|-------|------|-------------|
-| `config.apiKey` | `string` | Your Owney API key, used to authenticate with the routing API and fetch agent-specific keys |
+| Param                 | Type                                           | Description                                                                                 |
+| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `config.apiKey`       | `string`                                       | Your Owney API key, used to authenticate with the routing API and fetch agent-specific keys |
+| `config.zyfaiRpcUrls` | `{ 8453?: string; 42161?: string }` (optional) | Per-chain RPC URL overrides used by Zyfai SDK network calls                                 |
 
 ```typescript
 import { OwneySDK } from "@owney/sdk";
@@ -42,12 +43,32 @@ import { OwneySDK } from "@owney/sdk";
 const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
 ```
 
+#### Custom Zyfai RPC URLs
+
+Use `zyfaiRpcUrls` to override Zyfai SDK RPC endpoints (for example, to avoid public endpoint rate limits).
+
+```typescript
+const sdk = new OwneySDK({
+  apiKey: "your-owney-api-key",
+  zyfaiRpcUrls: {
+    8453: "https://base-mainnet.g.alchemy.com/v2/<key>",
+    42161: "https://arb-mainnet.g.alchemy.com/v2/<key>",
+  },
+});
+```
+
+Notes:
+
+- These overrides are used by Zyfai SDK flows only.
+- If omitted, Zyfai SDK uses its default RPC endpoints.
+- Other app-level RPC clients (for example, direct viem calls outside Zyfai) are configured separately.
+
 ### `connect(provider)`
 
 Establish connection state. Must be called before any wallet-dependent operation.
 
-| Param | Type | Description |
-|-------|------|-------------|
+| Param      | Type              | Description                                    |
+| ---------- | ----------------- | ---------------------------------------------- |
 | `provider` | EIP-1193 provider | Wallet provider (e.g. MetaMask, WalletConnect) |
 
 ```typescript
@@ -89,9 +110,9 @@ if (chainId) {
 
 Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted. Deploys the Safe contract and creates a session key if not already set up. Saves the chainId for use by all subsequent SDK calls.
 
-| Param | Type | Description |
-|-------|------|-------------|
-| `chainId` | `number` | Target chain ID (e.g. `8453` for Base, `42161` for Arbitrum) |
+| Param     | Type                   | Description                                                                   |
+| --------- | ---------------------- | ----------------------------------------------------------------------------- |
+| `chainId` | `number`               | Target chain ID (e.g. `8453` for Base, `42161` for Arbitrum)                  |
 | `agentId` | `AgentId[]` (optional) | Agents to activate. Omit to activate all agents that support the given chain. |
 
 ```typescript
@@ -104,14 +125,14 @@ await sdk.activateAgent(42161);
 
 ### `deposit(options)`
 
-Deposit funds into a specific agent, or split equally across all agents if `agentId` is omitted. Validates that the asset is supported by the target agent(s) on the active chain. When splitting across agents, `depositCallback` is invoked once per agent with that agent's split amount and smart wallet address — expect multiple wallet prompts.
+Deposit funds into a specific agent, or split equally across all agents if `agentId` is omitted. Validates that the asset is supported by the target agent(s) on the active chain, and agent minimum deposit amounts are taken into account. When splitting across agents, `depositCallback` is invoked once per final valid agent with that agent's split amount and smart wallet address — expect multiple wallet prompts.
 
-| Param | Type | Description |
-|-------|------|-------------|
-| `options.amount` | `string` | Amount in smallest unit (e.g. `"100000000"` for 100 USDC) |
-| `options.asset` | `string` | Asset symbol (e.g. `"USDC"`) |
-| `options.depositCallback` | `DepositCallback` | Callback that performs the token transfer and returns a tx hash |
-| `options.agentId` | `AgentId` (optional) | Target agent. Omit to split equally across all agents. |
+| Param                     | Type                 | Description                                                     |
+| ------------------------- | -------------------- | --------------------------------------------------------------- |
+| `options.amount`          | `string`             | Amount in smallest unit (e.g. `"100000000"` for 100 USDC)       |
+| `options.asset`           | `string`             | Asset symbol (e.g. `"USDC"`)                                    |
+| `options.depositCallback` | `DepositCallback`    | Callback that performs the token transfer and returns a tx hash |
+| `options.agentId`         | `AgentId` (optional) | Target agent. Omit to split equally across all agents.          |
 
 Returns: `OwneyDepositResult` (single agent) or `OwneyMultiDepositResult` (all agents)
 
@@ -126,9 +147,9 @@ const result = await sdk.deposit({
     return txHash;
   },
 });
-console.log(result.txHash);       // "0x..."
-console.log(result.smartWallet);  // "0x..."
-console.log(result.amount);       // "100000000"
+console.log(result.txHash); // "0x..."
+console.log(result.smartWallet); // "0x..."
+console.log(result.amount); // "100000000"
 
 // Split equally across all agents
 const results = await sdk.deposit({
@@ -138,19 +159,19 @@ const results = await sdk.deposit({
     return await transferTokens(smartWallet, amount);
   },
 });
-console.log(results.agentResults.zyfai.amount);  // "50000000"
-console.log(results.agentResults.sail.amount);    // "50000000"
+console.log(results.agentResults.zyfai.amount); // "50000000"
+console.log(results.agentResults.sail.amount); // "50000000"
 ```
 
 ### `withdraw(options)`
 
 Withdraw funds from a specific agent, or all agents that support the active chain+asset if `agentId` is omitted. Validates that the asset is supported.
 
-| Param | Type | Description |
-|-------|------|-------------|
-| `options.asset` | `string` | Asset symbol (e.g. `"USDC"`) |
-| `options.amount` | `string` (optional) | Amount to withdraw. Omit for full withdrawal. |
-| `options.agentId` | `AgentId` (optional) | Target agent. Omit to withdraw from all. |
+| Param             | Type                 | Description                                   |
+| ----------------- | -------------------- | --------------------------------------------- |
+| `options.asset`   | `string`             | Asset symbol (e.g. `"USDC"`)                  |
+| `options.amount`  | `string` (optional)  | Amount to withdraw. Omit for full withdrawal. |
+| `options.agentId` | `AgentId` (optional) | Target agent. Omit to withdraw from all.      |
 
 Returns: `AgentWithdrawResult` (single agent) or `OwneyWithdrawResult` (all agents)
 
@@ -161,21 +182,21 @@ const result = await sdk.withdraw({
   agentId: "zyfai",
   amount: "50000000",
 });
-console.log(result.type);    // "partial"
-console.log(result.amount);  // "50000000"
+console.log(result.type); // "partial"
+console.log(result.amount); // "50000000"
 
 // Full withdrawal from all agents
 const results = await sdk.withdraw({ asset: "USDC" });
-console.log(results.agentResult.zyfai.type);  // "full"
-console.log(results.agentResult.sail.type);   // "full"
+console.log(results.agentResult.zyfai.type); // "full"
+console.log(results.agentResult.sail.type); // "full"
 ```
 
 ### `getBalances(agentId?)`
 
 Get the user's balances for a specific agent, or aggregated across all agents.
 
-| Param | Type | Description |
-|-------|------|-------------|
+| Param     | Type                           | Description                          |
+| --------- | ------------------------------ | ------------------------------------ |
 | `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
 
 Returns: `AgentBalance` (single agent) or `OwneyBalances` (all agents)
@@ -183,23 +204,23 @@ Returns: `AgentBalance` (single agent) or `OwneyBalances` (all agents)
 ```typescript
 // Single agent
 const balance = await sdk.getBalances("zyfai");
-console.log(balance.totalBalance);  // "150.25"
-console.log(balance.smartWallet);   // "0x..."
-console.log(balance.tokens);       // [{ chain: "BASE", chainId: 8453, asset: "USDC", amount: "150.25" }]
+console.log(balance.totalBalance); // "150.25"
+console.log(balance.smartWallet); // "0x..."
+console.log(balance.tokens); // [{ chain: "BASE", chainId: 8453, asset: "USDC", amount: "150.25" }]
 
 // All agents
 const allBalances = await sdk.getBalances();
-console.log(allBalances.totalBalance);                    // "300.50"
+console.log(allBalances.totalBalance); // "300.50"
 console.log(allBalances.agentBalances.zyfai.totalBalance); // "150.25"
-console.log(allBalances.agentBalances.sail.totalBalance);  // "150.25"
+console.log(allBalances.agentBalances.sail.totalBalance); // "150.25"
 ```
 
 ### `getEarnings(agentId?)`
 
 Get the user's on-chain earnings for a specific agent, or aggregated across all agents.
 
-| Param | Type | Description |
-|-------|------|-------------|
+| Param     | Type                           | Description                          |
+| --------- | ------------------------------ | ------------------------------------ |
 | `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
 
 Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
@@ -207,12 +228,12 @@ Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
 ```typescript
 // Single agent
 const earnings = await sdk.getEarnings("zyfai");
-console.log(earnings.smartWallet);       // "0x..."
-console.log(earnings.lifetimeEarnings);  // 42.5
+console.log(earnings.smartWallet); // "0x..."
+console.log(earnings.lifetimeEarnings); // 42.5
 
 // All agents
 const allEarnings = await sdk.getEarnings();
-console.log(allEarnings.totalEarnings);                      // "85.0"
+console.log(allEarnings.totalEarnings); // "85.0"
 console.log(allEarnings.agentEarnings.zyfai.lifetimeEarnings); // 42.5
 ```
 
@@ -220,37 +241,37 @@ console.log(allEarnings.agentEarnings.zyfai.lifetimeEarnings); // 42.5
 
 Get the weighted APY for the user's account. When querying all agents, the total APY is a balance-weighted average.
 
-| Param | Type | Description |
-|-------|------|-------------|
+| Param     | Type                           | Description                                      |
+| --------- | ------------------------------ | ------------------------------------------------ |
 | `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for balance-weighted total. |
-| `days` | `"7D" \| "14D" \| "30D"` | Lookback period |
+| `days`    | `"7D" \| "14D" \| "30D"`       | Lookback period                                  |
 
 Returns: `AccountAgentApy` (single agent) or `OwneyAccountApy` (all agents)
 
 ```typescript
 // Single agent
 const apy = await sdk.getAccountApy({ agentId: "zyfai", days: "30D" });
-console.log(apy.walletAddress);       // "0x..."
+console.log(apy.walletAddress); // "0x..."
 console.log(apy.weightedApyAfterFee); // 5.2
 // Per chain + token breakdown, when the agent reports it
-console.log(apy.weightedApyAfterFeeDetails?.apyPerAsset[8453]?.USDC);  // 5.4
+console.log(apy.weightedApyAfterFeeDetails?.apyPerAsset[8453]?.USDC); // 5.4
 
 // All agents (balance-weighted)
 const allApy = await sdk.getAccountApy({ days: "30D" });
-console.log(allApy.totalApy);                        // "5.6"
+console.log(allApy.totalApy); // "5.6"
 console.log(allApy.agentApy.zyfai.weightedApyAfterFee); // 6.0
-console.log(allApy.agentApy.sail.weightedApyAfterFee);  // 4.0
+console.log(allApy.agentApy.sail.weightedApyAfterFee); // 4.0
 ```
 
 ### `getHistory({ agentId?, filters? })`
 
 Get transaction history for a specific agent, or all agents. When querying all agents, results are merged into a single list sorted by date (newest first). Each entry includes the originating `agent` and a `transactions` array with typed on-chain transaction details.
 
-| Param | Type | Description |
-|-------|------|-------------|
-| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
-| `filters.fromDate` | `string` (optional) | Start date (`YYYY-MM-DD`) |
-| `filters.toDate` | `string` (optional) | End date (`YYYY-MM-DD`) |
+| Param              | Type                           | Description                          |
+| ------------------ | ------------------------------ | ------------------------------------ |
+| `agentId`          | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
+| `filters.fromDate` | `string` (optional)            | Start date (`YYYY-MM-DD`)            |
+| `filters.toDate`   | `string` (optional)            | End date (`YYYY-MM-DD`)              |
 
 Returns: `OwneyAgentHistory`
 
@@ -260,65 +281,65 @@ const history = await sdk.getHistory({
   agentId: "zyfai",
   filters: { fromDate: "2025-01-01" },
 });
-console.log(history.total);                              // 42
-console.log(history.data[0].agent);                      // "zyfai"
-console.log(history.data[0].action);                     // "Rebalance"
-console.log(history.data[0].date);                       // "2025-03-15T12:00:00Z"
-console.log(history.data[0].transactions[0].txHashes);   // ["0x..."]
-console.log(history.data[0].transactions[0].amount);     // "100.00"
+console.log(history.total); // 42
+console.log(history.data[0].agent); // "zyfai"
+console.log(history.data[0].action); // "Rebalance"
+console.log(history.data[0].date); // "2025-03-15T12:00:00Z"
+console.log(history.data[0].transactions[0].txHashes); // ["0x..."]
+console.log(history.data[0].transactions[0].amount); // "100.00"
 console.log(history.data[0].transactions[0].tokenSymbol); // "USDC"
 
 // Rebalance logs show fund movement between protocols
 console.log(history.data[0].rebalanceLog[0].fromProtocol); // "Aave V3"
-console.log(history.data[0].rebalanceLog[0].toProtocol);   // "Morpho Blue"
-console.log(history.data[0].rebalanceLog[0].tokenSymbol);  // "USDC"
-console.log(history.data[0].rebalanceLog[0].amount);       // "100.00"
-console.log(history.data[0].rebalanceLog[0].status);       // "success"
+console.log(history.data[0].rebalanceLog[0].toProtocol); // "Morpho Blue"
+console.log(history.data[0].rebalanceLog[0].tokenSymbol); // "USDC"
+console.log(history.data[0].rebalanceLog[0].amount); // "100.00"
+console.log(history.data[0].rebalanceLog[0].status); // "success"
 
 // All agents (merged and sorted by date)
 const allHistory = await sdk.getHistory();
-console.log(allHistory.total);            // 57
-console.log(allHistory.data[0].agent);    // "sail" (most recent entry)
-console.log(allHistory.data[0].action);   // "Rebalance"
+console.log(allHistory.total); // 57
+console.log(allHistory.data[0].agent); // "sail" (most recent entry)
+console.log(allHistory.data[0].action); // "Rebalance"
 ```
 
 ### `pauseAgent(agentId)`
 
 Pause an agent's automated operations. The agent will stop rebalancing until resumed.
 
-| Param | Type | Description |
-|-------|------|-------------|
+| Param     | Type                | Description    |
+| --------- | ------------------- | -------------- |
 | `agentId` | `"zyfai" \| "sail"` | Agent to pause |
 
 Returns: `OwneyAgentStatus`
 
 ```typescript
 const status = await sdk.pauseAgent("zyfai");
-console.log(status.success);  // true
+console.log(status.success); // true
 ```
 
 ### `resumeAgent(agentId)`
 
 Resume an agent's automated operations.
 
-| Param | Type | Description |
-|-------|------|-------------|
+| Param     | Type                | Description     |
+| --------- | ------------------- | --------------- |
 | `agentId` | `"zyfai" \| "sail"` | Agent to resume |
 
 Returns: `OwneyAgentStatus`
 
 ```typescript
 const status = await sdk.resumeAgent("zyfai");
-console.log(status.success);    // true
-console.log(status.protocols);  // ["aave", "compound"]
+console.log(status.success); // true
+console.log(status.protocols); // ["aave", "compound"]
 ```
 
 ### `getUserProfile(agentId?)`
 
 Get the user's profile for a specific agent, or all agents.
 
-| Param | Type | Description |
-|-------|------|-------------|
+| Param     | Type                           | Description                          |
+| --------- | ------------------------------ | ------------------------------------ |
 | `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
 
 Returns: `AgentUserProfile` (single agent) or `OwneyUserProfile` (all agents)
@@ -326,28 +347,28 @@ Returns: `AgentUserProfile` (single agent) or `OwneyUserProfile` (all agents)
 ```typescript
 // Single agent
 const profile = await sdk.getUserProfile("zyfai");
-console.log(profile.address);             // "0x..."
-console.log(profile.smartWallet);         // "0x..."
-console.log(profile.chains);             // [8453]
+console.log(profile.address); // "0x..."
+console.log(profile.smartWallet); // "0x..."
+console.log(profile.chains); // [8453]
 console.log(profile.hasActiveSessionKey); // true
-console.log(profile.protocols);          // ["aave", "compound"]
+console.log(profile.protocols); // ["aave", "compound"]
 
 // All agents
 const allProfiles = await sdk.getUserProfile();
 console.log(allProfiles.agentUserProfile.zyfai.smartWallet); // "0x..."
-console.log(allProfiles.agentUserProfile.sail.smartWallet);  // "0x..."
+console.log(allProfiles.agentUserProfile.sail.smartWallet); // "0x..."
 ```
 
 ### `getAgentApy({ agentId?, days, tokenSymbol?, chainId? })`
 
 Get the agent's average APY performance over a time period. Does not require a wallet connection.
 
-| Param | Type | Description |
-|-------|------|-------------|
-| `agentId` | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents. |
-| `days` | `"7D" \| "14D" \| "30D"` | Lookback period |
-| `tokenSymbol` | `string` (optional) | Asset symbol (e.g. `"USDC"`, `"WETH"`). Scopes the upstream request to a specific asset when the agent's backend supports it. Zyfai forwards this; Sail currently ignores it at the API level. |
-| `chainId` | `number` (optional) | Chain id. Typically paired with `tokenSymbol` for per-asset+chain APY. Zyfai forwards this; Sail currently ignores it at the API level. |
+| Param         | Type                           | Description                                                                                                                                                                                    |
+| ------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `agentId`     | `"zyfai" \| "sail"` (optional) | Agent to query. Omit for all agents.                                                                                                                                                           |
+| `days`        | `"7D" \| "14D" \| "30D"`       | Lookback period                                                                                                                                                                                |
+| `tokenSymbol` | `string` (optional)            | Asset symbol (e.g. `"USDC"`, `"WETH"`). Scopes the upstream request to a specific asset when the agent's backend supports it. Zyfai forwards this; Sail currently ignores it at the API level. |
+| `chainId`     | `number` (optional)            | Chain id. Typically paired with `tokenSymbol` for per-asset+chain APY. Zyfai forwards this; Sail currently ignores it at the API level.                                                        |
 
 Returns: `AgentApy` (single agent) or `OwneyAgentApy` (all agents)
 
@@ -359,13 +380,13 @@ returns.
 ```typescript
 // Single agent
 const apy = await sdk.getAgentApy({ agentId: "zyfai", days: "30D" });
-console.log(apy.averageApy);  // 8.5
+console.log(apy.averageApy); // 8.5
 console.log(apy.detailedApys?.apyPerAsset[8453]?.USDC); // 8.7
 
 // All agents
 const allApy = await sdk.getAgentApy({ days: "30D" });
 console.log(allApy.agentApy.zyfai.averageApy); // 8.5
-console.log(allApy.agentApy.sail.averageApy);  // 6.2
+console.log(allApy.agentApy.sail.averageApy); // 6.2
 console.log(allApy.agentApy.sail.detailedApys?.apyPerAsset[42161]?.USDT); // 6.4
 
 // Scope the upstream query to USDC on Base (Zyfai-aware; Sail ignores the filter)
@@ -385,7 +406,7 @@ Returns: `OwneyAgentAllocation`
 
 ```typescript
 const allocation = await sdk.getAgentAllocation();
-console.log(allocation.agentAllocation);  // { zyfai: 75, sail: 25 }
+console.log(allocation.agentAllocation); // { zyfai: 75, sail: 25 }
 ```
 
 ## Types
@@ -408,6 +429,10 @@ type AgentSupportedAssets = {
 
 interface OwneySDKConfig {
   apiKey: string;
+  zyfaiRpcUrls?: {
+    8453?: string;
+    42161?: string;
+  };
 }
 
 interface ConnectionState {
@@ -417,8 +442,8 @@ interface ConnectionState {
 }
 
 type HistoryFilters = {
-  fromDate?: string;  // YYYY-MM-DD
-  toDate?: string;    // YYYY-MM-DD
+  fromDate?: string; // YYYY-MM-DD
+  toDate?: string; // YYYY-MM-DD
 };
 
 type HistoryOptions = {
@@ -447,8 +472,8 @@ type AccountApyOptions = {
 type AgentsApyOptions = {
   agentId?: AgentId;
   days: DailyApyDays;
-  tokenSymbol?: string;  // e.g. "USDC", "WETH"
-  chainId?: number;      // typically paired with tokenSymbol
+  tokenSymbol?: string; // e.g. "USDC", "WETH"
+  chainId?: number; // typically paired with tokenSymbol
 };
 ```
 
@@ -603,13 +628,83 @@ type DepositCallback = (
 ) => Promise<`0x${string}`> | `0x${string}`;
 ```
 
-### Error Classes
+### Error Handling
+
+All errors thrown by the SDK are instances of `OwneyError` (which extends `Error`), each carrying a stable `code` string and optional `details` object for programmatic handling.
+
+```typescript
+import { OwneyError } from "@owney/sdk";
+
+try {
+  await sdk.getBalances();
+} catch (error) {
+  if (error instanceof OwneyError) {
+    switch (error.code) {
+      case "NOT_CONNECTED":
+        // prompt user to connect wallet
+        break;
+      case "NO_ACTIVE_CHAIN":
+        // prompt user to activate an agent
+        break;
+      case "BALANCE_ALL_FAILED":
+        // all agents failed to return balances
+        break;
+      default:
+        console.error(`[${error.code}] ${error.message}`, error.details);
+    }
+  }
+}
+```
+
+```typescript
+type OwneyErrorCode =
+  // Connection & wallet
+  | "NOT_CONNECTED" // Wallet-dependent method called before connect()
+  | "NO_ACTIVE_CHAIN" // Method called before activateAgent()
+  | "WALLET_NO_ACCOUNTS" // Provider returned no accounts during connect()
+  | "WALLET_ADDRESS_REQUIRED" // Wallet address missing during agent auth
+  // Agent resolution
+  | "AGENT_NOT_FOUND" // Unknown agent ID passed
+  | "AGENT_CHAIN_INCOMPATIBLE" // Agent(s) don't support the given chain
+  | "AGENT_EMPTY_LIST" // Empty agentId array passed to activateAgent()
+  // Chain
+  | "CHAIN_UNSUPPORTED" // Chain ID not in supported list (8453, 42161)
+  | "CHAIN_NO_COMPATIBLE_AGENTS" // No agents support the given chain
+  // Asset
+  | "ASSET_UNSUPPORTED" // Agent doesn't support the asset on the active chain
+  | "ASSET_NO_COMPATIBLE_AGENTS" // No agents support the asset on the active chain
+  // Deposit
+  | "DEPOSIT_AMOUNT_BELOW_MINIMUM" // Amount below an agent's required minimum deposit
+  | "DEPOSIT_CALLBACK_REQUIRED" // Sail agent requires a depositCallback
+  | "DEPOSIT_CALLBACK_INVALID" // depositCallback didn't return a tx hash
+  | "DEPOSIT_NO_PERMITTED_TOKENS" // No permitted tokens available for deposit
+  // Withdraw
+  | "WITHDRAW_NO_PERMITTED_TOKENS" // No permitted tokens available for withdrawal
+  // API
+  | "API_ROUTING_ERROR" // Routing API returned a non-OK HTTP status
+  | "API_ROUTING_FAILED" // Routing API returned { success: false }
+  | "API_SAIL_ERROR" // Sail API returned a non-OK HTTP status
+  | "API_SAIL_TIMEOUT" // Sail API request timed out
+  | "API_NO_AGENTS" // No supported agents returned by routing API
+  // Aggregation
+  | "BALANCE_ALL_FAILED" // All agents failed to return balances
+  | "ALLOCATION_ALL_FAILED" // All agents failed to return allocation data
+  // Validation
+  | "VALIDATION_INVALID_DAYS"; // Invalid days value (expected "7D", "14D", or "30D")
+
+class OwneyError extends Error {
+  readonly code: OwneyErrorCode;
+  readonly details?: Record<string, unknown>;
+}
+```
+
+The three convenience subclasses extend `OwneyError` and remain backwards-compatible:
 
-| Error | Thrown when |
-|-------|------------|
-| `NotConnectedError` | A wallet-dependent method is called before `connect()` |
-| `AgentNotFoundError` | An unknown agent ID is passed (e.g. a typo) |
-| `AgentChainIncompatibleError` | `activateAgent` is called with agents that don't support the given chain. Exposes `incompatibleAgents` and `connectedChainId` properties for programmatic handling. |
+| Class                         | Code                       | Extra properties                         |
+| ----------------------------- | -------------------------- | ---------------------------------------- |
+| `NotConnectedError`           | `NOT_CONNECTED`            | —                                        |
+| `AgentNotFoundError`          | `AGENT_NOT_FOUND`          | —                                        |
+| `AgentChainIncompatibleError` | `AGENT_CHAIN_INCOMPATIBLE` | `incompatibleAgents`, `connectedChainId` |
 
 ## License