@owney/sdk 0.7.32-beta.4 → 0.7.32

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/README.md CHANGED
@@ -14,15 +14,12 @@ npm install @owney/sdk
14
14
  import { OwneySDK } from "@owney/sdk";
15
15
 
16
16
  // Create the SDK instance
17
- const sdk = new OwneySDK({
18
- apiKey: "your-owney-api-key",
19
- routingApiBaseUrl: "https://your-routing-api.example",
20
- });
17
+ const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
21
18
 
22
19
  // Connect with an EIP-1193 wallet provider
23
20
  await sdk.connect(provider);
24
21
 
25
- // Activate agents on Base (creates and initializes provider wallets as needed)
22
+ // Activate agents on Base (fetches agent keys on first call)
26
23
  await sdk.activateAgent(8453);
27
24
 
28
25
  // Get balances across all agents
@@ -35,79 +32,36 @@ const balances = await sdk.getBalances();
35
32
 
36
33
  Create a new SDK instance.
37
34
 
38
- | Param | Type | Description |
39
- | --------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
40
- | `config.apiKey` | `string` | Your Owney API key, used to authenticate with the routing API and fetch agent-specific keys |
41
- | `config.routingApiBaseUrl` | `string` (optional) | Routing API URL; required for proxy reads unless the SDK build has `OWNEY_ROUTING_API_BASE_URL` or all `rpcUrls` are set |
42
- | `config.rpcUrls` | `{ 1?: string; 8453?: string; 42161?: string }` (optional) | Per-chain RPC overrides used by agent reads and transaction-receipt polling |
43
- | `config.zyfaiRpcUrls` | Same as `rpcUrls` (deprecated) | Legacy Zyfai-only override; use `rpcUrls` for all application-owned reads |
35
+ | Param | Type | Description |
36
+ | --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------- |
37
+ | `config.apiKey` | `string` | Your Owney API key, used to authenticate with the routing API and fetch agent-specific keys |
38
+ | `config.zyfaiRpcUrls` | `{ 8453?: string; 42161?: string }` (optional) | Per-chain RPC URL overrides used by Zyfai SDK network calls |
44
39
 
45
40
  ```typescript
46
41
  import { OwneySDK } from "@owney/sdk";
47
42
 
48
- const sdk = new OwneySDK({
49
- apiKey: "your-owney-api-key",
50
- routingApiBaseUrl: "https://your-routing-api.example",
51
- });
43
+ const sdk = new OwneySDK({ apiKey: "your-owney-api-key" });
52
44
  ```
53
45
 
54
- #### Dedicated RPC URLs
55
-
56
- Use `rpcUrls` for application-owned chain reads and transaction-receipt
57
- polling. The connected wallet provider remains responsible for accounts, chain
58
- switching, signatures, and transaction submission.
59
-
60
- `rpcUrls` is optional. The SDK resolves an endpoint independently for each
61
- supported chain using this precedence:
62
-
63
- 1. The caller-provided `rpcUrls[chainId]`, when present and non-empty.
64
- 2. The Owney routing API read-only RPC proxy for that chain.
65
-
66
- The Alchemy credential stays on the routing API server. The SDK sends its
67
- existing organization key to the proxy for per-organization rate limiting.
68
- The proxy base URL must be provided through `routingApiBaseUrl` or the SDK
69
- build's `OWNEY_ROUTING_API_BASE_URL`; there is no hardcoded production fallback.
70
-
71
- ```typescript
72
- // All supported chains use the Owney routing API proxy.
73
- const sdk = new OwneySDK({
74
- apiKey: "your-owney-api-key",
75
- routingApiBaseUrl: "https://your-routing-api.example",
76
- });
77
- ```
46
+ #### Custom Zyfai RPC URLs
78
47
 
79
- Overrides can be complete or partial:
48
+ Use `zyfaiRpcUrls` to override Zyfai SDK RPC endpoints (for example, to avoid public endpoint rate limits).
80
49
 
