@owney/sdk 0.7.31 → 0.7.32-beta.10
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 +109 -20
- package/dist/chunk-CW55W2WO.js +622 -0
- package/dist/index.cjs +19232 -3856
- package/dist/index.d.cts +2327 -338
- package/dist/index.d.ts +2327 -338
- package/dist/index.js +18575 -3837
- package/dist/token-batch-family-TUGZWETV.js +32 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -14,12 +14,15 @@ npm install @owney/sdk
|
|
|
14
14
|
import { OwneySDK } from "@owney/sdk";
|
|
15
15
|
|
|
16
16
|
// Create the SDK instance
|
|
17
|
-
const sdk = new OwneySDK({
|
|
17
|
+
const sdk = new OwneySDK({
|
|
18
|
+
apiKey: "your-owney-api-key",
|
|
19
|
+
routingApiBaseUrl: "https://your-routing-api.example",
|
|
20
|
+
});
|
|
18
21
|
|
|
19
22
|
// Connect with an EIP-1193 wallet provider
|
|
20
23
|
await sdk.connect(provider);
|
|
21
24
|
|
|
22
|
-
// Activate agents on Base (
|
|
25
|
+
// Activate agents on Base (creates and initializes provider wallets as needed)
|
|
23
26
|
await sdk.activateAgent(8453);
|
|
24
27
|
|
|
25
28
|
// Get balances across all agents
|
|
@@ -32,36 +35,79 @@ const balances = await sdk.getBalances();
|
|
|
32
35
|
|
|
33
36
|
Create a new SDK instance.
|
|
34
37
|
|
|
35
|
-
| Param
|
|
36
|
-
|
|
|
37
|
-
| `config.apiKey`
|
|
38
|
-
| `config.
|
|
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 |
|
|
39
44
|
|
|
40
45
|
```typescript
|
|
41
46
|
import { OwneySDK } from "@owney/sdk";
|
|
42
47
|
|
|
43
|
-
const sdk = new OwneySDK({
|
|
48
|
+
const sdk = new OwneySDK({
|
|
49
|
+
apiKey: "your-owney-api-key",
|
|
50
|
+
routingApiBaseUrl: "https://your-routing-api.example",
|
|
51
|
+
});
|
|
44
52
|
```
|
|
45
53
|
|
|
46
|
-
####
|
|
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.
|
|
47
65
|
|
|
48
|
-
|
|
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.
|
|
49
70
|
|
|
50
71
|
```typescript
|
|
72
|
+
// All supported chains use the Owney routing API proxy.
|
|
51
73
|
const sdk = new OwneySDK({
|
|
52
74
|
apiKey: "your-owney-api-key",
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
75
|
+
routingApiBaseUrl: "https://your-routing-api.example",
|
|
76
|
+
});
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Overrides can be complete or partial:
|
|
80
|
+
|
|
81
|
+
```typescript
|
|
82
|
+
const sdk = new OwneySDK({
|
|
83
|
+
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",
|
|
56
88
|
},
|
|
57
89
|
});
|
|
58
90
|
```
|
|
59
91
|
|
|
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
|
+
|
|
60
103
|
Notes:
|
|
61
104
|
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
-
|
|
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.
|
|
65
111
|
|
|
66
112
|
### `connect(provider)`
|
|
67
113
|
|
|
@@ -106,14 +152,15 @@ if (chainId) {
|
|
|
106
152
|
}
|
|
107
153
|
```
|
|
108
154
|
|
|
109
|
-
### `activateAgent(chainId, agentId?)`
|
|
155
|
+
### `activateAgent(chainId, agentId?, options?)`
|
|
110
156
|
|
|
111
|
-
Activate the user's smart wallet for the specified agents, or all chain-compatible agents if omitted.
|
|
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.
|
|
112
158
|
|
|
113
159
|
| Param | Type | Description |
|
|
114
160
|
| --------- | ---------------------- | ----------------------------------------------------------------------------- |
|
|
115
161
|
| `chainId` | `number` | Target chain ID (e.g. `8453` for Base, `42161` for Arbitrum) |
|
|
116
162
|
| `agentId` | `AgentId[]` (optional) | Agents to activate. Omit to activate all agents that support the given chain. |
|
|
163
|
+
| `options` | `ActivateAgentOptions` (optional) | `asset` limits setup to that asset. `onAgentsSelected` fires once reads can start. |
|
|
117
164
|
|
|
118
165
|
```typescript
|
|
119
166
|
// Activate specific agents on Base
|
|
@@ -123,9 +170,27 @@ await sdk.activateAgent(8453, ["zyfai"]);
|
|
|
123
170
|
await sdk.activateAgent(42161);
|
|
124
171
|
```
|
|
125
172
|
|
|
173
|
+
Agents sign in one at a time, and activation stops at the first agent that fails, so no later agent's wallet prompt opens. A connect needs every agent: the app should end the session on any activation error. When an earlier agent activated, it throws `AGENT_ACTIVATION_PARTIAL_FAILURE` with `details: { activatedAgentIds, failedAgentIds, failures }`, plus `details.walletRejected: true` when the user rejected the signature. When the agent can never be readied (`details.permanent`), it throws `AGENT_ACTIVATION_BLOCKED`. Otherwise the agent's own error is thrown. Until it signs in, an agent whose signature the user rejected is read from a saved sign-in only (a read that would need a wallet prompt fails for that agent instead of opening one).
|
|
174
|
+
|
|
175
|
+
### `getUnavailableAgentIds(chainId, asset?)`
|
|
176
|
+
|
|
177
|
+
The agents that take no new deposits on this chain and asset this session, so the app can show them as unavailable: each agent whose provider has no agent for that slot (`IAgent.isSlotUnavailable`). They stay withdrawable.
|
|
178
|
+
|
|
179
|
+
```typescript
|
|
180
|
+
const unavailable = sdk.getUnavailableAgentIds(8453, "USDC"); // e.g. ["yieldseeker"]
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### `getAvailableAgents({ chainId?, asset?, includeDisabled?, includeUnavailable? })`
|
|
184
|
+
|
|
185
|
+
Lists the configured agents. Disabled agents and agents unavailable on `chainId` (and `asset`) this session are omitted by default, because neither takes deposits. Pass `includeUnavailable: true` to list the unavailable ones too; `includeDisabled: true` lists both, since a disabled or unavailable agent may still hold funds to withdraw.
|
|
186
|
+
|
|
187
|
+
An adapter may implement the optional `IAgent.isSlotUnavailable(state, chainId, asset)`: true when its provider reported this session that the user cannot have an agent for that chain and asset. That is not a failure: `activateAgent` returns normally for it, deposits leave the slot out, and withdrawals without an explicit agent skip it.
|
|
188
|
+
|
|
189
|
+
Yieldseeker closes (deactivates) agents that stayed empty. The SDK reopens the user's verified agent when it finds it closed, at sign-in, on reads and before a deposit (at most one reopen request per slot per 120 s, and none after a permanent refusal). An agent that cannot be reopened fails with `YIELDSEEKER_AGENT_CLOSED`; at Yieldseeker's active-agent limit the slot reports `YIELDSEEKER_SLOT_UNAVAILABLE` and is unavailable for the session. A deposit is never sent to a closed agent.
|
|
190
|
+
|
|
126
191
|
### `deposit(options)`
|
|
127
192
|
|
|
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.
|
|
193
|
+
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.
|
|
129
194
|
|
|
130
195
|
| Param | Type | Description |
|
|
131
196
|
| ------------------------- | -------------------- | --------------------------------------------------------------- |
|
|
@@ -225,6 +290,10 @@ Balances are shown after any applicable performance fees have been deducted.
|
|
|
225
290
|
|
|
226
291
|
Returns: `AgentBalance` (single agent) or `OwneyBalances` (all agents)
|
|
227
292
|
|
|
293
|
+
Aggregate reads keep successful agents when another agent fails. The response
|
|
294
|
+
includes `agentErrors` and, for rate limits, absolute `agentRetryAt` deadlines.
|
|
295
|
+
The SDK throws `BALANCE_ALL_FAILED` when every active agent fails.
|
|
296
|
+
|
|
228
297
|
```typescript
|
|
229
298
|
// Single agent
|
|
230
299
|
const balance = await sdk.getBalances("zyfai");
|
|
@@ -252,6 +321,10 @@ Earnings are shown after any applicable performance fees have been deducted.
|
|
|
252
321
|
|
|
253
322
|
Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
|
|
254
323
|
|
|
324
|
+
Aggregate reads keep successful agents when another agent fails. The response
|
|
325
|
+
includes `agentErrors` and, for rate limits, absolute `agentRetryAt` deadlines.
|
|
326
|
+
The SDK throws `EARNINGS_ALL_FAILED` when every active agent fails.
|
|
327
|
+
|
|
255
328
|
```typescript
|
|
256
329
|
// Single agent
|
|
257
330
|
const earnings = await sdk.getEarnings("zyfai");
|
|
@@ -281,6 +354,9 @@ snapshot is less than one hour old, the SDK returns it without recalculating.
|
|
|
281
354
|
|
|
282
355
|
Returns: `AgentEarnings` (single agent) or `OwneyEarnings` (all agents)
|
|
283
356
|
|
|
357
|
+
Aggregate refreshes use the same partial-result and all-failed behavior as
|
|
358
|
+
`getEarnings()`.
|
|
359
|
+
|
|
284
360
|
```typescript
|
|
285
361
|
// Single agent
|
|
286
362
|
const refreshed = await sdk.refreshEarnings("zyfai");
|
|
@@ -446,8 +522,8 @@ console.log(usdcBaseApy.agentApy.zyfai.averageApy); // APY scoped to USDC on Bas
|
|
|
446
522
|
type AgentId = "zyfai";
|
|
447
523
|
type Asset = string;
|
|
448
524
|
type DailyApyDays = "7D" | "14D" | "30D";
|
|
449
|
-
type OwneySupportedChainId = 8453 | 42161;
|
|
450
|
-
type OwneySupportedChains = "BASE" | "ARBITRUM";
|
|
525
|
+
type OwneySupportedChainId = 1 | 8453 | 42161;
|
|
526
|
+
type OwneySupportedChains = "ETHEREUM" | "BASE" | "ARBITRUM";
|
|
451
527
|
type OwneySupportedTokens = "USDC" | "WETH";
|
|
452
528
|
|
|
453
529
|
type AgentSupportedAsset = {
|
|
@@ -464,7 +540,14 @@ type AgentSupportedAssets = {
|
|
|
464
540
|
|
|
465
541
|
interface OwneySDKConfig {
|
|
466
542
|
apiKey: string;
|
|
543
|
+
rpcUrls?: {
|
|
544
|
+
1?: string;
|
|
545
|
+
8453?: string;
|
|
546
|
+
42161?: string;
|
|
547
|
+
};
|
|
548
|
+
/** @deprecated Use rpcUrls. */
|
|
467
549
|
zyfaiRpcUrls?: {
|
|
550
|
+
1?: string;
|
|
468
551
|
8453?: string;
|
|
469
552
|
42161?: string;
|
|
470
553
|
};
|
|
@@ -579,12 +662,14 @@ interface AccountAgentApy {
|
|
|
579
662
|
weightedApyAfterFee?: number;
|
|
580
663
|
weightedApyAfterFeeDetails?: AgentApyDetails;
|
|
581
664
|
apyByChainAndAsset?: ApyByChainAndAsset;
|
|
665
|
+
history?: ApyHistoryPoint[];
|
|
582
666
|
}
|
|
583
667
|
|
|
584
668
|
interface OwneyAccountApy {
|
|
585
669
|
totalApy: string;
|
|
586
670
|
agentApy: Record<AgentId, AccountAgentApy>;
|
|
587
671
|
apyByChainAndAsset: ApyByChainAndAsset;
|
|
672
|
+
history?: ApyHistoryPoint[]; // balance-weighted aggregate daily series
|
|
588
673
|
}
|
|
589
674
|
|
|
590
675
|
type HistoryAction = "Rebalance" | "Deposit" | "Top up" | "Withdraw" | "Earned";
|
|
@@ -703,6 +788,9 @@ type OwneyErrorCode =
|
|
|
703
788
|
| "AGENT_NOT_FOUND" // Unknown agent ID passed
|
|
704
789
|
| "AGENT_CHAIN_INCOMPATIBLE" // Agent(s) don't support the given chain
|
|
705
790
|
| "AGENT_EMPTY_LIST" // Empty agentId array passed to activateAgent()
|
|
791
|
+
| "AGENT_ACTIVATION_PARTIAL_FAILURE" // An earlier agent activated, then one failed and activation stopped; details.walletRejected when the user rejected a signature
|
|
792
|
+
| "YIELDSEEKER_AGENT_CLOSED" // Yieldseeker closed the slot's agent and it cannot be reopened; before a deposit details carry notSubmitted: true, safeToFallback: false (nothing was sent)
|
|
793
|
+
| "YIELDSEEKER_SLOT_UNAVAILABLE" // No Yieldseeker agent for this slot this session (the user's active-agent limit); details.providerCode names the limit
|
|
706
794
|
// Chain
|
|
707
795
|
| "CHAIN_UNSUPPORTED" // Chain ID not in supported list (8453, 42161)
|
|
708
796
|
| "CHAIN_NO_COMPATIBLE_AGENTS" // No agents support the given chain
|
|
@@ -726,6 +814,7 @@ type OwneyErrorCode =
|
|
|
726
814
|
| "API_NO_AGENTS" // No supported agents returned by routing API
|
|
727
815
|
// Aggregation
|
|
728
816
|
| "BALANCE_ALL_FAILED" // All agents failed to return balances
|
|
817
|
+
| "EARNINGS_ALL_FAILED" // All agents failed to return earnings
|
|
729
818
|
| "ALLOCATION_ALL_FAILED" // All agents failed to return allocation data
|
|
730
819
|
// Validation
|
|
731
820
|
| "VALIDATION_INVALID_DAYS"; // Invalid days value (expected "7D", "14D", or "30D")
|