@exagent/sdk 0.1.20 → 0.2.0

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.ts CHANGED
@@ -1,2099 +1,489 @@
1
- import * as viem from 'viem';
2
- import { Address, Hash, Chain, Account, Hex, WalletClient } from 'viem';
3
- import * as viem_chains from 'viem/chains';
1
+ import { z } from 'zod';
4
2
 
5
- /**
6
- * ERC-8004 Global Agent Identifier
7
- * Format: eip155:{chainId}:{registryAddress}:{agentId}
8
- *
9
- * This creates a universally unique identifier for any agent across
10
- * all EVM chains, enabling cross-protocol agent discovery.
11
- *
12
- * @example
13
- * ```
14
- * // Base mainnet agent #42
15
- * "eip155:8453:0xABC...DEF:42"
16
- *
17
- * // Another Base mainnet agent
18
- * "eip155:8453:0x123...789:7"
19
- * ```
20
- */
21
- type GlobalAgentId = `eip155:${number}:${Address}:${number}`;
22
- /**
23
- * Build an ERC-8004 compliant global agent identifier
24
- *
25
- * @param chainId - EVM chain ID (8453 for Base)
26
- * @param registryAddress - ExagentRegistry contract address
27
- * @param agentId - On-chain agent ID (from ExagentRegistry)
28
- * @returns Global agent identifier string
29
- *
30
- * @example
31
- * ```typescript
32
- * import { buildGlobalAgentId } from '@exagent/sdk';
33
- *
34
- * const globalId = buildGlobalAgentId(8453, '0xABC...DEF', 42);
35
- * // => "eip155:8453:0xABC...DEF:42"
36
- * ```
37
- */
38
- declare function buildGlobalAgentId(chainId: number, registryAddress: Address, agentId: number | bigint): GlobalAgentId;
39
- /**
40
- * Parse an ERC-8004 global agent identifier into its components
41
- *
42
- * @param globalId - The global agent identifier string
43
- * @returns Parsed components: chainId, registryAddress, agentId
44
- * @throws Error if the format is invalid
45
- */
46
- declare function parseGlobalAgentId(globalId: string): {
47
- chainId: number;
48
- registryAddress: Address;
49
- agentId: number;
50
- };
51
- /**
52
- * Agent profile as stored on-chain
53
- */
54
3
  interface AgentProfile {
55
- agentId: bigint;
56
- owner: Address;
4
+ id: string;
5
+ userId: string;
57
6
  name: string;
58
- metadataURI: string;
59
- registrationTime: bigint;
60
- verified: boolean;
61
- linkedWalletCount: bigint;
7
+ description?: string;
8
+ status: AgentStatus;
9
+ config: AgentConfig;
10
+ createdAt: string;
11
+ updatedAt: string;
62
12
  }
