@0xkoaj/sdk 0.0.1-beta.1

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.
Files changed (2) hide show
  1. package/README.md +821 -0
  2. package/package.json +60 -0
package/README.md ADDED
@@ -0,0 +1,821 @@
1
+ # Web3 SDK
2
+
3
+ A comprehensive TypeScript SDK for interacting with the different contracts and accounts accross multiple networks.
4
+
5
+ ## ๐Ÿงช Installation
6
+
7
+ ### Yarn
8
+
9
+ ```bash
10
+ yarn add @nchamo/sdk
11
+ ```
12
+
13
+ ### NPM
14
+
15
+ ```bash
16
+ npm install @nchamo/sdk
17
+ ```
18
+
19
+ ## Quick Start
20
+
21
+ ### ๐Ÿ‘ท๐Ÿฝโ€โ™€๏ธ Building the SDK
22
+
23
+ ```typescript
24
+ import { buildSDK } from "@nchamo/sdk";
25
+
26
+ const sdk = buildSDK(config);
27
+ ```
28
+
29
+ ### โš–๏ธ Getting Balance for Multiple Tokens
30
+
31
+ ```typescript
32
+ const accountBalances = await sdk.balanceService.getBalancesForTokens({
33
+ account: "0x000000000000000000000000000000000000dead",
34
+ tokens: {
35
+ [Chains.ETHEREUM.chainId]: [
36
+ "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
37
+ "0x6b175474e89094c44da98b954eedeac495271d0f", // DAI
38
+ ],
39
+ [Chains.OPTIMISM.chainId]: [
40
+ "0x7f5c764cbc14f9669b88837ca1490cca17c31607", // USDC
41
+ "0xda10009cbd5d07dd0cecc66161fc93d7c9000da1", // DAI
42
+ ],
43
+ },
44
+ config: {
45
+ timeout: "30s",
46
+ },
47
+ });
48
+ ```
49
+
50
+ ### ๐Ÿ’ธ Getting Allowances
51
+
52
+ ```typescript
53
+ const accountAllowances = await sdk.allowanceService.getAllowances({
54
+ chainId: Chains.ETHEREUM.chainId,
55
+ token: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
56
+ owner: "0x000000000000000000000000000000000000dead",
57
+ spenders: ["0x6666666600000000000000000000000000009999"],
58
+ });
59
+ ```
60
+
61
+ ### ๐Ÿ”„ Getting Trade Quotes
62
+
63
+ ```typescript
64
+ const allQuotes = await sdk.quoteService.getAllQuotesWithTxs({
65
+ request: {
66
+ chainId: Chains.ETHEREUM.chainId,
67
+ sellToken: "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
68
+ buyToken: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
69
+ order: {
70
+ type: "sell",
71
+ sellAmount: utils.parseUnits("1000", 6), // 1000 USDC
72
+ },
73
+ slippagePercentage: 1,
74
+ takerAddress: signer.address,
75
+ gasSpeed: {
76
+ speed: "instant",
77
+ },
78
+ },
79
+ config: {
80
+ sort: {
81
+ by: "most-swapped-accounting-for-gas",
82
+ },
83
+ },
84
+ });
85
+ ```
86
+
87
+ ## Overview
88
+
89
+ The Web3 SDK provides efficient tools to manage token balances, retrieve trade quotes from DEX aggregators, and check token holdings across multiple chains. It's designed to be modular, with each functionality organized into specialized services that handle specific aspects of blockchain interaction.
90
+
91
+ ### Available Services
92
+
93
+ The SDK is divided into the following services:
94
+
95
+ - **[Allowances Service](#allowances-service)**: Manage token approvals and permissions across different chains
96
+ - **[Balances Service](#balances-service)**: Query token balances across multiple chains and tokens
97
+ - **[Quotes Service](#quotes-service)**: Get optimized swap quotes from various DEX aggregators
98
+ - **[Gas Service](#gas-service)**: Optimize transaction costs and estimate gas prices
99
+ - **[Prices Service](#prices-service)**: Retrieve token price information across multiple chains
100
+ - **[Metadata Service](#metadata-service)**: Access token metadata and information
101
+
102
+ Each service provides a focused set of functionality while maintaining a consistent interface and error handling approach. This modular design allows developers to use only the services they need while ensuring a cohesive experience across the entire SDK.
103
+
104
+ ## Services
105
+
106
+ ### Allowances Service
107
+
108
+ The Allowances Service provides functionality to check and manage token allowances across different chains.
109
+
110
+ #### Objective and Potential
111
+
112
+ - **Objective**: Enable efficient management of token approvals across multiple chains and protocols
113
+ - **Potential Use Cases**:
114
+ - Batch checking multiple token approvals in a single call
115
+ - Optimizing gas costs by checking approvals before transactions
116
+ - Managing permissions for DeFi protocols and dApps
117
+ - Cross-chain allowance monitoring and management
118
+
119
+ #### Methods
120
+
121
+ ##### `supportedChains()`
122
+
123
+ Returns an array of chain IDs that are supported by the service.
124
+
125
+ ```typescript
126
+ const chains = sdk.allowanceService.supportedChains();
127
+ ```
128
+
129
+ ##### `getAllowanceInChain(params)`
130
+
131
+ Gets the allowance for a specific token and spender on a given chain.
132
+
133
+ ```typescript
134
+ const allowance = await sdk.allowanceService.getAllowanceInChain({
135
+ chainId: Chains.ETHEREUM.chainId,
136
+ token: "0x...", // Token address
137
+ owner: "0x...", // Owner address
138
+ spender: "0x...", // Spender address
139
+ config: { timeout: TimeString },
140
+ });
141
+ ```
142
+
143
+ ##### `getAllowancesInChain(params)`
144
+
145
+ Gets multiple allowances in a single call for a specific chain.
146
+
147
+ ```typescript
148
+ const allowances = await sdk.allowanceService.getAllowancesInChain({
149
+ chainId: Chains.ETHEREUM.chainId,
150
+ allowances: [
151
+ { token: "0x...", owner: "0x...", spender: "0x..." },
152
+ { token: "0x...", owner: "0x...", spender: "0x..." },
153
+ ],
154
+ config: { timeout: TimeString },
155
+ });
156
+ ```
157
+
158
+ ##### `getAllowances(params)`
159
+
160
+ Gets allowances across multiple chains in a single call.
161
+
162
+ ```typescript
163
+ const allowances = await sdk.allowanceService.getAllowances({
164
+ allowances: [
165
+ {
166
+ chainId: Chains.ETHEREUM.chainId,
167
+ token: "0x...",
168
+ owner: "0x...",
169
+ spender: "0x...",
170
+ },
171
+ {
172
+ chainId: Chains.OPTIMISM.chainId,
173
+ token: "0x...",
174
+ owner: "0x...",
175
+ spender: "0x...",
176
+ },
177
+ ],
178
+ config: { timeout: TimeString },
179
+ });
180
+ ```
181
+
182
+ ### Balances Service
183
+
184
+ The Balances Service allows querying token balances across multiple chains and tokens.
185
+
186
+ #### Objective and Potential
187
+
188
+ - **Objective**: Provide a unified interface for retrieving token balances across multiple chains
189
+ - **Potential Use Cases**:
190
+ - Portfolio tracking across multiple chains
191
+ - Balance monitoring for DeFi positions
192
+ - Multi-chain wallet integration
193
+ - Automated balance checks for trading strategies
194
+
195
+ #### Methods
196
+
197
+ ##### `supportedChains()`
198
+
199
+ Returns an array of chain IDs that are supported by the service.
200
+
201
+ ```typescript
202
+ const chains = sdk.balanceService.supportedChains();
203
+ ```
204
+
205
+ ##### `getBalancesForAccountInChain(params)`
206
+
207
+ Gets balances for a specific account in a single chain.
208
+
209
+ ```typescript
210
+ const balances = await sdk.balanceService.getBalancesForAccountInChain({
211
+ chainId: Chains.ETHEREUM.chainId,
212
+ account: "0x...",
213
+ tokens: ["0x...", "0x..."],
214
+ config: { timeout: "30s" },
215
+ });
216
+ ```
217
+
218
+ ##### `getBalancesForAccount(params)`
219
+
220
+ Gets balances for a specific account across multiple chains.
221
+
222
+ ```typescript
223
+ const balances = await sdk.balanceService.getBalancesForAccount({
224
+ account: "0x...",
225
+ tokens: [
226
+ { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
227
+ { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
228
+ ],
229
+ config: { timeout: "30s" },
230
+ });
231
+ ```
232
+
233
+ ##### `getBalancesInChain(params)`
234
+
235
+ Gets balances for multiple accounts in a single chain.
236
+
237
+ ```typescript
238
+ const balances = await sdk.balanceService.getBalancesInChain({
239
+ chainId: Chains.ETHEREUM.chainId,
240
+ tokens: [
241
+ { account: "0x...", token: "0x..." },
242
+ { account: "0x...", token: "0x..." },
243
+ ],
244
+ config: { timeout: "30s" },
245
+ });
246
+ ```
247
+
248
+ ##### `getBalances(params)`
249
+
250
+ Gets balances for multiple accounts across multiple chains.
251
+
252
+ ```typescript
253
+ const balances = await sdk.balanceService.getBalances({
254
+ tokens: [
255
+ { chainId: Chains.ETHEREUM.chainId, account: "0x...", token: "0x..." },
256
+ { chainId: Chains.OPTIMISM.chainId, account: "0x...", token: "0x..." },
257
+ ],
258
+ config: { timeout: "30s" },
259
+ });
260
+ ```
261
+
262
+ ### Quotes Service
263
+
264
+ The Quotes Service provides comprehensive functionality for getting trade quotes from various DEX aggregators.
265
+
266
+ #### Objective and Potential
267
+
268
+ - **Objective**: Aggregate and optimize trade quotes from multiple DEX sources
269
+ - **Potential Use Cases**:
270
+ - Finding the best trade routes across multiple DEXs
271
+ - Gas-optimized trading strategies
272
+ - Cross-chain arbitrage opportunities
273
+ - Automated trading systems
274
+ - Price impact analysis
275
+
276
+ #### Methods
277
+
278
+ ##### `supportedSources()`
279
+
280
+ Returns metadata about all supported quote sources.
281
+
282
+ ```typescript
283
+ const sources = sdk.quoteService.supportedSources();
284
+ ```
285
+
286
+ ##### `supportedChains()`
287
+
288
+ Returns an array of chain IDs that are supported by the service.
289
+
290
+ ```typescript
291
+ const chains = sdk.quoteService.supportedChains();
292
+ ```
293
+
294
+ ##### `supportedSourcesInChain(params)`
295
+
296
+ Returns metadata about quote sources supported in a specific chain.
297
+
298
+ ```typescript
299
+ const sources = sdk.quoteService.supportedSourcesInChain({
300
+ chainId: Chains.ETHEREUM.chainId,
301
+ });
302
+ ```
303
+
304
+ ##### `supportedGasSpeeds()`
305
+
306
+ Returns supported gas speeds for each chain.
307
+
308
+ ```typescript
309
+ const gasSpeeds = sdk.quoteService.supportedGasSpeeds();
310
+ ```
311
+
312
+ ##### `estimateQuotes(params)`
313
+
314
+ Gets estimated quotes from all sources without transaction details.
315
+
316
+ ```typescript
317
+ const quotes = sdk.quoteService.estimateQuotes({
318
+ request: {
319
+ chainId: Chains.ETHEREUM.chainId,
320
+ sellToken: "0x...",
321
+ buyToken: "0x...",
322
+ order: { type: "sell", sellAmount: BigInt("1000000") },
323
+ slippagePercentage: 1,
324
+ },
325
+ config: { timeout: TimeString },
326
+ });
327
+ ```
328
+
329
+ ##### `estimateAllQuotes(params)`
330
+
331
+ Gets estimated quotes from all sources and returns them in a sorted array.
332
+
333
+ ```typescript
334
+ const quotes = await sdk.quoteService.estimateAllQuotes({
335
+ request: {
336
+ chainId: Chains.ETHEREUM.chainId,
337
+ sellToken: "0x...",
338
+ buyToken: "0x...",
339
+ order: { type: "sell", sellAmount: BigInt("1000000") },
340
+ slippagePercentage: 1,
341
+ },
342
+ config: {
343
+ ignoredFailed: boolean,
344
+ sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
345
+ timeout: TimeString,
346
+ },
347
+ });
348
+ ```
349
+
350
+ ##### `getQuotes(params)`
351
+
352
+ Gets quotes from all sources with transaction details.
353
+
354
+ ```typescript
355
+ const quotes = sdk.quoteService.getQuotes({
356
+ request: {
357
+ chainId: Chains.ETHEREUM.chainId,
358
+ sellToken: "0x...",
359
+ buyToken: "0x...",
360
+ order: { type: "sell", sellAmount: BigInt("1000000") },
361
+ slippagePercentage: 1,
362
+ takerAddress: "0x...",
363
+ },
364
+ config: { timeout: TimeString },
365
+ });
366
+ ```
367
+
368
+ ##### `getAllQuotes(params)`
369
+
370
+ Gets quotes from all sources and returns them in a sorted array.
371
+
372
+ ```typescript
373
+ const quotes = await sdk.quoteService.getAllQuotes({
374
+ request: {
375
+ chainId: Chains.ETHEREUM.chainId,
376
+ sellToken: "0x...",
377
+ buyToken: "0x...",
378
+ order: { type: "sell", sellAmount: BigInt("1000000") },
379
+ slippagePercentage: 1,
380
+ takerAddress: "0x...",
381
+ },
382
+ config: {
383
+ ignoredFailed: boolean,
384
+ sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
385
+ timeout: TimeString,
386
+ },
387
+ });
388
+ ```
389
+
390
+ ##### `getBestQuote(params)`
391
+
392
+ Gets the best quote according to specified criteria.
393
+
394
+ ```typescript
395
+ const bestQuote = await sdk.quoteService.getBestQuote({
396
+ request: {
397
+ chainId: Chains.ETHEREUM.chainId,
398
+ sellToken: "0x...",
399
+ buyToken: "0x...",
400
+ order: { type: "sell", sellAmount: BigInt("1000000") },
401
+ slippagePercentage: 1,
402
+ takerAddress: "0x...",
403
+ },
404
+ config: {
405
+ choose: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
406
+ timeout: TimeString,
407
+ },
408
+ });
409
+ ```
410
+
411
+ ##### `getAllQuotesWithTxs(params)`
412
+
413
+ Gets quotes with built transactions from all sources.
414
+
415
+ ```typescript
416
+ const quotesWithTxs = await sdk.quoteService.getAllQuotesWithTxs({
417
+ request: {
418
+ chainId: Chains.ETHEREUM.chainId,
419
+ sellToken: "0x...",
420
+ buyToken: "0x...",
421
+ order: { type: "sell", sellAmount: BigInt("1000000") },
422
+ slippagePercentage: 1,
423
+ takerAddress: "0x...",
424
+ },
425
+ config: {
426
+ ignoredFailed: boolean,
427
+ sort: { by: "most-swapped-accounting-for-gas", using: "gas-price" },
428
+ timeout: TimeString,
429
+ },
430
+ });
431
+ ```
432
+
433
+ ##### `buildTxs(params)`
434
+
435
+ Builds transactions for given quotes.
436
+
437
+ ```typescript
438
+ const txs = sdk.quoteService.buildTxs({
439
+ quotes: quotes,
440
+ sourceConfig: SourceConfig,
441
+ config: { timeout: TimeString },
442
+ });
443
+ ```
444
+
445
+ ##### `buildAllTxs(params)`
446
+
447
+ Builds transactions for all quotes and returns them in a sorted array.
448
+
449
+ ```typescript
450
+ const allTxs = await sdk.quoteService.buildAllTxs({
451
+ quotes: quotes,
452
+ sourceConfig: SourceConfig,
453
+ config: {
454
+ timeout: TimeString,
455
+ ignoredFailed: boolean,
456
+ },
457
+ });
458
+ ```
459
+
460
+ ### Gas Service
461
+
462
+ The Gas Service provides gas price estimation and optimization across different chains.
463
+
464
+ #### Objective and Potential
465
+
466
+ - **Objective**: Optimize transaction costs across different chains and networks
467
+ - **Potential Use Cases**:
468
+ - Gas price monitoring and optimization
469
+ - Transaction cost estimation
470
+ - Gas-aware trading strategies
471
+ - Multi-chain gas price comparison
472
+ - Automated gas price optimization
473
+
474
+ #### Methods
475
+
476
+ ##### `supportedChains()`
477
+
478
+ Returns an array of chain IDs that are supported by the service.
479
+
480
+ ```typescript
481
+ const chains = sdk.gasService.supportedChains();
482
+ ```
483
+
484
+ ##### `supportedSpeeds()`
485
+
486
+ Returns supported gas speeds for each chain.
487
+
488
+ ```typescript
489
+ const speeds = sdk.gasService.supportedSpeeds();
490
+ ```
491
+
492
+ ##### `estimateGas(params)`
493
+
494
+ Estimates gas usage for a transaction.
495
+
496
+ ```typescript
497
+ const gasEstimation = await sdk.gasService.estimateGas({
498
+ chainId: Chains.ETHEREUM.chainId,
499
+ tx: {
500
+ from: "0x...",
501
+ to: "0x...",
502
+ data: "0x...",
503
+ },
504
+ config: { timeout: TimeString },
505
+ });
506
+ ```
507
+
508
+ ##### `getGasPrice(params)`
509
+
510
+ Gets gas prices for different speeds on a chain.
511
+
512
+ ```typescript
513
+ const gasPrices = await sdk.gasService.getGasPrice({
514
+ chainId: Chains.ETHEREUM.chainId,
515
+ config: {
516
+ timeout: TimeString,
517
+ fields: {
518
+ standard: "required" | "best effort" | "can ignore",
519
+ fast: "required" | "best effort" | "can ignore",
520
+ instant: "required" | "best effort" | "can ignore",
521
+ },
522
+ },
523
+ });
524
+ ```
525
+
526
+ ##### `calculateGasCost(params)`
527
+
528
+ Calculates gas cost for a transaction.
529
+
530
+ ```typescript
531
+ const gasCost = await sdk.gasService.calculateGasCost({
532
+ chainId: Chains.ETHEREUM.chainId,
533
+ gasEstimation: BigInt("21000"),
534
+ tx: {
535
+ from: "0x...",
536
+ to: "0x...",
537
+ data: "0x...",
538
+ },
539
+ config: {
540
+ timeout: TimeString,
541
+ fields: {
542
+ standard: "required" | "best effort" | "can ignore",
543
+ fast: "required" | "best effort" | "can ignore",
544
+ instant: "required" | "best effort" | "can ignore",
545
+ },
546
+ },
547
+ });
548
+ ```
549
+
550
+ ##### `getQuickGasCalculator(params)`
551
+
552
+ Gets a quick gas calculator for a specific chain.
553
+
554
+ ```typescript
555
+ const calculator = await sdk.gasService.getQuickGasCalculator({
556
+ chainId: Chains.ETHEREUM.chainId,
557
+ config: {
558
+ timeout: TimeString,
559
+ fields: {
560
+ standard: "required" | "best effort" | "can ignore",
561
+ fast: "required" | "best effort" | "can ignore",
562
+ instant: "required" | "best effort" | "can ignore",
563
+ },
564
+ },
565
+ });
566
+
567
+ // Use the calculator
568
+ const gasPrices = calculator.getGasPrice();
569
+ const gasCost = calculator.calculateGasCost({
570
+ gasEstimation: BigInt("21000"),
571
+ tx: {
572
+ from: "0x...",
573
+ to: "0x...",
574
+ data: "0x...",
575
+ },
576
+ });
577
+ ```
578
+
579
+ ### Prices Service
580
+
581
+ The Prices Service provides token price information across multiple chains.
582
+
583
+ #### Objective and Potential
584
+
585
+ - **Objective**: Provide a unified interface for retrieving token prices across multiple chains
586
+ - **Potential Use Cases**:
587
+ - Price feeds for DeFi applications
588
+ - Token value calculations
589
+ - Historical price analysis
590
+ - Price chart generation
591
+ - Multi-chain price aggregation
592
+
593
+ #### Methods
594
+
595
+ ##### `supportedChains()`
596
+
597
+ Returns an array of chain IDs that are supported by the service.
598
+
599
+ ```typescript
600
+ const chains = sdk.pricesService.supportedChains();
601
+ ```
602
+
603
+ ##### `supportedQueries()`
604
+
605
+ Returns the supported price queries for each chain.
606
+
607
+ ```typescript
608
+ const queries = sdk.pricesService.supportedQueries();
609
+ ```
610
+
611
+ ##### `getCurrentPricesInChain(params)`
612
+
613
+ Gets current prices for tokens in a specific chain.
614
+
615
+ ```typescript
616
+ const prices = await sdk.pricesService.getCurrentPricesInChain({
617
+ chainId: Chains.ETHEREUM.chainId,
618
+ tokens: ["0x...", "0x..."],
619
+ config: { timeout: "30s" },
620
+ });
621
+ ```
622
+
623
+ ##### `getCurrentPrices(params)`
624
+
625
+ Gets current prices for tokens across multiple chains.
626
+
627
+ ```typescript
628
+ const prices = await sdk.pricesService.getCurrentPrices({
629
+ tokens: [
630
+ { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
631
+ { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
632
+ ],
633
+ config: { timeout: "30s" },
634
+ });
635
+ ```
636
+
637
+ ##### `getHistoricalPricesInChain(params)`
638
+
639
+ Gets historical prices for tokens in a specific chain at a given timestamp.
640
+
641
+ ```typescript
642
+ const prices = await sdk.pricesService.getHistoricalPricesInChain({
643
+ chainId: Chains.ETHEREUM.chainId,
644
+ tokens: ["0x...", "0x..."],
645
+ timestamp: 1234567890,
646
+ searchWidth: "1h",
647
+ config: { timeout: "30s" },
648
+ });
649
+ ```
650
+
651
+ ##### `getHistoricalPrices(params)`
652
+
653
+ Gets historical prices for tokens across multiple chains at a given timestamp.
654
+
655
+ ```typescript
656
+ const prices = await sdk.pricesService.getHistoricalPrices({
657
+ tokens: [
658
+ { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
659
+ { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
660
+ ],
661
+ timestamp: 1234567890,
662
+ searchWidth: "1h",
663
+ config: { timeout: "30s" },
664
+ });
665
+ ```
666
+
667
+ ##### `getBulkHistoricalPrices(params)`
668
+
669
+ Gets historical prices for multiple tokens at different timestamps.
670
+
671
+ ```typescript
672
+ const prices = await sdk.pricesService.getBulkHistoricalPrices({
673
+ tokens: [
674
+ { chainId: Chains.ETHEREUM.chainId, token: "0x...", timestamp: 1234567890 },
675
+ { chainId: Chains.OPTIMISM.chainId, token: "0x...", timestamp: 1234567890 },
676
+ ],
677
+ searchWidth: "1h",
678
+ config: { timeout: "30s" },
679
+ });
680
+ ```
681
+
682
+ ##### `getChart(params)`
683
+
684
+ Gets price chart data for tokens over a specified time period.
685
+
686
+ ```typescript
687
+ const chart = await sdk.pricesService.getChart({
688
+ tokens: [
689
+ { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
690
+ { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
691
+ ],
692
+ span: 100,
693
+ period: "1d",
694
+ bound: { from: 1234567890 },
695
+ searchWidth: "1h",
696
+ });
697
+ ```
698
+
699
+ ### Metadata Service
700
+
701
+ The Metadata Service provides token metadata information across multiple chains.
702
+
703
+ #### Objective and Potential
704
+
705
+ - **Objective**: Provide a unified interface for retrieving token metadata across multiple chains
706
+ - **Potential Use Cases**:
707
+ - Token information display in UIs
708
+ - Token validation and verification
709
+ - Multi-chain token management
710
+ - Token data aggregation
711
+
712
+ #### Methods
713
+
714
+ ##### `supportedChains()`
715
+
716
+ Returns an array of chain IDs that are supported by the service.
717
+
718
+ ```typescript
719
+ const chains = sdk.metadataService.supportedChains();
720
+ ```
721
+
722
+ ##### `supportedProperties()`
723
+
724
+ Returns the supported metadata properties for each chain.
725
+
726
+ ```typescript
727
+ const properties = sdk.metadataService.supportedProperties();
728
+ ```
729
+
730
+ ##### `getMetadataInChain(params)`
731
+
732
+ Gets metadata for tokens in a specific chain.
733
+
734
+ ```typescript
735
+ const metadata = await sdk.metadataService.getMetadataInChain({
736
+ chainId: Chains.ETHEREUM.chainId,
737
+ tokens: ["0x...", "0x..."],
738
+ config: {
739
+ fields: { symbol: "required", decimals: "required" },
740
+ timeout: "30s",
741
+ },
742
+ });
743
+ ```
744
+
745
+ ##### `getMetadata(params)`
746
+
747
+ Gets metadata for tokens across multiple chains.
748
+
749
+ ```typescript
750
+ const metadata = await sdk.metadataService.getMetadata({
751
+ tokens: [
752
+ { chainId: Chains.ETHEREUM.chainId, token: "0x..." },
753
+ { chainId: Chains.OPTIMISM.chainId, token: "0x..." },
754
+ ],
755
+ config: {
756
+ fields: { symbol: "required", decimals: "required" },
757
+ timeout: "30s",
758
+ },
759
+ });
760
+ ```
761
+
762
+ ## Advanced Usage
763
+
764
+ ### Error Handling
765
+
766
+ The SDK provides comprehensive error handling for all services:
767
+
768
+ ```typescript
769
+ try {
770
+ const quotes = await sdk.quoteService.getAllQuotes({...});
771
+ } catch (error) {
772
+ if (error instanceof FailedToGenerateAnyQuotesError) {
773
+ // Handle quote generation failure
774
+ }
775
+ }
776
+ ```
777
+
778
+ ### Configuration
779
+
780
+ Each service can be configured with custom timeouts and other parameters:
781
+
782
+ ```typescript
783
+ const quotes = await sdk.quoteService.getAllQuotes({
784
+ request: {...},
785
+ config: {
786
+ timeout: "30s",
787
+ ignoredFailed: true,
788
+ sort: {
789
+ by: "most-swapped-accounting-for-gas",
790
+ using: "gas-price"
791
+ }
792
+ }
793
+ });
794
+ ```
795
+
796
+ ### Multi-chain Support
797
+
798
+ All services support operations across multiple chains:
799
+
800
+ ```typescript
801
+ const balances = await sdk.balanceService.getBalancesForTokens({
802
+ account: "0x...",
803
+ tokens: {
804
+ [Chains.ETHEREUM.chainId]: ["0x..."],
805
+ [Chains.OPTIMISM.chainId]: ["0x..."],
806
+ [Chains.ARBITRUM.chainId]: ["0x..."],
807
+ },
808
+ });
809
+ ```
810
+
811
+ ## ๐Ÿ‘จโ€๐Ÿ’ป Development
812
+
813
+ ### Environment Setup
814
+
815
+ ```bash
816
+ yarn install
817
+ ```
818
+
819
+ ## Contributing
820
+
821
+ Contributions are welcome! Please feel free to submit a Pull Request.
package/package.json ADDED
@@ -0,0 +1,60 @@
1
+ {
2
+ "name": "@0xkoaj/sdk",
3
+ "version": "0.0.1-beta.1",
4
+ "contributors": [],
5
+ "main": "./dist/index.js",
6
+ "files": [
7
+ "dist/**"
8
+ ],
9
+ "scripts": {
10
+ "build": "tsc -p tsconfig.json && tsconfig-replace-paths -s src -p tsconfig.json",
11
+ "lint:check": "prettier --check .",
12
+ "lint:fix": "sort-package-json && prettier --write .",
13
+ "prepare": "husky install",
14
+ "script": "ts-node -r tsconfig-paths/register",
15
+ "test": "jest --forceExit --detectOpenHandles --verbose",
16
+ "test:integration": "jest --forceExit --detectOpenHandles --verbose --testPathPattern=test/integration",
17
+ "test:unit": "jest --forceExit --detectOpenHandles --verbose --testPathPattern=test/unit"
18
+ },
19
+ "lint-staged": {
20
+ "*.{js,css,md,ts,sol}": "prettier --write",
21
+ "package.json": "sort-package-json"
22
+ },
23
+ "dependencies": {
24
+ "cross-fetch": "4.1.0",
25
+ "crypto-js": "4.2.0",
26
+ "deepmerge": "4.3.1",
27
+ "lru-cache": "11.1.0",
28
+ "ms": "3.0.0-canary.1",
29
+ "qs": "6.14.0",
30
+ "viem": "2.33.1"
31
+ },
32
+ "devDependencies": {
33
+ "@commitlint/cli": "19.8.1",
34
+ "@commitlint/config-conventional": "19.8.1",
35
+ "@types/chai": "5.2.2",
36
+ "@types/chai-as-promised": "7.1.8",
37
+ "@types/crypto-js": "4.1.2",
38
+ "@types/jest": "29.5.6",
39
+ "@types/node": "24.1.0",
40
+ "@types/qs": "6.14.0",
41
+ "@types/ws": "8.5.10",
42
+ "chai": "4.3.7",
43
+ "chai-as-promised": "7.1.2",
44
+ "dotenv": "16.3.1",
45
+ "husky": "8.0.3",
46
+ "jest": "29.7.0",
47
+ "lint-staged": "13.2.2",
48
+ "patch-package": "8.0.0",
49
+ "prettier": "2.8.8",
50
+ "sort-package-json": "3.4.0",
51
+ "ts-jest": "29.4.0",
52
+ "ts-node": "10.9.1",
53
+ "tsconfig-paths": "4.2.0",
54
+ "tsconfig-replace-paths": "0.0.14",
55
+ "typescript": "5.4.2"
56
+ },
57
+ "publishConfig": {
58
+ "access": "public"
59
+ }
60
+ }