81
50
  ```typescript
82
51
  const sdk = new OwneySDK({
83
52
  apiKey: "your-owney-api-key",
84
- routingApiBaseUrl: "https://your-routing-api.example",
85
- rpcUrls: {
86
- // Ethereum and Arbitrum continue using the routing API proxy.
87
- 8453: "https://your-own-rpc.example/rpc",
53
+ zyfaiRpcUrls: {
54
+ 8453: "https://base-mainnet.g.alchemy.com/v2/<key>",
55
+ 42161: "https://arb-mainnet.g.alchemy.com/v2/<key>",
88
56
  },
89
57
  });
90
58
  ```
91
59
 
92
- The resolved URLs are shared across Owney-owned reads and agent integrations:
93
-
94
- - Wagmi or application transports remain the consuming application's
95
- responsibility; Owney mini-apps configure them from the same URL map.
96
- - Zyfai receives the resolved Owney URL map, so its internal provider defaults
97
- do not determine routing for Owney SDK consumers.
98
- - Yieldseeker uses the resolved Base URL for transaction-receipt polling.
99
- - Balance, allowance, module-state, and receipt reads use the resolved RPC.
100
- - Account access, chain switching, signatures, approvals, and transaction
101
- submission continue through the connected wallet provider.
102
-
103
60
  Notes:
104
61
 
105
- - Owney mini-apps pass the same routing API proxy URLs to Wagmi and the SDK.
106
- - SDK consumers may override endpoints if they operate their own RPC provider.
107
- - Partial maps override only the supplied chains; missing chains use Owney's
108
- routing API proxy.
109
- - HTTP reads use bounded retries and honor provider `Retry-After` responses.
110
- - `zyfaiRpcUrls` remains available for compatibility but applies only to Zyfai.
62
+ - These overrides are used by Zyfai SDK flows only.
63
+ - If omitted, Zyfai SDK uses its default RPC endpoints.
64
+ - Other app-level RPC clients (for example, direct viem calls outside Zyfai) are configured separately.
111
65
 
112
66
  ### `connect(provider)`
113
67
 