63
- /**
64
- * Agent metadata stored on IPFS
65
- */
66
- interface AgentMetadata {
67
- name: string;
68
- description: string;
69
- capabilities: string[];
13
+ type AgentStatus = 'online' | 'idle' | 'trading' | 'error' | 'offline';
14
+ interface AgentConfig {
15
+ llm: LLMConfig;
16
+ strategy: StrategyConfig;
17
+ trading: TradingConfig;
18
+ relay: RelayConfig;
19
+ venues?: VenueConfig;
20
+ }
21
+ interface LLMConfig {
22
+ provider: LLMProvider;
70
23
  model?: string;
71
- framework?: string;
72
- avatar?: string;
73
- website?: string;
74
- social?: {
75
- twitter?: string;
76
- github?: string;
77
- };
24
+ apiKey?: string;
25
+ endpoint?: string;
26
+ temperature?: number;
27
+ maxTokens?: number;
78
28
  }
79
- /**
80
- * Trade intent for broadcasting
81
- */
82
- interface TradeIntent {
83
- action: 'BUY' | 'SELL';
84
- tokenIn: Address;
85
- tokenOut: Address;
86
- amountIn: bigint;
87
- minAmountOut?: bigint;
88
- maxSlippageBps?: number;
89
- deadline?: number;
90
- /** LLM config hash (bytes32) for epoch attribution — passed to on-chain router */
91
- configHash?: `0x${string}`;
29
+ type LLMProvider = 'openai' | 'anthropic' | 'google' | 'deepseek' | 'mistral' | 'groq' | 'together' | 'ollama';
30
+ interface StrategyConfig {
31
+ file?: string;
32
+ template?: string;
92
33
  }
93
- /**
94
- * M2M service request
95
- */
96
- interface ServiceRequest {
97
- serviceType: string;
98
- providerId?: bigint;
99
- maxPriceAX: bigint;
100
- payload: Record<string, unknown>;
101
- deadline?: number;
34
+ interface TradingConfig {
35
+ mode: 'live' | 'paper';
36
+ timeHorizon: 'intraday' | 'swing' | 'position';
37
+ maxPositionSizeBps: number;
38
+ maxDailyLossBps: number;
39
+ maxConcurrentPositions: number;
40
+ tradingIntervalMs: number;
41
+ maxSlippageBps: number;
42
+ minTradeValueUSD: number;
43
+ initialCapitalUSD?: number;
102
44
  }
103
- /**
104
- * Performance metrics snapshot
105
- */
106
- interface PerformanceSnapshot {
107
- agentId: bigint;
108
- timestamp: bigint;
109
- pnlBps: number;
110
- tradeCount: number;
111
- volumeUSD: bigint;
112
- sharpeRatio?: number;
113
- sortinoRatio?: number;
114
- maxDrawdownBps?: number;
45
+ interface RelayConfig {
46
+ url: string;
47
+ heartbeatIntervalMs?: number;
48
+ reconnectMaxAttempts?: number;
115
49
  }
116
- /**
117
- * DEX route quote from 0x API
118
- */
119
- interface RouteQuote {
120
- tokenIn: Address;
121
- tokenOut: Address;
122
- amountIn: string;
123
- amountOut: string;
124
- minAmountOut: string;
125
- priceImpactBps: number;
126
- route: RouteStep[];
127
- transaction: {
128
- to: Address;
129
- data: `0x${string}`;
130
- value: string;
50
+ interface VenueConfig {
51
+ hyperliquid?: {
52
+ enabled: boolean;
53
+ maxLeverage?: number;
54
+ maxNotionalUSD?: number;
131
55
  };
132
- gasEstimate: string;
133
- validUntil: number;
134
- permit2?: {
135
- eip712: unknown;
56
+ polymarket?: {
57
+ enabled: boolean;
58
+ maxNotionalUSD?: number;
59
+ maxExposureUSD?: number;
136
60
  };
137
- issues?: {
138
- allowance?: {
139
- spender: Address;
140
- actual: string;
141
- expected: string;
142
- };
61
+ spot?: {
62
+ enabled: boolean;
63
+ chains?: string[];
143
64
  };
144
- mock?: boolean;
145
65
  }
146
- /**
147
- * Route step through a DEX
148
- */
149
- interface RouteStep {
150
- dex: string;
151
- pool: string;
152
- share: number;
66
+ interface TradeSignal {
67
+ venue: string;
68
+ chain?: string;
69
+ symbol: string;
70
+ side: 'long' | 'short' | 'buy' | 'sell';
71
+ size: number;
72
+ price: number;
73
+ fee: number;
74
+ venueFillId: string;
75
+ venueTimestamp: string;
76
+ leverage?: number;
77
+ orderType?: string;
78
+ confidence?: number;
79
+ reasoning?: string;
153
80
  }
154
- /**
155
- * Price quote (no transaction data)
156
- */
157
- interface PriceQuote {
158
- tokenIn: Address;
159
- tokenOut: Address;
160
- amountIn: string;
161
- amountOut: string;
162
- priceImpactBps: number;
163
- mock?: boolean;
81
+ interface PerpTradeSignal {
82
+ action: 'open_long' | 'open_short' | 'close_long' | 'close_short' | 'hold';
83
+ instrument: string;
84
+ size: number;
85
+ price: number;
86
+ leverage: number;
87
+ orderType: 'limit' | 'market';
88
+ reduceOnly: boolean;
89
+ confidence: number;
90
+ reasoning?: string;
164
91
  }
165
- /**
166
- * Router trade response - transaction routed through ExagentRouter
167
- */
168
- interface RouterTradeResponse {
169
- agentId: number;
170
- tokenIn: Address;
171
- tokenOut: Address;
172
- amountIn: string;
173
- amountOut: string;
174
- minAmountOut: string;
175
- priceImpactBps: number;
176
- route: RouteStep[];
177
- transaction: {
178
- to: Address;
179
- data: `0x${string}`;
180
- value: string;
181
- };
182
- approvals: Array<{
183
- token: Address;
184
- spender: Address;
185
- amount: string;
186
- }>;
187
- gasEstimate: string;
188
- validUntil: number;
189
- attribution: {
190
- router: Address;
191
- aggregator: Address;
192
- agentId: number;
92
+ interface PredictionTradeSignal {
93
+ action: 'buy_yes' | 'buy_no' | 'sell_yes' | 'sell_no' | 'hold';
94
+ marketConditionId: string;
95
+ marketQuestion: string;
96
+ outcomeIndex: number;
97
+ amount: number;
98
+ limitPrice: number;
99
+ confidence: number;
100
+ reasoning?: string;
101
+ }
102
+ interface LLMMessage {
103
+ role: 'user' | 'assistant' | 'system';
104
+ content: string;
105
+ }
106
+ interface LLMResponse {
107
+ content: string;
108
+ tokens?: {
109
+ input: number;
110
+ output: number;
193
111
  };
194
- mock?: boolean;
195
- /** Present when API's pre-flight simulation failed (for sells) */
196
- simulationSkipped?: boolean;
197
- /** Warning message when simulation failed */
198
- simulationWarning?: string;
199
112
  }
200
- /**
201
- * Trade execution result
202
- */
203
- interface TradeResult {
204
- hash: Hash;
205
- agentId: bigint;
206
- tokenIn: Address;
207
- tokenOut: Address;
208
- amountIn: string;
209
- expectedAmountOut: string;
113
+ interface LLMAdapter {
114
+ chat(messages: LLMMessage[]): Promise<LLMResponse>;
115
+ getMetadata(): LLMMetadata;
210
116
  }
211
- /**
212
- * Vault configuration for creating a new vault
213
- */
214
- interface VaultConfig {
215
- agentId: bigint;
216
- asset: Address;
217
- name: string;
218
- symbol: string;
219
- feeRecipient: Address;
220
- performanceFeeBps?: number;
221
- managementFeeBps?: number;
117
+ interface LLMMetadata {
118
+ provider: string;
119
+ model: string;
120
+ maxTokens?: number;
121
+ }
122
+ interface StrategyContext {
123
+ llm: LLMAdapter;
124
+ market: MarketData;
125
+ position: PositionSummary;
126
+ store: StrategyStore;
127
+ config: TradingConfig;
128
+ log: (message: string) => void;
222
129
  }
223
- /**
224
- * Vault summary for listing
225
- */
226
- interface VaultSummary {
227
- address: Address;
130
+ type StrategyFunction = (context: StrategyContext) => Promise<TradeSignal[]>;
131
+ interface StrategyStore {
132
+ get<T>(key: string): T | undefined;
133
+ set<T>(key: string, value: T): void;
134
+ delete(key: string): void;
135
+ keys(): string[];
136
+ }
137
+ interface StrategyTemplate {
138
+ id: string;
228
139
  name: string;
229
- symbol: string;
230
- asset: Address;
231
- agentId: bigint;
232
- totalAssets: bigint;
233
- sharePrice: bigint;
234
- performanceFeeBps: number;
235
- managementFeeBps: number;
236
- depositorCount: number;
237
- totalPnlBps: number;
238
- isAcceptingDeposits: boolean;
140
+ description: string;
141
+ category: 'momentum' | 'value' | 'arbitrage' | 'market_making' | 'custom';
142
+ venues: string[];
143
+ riskLevel: 'conservative' | 'moderate' | 'aggressive';
144
+ code: string;
145
+ systemPrompt: string;
239
146
  }
240
- /**
241
- * User's vault position for portfolio display
242
- */
243
- interface UserVaultPosition {
244
- vault: Address;
245
- vaultName: string;
246
- shares: bigint;
247
- assetsValue: bigint;
248
- entryPrice: bigint;
249
- currentPrice: bigint;
250
- pnlBps: number;
251
- pnlUsd: bigint;
252
- pendingWithdrawals: bigint;
147
+ interface MarketData {
148
+ getPrice(symbol: string): number | undefined;
149
+ getPrices(): Record<string, number>;
150
+ getOHLCV(symbol: string, timeframe: string): OHLCV[];
253
151
  }
254
- /**
255
- * Vault deposit/withdrawal history entry
256
- */
257
- interface VaultActivityEntry {
258
- type: 'deposit' | 'withdraw' | 'request_withdrawal' | 'claim_withdrawal' | 'emergency_withdraw';
259
- user: Address;
260
- vault: Address;
261
- shares: bigint;
262
- assets: bigint;
263
- timestamp: bigint;
264
- txHash: Hash;
152
+ interface OHLCV {
153
+ timestamp: number;
154
+ open: number;
155
+ high: number;
156
+ low: number;
157
+ close: number;
158
+ volume: number;
265
159
  }
266
- /**
267
- * Vault trade executed by agent
268
- */
269
- interface VaultTradeEntry {
270
- agentId: bigint;
271
- vault: Address;
272
- tokenIn: Address;
273
- tokenOut: Address;
274
- amountIn: bigint;
275
- amountOut: bigint;
276
- aggregator: Address;
277
- timestamp: bigint;
278
- txHash: Hash;
160
+ interface TrackedPosition {
161
+ token: string;
162
+ quantity: number;
163
+ costBasisPerUnit: number;
164
+ entryTimestamp: number;
165
+ venue?: string;
166
+ chain?: string;
279
167
  }
280
-
281
- /**
282
- * ABI for ExagentRegistry contract
283
- */
284
- declare const EXAGENT_REGISTRY_ABI: readonly [{
285
- readonly type: "function";
286
- readonly name: "registerAgent";
287
- readonly inputs: readonly [{
288
- readonly name: "name";
289
- readonly type: "string";
290
- }, {
291
- readonly name: "metadataURI";
292
- readonly type: "string";
293
- }, {
294
- readonly name: "riskUniverse";
295
- readonly type: "uint8";
296
- }, {
297
- readonly name: "maxPositionSizeBps";
298
- readonly type: "uint256";
299
- }, {
300
- readonly name: "maxDailyLossBps";
301
- readonly type: "uint256";
302
- }];
303
- readonly outputs: readonly [{
304
- readonly name: "agentId";
305
- readonly type: "uint256";
306
- }];
307
- readonly stateMutability: "nonpayable";
308
- }, {
309
- readonly type: "function";
310
- readonly name: "isNameAvailable";
311
- readonly inputs: readonly [{
312
- readonly name: "name";
313
- readonly type: "string";
314
- }];
315
- readonly outputs: readonly [{
316
- readonly name: "available";
317
- readonly type: "bool";
318
- }];
319
- readonly stateMutability: "view";
320
- }, {
321
- readonly type: "function";
322
- readonly name: "getAgentByName";
323
- readonly inputs: readonly [{
324
- readonly name: "name";
325
- readonly type: "string";
326
- }];
327
- readonly outputs: readonly [{
328
- readonly name: "agentId";
329
- readonly type: "uint256";
330
- }];
331
- readonly stateMutability: "view";
332
- }, {
333
- readonly type: "function";
334
- readonly name: "linkWallet";
335
- readonly inputs: readonly [{
336
- readonly name: "agentId";
337
- readonly type: "uint256";
338
- }, {
339
- readonly name: "wallet";
340
- readonly type: "address";
341
- }, {
342
- readonly name: "signature";
343
- readonly type: "bytes";
344
- }];
345
- readonly outputs: readonly [];
346
- readonly stateMutability: "nonpayable";
347
- }, {
348
- readonly type: "function";
349
- readonly name: "linkOwnWallet";
350
- readonly inputs: readonly [{
351
- readonly name: "agentId";
352
- readonly type: "uint256";
353
- }];
354
- readonly outputs: readonly [];
355
- readonly stateMutability: "nonpayable";
356
- }, {
357
- readonly type: "function";
358
- readonly name: "unlinkWallet";
359
- readonly inputs: readonly [{
360
- readonly name: "agentId";
361
- readonly type: "uint256";
362
- }, {
363
- readonly name: "wallet";
364
- readonly type: "address";
365
- }];
366
- readonly outputs: readonly [];
367
- readonly stateMutability: "nonpayable";
368
- }, {
369
- readonly type: "function";
370
- readonly name: "updateMetadata";
371
- readonly inputs: readonly [{
372
- readonly name: "agentId";
373
- readonly type: "uint256";
374
- }, {
375
- readonly name: "newURI";
376
- readonly type: "string";
377
- }];
378
- readonly outputs: readonly [];
379
- readonly stateMutability: "nonpayable";
380
- }, {
381
- readonly type: "function";
382
- readonly name: "agents";
383
- readonly inputs: readonly [{
384
- readonly name: "agentId";
385
- readonly type: "uint256";
386
- }];
387
- readonly outputs: readonly [{
388
- readonly name: "owner";
389
- readonly type: "address";
390
- }, {
391
- readonly name: "name";
392
- readonly type: "string";
393
- }, {
394
- readonly name: "metadataURI";
395
- readonly type: "string";
396
- }, {
397
- readonly name: "registrationTime";
398
- readonly type: "uint256";
399
- }, {
400
- readonly name: "verified";
401
- readonly type: "bool";
402
- }, {
403
- readonly name: "linkedWalletCount";
404
- readonly type: "uint256";
405
- }];
406
- readonly stateMutability: "view";
407
- }, {
408
- readonly type: "function";
409
- readonly name: "getLinkedWallets";
410
- readonly inputs: readonly [{
411
- readonly name: "agentId";
412
- readonly type: "uint256";
413
- }];
414
- readonly outputs: readonly [{
415
- readonly name: "";
416
- readonly type: "address[]";
417
- }];
418
- readonly stateMutability: "view";
419
- }, {
420
- readonly type: "function";
421
- readonly name: "getAgentForWallet";
422
- readonly inputs: readonly [{
423
- readonly name: "wallet";
424
- readonly type: "address";
425
- }];
426
- readonly outputs: readonly [{
427
- readonly name: "";
428
- readonly type: "uint256";
429
- }];
430
- readonly stateMutability: "view";
431
- }, {
432
- readonly type: "function";
433
- readonly name: "walletToAgent";
434
- readonly inputs: readonly [{
435
- readonly name: "wallet";
436
- readonly type: "address";
437
- }];
438
- readonly outputs: readonly [{
439
- readonly name: "";
440
- readonly type: "uint256";
441
- }];
442
- readonly stateMutability: "view";
443
- }, {
444
- readonly type: "function";
445
- readonly name: "nonces";
446
- readonly inputs: readonly [{
447
- readonly name: "wallet";
448
- readonly type: "address";
449
- }];
450
- readonly outputs: readonly [{
451
- readonly name: "";
452
- readonly type: "uint256";
453
- }];
454
- readonly stateMutability: "view";
455
- }, {
456
- readonly type: "function";
457
- readonly name: "ownerOf";
458
- readonly inputs: readonly [{
459
- readonly name: "tokenId";
460
- readonly type: "uint256";
461
- }];
462
- readonly outputs: readonly [{
463
- readonly name: "";
464
- readonly type: "address";
465
- }];
466
- readonly stateMutability: "view";
467
- }, {
468
- readonly type: "function";
469
- readonly name: "balanceOf";
470
- readonly inputs: readonly [{
471
- readonly name: "owner";
472
- readonly type: "address";
473
- }];
474
- readonly outputs: readonly [{
475
- readonly name: "";
476
- readonly type: "uint256";
477
- }];
478
- readonly stateMutability: "view";
479
- }, {
480
- readonly type: "event";
481
- readonly name: "AgentRegistered";
482
- readonly inputs: readonly [{
483
- readonly name: "agentId";
484
- readonly type: "uint256";
485
- readonly indexed: true;
486
- }, {
487
- readonly name: "owner";
488
- readonly type: "address";
489
- readonly indexed: true;
490
- }, {
491
- readonly name: "name";
492
- readonly type: "string";
493
- readonly indexed: false;
494
- }, {
495
- readonly name: "metadataURI";
496
- readonly type: "string";
497
- readonly indexed: false;
498
- }];
499
- }, {
500
- readonly type: "event";
501
- readonly name: "WalletLinked";
502
- readonly inputs: readonly [{
503
- readonly name: "agentId";
504
- readonly type: "uint256";
505
- readonly indexed: true;
506
- }, {
507
- readonly name: "wallet";
508
- readonly type: "address";
509
- readonly indexed: true;
510
- }];
511
- }, {
512
- readonly type: "event";
513
- readonly name: "WalletUnlinked";
514
- readonly inputs: readonly [{
515
- readonly name: "agentId";
516
- readonly type: "uint256";
517
- readonly indexed: true;
518
- }, {
519
- readonly name: "wallet";
520
- readonly type: "address";
521
- readonly indexed: true;
522
- }];
523
- }, {
524
- readonly type: "function";
525
- readonly name: "ownerToAgentId";
526
- readonly inputs: readonly [{
527
- readonly name: "owner";
528
- readonly type: "address";
529
- }];
530
- readonly outputs: readonly [{
531
- readonly name: "";
532
- readonly type: "uint256";
533
- }];
534
- readonly stateMutability: "view";
535
- }, {
536
- readonly type: "function";
537
- readonly name: "getAgentByOwner";
538
- readonly inputs: readonly [{
539
- readonly name: "wallet";
540
- readonly type: "address";
541
- }];
542
- readonly outputs: readonly [{
543
- readonly name: "agentId";
544
- readonly type: "uint256";
545
- }];
546
- readonly stateMutability: "view";
547
- }, {
548
- readonly type: "function";
549
- readonly name: "canWalletRegister";
550
- readonly inputs: readonly [{
551
- readonly name: "wallet";
552
- readonly type: "address";
553
- }];
554
- readonly outputs: readonly [{
555
- readonly name: "canRegister";
556
- readonly type: "bool";
557
- }, {
558
- readonly name: "existingAgentId";
559
- readonly type: "uint256";
560
- }];
561
- readonly stateMutability: "view";
562
- }, {
563
- readonly type: "function";
564
- readonly name: "setConfig";
565
- readonly inputs: readonly [{
566
- readonly name: "agentId";
567
- readonly type: "uint256";
568
- }, {
569
- readonly name: "configHash";
570
- readonly type: "bytes32";
571
- }];
572
- readonly outputs: readonly [];
573
- readonly stateMutability: "nonpayable";
574
- }, {
575
- readonly type: "function";
576
- readonly name: "getConfigHash";
577
- readonly inputs: readonly [{
578
- readonly name: "agentId";
579
- readonly type: "uint256";
580
- }];
581
- readonly outputs: readonly [{
582
- readonly name: "";
583
- readonly type: "bytes32";
584
- }];
585
- readonly stateMutability: "view";
586
- }, {
587
- readonly type: "function";
588
- readonly name: "retireAgent";
589
- readonly inputs: readonly [{
590
- readonly name: "agentId";
591
- readonly type: "uint256";
592
- }];
593
- readonly outputs: readonly [];
594
- readonly stateMutability: "nonpayable";
595
- }, {
596
- readonly type: "function";
597
- readonly name: "retired";
598
- readonly inputs: readonly [{
599
- readonly name: "agentId";
600
- readonly type: "uint256";
601
- }];
602
- readonly outputs: readonly [{
603
- readonly type: "bool";
604
- }];
605
- readonly stateMutability: "view";
606
- }, {
607
- readonly type: "function";
608
- readonly name: "isRetired";
609
- readonly inputs: readonly [{
610
- readonly name: "agentId";
611
- readonly type: "uint256";
612
- }];
613
- readonly outputs: readonly [{
614
- readonly type: "bool";
615
- }];
616
- readonly stateMutability: "view";
617
- }, {
618
- readonly type: "function";
619
- readonly name: "isTradeAllowed";
620
- readonly inputs: readonly [{
621
- readonly name: "agentId";
622
- readonly type: "uint256";
623
- }, {
624
- readonly name: "token";
625
- readonly type: "address";
626
- }, {
627
- readonly name: "aggregator";
628
- readonly type: "address";
629
- }];
630
- readonly outputs: readonly [{
631
- readonly type: "bool";
632
- }];
633
- readonly stateMutability: "view";
634
- }, {
635
- readonly type: "function";
636
- readonly name: "getRiskUniverse";
637
- readonly inputs: readonly [{
638
- readonly name: "agentId";
639
- readonly type: "uint256";
640
- }];
641
- readonly outputs: readonly [{
642
- readonly type: "uint8";
643
- }];
644
- readonly stateMutability: "view";
645
- }, {
646
- readonly type: "function";
647
- readonly name: "tradeCount";
648
- readonly inputs: readonly [{
649
- readonly name: "agentId";
650
- readonly type: "uint256";
651
- }];
652
- readonly outputs: readonly [{
653
- readonly type: "uint256";
654
- }];
655
- readonly stateMutability: "view";
656
- }, {
657
- readonly type: "event";
658
- readonly name: "AgentRetired";
659
- readonly inputs: readonly [{
660
- readonly name: "agentId";
661
- readonly type: "uint256";
662
- readonly indexed: true;
663
- }];
664
- }, {
665
- readonly type: "event";
666
- readonly name: "ConfigUpdated";
667
- readonly inputs: readonly [{
668
- readonly name: "agentId";
669
- readonly type: "uint256";
670
- readonly indexed: true;
671
- }, {
672
- readonly name: "oldConfigHash";
673
- readonly type: "bytes32";
674
- readonly indexed: false;
675
- }, {
676
- readonly name: "newConfigHash";
677
- readonly type: "bytes32";
678
- readonly indexed: false;
679
- }, {
680
- readonly name: "epochId";
681
- readonly type: "uint256";
682
- readonly indexed: false;
683
- }, {
684
- readonly name: "blockNumber";
685
- readonly type: "uint256";
686
- readonly indexed: false;
687
- }];
688
- }, {
689
- readonly type: "error";
690
- readonly name: "AgentNotOwner";
691
- readonly inputs: readonly [];
692
- }, {
693
- readonly type: "error";
694
- readonly name: "WalletAlreadyLinked";
695
- readonly inputs: readonly [];
696
- }, {
697
- readonly type: "error";
698
- readonly name: "WalletNotLinked";
699
- readonly inputs: readonly [];
700
- }, {
701
- readonly type: "error";
702
- readonly name: "InvalidSignature";
703
- readonly inputs: readonly [];
704
- }, {
705
- readonly type: "error";
706
- readonly name: "TransferDisabled";
707
- readonly inputs: readonly [];
708
- }, {
709
- readonly type: "error";
710
- readonly name: "InvalidMetadataURI";
711
- readonly inputs: readonly [];
712
- }, {
713
- readonly type: "error";
714
- readonly name: "AgentDoesNotExist";
715
- readonly inputs: readonly [];
716
- }, {
717
- readonly type: "error";
718
- readonly name: "NameAlreadyTaken";
719
- readonly inputs: readonly [];
720
- }, {
721
- readonly type: "error";
722
- readonly name: "InvalidName";
723
- readonly inputs: readonly [];
724
- }, {
725
- readonly type: "error";
726
- readonly name: "OwnerAlreadyHasAgent";
727
- readonly inputs: readonly [{
728
- readonly name: "existingAgentId";
729
- readonly type: "uint256";
730
- }];
731
- }, {
732
- readonly type: "error";
733
- readonly name: "InvalidRiskUniverse";
734
- readonly inputs: readonly [];
735
- }, {
736
- readonly type: "error";
737
- readonly name: "InvalidTradingConfig";
738
- readonly inputs: readonly [];
739
- }, {
740
- readonly type: "error";
741
- readonly name: "NotAuthorizedCaller";
742
- readonly inputs: readonly [];
743
- }, {
744
- readonly type: "error";
745
- readonly name: "MetadataValueTooLarge";
746
- readonly inputs: readonly [];
747
- }, {
748
- readonly type: "error";
749
- readonly name: "AgentIsRetired";
750
- readonly inputs: readonly [];
751
- }, {
752
- readonly type: "error";
753
- readonly name: "InvalidRiskUniverseForWhitelist";
754
- readonly inputs: readonly [];
755
- }];
756
- /**
757
- * Wrapper for ExagentRegistry contract interactions
758
- */
759
- declare class ExagentRegistry {
760
- readonly address: Address;
761
- private readonly publicClient;
762
- private readonly walletClient?;
763
- private readonly chain;
764
- private readonly account?;
765
- constructor(address: Address, publicClient: any, walletClient: any | undefined, chain: Chain, account?: Account);
766
- /**
767
- * Register a new agent
768
- * @param name Unique agent name (3-32 chars, alphanumeric + spaces/hyphens/underscores)
769
- * @param metadataURI IPFS URI for agent metadata
770
- * @param riskUniverse Risk tier: 0=Core, 1=Established, 2=Derivatives, 3=Emerging, 4=Frontier
771
- * @param maxPositionSizeBps Maximum position size in basis points (1-10000)
772
- * @param maxDailyLossBps Maximum daily loss in basis points (1-10000)
773
- * @returns Transaction hash
774
- */
775
- register(name: string, metadataURI: string, riskUniverse?: number, maxPositionSizeBps?: bigint, maxDailyLossBps?: bigint): Promise<Hash>;
776
- /**
777
- * Check if a name is available for registration
778
- * @param name The name to check
779
- * @returns True if the name can be used
780
- */
781
- isNameAvailable(name: string): Promise<boolean>;
782
- /**
783
- * Get the agent ID that owns a specific name
784
- * @param name The name to look up
785
- * @returns Agent ID (0 if not taken)
786
- */
787
- getAgentByName(name: string): Promise<bigint>;
788
- /**
789
- * Link the wallet used by the agent to their agent ID
790
- * @param agentId The agent's ID
791
- * @returns Transaction hash
792
- */
793
- linkOwnWallet(agentId: bigint): Promise<Hash>;
794
- /**
795
- * Link an external wallet with signature proof
796
- * @param agentId The agent's ID
797
- * @param wallet The wallet to link
798
- * @param signature Signature from the wallet proving ownership
799
- * @returns Transaction hash
800
- */
801
- linkWallet(agentId: bigint, wallet: Address, signature: `0x${string}`): Promise<Hash>;
802
- /**
803
- * Unlink a wallet from an agent
804
- * @param agentId The agent's ID
805
- * @param wallet The wallet to unlink
806
- * @returns Transaction hash
807
- */
808
- unlinkWallet(agentId: bigint, wallet: Address): Promise<Hash>;
809
- /**
810
- * Update agent metadata
811
- * @param agentId The agent's ID
812
- * @param newURI New IPFS URI for metadata
813
- * @returns Transaction hash
814
- */
815
- updateMetadata(agentId: bigint, newURI: string): Promise<Hash>;
816
- /**
817
- * Get agent profile by ID
818
- * @param agentId The agent's ID
819
- * @returns Agent profile data
820
- */
821
- getAgent(agentId: bigint): Promise<AgentProfile>;
822
- /**
823
- * Get all linked wallets for an agent
824
- * @param agentId The agent's ID
825
- * @returns Array of linked wallet addresses
826
- */
827
- getLinkedWallets(agentId: bigint): Promise<Address[]>;
828
- /**
829
- * Get agent ID for a wallet (for trade attribution)
830
- * @param wallet The wallet address
831
- * @returns Agent ID (0 if not linked)
832
- */
833
- getAgentForWallet(wallet: Address): Promise<bigint>;
834
- /**
835
- * Check if a wallet is linked to a specific agent
836
- * @param agentId The agent's ID
837
- * @param wallet The wallet address to check
838
- * @returns True if the wallet is linked to the agent
839
- */
840
- isLinkedWallet(agentId: bigint, wallet: Address): Promise<boolean>;
841
- /**
842
- * Get the nonce for wallet linking signature
843
- * @param wallet The wallet address
844
- * @returns Current nonce
845
- */
846
- getNonce(wallet: Address): Promise<bigint>;
847
- /**
848
- * Generate the message hash for wallet linking.
849
- * Matches the contract's keccak256(abi.encodePacked(...)) exactly.
850
- * Sign the returned hash with signMessage({ raw: hash }) to produce a valid signature.
851
- * @param wallet The wallet to link
852
- * @param agentId The agent ID to link to
853
- * @param nonce The current nonce for the wallet
854
- * @returns keccak256 hash of the packed message (32 bytes)
855
- */
856
- static generateLinkMessage(wallet: Address, agentId: bigint, nonce: bigint): Hex;
857
- /**
858
- * Get the agent owned by a wallet (not linked, owned)
859
- * @param wallet The wallet to look up
860
- * @returns Agent ID (0 if wallet doesn't own an agent)
861
- */
862
- getAgentByOwner(wallet: Address): Promise<bigint>;
863
- /**
864
- * Check if a wallet can register a new agent
865
- * @param wallet The wallet to check
866
- * @returns Object with canRegister boolean and existingAgentId (0 if none)
867
- */
868
- canWalletRegister(wallet: Address): Promise<{
869
- canRegister: boolean;
870
- existingAgentId: bigint;
871
- }>;
872
- /**
873
- * Update the agent's LLM config hash on-chain
874
- * @param agentId The agent's ID
875
- * @param configHash The keccak256 hash of (provider, model)
876
- * @returns Transaction hash
877
- */
878
- updateConfig(agentId: bigint, configHash: `0x${string}`): Promise<Hash>;
879
- /**
880
- * Get the current config hash for an agent
881
- * @param agentId The agent's ID
882
- * @returns Config hash (bytes32(0) if never set)
883
- */
884
- getConfigHash(agentId: bigint): Promise<`0x${string}`>;
885
- /**
886
- * Calculate the config hash for a provider and model
887
- * @param provider The LLM provider name (e.g., "openai", "anthropic")
888
- * @param model The model name (e.g., "gpt-4", "claude-opus-4.5")
889
- * @returns keccak256 hash of the config
890
- */
891
- static calculateConfigHash(provider: string, model: string): `0x${string}`;
892
- /**
893
- * Retire an agent — marks it as retired, unlinks all wallets, allows new agent registration
894
- * @param agentId The agent's ID
895
- * @returns Transaction hash
896
- */
897
- retireAgent(agentId: bigint): Promise<Hash>;
898
- /**
899
- * Check if an agent is retired
900
- * @param agentId The agent's ID
901
- * @returns True if agent is retired
902
- */
903
- isRetired(agentId: bigint): Promise<boolean>;
904
- /**
905
- * Check if a token trade is allowed for an agent's risk universe
906
- * @param agentId The agent's ID
907
- * @param token The token address to check
908
- * @param aggregator The aggregator being used (for trusted aggregator bypass)
909
- * @returns True if the trade is allowed
910
- */
911
- isTradeAllowed(agentId: bigint, token: Address, aggregator: Address): Promise<boolean>;
912
- /**
913
- * Get the risk universe for an agent
914
- * @param agentId The agent's ID
915
- * @returns Risk universe (0=Core, 1=Established, 2=Derivatives, 3=Emerging, 4=Frontier)
916
- */
917
- getRiskUniverse(agentId: bigint): Promise<number>;
918
- /**
919
- * Get trade count for an agent
920
- * @param agentId The agent's ID
921
- * @returns Number of recorded trades
922
- */
923
- getTradeCount(agentId: bigint): Promise<bigint>;
168
+ interface TradeRecord {
169
+ token: string;
170
+ action: 'buy' | 'sell';
171
+ quantity: number;
172
+ price: number;
173
+ fee: number;
174
+ timestamp: number;
175
+ venue?: string;
176
+ chain?: string;
177
+ venueFillId?: string;
924
178
  }
925
-
926
- /**
927
- * Vault info
928
- */
929
- interface VaultInfo {
930
- address: Address;
931
- name: string;
932
- symbol: string;
933
- asset: Address;
934
- agentId: bigint;
935
- totalAssets: bigint;
936
- totalSupply: bigint;
937
- sharePrice: bigint;
938
- highWaterMark: bigint;
939
- performanceFeeBps: bigint;
940
- managementFeeBps: bigint;
941
- feeRecipient: Address;
942
- depositsPaused: boolean;
943
- withdrawalsPaused: boolean;
944
- circuitBreakerActive: boolean;
179
+ interface PositionSummary {
180
+ openPositions: TrackedPosition[];
181
+ totalUnrealizedPnL: number;
182
+ totalRealizedPnL: number;
945
183
  }
946
- /**
947
- * User's vault position
948
- */
949
- interface VaultPosition {
950
- shares: bigint;
951
- effectiveShares: bigint;
952
- pendingWithdrawals: bigint;
953
- assetsValue: bigint;
954
- userHighWaterMark: bigint;
184
+ interface RiskParams {
185
+ maxPositionSizeBps: number;
186
+ maxDailyLossBps: number;
187
+ maxConcurrentPositions: number;
188
+ maxSlippageBps: number;
189
+ minTradeValueUSD: number;
190
+ confidenceThreshold?: number;
955
191
  }
956
- /**
957
- * Withdrawal request details
958
- */
959
- interface WithdrawalRequest {
960
- requestId: bigint;
961
- owner: Address;
962
- receiver: Address;
963
- shares: bigint;
964
- requestTime: bigint;
965
- processed: boolean;
966
- claimableAt: bigint;
192
+ interface PaperTrade {
193
+ id: string;
194
+ symbol: string;
195
+ side: 'buy' | 'sell';
196
+ size: number;
197
+ entryPrice: number;
198
+ exitPrice?: number;
199
+ fee: number;
200
+ pnl?: number;
201
+ timestamp: number;
202
+ venue: string;
967
203
  }
968
- /**
969
- * ExagentVault SDK interface for ERC-4626 copy trading vaults
970
- */
971
- declare class ExagentVault {
972
- readonly address: Address;
973
- private readonly publicClient;
974
- private readonly walletClient?;
975
- private readonly chain;
976
- private readonly account?;
977
- constructor(vaultAddress: Address, publicClient: any, walletClient?: any, chain?: Chain, account?: Account);
978
- /**
979
- * Get comprehensive vault info
980
- */
981
- getVaultInfo(): Promise<VaultInfo>;
982
- /**
983
- * Get user's position in the vault
984
- */
985
- getPosition(user: Address): Promise<VaultPosition>;
986
- /**
987
- * Get current share price (assets per share, scaled to 1e18)
988
- */
989
- getSharePrice(): Promise<bigint>;
990
- /**
991
- * Preview deposit - get shares for given assets
992
- */
993
- previewDeposit(assets: bigint): Promise<bigint>;
994
- /**
995
- * Preview withdrawal - get assets for given shares
996
- */
997
- previewRedeem(shares: bigint): Promise<bigint>;
998
- /**
999
- * Get max deposit amount
1000
- */
1001
- maxDeposit(receiver: Address): Promise<bigint>;
1002
- /**
1003
- * Get max withdrawal amount
1004
- */
1005
- maxWithdraw(owner: Address): Promise<bigint>;
1006
- /**
1007
- * Get rate limit status
1008
- */
1009
- getRateLimitStatus(): Promise<{
1010
- remaining: bigint;
1011
- periodEnds: bigint;
204
+ interface PaperPortfolio {
205
+ cash: number;
206
+ positions: Map<string, {
207
+ quantity: number;
208
+ avgPrice: number;
1012
209
  }>;
1013
- /**
1014
- * Get pending withdrawal request
1015
- */
1016
- getPendingWithdrawal(requestId: bigint): Promise<WithdrawalRequest>;
1017
- /**
1018
- * Deposit assets into the vault
1019
- * @param assets Amount of underlying asset to deposit
1020
- * @param receiver Address to receive vault shares
1021
- * @returns Transaction hash
1022
- */
1023
- deposit(assets: bigint, receiver?: Address): Promise<Hash>;
1024
- /**
1025
- * Withdraw assets from the vault
1026
- * @param assets Amount of underlying asset to withdraw
1027
- * @param receiver Address to receive assets
1028
- * @param owner Address whose shares to burn (defaults to caller)
1029
- * @returns Transaction hash
1030
- */
1031
- withdraw(assets: bigint, receiver?: Address, owner?: Address): Promise<Hash>;
1032
- /**
1033
- * Redeem shares for assets
1034
- * @param shares Amount of shares to redeem
1035
- * @param receiver Address to receive assets
1036
- * @param owner Address whose shares to burn (defaults to caller)
1037
- * @returns Transaction hash
1038
- */
1039
- redeem(shares: bigint, receiver?: Address, owner?: Address): Promise<Hash>;
1040
- /**
1041
- * Redeem all shares safely — charges performance fee first, then redeems remaining balance.
1042
- * Use this instead of redeem(fullBalance) to avoid ERC4626ExceededMaxRedeem revert.
1043
- * @param receiver Address to receive assets
1044
- * @param owner Address whose shares to burn (defaults to caller)
1045
- * @returns Transaction hash
1046
- */
1047
- redeemMax(receiver?: Address, owner?: Address): Promise<Hash>;
1048
- /**
1049
- * Withdraw all assets safely — charges performance fee first, then withdraws remaining balance.
1050
- * @param receiver Address to receive assets
1051
- * @param owner Address whose shares to burn (defaults to caller)
1052
- * @returns Transaction hash
1053
- */
1054
- withdrawMax(receiver?: Address, owner?: Address): Promise<Hash>;
1055
- /**
1056
- * Request a queued withdrawal (for large amounts)
1057
- * @param shares Amount of shares to withdraw
1058
- * @param receiver Address to receive assets
1059
- * @returns Transaction hash
1060
- */
1061
- requestWithdrawal(shares: bigint, receiver?: Address): Promise<Hash>;
1062
- /**
1063
- * Claim a pending withdrawal request
1064
- * @param requestId The withdrawal request ID
1065
- * @returns Transaction hash
1066
- */
1067
- claimWithdrawal(requestId: bigint): Promise<Hash>;
1068
- /**
1069
- * Cancel a pending withdrawal request
1070
- * @param requestId The withdrawal request ID
1071
- * @returns Transaction hash
1072
- */
1073
- cancelWithdrawal(requestId: bigint): Promise<Hash>;
1074
- /**
1075
- * Emergency withdrawal with penalty (50% if vault < 7 days old, 20% otherwise).
1076
- * Penalty stays in the vault for remaining backers.
1077
- * @returns Transaction hash
1078
- */
1079
- emergencyWithdraw(): Promise<Hash>;
1080
- /**
1081
- * Approve vault to spend underlying asset
1082
- * @param assetAddress The asset token address
1083
- * @param amount Amount to approve
1084
- * @returns Transaction hash
1085
- */
1086
- approveAsset(assetAddress: Address, amount: bigint): Promise<Hash>;
210
+ equity: number;
211
+ trades: PaperTrade[];
212
+ equityCurve: {
213
+ timestamp: number;
214
+ equity: number;
215
+ }[];
1087
216
  }
1088
-
1089
- /** SDK version — sent to API for version gating */
1090
- declare const SDK_VERSION = "0.1.18";
1091
- /**
1092
- * Default RPC URL for Base mainnet.
1093
- * Coinbase's official Base RPC — reliable for reads and transactions.
1094
- * Users should set BASE_RPC_URL env var for higher rate limits.
1095
- */
1096
- declare const DEFAULT_RPC_URL = "https://mainnet.base.org";
1097
- /**
1098
- * Get RPC URL from environment or use default.
1099
- */
1100
- declare function getRpcUrl(): string;
1101
- declare const CHAIN_CONFIG: {
1102
- readonly mainnet: {
1103
- blockExplorers: {
1104
- readonly default: {
1105
- readonly name: "Basescan";
1106
- readonly url: "https://basescan.org";
1107
- readonly apiUrl: "https://api.basescan.org/api";
1108
- };
217
+ interface PaperMetrics {
218
+ totalReturn: number;
219
+ sharpeRatio: number;
220
+ maxDrawdown: number;
221
+ winRate: number;
222
+ profitFactor: number;
223
+ totalTrades: number;
224
+ }
225
+ type AgentMode = 'idle' | 'trading' | 'paper' | 'paused';
226
+ type CommandType = 'start_trading' | 'stop_trading' | 'pause_trading' | 'update_risk_params' | 'update_strategy' | 'reload_config' | 'get_status' | 'close_all_positions' | 'shutdown';
227
+ type MessageType = 'trade_executed' | 'perp_fill' | 'prediction_fill' | 'spot_fill' | 'bridge_fill' | 'strategy_decision' | 'risk_blocked' | 'error' | 'info' | 'funds_low' | 'daily_limit_hit' | 'started' | 'stopped';
228
+ type MessageLevel = 'info' | 'warning' | 'error' | 'success';
229
+ interface RelayCommand {
230
+ id: string;
231
+ type: CommandType;
232
+ params?: Record<string, unknown>;
233
+ }
234
+ interface AgentStatusPayload {
235
+ mode: AgentMode;
236
+ agentId: string;
237
+ walletAddress?: string;
238
+ sdkVersion?: string;
239
+ cycleCount?: number;
240
+ lastCycleAt?: number;
241
+ tradingIntervalMs?: number;
242
+ portfolioValue?: number;
243
+ llm?: {
244
+ provider: string;
245
+ model: string;
246
+ dailyTokens?: number;
247
+ totalTokens?: number;
248
+ dailyCalls?: number;
249
+ totalCalls?: number;
250
+ dailyBudgetExceeded?: boolean;
251
+ };
252
+ risk?: {
253
+ dailyPnL: number;
254
+ dailyLossLimit: number;
255
+ isLimitHit: boolean;
256
+ };
257
+ positions?: {
258
+ openPositions: number;
259
+ totalUnrealizedPnL: number;
260
+ totalRealizedPnL: number;
261
+ };
262
+ paper?: {
263
+ active: boolean;
264
+ simulatedValue: number;
265
+ simulatedPnLPct: number;
266
+ };
267
+ venues?: {
268
+ hyperliquid?: {
269
+ enabled: boolean;
270
+ trading: boolean;
1109
271
  };
1110
- blockTime: 2000;
1111
- contracts: {
1112
- readonly disputeGameFactory: {
1113
- readonly 1: {
1114
- readonly address: "0x43edB88C4B80fDD2AdFF2412A7BebF9dF42cB40e";
1115
- };
1116
- };
1117
- readonly l2OutputOracle: {
1118
- readonly 1: {
1119
- readonly address: "0x56315b90c40730925ec5485cf004d835058518A0";
1120
- };
1121
- };
1122
- readonly multicall3: {
1123
- readonly address: "0xca11bde05977b3631167028862be2a173976ca11";
1124
- readonly blockCreated: 5022;
1125
- };
1126
- readonly portal: {
1127
- readonly 1: {
1128
- readonly address: "0x49048044D57e1C92A77f79988d21Fa8fAF74E97e";
1129
- readonly blockCreated: 17482143;
1130
- };
1131
- };
1132
- readonly l1StandardBridge: {
1133
- readonly 1: {
1134
- readonly address: "0x3154Cf16ccdb4C6d922629664174b904d80F2C35";
1135
- readonly blockCreated: 17482143;
1136
- };
1137
- };
1138
- readonly gasPriceOracle: {
1139
- readonly address: "0x420000000000000000000000000000000000000F";
1140
- };
1141
- readonly l1Block: {
1142
- readonly address: "0x4200000000000000000000000000000000000015";
1143
- };
1144
- readonly l2CrossDomainMessenger: {
1145
- readonly address: "0x4200000000000000000000000000000000000007";
1146
- };
1147
- readonly l2Erc721Bridge: {
1148
- readonly address: "0x4200000000000000000000000000000000000014";
1149
- };
1150
- readonly l2StandardBridge: {
1151
- readonly address: "0x4200000000000000000000000000000000000010";
1152
- };
1153
- readonly l2ToL1MessagePasser: {
1154
- readonly address: "0x4200000000000000000000000000000000000016";
1155
- };
272
+ polymarket?: {
273
+ enabled: boolean;
274
+ trading: boolean;
1156
275
  };
1157
- ensTlds?: readonly string[] | undefined;
1158
- id: 8453;
1159
- name: "Base";
1160
- nativeCurrency: {
1161
- readonly name: "Ether";
1162
- readonly symbol: "ETH";
1163
- readonly decimals: 18;
276
+ spot?: {
277
+ enabled: boolean;
278
+ trading: boolean;
1164
279
  };
1165
- experimental_preconfirmationTime?: number | undefined | undefined;
1166
- rpcUrls: {
1167
- readonly default: {
1168
- readonly http: readonly ["https://mainnet.base.org"];
1169
- };
280
+ bridge?: {
281
+ enabled: boolean;
1170
282
  };
1171
- sourceId: 1;
1172
- testnet?: boolean | undefined | undefined;
1173
- custom?: Record<string, unknown> | undefined;
1174
- extendSchema?: Record<string, unknown> | undefined;
1175
- fees?: viem.ChainFees<undefined> | undefined;
1176
- formatters: {
1177
- readonly block: {
1178
- exclude: [] | undefined;
1179
- format: (args: viem_chains.OpStackRpcBlock, action?: string | undefined) => {
1180
- baseFeePerGas: bigint | null;
1181
- blobGasUsed: bigint;
1182
- difficulty: bigint;
1183
- excessBlobGas: bigint;
1184
- extraData: viem.Hex;
1185
- gasLimit: bigint;
1186
- gasUsed: bigint;
1187
- hash: `0x${string}` | null;
1188
- logsBloom: `0x${string}` | null;
1189
- miner: `0x${string}`;
1190
- mixHash: viem.Hash;
1191
- nonce: `0x${string}` | null;
1192
- number: bigint | null;
1193
- parentBeaconBlockRoot?: `0x${string}` | undefined;
1194
- parentHash: viem.Hash;
1195
- receiptsRoot: viem.Hex;
1196
- sealFields: viem.Hex[];
1197
- sha3Uncles: viem.Hash;
1198
- size: bigint;
1199
- stateRoot: viem.Hash;
1200
- timestamp: bigint;
1201
- totalDifficulty: bigint | null;
1202
- transactions: `0x${string}`[] | viem_chains.OpStackTransaction<boolean>[];
1203
- transactionsRoot: viem.Hash;
1204
- uncles: viem.Hash[];
1205
- withdrawals?: viem.Withdrawal[] | undefined | undefined;
1206
- withdrawalsRoot?: `0x${string}` | undefined;
1207
- } & {};
1208
- type: "block";
1209
- };
1210
- readonly transaction: {
1211
- exclude: [] | undefined;
1212
- format: (args: viem_chains.OpStackRpcTransaction, action?: string | undefined) => ({
1213
- blockHash: `0x${string}` | null;
1214
- blockNumber: bigint | null;
1215
- from: `0x${string}`;
1216
- gas: bigint;
1217
- hash: viem.Hash;
1218
- input: viem.Hex;
1219
- nonce: number;
1220
- r: viem.Hex;
1221
- s: viem.Hex;
1222
- to: `0x${string}` | null;
1223
- transactionIndex: number | null;
1224
- typeHex: viem.Hex | null;
1225
- v: bigint;
1226
- value: bigint;
1227
- yParity: number;
1228
- gasPrice?: undefined | undefined;
1229
- maxFeePerBlobGas?: undefined | undefined;
1230
- maxFeePerGas: bigint;
1231
- maxPriorityFeePerGas: bigint;
1232
- isSystemTx?: boolean;
1233
- mint?: bigint | undefined | undefined;
1234
- sourceHash: viem.Hex;
1235
- type: "deposit";
1236
- } | {
1237
- r: viem.Hex;
1238
- s: viem.Hex;
1239
- v: bigint;
1240
- to: `0x${string}` | null;
1241
- from: `0x${string}`;
1242
- gas: bigint;
1243
- nonce: number;
1244
- value: bigint;
1245
- blockHash: `0x${string}` | null;
1246
- blockNumber: bigint | null;
1247
- hash: viem.Hash;
1248
- input: viem.Hex;
1249
- transactionIndex: number | null;
1250
- typeHex: viem.Hex | null;
1251
- accessList?: undefined | undefined;
1252
- authorizationList?: undefined | undefined;
1253
- blobVersionedHashes?: undefined | undefined;
1254
- chainId?: number | undefined;
1255
- yParity?: undefined | undefined;
1256
- type: "legacy";
1257
- gasPrice: bigint;
1258
- maxFeePerBlobGas?: undefined | undefined;
1259
- maxFeePerGas?: undefined | undefined;
1260
- maxPriorityFeePerGas?: undefined | undefined;
1261
- isSystemTx?: undefined | undefined;
1262
- mint?: undefined | undefined;
1263
- sourceHash?: undefined | undefined;
1264
- } | {
1265
- blockHash: `0x${string}` | null;
1266
- blockNumber: bigint | null;
1267
- from: `0x${string}`;
1268
- gas: bigint;
1269
- hash: viem.Hash;
1270
- input: viem.Hex;
1271
- nonce: number;
1272
- r: viem.Hex;
1273
- s: viem.Hex;
1274
- to: `0x${string}` | null;
1275
- transactionIndex: number | null;
1276
- typeHex: viem.Hex | null;
1277
- v: bigint;
1278
- value: bigint;
1279
- yParity: number;
1280
- accessList: viem.AccessList;
1281
- authorizationList?: undefined | undefined;
1282
- blobVersionedHashes?: undefined | undefined;
1283
- chainId: number;
1284
- type: "eip2930";
1285
- gasPrice: bigint;
1286
- maxFeePerBlobGas?: undefined | undefined;
1287
- maxFeePerGas?: undefined | undefined;
1288
- maxPriorityFeePerGas?: undefined | undefined;
1289
- isSystemTx?: undefined | undefined;
1290
- mint?: undefined | undefined;
1291
- sourceHash?: undefined | undefined;
1292
- } | {
1293
- blockHash: `0x${string}` | null;
1294
- blockNumber: bigint | null;
1295
- from: `0x${string}`;
1296
- gas: bigint;
1297
- hash: viem.Hash;
1298
- input: viem.Hex;
1299
- nonce: number;
1300
- r: viem.Hex;
1301
- s: viem.Hex;
1302
- to: `0x${string}` | null;
1303
- transactionIndex: number | null;
1304
- typeHex: viem.Hex | null;
1305
- v: bigint;
1306
- value: bigint;
1307
- yParity: number;
1308
- accessList: viem.AccessList;
1309
- authorizationList?: undefined | undefined;
1310
- blobVersionedHashes?: undefined | undefined;
1311
- chainId: number;
1312
- type: "eip1559";
1313
- gasPrice?: undefined | undefined;
1314
- maxFeePerBlobGas?: undefined | undefined;
1315
- maxFeePerGas: bigint;
1316
- maxPriorityFeePerGas: bigint;
1317
- isSystemTx?: undefined | undefined;
1318
- mint?: undefined | undefined;
1319
- sourceHash?: undefined | undefined;
1320
- } | {
1321
- blockHash: `0x${string}` | null;
1322
- blockNumber: bigint | null;
1323
- from: `0x${string}`;
1324
- gas: bigint;
1325
- hash: viem.Hash;
1326
- input: viem.Hex;
1327
- nonce: number;
1328
- r: viem.Hex;
1329
- s: viem.Hex;
1330
- to: `0x${string}` | null;
1331
- transactionIndex: number | null;
1332
- typeHex: viem.Hex | null;
1333
- v: bigint;
1334
- value: bigint;
1335
- yParity: number;
1336
- accessList: viem.AccessList;
1337
- authorizationList?: undefined | undefined;
1338
- blobVersionedHashes: readonly viem.Hex[];
1339
- chainId: number;
1340
- type: "eip4844";
1341
- gasPrice?: undefined | undefined;
1342
- maxFeePerBlobGas: bigint;
1343
- maxFeePerGas: bigint;
1344
- maxPriorityFeePerGas: bigint;
1345
- isSystemTx?: undefined | undefined;
1346
- mint?: undefined | undefined;
1347
- sourceHash?: undefined | undefined;
1348
- } | {
1349
- blockHash: `0x${string}` | null;
1350
- blockNumber: bigint | null;
1351
- from: `0x${string}`;
1352
- gas: bigint;
1353
- hash: viem.Hash;
1354
- input: viem.Hex;
1355
- nonce: number;
1356
- r: viem.Hex;
1357
- s: viem.Hex;
1358
- to: `0x${string}` | null;
1359
- transactionIndex: number | null;
1360
- typeHex: viem.Hex | null;
1361
- v: bigint;
1362
- value: bigint;
1363
- yParity: number;
1364
- accessList: viem.AccessList;
1365
- authorizationList: viem.SignedAuthorizationList;
1366
- blobVersionedHashes?: undefined | undefined;
1367
- chainId: number;
1368
- type: "eip7702";
1369
- gasPrice?: undefined | undefined;
1370
- maxFeePerBlobGas?: undefined | undefined;
1371
- maxFeePerGas: bigint;
1372
- maxPriorityFeePerGas: bigint;
1373
- isSystemTx?: undefined | undefined;
1374
- mint?: undefined | undefined;
1375
- sourceHash?: undefined | undefined;
1376
- }) & {};
1377
- type: "transaction";
1378
- };
1379
- readonly transactionReceipt: {
1380
- exclude: [] | undefined;
1381
- format: (args: viem_chains.OpStackRpcTransactionReceipt, action?: string | undefined) => {
1382
- blobGasPrice?: bigint | undefined;
1383
- blobGasUsed?: bigint | undefined;
1384
- blockHash: viem.Hash;
1385
- blockNumber: bigint;
1386
- contractAddress: `0x${string}` | null | undefined;
1387
- cumulativeGasUsed: bigint;
1388
- effectiveGasPrice: bigint;
1389
- from: `0x${string}`;
1390
- gasUsed: bigint;
1391
- logs: viem.Log<bigint, number, false>[];
1392
- logsBloom: viem.Hex;
1393
- root?: `0x${string}` | undefined;
1394
- status: "success" | "reverted";
1395
- to: `0x${string}` | null;
1396
- transactionHash: viem.Hash;
1397
- transactionIndex: number;
1398
- type: viem.TransactionType;
1399
- l1GasPrice: bigint | null;
1400
- l1GasUsed: bigint | null;
1401
- l1Fee: bigint | null;
1402
- l1FeeScalar: number | null;
1403
- } & {};
1404
- type: "transactionReceipt";
1405
- };
283
+ };
284
+ diagnostics?: {
285
+ uptime?: number;
286
+ uptimeHuman?: string;
287
+ memoryMB?: number;
288
+ cycleStats?: {
289
+ total: number;
290
+ succeeded: number;
291
+ failed: number;
292
+ successRate: number;
293
+ avgCycleMs: number;
294
+ lastCycleMs: number;
295
+ };
296
+ lastCycleTimings?: {
297
+ totalMs: number;
298
+ priceRefreshMs: number;
299
+ strategyMs: number;
300
+ riskFilterMs: number;
301
+ executionMs: number;
1406
302
  };
1407
- prepareTransactionRequest?: ((args: viem.PrepareTransactionRequestParameters, options: {
1408
- phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
1409
- }) => Promise<viem.PrepareTransactionRequestParameters>) | [fn: ((args: viem.PrepareTransactionRequestParameters, options: {
1410
- phase: "beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters";
1411
- }) => Promise<viem.PrepareTransactionRequestParameters>) | undefined, options: {
1412
- runAt: readonly ("beforeFillTransaction" | "beforeFillParameters" | "afterFillParameters")[];
1413
- }] | undefined;
1414
- serializers: {
1415
- readonly transaction: typeof viem_chains.serializeTransactionOpStack;
303
+ errorCounts?: Record<string, number>;
304
+ recentErrors?: Array<{
305
+ category: string;
306
+ message: string;
307
+ timestamp: number;
308
+ }>;
309
+ llmStats?: {
310
+ totalCalls: number;
311
+ avgLatencyMs: number;
312
+ errorRate: number;
313
+ recentCalls: number;
314
+ };
315
+ signalQueue?: {
316
+ pending: number;
317
+ flushedTotal: number;
1416
318
  };
1417
- verifyHash?: ((client: viem.Client, parameters: viem.VerifyHashActionParameters) => Promise<viem.VerifyHashActionReturnType>) | undefined;
1418
319
  };
320
+ }
321
+ interface AgentRelayMessage {
322
+ type: 'message';
323
+ agentId: string;
324
+ messageType: MessageType;
325
+ level: MessageLevel;
326
+ title: string;
327
+ body: string;
328
+ data?: Record<string, unknown>;
329
+ timestamp: number;
330
+ }
331
+ interface HeartbeatMessage {
332
+ type: 'heartbeat';
333
+ agentId: string;
334
+ status: AgentStatusPayload;
335
+ timestamp: number;
336
+ }
337
+ interface TradeSignalMessage {
338
+ type: 'trade_signal';
339
+ agentId: string;
340
+ signal: TradeSignal;
341
+ timestamp: number;
342
+ }
343
+ interface CommandAckMessage {
344
+ type: 'command_ack';
345
+ agentId: string;
346
+ commandId: string;
347
+ success: boolean;
348
+ message?: string;
349
+ timestamp: number;
350
+ }
351
+ type AgentToAPIMessage = {
352
+ type: 'auth';
353
+ agentId: string;
354
+ token: string;
355
+ } | HeartbeatMessage | AgentRelayMessage | TradeSignalMessage | CommandAckMessage;
356
+ type APIToAgentMessage = {
357
+ type: 'auth_success';
358
+ agentId: string;
359
+ } | {
360
+ type: 'auth_error';
361
+ error: string;
362
+ } | {
363
+ type: 'command';
364
+ command: RelayCommand;
365
+ } | {
366
+ type: 'pong';
1419
367
  };
1420
- type NetworkType = 'mainnet';
1421
- /**
1422
- * Contract addresses by network
1423
- */
1424
- declare const CONTRACT_ADDRESSES: Record<NetworkType, {
1425
- agentRegistry: Address;
1426
- router: Address;
1427
- vaultFactory: Address;
1428
- feeCollector: Address;
1429
- serviceEscrow: Address;
1430
- }>;
1431
- /**
1432
- * DEX router addresses on Base
1433
- */
1434
- declare const DEX_ADDRESSES: {
1435
- readonly aerodromeRouter: Address;
1436
- readonly aerodromeSlipstream: Address;
1437
- readonly uniswapUniversalRouter: Address;
1438
- readonly uniswapV4Router: Address;
1439
- readonly WETH: Address;
1440
- readonly USDC: Address;
1441
- };
1442
- /**
1443
- * 0x API configuration
1444
- */
1445
- declare const ZERO_X_CONFIG: {
1446
- readonly baseUrl: "https://api.0x.org";
1447
- readonly chainId: 8453;
1448
- };
1449
- /**
1450
- * Exagent API configuration
1451
- */
1452
- declare const EXAGENT_API_CONFIG: {
1453
- readonly mainnet: "https://exagent-api.onrender.com";
368
+ type APIToDashboardMessage = {
369
+ type: 'agent_status';
370
+ agentId: string;
371
+ status: AgentStatusPayload;
372
+ } | {
373
+ type: 'agent_message';
374
+ message: AgentRelayMessage;
375
+ } | {
376
+ type: 'agent_connected';
377
+ agentId: string;
378
+ } | {
379
+ type: 'agent_disconnected';
380
+ agentId: string;
381
+ } | {
382
+ type: 'trade_signal';
383
+ agentId: string;
384
+ signal: TradeSignal;
385
+ } | {
386
+ type: 'command_ack';
387
+ agentId: string;
388
+ commandId: string;
389
+ success: boolean;
390
+ message?: string;
1454
391
  };
392
+ declare const tradeSignalSchema: z.ZodObject<{
393
+ venue: z.ZodString;
394
+ chain: z.ZodOptional<z.ZodString>;
395
+ symbol: z.ZodString;
396
+ side: z.ZodEnum<["long", "short", "buy", "sell"]>;
397
+ size: z.ZodNumber;
398
+ price: z.ZodNumber;
399
+ fee: z.ZodNumber;
400
+ venueFillId: z.ZodString;
401
+ venueTimestamp: z.ZodString;
402
+ leverage: z.ZodOptional<z.ZodNumber>;
403
+ orderType: z.ZodOptional<z.ZodString>;
404
+ confidence: z.ZodOptional<z.ZodNumber>;
405
+ reasoning: z.ZodOptional<z.ZodString>;
406
+ }, "strip", z.ZodTypeAny, {
407
+ symbol: string;
408
+ venue: string;
409
+ side: "long" | "short" | "buy" | "sell";
410
+ size: number;
411
+ price: number;
412
+ fee: number;
413
+ venueFillId: string;
414
+ venueTimestamp: string;
415
+ chain?: string | undefined;
416
+ leverage?: number | undefined;
417
+ orderType?: string | undefined;
418
+ confidence?: number | undefined;
419
+ reasoning?: string | undefined;
420
+ }, {
421
+ symbol: string;
422
+ venue: string;
423
+ side: "long" | "short" | "buy" | "sell";
424
+ size: number;
425
+ price: number;
426
+ fee: number;
427
+ venueFillId: string;
428
+ venueTimestamp: string;
429
+ chain?: string | undefined;
430
+ leverage?: number | undefined;
431
+ orderType?: string | undefined;
432
+ confidence?: number | undefined;
433
+ reasoning?: string | undefined;
434
+ }>;
435
+ declare const tradingConfigSchema: z.ZodObject<{
436
+ mode: z.ZodDefault<z.ZodEnum<["live", "paper"]>>;
437
+ timeHorizon: z.ZodDefault<z.ZodEnum<["intraday", "swing", "position"]>>;
438
+ maxPositionSizeBps: z.ZodDefault<z.ZodNumber>;
439
+ maxDailyLossBps: z.ZodDefault<z.ZodNumber>;
440
+ maxConcurrentPositions: z.ZodDefault<z.ZodNumber>;
441
+ tradingIntervalMs: z.ZodDefault<z.ZodNumber>;
442
+ maxSlippageBps: z.ZodDefault<z.ZodNumber>;
443
+ minTradeValueUSD: z.ZodDefault<z.ZodNumber>;
444
+ initialCapitalUSD: z.ZodOptional<z.ZodNumber>;
445
+ }, "strip", z.ZodTypeAny, {
446
+ mode: "live" | "paper";
447
+ timeHorizon: "intraday" | "swing" | "position";
448
+ maxPositionSizeBps: number;
449
+ maxDailyLossBps: number;
450
+ maxConcurrentPositions: number;
451
+ tradingIntervalMs: number;
452
+ maxSlippageBps: number;
453
+ minTradeValueUSD: number;
454
+ initialCapitalUSD?: number | undefined;
455
+ }, {
456
+ mode?: "live" | "paper" | undefined;
457
+ timeHorizon?: "intraday" | "swing" | "position" | undefined;
458
+ maxPositionSizeBps?: number | undefined;
459
+ maxDailyLossBps?: number | undefined;
460
+ maxConcurrentPositions?: number | undefined;
461
+ tradingIntervalMs?: number | undefined;
462
+ maxSlippageBps?: number | undefined;
463
+ minTradeValueUSD?: number | undefined;
464
+ initialCapitalUSD?: number | undefined;
465
+ }>;
1455
466
 
1456
- /**
1457
- * Configuration for ExagentClient
1458
- */
1459
467
  interface ExagentClientConfig {
1460
- /** Network to connect to */
1461
- network?: NetworkType;
1462
- /** Private key for the agent's wallet */
1463
- privateKey?: `0x${string}`;
1464
- /** Pre-configured wallet client */
1465
- walletClient?: WalletClient;
1466
- /** RPC URL override */
1467
- rpcUrl?: string;
1468
- /** Exagent API key (optional, for enhanced features) */
1469
- apiKey?: string;
468
+ baseUrl: string;
469
+ token: string;
1470
470
  }
1471
- /**
1472
- * Main client for interacting with Exagent
1473
- *
1474
- * @example
1475
- * ```typescript
1476
- * import { ExagentClient } from '@exagent/sdk';
1477
- *
1478
- * const exagent = new ExagentClient({
1479
- * privateKey: process.env.AGENT_PRIVATE_KEY,
1480
- * network: 'mainnet',
1481
- * });
1482
- *
1483
- * // Register agent
1484
- * const agentId = await exagent.register({
1485
- * name: 'My Trading Agent',
1486
- * description: 'Momentum-based trading strategy',
1487
- * capabilities: ['spot_trading'],
1488
- * });
1489
- *
1490
- * // Execute trade (always through ExagentRouter for attribution + fees)
1491
- * const result = await exagent.trade({
1492
- * tokenIn: WETH,
1493
- * tokenOut: USDC,
1494
- * amountIn: parseEther('1'),
1495
- * maxSlippageBps: 50,
1496
- * });
1497
- * console.log('Trade submitted:', result.hash);
1498
- * ```
1499
- */
1500
471
  declare class ExagentClient {
1501
- private readonly publicClient;
1502
- private readonly walletClient;
1503
- private readonly account;
1504
- private readonly network;
1505
- private readonly apiKey?;
1506
- readonly registry: ExagentRegistry;
1507
- private _agentId?;
472
+ private baseUrl;
473
+ private token;
1508
474
  constructor(config: ExagentClientConfig);
1509
- /** Standard headers for all API requests (includes SDK version for gating) */
1510
- private apiHeaders;
1511
- /**
1512
- * Register as a new agent on Exagent.
1513
- *
1514
- * RECOMMENDED: Register your agent at https://exagent.io instead of using this method.
1515
- * The website handles the full registration flow including risk universe selection,
1516
- * position size limits, daily loss limits, and metadata upload — all in one step.
1517
- * After registering on the website, use your agent ID in agent-config.json.
1518
- *
1519
- * This SDK method is available for programmatic registration but uses default
1520
- * risk parameters (universe=1, maxPositionSize=10%, maxDailyLoss=5%).
1521
- *
1522
- * @param metadata Agent metadata (will be uploaded to IPFS)
1523
- * @returns The assigned agent ID
1524
- * @throws Error if wallet already owns an agent (one agent per wallet rule)
1525
- */
1526
- register(metadata: AgentMetadata): Promise<bigint>;
1527
- /**
1528
- * Check if an agent name is available for registration
1529
- * @param name The name to check
1530
- * @returns True if the name is available
1531
- */
1532
- isNameAvailable(name: string): Promise<boolean>;
1533
- /**
1534
- * Get agent by name (returns 0 if not found)
1535
- * @param name The agent name to look up
1536
- * @returns Agent ID or 0 if not found
1537
- */
1538
- getAgentByName(name: string): Promise<bigint>;
1539
- /**
1540
- * Get the current agent's ID (if registered).
1541
- *
1542
- * Resolution order:
1543
- * 1. Cached value (from prior register() or getAgentId() call)
1544
- * 2. walletToAgent mapping (linked wallets)
1545
- * 3. Owner lookup (unlinked owner wallet)
1546
- *
1547
- * If the agent was just registered, public RPCs may return stale data (0).
1548
- * Use `retries` to wait for the on-chain state to propagate.
1549
- *
1550
- * @param retries Number of retries with 2s delay for stale RPC reads (default: 0)
1551
- */
1552
- getAgentId(retries?: number): Promise<bigint | undefined>;
1553
- /**
1554
- * Get agent profile
1555
- * @param agentId Optional agent ID (defaults to current agent)
1556
- */
1557
- getAgent(agentId?: bigint): Promise<AgentProfile>;
1558
- /**
1559
- * Link an additional wallet to this agent
1560
- * @param wallet Wallet address to link
1561
- * @param signMessage Function to sign the message hash with the wallet (use signMessage({ raw: hash }))
1562
- */
1563
- linkWallet(wallet: Address, signMessage: (message: {
1564
- raw: `0x${string}`;
1565
- }) => Promise<`0x${string}`>): Promise<Hash>;
1566
- /**
1567
- * Get all wallets linked to this agent
1568
- */
1569
- getLinkedWallets(): Promise<Address[]>;
1570
- /**
1571
- * Execute a trade through ExagentRouter
1572
- *
1573
- * All trades MUST go through the ExagentRouter. This ensures:
1574
- * - Trade attribution for leaderboard ranking
1575
- * - Protocol fee collection (0.2%)
1576
- * - On-chain performance tracking
1577
- * - Token whitelist enforcement per risk universe
1578
- *
1579
- * There is no way to trade outside the router. This is by design.
1580
- *
1581
- * @param intent Trade parameters
1582
- * @returns Trade result with transaction hash
1583
- *
1584
- * @example
1585
- * ```typescript
1586
- * const result = await exagent.trade({
1587
- * tokenIn: WETH,
1588
- * tokenOut: USDC,
1589
- * amountIn: parseEther('1'),
1590
- * maxSlippageBps: 50,
1591
- * });
1592
- * console.log('Trade submitted:', result.hash);
1593
- * ```
1594
- */
1595
- trade(intent: Omit<TradeIntent, 'action'>): Promise<TradeResult>;
1596
- /**
1597
- * Build a router trade transaction without executing
1598
- * Useful for simulation or multi-step workflows
1599
- */
1600
- buildRouterTrade(intent: Omit<TradeIntent, 'action'>, agentId?: bigint): Promise<RouterTradeResponse>;
1601
- /**
1602
- * Check if an address is the ETH sentinel or WETH
1603
- */
1604
- private isETHAddress;
1605
- /**
1606
- * Read current ERC-20 allowance for a (token, spender) pair
1607
- */
1608
- private getAllowance;
1609
- /**
1610
- * Approve token spending for router.
1611
- * Verifies the approval receipt succeeded — previous version silently continued
1612
- * on reverted approvals, causing downstream "transfer amount exceeds allowance" errors.
1613
- */
1614
- private approveToken;
1615
- /**
1616
- * Encode ERC20 approve calldata
1617
- */
1618
- private encodeApprove;
1619
- /**
1620
- * Request a service from another agent
1621
- */
1622
- requestService(request: ServiceRequest): Promise<{
1623
- requestId: string;
1624
- }>;
1625
- /**
1626
- * List available services
1627
- */
1628
- listServices(serviceType?: string): Promise<unknown[]>;
1629
- /**
1630
- * Get agent leaderboard
1631
- */
1632
- getLeaderboard(options?: {
1633
- category?: string;
1634
- limit?: number;
1635
- offset?: number;
1636
- }): Promise<AgentProfile[]>;
1637
- /**
1638
- * Get a vault interface for interacting with an ExagentVault
1639
- * @param vaultAddress The vault contract address
1640
- * @returns ExagentVault instance
1641
- */
1642
- getVault(vaultAddress: Address): ExagentVault;
1643
- /**
1644
- * List all vaults for a given agent
1645
- * @param agentId Agent ID to get vaults for
1646
- * @returns Array of vault summaries
1647
- */
1648
- getAgentVaults(agentId?: bigint): Promise<VaultSummary[]>;
1649
- /**
1650
- * List all vaults the user has positions in
1651
- * @param userAddress User address (defaults to connected wallet)
1652
- * @returns Array of vault summaries with user position info
1653
- */
1654
- getUserVaults(userAddress?: Address): Promise<VaultSummary[]>;
1655
- /**
1656
- * List top performing vaults
1657
- * @param options Filter options
1658
- * @returns Array of vault summaries sorted by performance
1659
- */
1660
- getTopVaults(options?: {
1661
- asset?: Address;
1662
- minTvl?: bigint;
1663
- period?: '7d' | '30d' | '90d' | 'all';
1664
- limit?: number;
1665
- }): Promise<VaultSummary[]>;
1666
- /**
1667
- * Deposit into a vault
1668
- * @param vaultAddress Vault contract address
1669
- * @param amount Amount of underlying asset to deposit
1670
- * @returns Transaction hash
1671
- */
1672
- depositToVault(vaultAddress: Address, amount: bigint): Promise<Hash>;
1673
- /**
1674
- * Withdraw from a vault
1675
- * @param vaultAddress Vault contract address
1676
- * @param assets Amount of underlying asset to withdraw
1677
- * @returns Transaction hash
1678
- */
1679
- withdrawFromVault(vaultAddress: Address, assets: bigint): Promise<Hash>;
1680
- /**
1681
- * Redeem shares from a vault
1682
- * @param vaultAddress Vault contract address
1683
- * @param shares Amount of shares to redeem
1684
- * @returns Transaction hash
1685
- */
1686
- redeemFromVault(vaultAddress: Address, shares: bigint): Promise<Hash>;
1687
- /**
1688
- * Get the ERC-8004 global agent identifier for the current agent
1689
- *
1690
- * Format: eip155:{chainId}:{registryAddress}:{agentId}
1691
- *
1692
- * This creates a universally unique identifier that can be used for
1693
- * cross-protocol agent discovery and interoperability.
1694
- *
1695
- * @returns The global agent ID string
1696
- * @throws Error if agent is not registered
1697
- *
1698
- * @example
1699
- * ```typescript
1700
- * const globalId = await exagent.getGlobalAgentId();
1701
- * // => "eip155:8453:0xABC...DEF:42"
1702
- * ```
1703
- */
1704
- getGlobalAgentId(): Promise<GlobalAgentId>;
1705
- /**
1706
- * Build a global agent ID for any agent (static utility)
1707
- *
1708
- * @param chainId - EVM chain ID
1709
- * @param registryAddress - ExagentRegistry contract address
1710
- * @param agentId - On-chain agent ID
1711
- * @returns ERC-8004 global agent identifier
1712
- */
1713
- static buildGlobalAgentId(chainId: number, registryAddress: Address, agentId: number | bigint): GlobalAgentId;
1714
- /**
1715
- * Get the agent's wallet address
1716
- */
1717
- get address(): Address;
1718
- /**
1719
- * Sign a message with the wallet's private key (EIP-191 personal sign)
1720
- * @param message The message to sign — string for UTF-8, or { raw: Hex } for raw bytes
1721
- * @returns The signature
1722
- */
1723
- signMessage(message: string | {
1724
- raw: `0x${string}`;
1725
- }): Promise<`0x${string}`>;
1726
- private uploadMetadata;
1727
- private parseAgentIdFromReceipt;
1728
- }
1729
-
1730
- /**
1731
- * ABI for ExagentRouter custom errors
1732
- * Used for decoding revert reasons from router transactions
1733
- */
1734
- declare const EXAGENT_ROUTER_ABI: readonly [{
1735
- readonly type: "error";
1736
- readonly name: "InvalidAgentId";
1737
- readonly inputs: readonly [];
1738
- }, {
1739
- readonly type: "error";
1740
- readonly name: "SwapFailed";
1741
- readonly inputs: readonly [];
1742
- }, {
1743
- readonly type: "error";
1744
- readonly name: "InsufficientOutput";
1745
- readonly inputs: readonly [];
1746
- }, {
1747
- readonly type: "error";
1748
- readonly name: "ZeroAddress";
1749
- readonly inputs: readonly [];
1750
- }, {
1751
- readonly type: "error";
1752
- readonly name: "ZeroAmount";
1753
- readonly inputs: readonly [];
1754
- }, {
1755
- readonly type: "error";
1756
- readonly name: "AggregatorNotWhitelisted";
1757
- readonly inputs: readonly [];
1758
- }, {
1759
- readonly type: "error";
1760
- readonly name: "ETHTransferFailed";
1761
- readonly inputs: readonly [];
1762
- }, {
1763
- readonly type: "error";
1764
- readonly name: "FeeBpsTooHigh";
1765
- readonly inputs: readonly [];
1766
- }, {
1767
- readonly type: "error";
1768
- readonly name: "NotAuthorizedForAgent";
1769
- readonly inputs: readonly [{
1770
- readonly name: "agentId";
1771
- readonly type: "uint256";
1772
- }, {
1773
- readonly name: "caller";
1774
- readonly type: "address";
1775
- }];
1776
- }, {
1777
- readonly type: "error";
1778
- readonly name: "ConfigMismatch";
1779
- readonly inputs: readonly [{
1780
- readonly name: "provided";
1781
- readonly type: "bytes32";
1782
- }, {
1783
- readonly name: "onChain";
1784
- readonly type: "bytes32";
1785
- }];
1786
- }, {
1787
- readonly type: "error";
1788
- readonly name: "MsgValueMismatch";
1789
- readonly inputs: readonly [];
1790
- }, {
1791
- readonly type: "error";
1792
- readonly name: "FeeCollectorNotSet";
1793
- readonly inputs: readonly [];
1794
- }, {
1795
- readonly type: "error";
1796
- readonly name: "TokenNotAllowedForAgent";
1797
- readonly inputs: readonly [{
1798
- readonly name: "agentId";
1799
- readonly type: "uint256";
1800
- }, {
1801
- readonly name: "token";
1802
- readonly type: "address";
1803
- }];
1804
- }, {
1805
- readonly type: "error";
1806
- readonly name: "NotAuthorized";
1807
- readonly inputs: readonly [];
1808
- }, {
1809
- readonly type: "error";
1810
- readonly name: "RiskUniverseTooLow";
1811
- readonly inputs: readonly [{
1812
- readonly name: "agentId";
1813
- readonly type: "uint256";
1814
- }, {
1815
- readonly name: "riskUniverse";
1816
- readonly type: "uint256";
1817
- }];
1818
- }, {
1819
- readonly type: "error";
1820
- readonly name: "FillAlreadyProcessed";
1821
- readonly inputs: readonly [{
1822
- readonly name: "fillId";
1823
- readonly type: "bytes32";
1824
- }];
1825
- }];
1826
-
1827
- /**
1828
- * ExagentVaultFactory ABI (Mainnet — no burn fee, seed-based creation)
1829
- */
1830
- declare const EXAGENT_VAULT_FACTORY_ABI: readonly [{
1831
- readonly type: "function";
1832
- readonly name: "owner";
1833
- readonly inputs: readonly [];
1834
- readonly outputs: readonly [{
1835
- readonly type: "address";
1836
- }];
1837
- readonly stateMutability: "view";
1838
- }, {
1839
- readonly type: "function";
1840
- readonly name: "registry";
1841
- readonly inputs: readonly [];
1842
- readonly outputs: readonly [{
1843
- readonly type: "address";
1844
- }];
1845
- readonly stateMutability: "view";
1846
- }, {
1847
- readonly type: "function";
1848
- readonly name: "router";
1849
- readonly inputs: readonly [];
1850
- readonly outputs: readonly [{
1851
- readonly type: "address";
1852
- }];
1853
- readonly stateMutability: "view";
1854
- }, {
1855
- readonly type: "function";
1856
- readonly name: "feeCollector";
1857
- readonly inputs: readonly [];
1858
- readonly outputs: readonly [{
1859
- readonly type: "address";
1860
- }];
1861
- readonly stateMutability: "view";
1862
- }, {
1863
- readonly type: "function";
1864
- readonly name: "stakingContract";
1865
- readonly inputs: readonly [];
1866
- readonly outputs: readonly [{
1867
- readonly type: "address";
1868
- }];
1869
- readonly stateMutability: "view";
1870
- }, {
1871
- readonly type: "function";
1872
- readonly name: "VERIFIED_VEXA_REQUIREMENT";
1873
- readonly inputs: readonly [];
1874
- readonly outputs: readonly [{
1875
- readonly type: "uint256";
1876
- }];
1877
- readonly stateMutability: "view";
1878
- }, {
1879
- readonly type: "function";
1880
- readonly name: "MIN_SEED_AMOUNT";
1881
- readonly inputs: readonly [];
1882
- readonly outputs: readonly [{
1883
- readonly type: "uint256";
1884
- }];
1885
- readonly stateMutability: "view";
1886
- }, {
1887
- readonly type: "function";
1888
- readonly name: "UNVERIFIED_CAP_MULTIPLIER";
1889
- readonly inputs: readonly [];
1890
- readonly outputs: readonly [{
1891
- readonly type: "uint256";
1892
- }];
1893
- readonly stateMutability: "view";
1894
- }, {
1895
- readonly type: "function";
1896
- readonly name: "VERIFIED_CAP_MULTIPLIER";
1897
- readonly inputs: readonly [];
1898
- readonly outputs: readonly [{
1899
- readonly type: "uint256";
1900
- }];
1901
- readonly stateMutability: "view";
1902
- }, {
1903
- readonly type: "function";
1904
- readonly name: "allowedAssets";
1905
- readonly inputs: readonly [{
1906
- readonly name: "asset";
1907
- readonly type: "address";
1908
- }];
1909
- readonly outputs: readonly [{
1910
- readonly type: "bool";
1911
- }];
1912
- readonly stateMutability: "view";
1913
- }, {
1914
- readonly type: "function";
1915
- readonly name: "vaults";
1916
- readonly inputs: readonly [{
1917
- readonly name: "agentId";
1918
- readonly type: "uint256";
1919
- }, {
1920
- readonly name: "asset";
1921
- readonly type: "address";
1922
- }];
1923
- readonly outputs: readonly [{
1924
- readonly type: "address";
1925
- }];
1926
- readonly stateMutability: "view";
1927
- }, {
1928
- readonly type: "function";
1929
- readonly name: "agentVaultCount";
1930
- readonly inputs: readonly [{
1931
- readonly name: "agentId";
1932
- readonly type: "uint256";
1933
- }];
1934
- readonly outputs: readonly [{
1935
- readonly type: "uint256";
1936
- }];
1937
- readonly stateMutability: "view";
1938
- }, {
1939
- readonly type: "function";
1940
- readonly name: "createVault";
1941
- readonly inputs: readonly [{
1942
- readonly name: "agentId";
1943
- readonly type: "uint256";
1944
- }, {
1945
- readonly name: "asset";
1946
- readonly type: "address";
1947
- }, {
1948
- readonly name: "seedAmount";
1949
- readonly type: "uint256";
1950
- }, {
1951
- readonly name: "name";
1952
- readonly type: "string";
1953
- }, {
1954
- readonly name: "symbol";
1955
- readonly type: "string";
1956
- }, {
1957
- readonly name: "feeRecipient";
1958
- readonly type: "address";
1959
- }];
1960
- readonly outputs: readonly [{
1961
- readonly type: "address";
1962
- }];
1963
- readonly stateMutability: "nonpayable";
1964
- }, {
1965
- readonly type: "event";
1966
- readonly name: "VaultCreated";
1967
- readonly inputs: readonly [{
1968
- readonly name: "vault";
1969
- readonly type: "address";
1970
- readonly indexed: true;
1971
- }, {
1972
- readonly name: "agentId";
1973
- readonly type: "uint256";
1974
- readonly indexed: true;
1975
- }, {
1976
- readonly name: "asset";
1977
- readonly type: "address";
1978
- readonly indexed: true;
1979
- }, {
1980
- readonly name: "creator";
1981
- readonly type: "address";
1982
- readonly indexed: false;
1983
- }, {
1984
- readonly name: "name";
1985
- readonly type: "string";
1986
- readonly indexed: false;
1987
- }, {
1988
- readonly name: "symbol";
1989
- readonly type: "string";
1990
- readonly indexed: false;
1991
- }];
1992
- }, {
1993
- readonly type: "event";
1994
- readonly name: "AllowedAssetUpdated";
1995
- readonly inputs: readonly [{
1996
- readonly name: "asset";
1997
- readonly type: "address";
1998
- readonly indexed: true;
1999
- }, {
2000
- readonly name: "allowed";
2001
- readonly type: "bool";
2002
- readonly indexed: false;
2003
- }];
2004
- }];
2005
- /**
2006
- * Vault creation requirements from the mainnet factory
2007
- */
2008
- interface VaultCreationRequirements {
2009
- minSeedAmount: bigint;
2010
- unverifiedCapMultiplier: bigint;
2011
- verifiedCapMultiplier: bigint;
2012
- }
2013
- /**
2014
- * Result of checking if an address can create a vault
2015
- */
2016
- interface CanCreateVaultResult {
2017
- canCreate: boolean;
2018
- reason: string;
2019
- }
2020
- /**
2021
- * Options for creating a vault
2022
- */
2023
- interface CreateVaultOptions {
2024
- agentId: bigint;
2025
- asset: Address;
2026
- seedAmount: bigint;
2027
- name: string;
2028
- symbol: string;
2029
- feeRecipient?: Address;
2030
- }
2031
- /**
2032
- * ExagentVaultFactory SDK class for vault creation and management
2033
- */
2034
- declare class ExagentVaultFactory {
2035
- readonly address: Address;
2036
- private readonly publicClient;
2037
- private readonly walletClient?;
2038
- private readonly chain;
2039
- private readonly account?;
2040
- constructor(factoryAddress: Address, publicClient: any, walletClient?: any, chain?: Chain, account?: Account);
2041
- /**
2042
- * Get vault creation requirements (mainnet: seed-based, no burn fee)
2043
- */
2044
- getRequirements(): Promise<VaultCreationRequirements>;
2045
- /**
2046
- * Check if an address can create a vault.
2047
- * Performs inline validation since the on-chain contract does not expose
2048
- * a canCreateVault() view function.
2049
- * @param creator Address to check
2050
- */
2051
- canCreateVault(creator: Address): Promise<CanCreateVaultResult>;
2052
- /**
2053
- * Check if an asset is whitelisted for vault creation
2054
- * @param asset Asset address to check
2055
- */
2056
- isAssetAllowed(asset: Address): Promise<boolean>;
2057
- /**
2058
- * Get existing vault for an agent and asset
2059
- * @param agentId Agent ID
2060
- * @param asset Asset address
2061
- * @returns Vault address or zero address if none exists
2062
- */
2063
- getVault(agentId: bigint, asset: Address): Promise<Address>;
2064
- /**
2065
- * Get count of vaults for an agent
2066
- * @param agentId Agent ID
2067
- */
2068
- getAgentVaultCount(agentId: bigint): Promise<bigint>;
2069
- /**
2070
- * Check if agent already has a vault for an asset
2071
- * @param agentId Agent ID
2072
- * @param asset Asset address
2073
- */
2074
- hasVault(agentId: bigint, asset: Address): Promise<boolean>;
2075
- /**
2076
- * Create a new vault for an agent (mainnet: requires seed amount)
2077
- * @param options Vault creation options including seedAmount
2078
- * @returns Transaction hash
2079
- */
2080
- createVault(options: CreateVaultOptions): Promise<Hash>;
2081
- /**
2082
- * Check all requirements and create a vault if possible
2083
- * Returns detailed status about each requirement
2084
- */
2085
- checkAndCreateVault(agentId: bigint, asset: Address, seedAmount: bigint, name: string, symbol: string, feeRecipient?: Address): Promise<{
2086
- success: boolean;
2087
- vaultAddress?: Address;
2088
- txHash?: Hash;
2089
- error?: string;
2090
- checks: {
2091
- canCreate: boolean;
2092
- canCreateReason: string;
2093
- assetAllowed: boolean;
2094
- hasExistingVault: boolean;
2095
- };
2096
- }>;
475
+ private request;
476
+ getMe(): Promise<Record<string, unknown>>;
477
+ listAgents(): Promise<AgentProfile[]>;
478
+ getAgent(agentId: string): Promise<AgentProfile>;
479
+ createAgent(data: {
480
+ name: string;
481
+ description?: string;
482
+ config: Record<string, unknown>;
483
+ }): Promise<AgentProfile>;
484
+ reportTradeSignal(agentId: string, signal: TradeSignal): Promise<void>;
485
+ getWebSocketUrl(): string;
486
+ getDashboardWebSocketUrl(): string;
2097
487
  }
2098
488
 
2099
- export { type AgentMetadata, type AgentProfile, CHAIN_CONFIG, CONTRACT_ADDRESSES, type CanCreateVaultResult, type CreateVaultOptions, DEFAULT_RPC_URL, DEX_ADDRESSES, EXAGENT_API_CONFIG, EXAGENT_REGISTRY_ABI, EXAGENT_ROUTER_ABI, EXAGENT_VAULT_FACTORY_ABI, ExagentClient, type ExagentClientConfig, ExagentRegistry, ExagentVault, ExagentVaultFactory, type GlobalAgentId, type NetworkType, type PerformanceSnapshot, type PriceQuote, type RouteQuote, type RouteStep, type RouterTradeResponse, SDK_VERSION, type ServiceRequest, type TradeIntent, type TradeResult, type UserVaultPosition, type VaultActivityEntry, type VaultConfig, type VaultCreationRequirements, type VaultInfo, type VaultPosition, type VaultSummary, type VaultTradeEntry, type WithdrawalRequest, ZERO_X_CONFIG, buildGlobalAgentId, getRpcUrl, parseGlobalAgentId };
489
+ export { type APIToAgentMessage, type APIToDashboardMessage, type AgentConfig, type AgentMode, type AgentProfile, type AgentRelayMessage, type AgentStatus, type AgentStatusPayload, type AgentToAPIMessage, type CommandType, ExagentClient, type ExagentClientConfig, type HeartbeatMessage, type LLMAdapter, type LLMConfig, type LLMMessage, type LLMMetadata, type LLMProvider, type LLMResponse, type MarketData, type MessageLevel, type MessageType, type OHLCV, type PaperMetrics, type PaperPortfolio, type PaperTrade, type PerpTradeSignal, type PositionSummary, type PredictionTradeSignal, type RelayCommand, type RelayConfig, type RiskParams, type StrategyConfig, type StrategyContext, type StrategyFunction, type StrategyStore, type StrategyTemplate, type TrackedPosition, type TradeRecord, type TradeSignal, type TradeSignalMessage, type TradingConfig, type VenueConfig, tradeSignalSchema, tradingConfigSchema };