@@ -154,7 +108,7 @@ if (chainId) {
154
108
 
155
109
  ### `activateAgent(chainId, agentId?)`
156
110
 
157
- Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted. Activation performs each provider's required setup before deposits are allowed. For Yieldseeker, this creates the user and agent when needed and calls the agent `/deploy` endpoint before any funding transfer. Saves the chainId for use by all subsequent SDK calls.
111
+ Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted. Smart wallets are pre-deployed by the underlying providers, so activation only performs authentication and profile syncing — no deploy or session-key signatures. Saves the chainId for use by all subsequent SDK calls.
158
112
 
159
113
  | Param | Type | Description |
160
114
  | --------- | ---------------------- | ----------------------------------------------------------------------------- |
@@ -171,7 +125,7 @@ await sdk.activateAgent(42161);
171
125
 
172
126
  ### `deposit(options)`
173
127
 
174
- 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 per-agent minimum deposit amounts (defined per chain+asset on `agent.supportedAssets[].assets[].minDepositAmount`) are taken into account. Custom `depositCallback` implementations run once per final valid agent. The default Permit2 flow signs one recipient-bound batch authorization for every agent share. On the first Base USDC deposit, the SDK first requests an ERC-2612 signature; the relayer then submits the Permit2 approval and deposit as two sponsored transactions. Later deposits need only the batch signature.
128
+ 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 per-agent minimum deposit amounts (defined per chain+asset on `agent.supportedAssets[].assets[].minDepositAmount`) 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.
175
129
 
176
130
  | Param | Type | Description |
177
131
  | ------------------------- | -------------------- | --------------------------------------------------------------- |
@@ -271,10 +225,6 @@ Balances are shown after any applicable performance fees have been deducted.
271
225
 
272
226
  Returns: `AgentBalance` (single agent) or `OwneyBalances` (all agents)
273
227
 
274
- Aggregate reads keep successful agents when another agent fails. The response
275
- includes `agentErrors` and, for rate limits, absolute `agentRetryAt` deadlines.
276
- The SDK throws `BALANCE_ALL_FAILED` when every active agent fails.
277
-
278
228
  ```typescript
279
229
  // Single agent
280
230
  const balance = await sdk.getBalances("zyfai");
@@ -302,10 +252,6 @@ Earnings are shown after any applicable performance fees have been deducted.
302
252
 
303
253
  Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
304
254
 
305
- Aggregate reads keep successful agents when another agent fails. The response
306
- includes `agentErrors` and, for rate limits, absolute `agentRetryAt` deadlines.
307
- The SDK throws `EARNINGS_ALL_FAILED` when every active agent fails.
308
-
309
255
  ```typescript
310
256
  // Single agent
311
257
  const earnings = await sdk.getEarnings("zyfai");
@@ -335,9 +281,6 @@ snapshot is less than one hour old, the SDK returns it without recalculating.
335
281
 
336
282
  Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
337
283
 
338
- Aggregate refreshes use the same partial-result and all-failed behavior as
339
- `getEarnings()`.
340
-
341
284
  ```typescript
342
285
  // Single agent
343
286
  const refreshed = await sdk.refreshEarnings("zyfai");
@@ -503,8 +446,8 @@ console.log(usdcBaseApy.agentApy.zyfai.averageApy); // APY scoped to USDC on Bas
503
446
  type AgentId = "zyfai";
504
447
  type Asset = string;
505
448
  type DailyApyDays = "7D" | "14D" | "30D";
506
- type OwneySupportedChainId = 1 | 8453 | 42161;
507
- type OwneySupportedChains = "ETHEREUM" | "BASE" | "ARBITRUM";
449
+ type OwneySupportedChainId = 8453 | 42161;
450
+ type OwneySupportedChains = "BASE" | "ARBITRUM";
508
451
  type OwneySupportedTokens = "USDC" | "WETH";
509
452
 
510
453
  type AgentSupportedAsset = {
@@ -521,14 +464,7 @@ type AgentSupportedAssets = {
521
464
 
522
465
  interface OwneySDKConfig {
523
466
  apiKey: string;
524
- rpcUrls?: {
525
- 1?: string;
526
- 8453?: string;
527
- 42161?: string;
528
- };
529
- /** @deprecated Use rpcUrls. */
530
467
  zyfaiRpcUrls?: {
531
- 1?: string;
532
468
  8453?: string;
533
469
  42161?: string;
534
470
  };
@@ -643,14 +579,12 @@ interface AccountAgentApy {
643
579
  weightedApyAfterFee?: number;
644
580
  weightedApyAfterFeeDetails?: AgentApyDetails;
645
581
  apyByChainAndAsset?: ApyByChainAndAsset;
646
- history?: ApyHistoryPoint[];
647
582
  }
648
583
 
649
584
  interface OwneyAccountApy {
650
585
  totalApy: string;
651
586
  agentApy: Record<AgentId, AccountAgentApy>;
652
587
  apyByChainAndAsset: ApyByChainAndAsset;
653
- history?: ApyHistoryPoint[]; // balance-weighted aggregate daily series
654
588
  }
655
589
 
656
590
  type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
@@ -792,7 +726,6 @@ type OwneyErrorCode =
792
726
  | "API_NO_AGENTS" // No supported agents returned by routing API
793
727
  // Aggregation
794
728
  | "BALANCE_ALL_FAILED" // All agents failed to return balances
795
- | "EARNINGS_ALL_FAILED" // All agents failed to return earnings
796
729
  | "ALLOCATION_ALL_FAILED" // All agents failed to return allocation data
797
730
  // Validation
798
731
  | "VALIDATION_INVALID_DAYS"; // Invalid days value (expected "7D", "14D", or "30D")