@quicknode/sdk 1.0.0-beta.0 → 1.0.0-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.
- package/README.md +174 -42
- package/cjs/index.js +481 -61
- package/esm/index.js +481 -62
- package/index.d.ts +2164 -188
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -43,6 +43,7 @@ Currently the SDK makes it even easier to use the [QuickNode Graph API](https://
|
|
|
43
43
|
- [events.getAll](#eventsgetall)
|
|
44
44
|
- [utils.getGasPrices](#utilsgetgasprices)
|
|
45
45
|
- [graphApiClient.query](#graphapiclientquery)
|
|
46
|
+
- [Error Handling](#error-handling)
|
|
46
47
|
- [Filters](#filters)
|
|
47
48
|
- [Token Event Filters](#token-event-filters)
|
|
48
49
|
- [Pagination](#pagination)
|
|
@@ -91,7 +92,7 @@ These functions return data from the powerful [QuickNode Graph API](https://www.
|
|
|
91
92
|
|
|
92
93
|
### Configuration
|
|
93
94
|
|
|
94
|
-
Sign up for a [QuickNode](https://www.quicknode.com/) account to use the multi-chain [QuickNode
|
|
95
|
+
Sign up for a [QuickNode](https://www.quicknode.com/) account to use the multi-chain [QuickNode Graph API](https://www.quicknode.com/graph-api) API key in the SDK. The API functions in the SDK (and the underlying Graph API) can be used without an API key, but its usage will be heavily rate limited, intended for trial and development purposes only. For more information, please see [QuickNode's Graph API documentation](https://docs.quicknode.com/docs/graphql/getting-started/)
|
|
95
96
|
|
|
96
97
|
```ts
|
|
97
98
|
import QuickNode from '@quicknode/sdk';
|
|
@@ -127,19 +128,20 @@ If no `defaultChain` is passed into the initializer or a `chain` argument to a f
|
|
|
127
128
|
|
|
128
129
|
Returns NFTs owned by a wallet
|
|
129
130
|
|
|
130
|
-
| Argument | Values | Required | Description | Example
|
|
131
|
-
| -------- | ------ | -------- | --------------------------------------------------- |
|
|
132
|
-
| address | string | ✅ | Wallet address or ENS domain | quicknode.eth
|
|
133
|
-
| first | number | ❌ | Number of results to return | 10
|
|
134
|
-
|
|
|
135
|
-
|
|
|
136
|
-
|
|
|
131
|
+
| Argument | Values | Required | Description | Example |
|
|
132
|
+
| -------- | ------ | -------- | --------------------------------------------------- | --------------------------------------------------- |
|
|
133
|
+
| address | string | ✅ | Wallet address or ENS domain | quicknode.eth |
|
|
134
|
+
| first | number | ❌ | Number of results to return | 10 |
|
|
135
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
136
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
137
|
+
| chain | string | ❌ | Blockchain name | polygon |
|
|
138
|
+
| filter | object | ❌ | An object with the optional filters for the request | { contractTokens: [{ contractAddress: "0x00..." }]} |
|
|
137
139
|
|
|
138
140
|
`filter` Parameters
|
|
139
141
|
|
|
140
|
-
| Argument
|
|
141
|
-
|
|
|
142
|
-
|
|
|
142
|
+
| Argument | Values | Description | Example |
|
|
143
|
+
| -------------- | ------ | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
144
|
+
| contractTokens | Array | An array of objects with NFT contract addresses and optional tokenIds | [{ contractAddress: "0x2106C00Ac7dA0A3430aE667879139E832307AeAa" }] |
|
|
143
145
|
|
|
144
146
|
```ts
|
|
145
147
|
import QuickNode from '@quicknode/sdk';
|
|
@@ -170,11 +172,12 @@ qn.nfts
|
|
|
170
172
|
|
|
171
173
|
Returns trending NFT Collections
|
|
172
174
|
|
|
173
|
-
| Argument | Values | Required | Description
|
|
174
|
-
| -------- | ------ | -------- |
|
|
175
|
-
| first | number | ❌ | Number of results to return
|
|
176
|
-
|
|
|
177
|
-
|
|
|
175
|
+
| Argument | Values | Required | Description | Example |
|
|
176
|
+
| -------- | ------ | -------- | ---------------------------- | ------------------------ |
|
|
177
|
+
| first | number | ❌ | Number of results to return | 10 |
|
|
178
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
179
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
180
|
+
| chain | string | ❌ | Blockchain name | polygon |
|
|
178
181
|
|
|
179
182
|
```ts
|
|
180
183
|
import QuickNode from '@quicknode/sdk';
|
|
@@ -196,12 +199,13 @@ qn.nfts
|
|
|
196
199
|
|
|
197
200
|
Returns NFTs by contract address. The response differs based on if they are an ERC721 or ERC1155 standard.
|
|
198
201
|
|
|
199
|
-
| Argument | Values | Required | Description
|
|
200
|
-
| --------------- | ------ | -------- |
|
|
201
|
-
| contractAddress | string | ✅ | NFT contract address
|
|
202
|
-
| first | number | ❌ | Number of results to return
|
|
203
|
-
|
|
|
204
|
-
|
|
|
202
|
+
| Argument | Values | Required | Description | Example |
|
|
203
|
+
| --------------- | ------ | -------- | ---------------------------- | ------------------------------------------ |
|
|
204
|
+
| contractAddress | string | ✅ | NFT contract address | 0x2106C00Ac7dA0A3430aE667879139E832307AeAa |
|
|
205
|
+
| first | number | ❌ | Number of results to return | 10 |
|
|
206
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
207
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
208
|
+
| chain | string | ❌ | Blockchain name | polygon |
|
|
205
209
|
|
|
206
210
|
```ts
|
|
207
211
|
import QuickNode from '@quicknode/sdk';
|
|
@@ -272,16 +276,77 @@ qn.nfts
|
|
|
272
276
|
|
|
273
277
|
<br>
|
|
274
278
|
|
|
279
|
+
### nfts.verifyOwnership
|
|
280
|
+
|
|
281
|
+
Check if the wallet address is an owner of any of the provided NFT contract addresses. Returns a boolean if they own and NFT from _any_ of the provided contract addresses.
|
|
282
|
+
|
|
283
|
+
| Argument | Values | Required | Description | Example |
|
|
284
|
+
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
285
|
+
| address | string | ✅ | Address or ENS name of wallet to check as owner | 0x3C6aEFF92b4B35C2e1b196B57d0f8FFB56884A17 |
|
|
286
|
+
| nfts | array | ✅ | an array of objects with `contractAddress` and optional `tokenId` to check ownership of. Ownership is verified if any of the parameters are owned by the wallet | [{ contractAddress: "0x2106C00Ac7dA0A3430aE667879139E832307AeAa" }] |
|
|
287
|
+
| chain | string | ❌ | Blockchain name | polygon |
|
|
288
|
+
|
|
289
|
+
```typescript
|
|
290
|
+
import QuickNode from '@quicknode/sdk';
|
|
291
|
+
|
|
292
|
+
const qn = new QuickNode.API({
|
|
293
|
+
graphApiKey: 'my-api-key', // which is obtained by signing up on https://www.quicknode.com/signup
|
|
294
|
+
});
|
|
295
|
+
|
|
296
|
+
// returns true if wallet owns at least one NFT of 0x2106C00Ac7dA0A3430aE667879139E832307AeAa
|
|
297
|
+
qn.nfts
|
|
298
|
+
.verifyOwnership({
|
|
299
|
+
address: '0xD10E24685c7CDD3cd3BaAA86b09C92Be28c834B6',
|
|
300
|
+
nfts: [
|
|
301
|
+
{
|
|
302
|
+
contractAddress: '0x2106C00Ac7dA0A3430aE667879139E832307AeAa',
|
|
303
|
+
},
|
|
304
|
+
],
|
|
305
|
+
})
|
|
306
|
+
.then((response) => console.log(response));
|
|
307
|
+
|
|
308
|
+
// returns true if quicknode.eth owns the exact NFT id 123 from contract address 0x2106C00Ac7dA0A3430aE667879139E832307AeAa
|
|
309
|
+
qn.nfts
|
|
310
|
+
.verifyOwnership({
|
|
311
|
+
address: 'quicknode.eth', // or wallet address
|
|
312
|
+
nfts: [
|
|
313
|
+
{
|
|
314
|
+
contractAddress: '0x2106C00Ac7dA0A3430aE667879139E832307AeAa',
|
|
315
|
+
tokenId: '123',
|
|
316
|
+
},
|
|
317
|
+
],
|
|
318
|
+
})
|
|
319
|
+
.then((response) => console.log(response));
|
|
320
|
+
|
|
321
|
+
// returns true if quicknode.eth owns an NFT from either 0x2106C00Ac7dA0A3430aE667879139E832307AeAa or 0x9D90669665607F08005CAe4A7098143f554c59EF
|
|
322
|
+
qn.nfts
|
|
323
|
+
.verifyOwnership({
|
|
324
|
+
address: 'quicknode.eth', // or wallet address
|
|
325
|
+
nfts: [
|
|
326
|
+
{
|
|
327
|
+
contractAddress: '0x2106C00Ac7dA0A3430aE667879139E832307AeAa',
|
|
328
|
+
},
|
|
329
|
+
{
|
|
330
|
+
contractAddress: '0x9D90669665607F08005CAe4A7098143f554c59EF',
|
|
331
|
+
},
|
|
332
|
+
],
|
|
333
|
+
})
|
|
334
|
+
.then((response) => console.log(response));
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
<br>
|
|
338
|
+
|
|
275
339
|
### tokens.getBalancesByWallet
|
|
276
340
|
|
|
277
341
|
Returns ERC20 token balances for a wallet
|
|
278
342
|
|
|
279
|
-
| Argument | Values | Required | Description
|
|
280
|
-
| -------- | ------ | -------- |
|
|
281
|
-
| address | string | ✅ | Wallet address or ENS domain
|
|
282
|
-
| first | number | ❌ | Number of results to return
|
|
283
|
-
|
|
|
284
|
-
|
|
|
343
|
+
| Argument | Values | Required | Description | Example |
|
|
344
|
+
| -------- | ------ | -------- | ---------------------------- | ------------------------------------------ |
|
|
345
|
+
| address | string | ✅ | Wallet address or ENS domain | 0x3C6aEFF92b4B35C2e1b196B57d0f8FFB56884A17 |
|
|
346
|
+
| first | number | ❌ | Number of results to return | 10 |
|
|
347
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
348
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
349
|
+
| chain | string | ❌ | Blockchain name | polygon |
|
|
285
350
|
|
|
286
351
|
```ts
|
|
287
352
|
import QuickNode from '@quicknode/sdk';
|
|
@@ -337,12 +402,13 @@ qn.contracts
|
|
|
337
402
|
|
|
338
403
|
Returns transactions for a wallet
|
|
339
404
|
|
|
340
|
-
| Argument | Values | Required | Description
|
|
341
|
-
| -------- | ------ | -------- |
|
|
342
|
-
| address | string | ✅ | Wallet address or ENS domain
|
|
343
|
-
| first | number | ❌ | Number of results to return
|
|
344
|
-
|
|
|
345
|
-
|
|
|
405
|
+
| Argument | Values | Required | Description | Example |
|
|
406
|
+
| -------- | ------ | -------- | ---------------------------- | ------------------------------------------ |
|
|
407
|
+
| address | string | ✅ | Wallet address or ENS domain | 0x3C6aEFF92b4B35C2e1b196B57d0f8FFB56884A17 |
|
|
408
|
+
| first | number | ❌ | Number of results to return | 10 |
|
|
409
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
410
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
411
|
+
| chain | string | ❌ | Blockchain name | polygon |
|
|
346
412
|
|
|
347
413
|
```ts
|
|
348
414
|
import QuickNode from '@quicknode/sdk';
|
|
@@ -376,7 +442,8 @@ Returns transactions filtered by search parameters
|
|
|
376
442
|
| Argument | Values | Required | Description | Example |
|
|
377
443
|
| -------- | ------ | -------- | --------------------------------------------------- | ------------------------------- |
|
|
378
444
|
| first | number | ❌ | Number of results to return | 10 |
|
|
379
|
-
|
|
|
445
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
446
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
380
447
|
| chain | string | ❌ | Blockchain name | polygon |
|
|
381
448
|
| filter | object | ✅ | An object with the optional filters for the request | { blockNumber: { eq: 123456 } } |
|
|
382
449
|
|
|
@@ -447,7 +514,8 @@ Returns events by contract address
|
|
|
447
514
|
| Argument | Values | Required | Description | Example |
|
|
448
515
|
| -------- | ------ | -------- | --------------------------------------------------- | ------------------------------- |
|
|
449
516
|
| first | number | ❌ | Number of results to return | 10 |
|
|
450
|
-
|
|
|
517
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
518
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
451
519
|
| chain | string | ❌ | Blockchain name | polygon |
|
|
452
520
|
| filter | object | ❌ | An object with the optional filters for the request | { blockNumber: { eq: 123456 } } |
|
|
453
521
|
|
|
@@ -496,7 +564,8 @@ Returns the events for an NFT Collection
|
|
|
496
564
|
| contractAddress | string | ✅ | NFT contract address | 0x2106C00Ac7dA0A3430aE667879139E832307AeAa |
|
|
497
565
|
| chain | string | ❌ | Blockchain name | polygon |
|
|
498
566
|
| first | number | ❌ | Number of results to return | 10 |
|
|
499
|
-
|
|
|
567
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
568
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
500
569
|
| filter | object | ❌ | An object with the optional filters for the request | { blockNumber: { eq: 123456 } } |
|
|
501
570
|
|
|
502
571
|
`filter` Parameters
|
|
@@ -543,7 +612,8 @@ Returns the events for a specific NFT
|
|
|
543
612
|
| tokenId | string | ✅ | NFT Token ID | 1 |
|
|
544
613
|
| chain | string | ❌ | Blockchain name | polygon |
|
|
545
614
|
| first | number | ❌ | Number of results to return | 10 |
|
|
546
|
-
|
|
|
615
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
616
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
547
617
|
| filter | object | ❌ | An object with the optional filters for the request | { blockNumber: { eq: 123456 } } |
|
|
548
618
|
|
|
549
619
|
`filter` Parameters
|
|
@@ -587,7 +657,8 @@ Returns events filtered by search parameters
|
|
|
587
657
|
| -------- | ------ | -------- | --------------------------------------------------- | ------------------------------- |
|
|
588
658
|
| chain | string | ❌ | Blockchain name | polygon |
|
|
589
659
|
| first | number | ❌ | Number of results to return | 10 |
|
|
590
|
-
|
|
|
660
|
+
| before | string | ❌ | Return results before cursor | T2Zmc2V0Q29ubmVjdGlvbjow |
|
|
661
|
+
| after | string | ❌ | Return results after cursor | T2Zmc2V0Q29ubmVjdGlvbjo2 |
|
|
591
662
|
| filter | object | ❌ | An object with the optional filters for the request | { blockNumber: { eq: 123456 } } |
|
|
592
663
|
|
|
593
664
|
`filter` Parameters
|
|
@@ -694,6 +765,43 @@ qn.graphApiClient.query({ query, variables }).then(({ data }) => console.log(dat
|
|
|
694
765
|
|
|
695
766
|
<br>
|
|
696
767
|
|
|
768
|
+
### Error handling
|
|
769
|
+
|
|
770
|
+
The input to API functions is validated at runtime in order to handle both untyped JavaScript input and user input in end user applications. In short, this will help prevent you sending invalid Graph API queries because of bad input. The validation is done by [zod](https://www.npmjs.com/package/zod) under the hood and we expose the errors to you in a `QNInputValidationError` instance.
|
|
771
|
+
|
|
772
|
+
For example, you can handle these errors:
|
|
773
|
+
|
|
774
|
+
```typescript
|
|
775
|
+
import QuickNode from '@quicknode/sdk';
|
|
776
|
+
|
|
777
|
+
const qn = new QuickNode.API({ graphApiKey: 'my-api-key' });
|
|
778
|
+
|
|
779
|
+
// Inside async function
|
|
780
|
+
try {
|
|
781
|
+
const eventsByContract = await events.getByContract({
|
|
782
|
+
contractAddress: userInput, // Input comes from the user, we don't know what will be here
|
|
783
|
+
});
|
|
784
|
+
return eventsByContract;
|
|
785
|
+
} catch (error) {
|
|
786
|
+
if (error instanceof QNInputValidationError) {
|
|
787
|
+
console.error(error.stack);
|
|
788
|
+
return { errors: error.issues }; // Return formatted issues to handle as needed by UI or user
|
|
789
|
+
} else {
|
|
790
|
+
// handle unexpected errors here
|
|
791
|
+
}
|
|
792
|
+
}
|
|
793
|
+
```
|
|
794
|
+
|
|
795
|
+
The `QNInputValidationError` instance has the following properties:
|
|
796
|
+
|
|
797
|
+
| Property | Type | Description |
|
|
798
|
+
| -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
799
|
+
| messages | string[] | An array of concise error messages |
|
|
800
|
+
| zodError | ZodError | The full `ZodError` instance, see [the Zod error handling docs](https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md) for more information |
|
|
801
|
+
| issues | ZodIssue[] | An array of [Zod Issue](https://github.com/colinhacks/zod/blob/master/ERROR_HANDLING.md#zodissue) instances, which is a formatted error data structure |
|
|
802
|
+
|
|
803
|
+
<br>
|
|
804
|
+
|
|
697
805
|
## Filters
|
|
698
806
|
|
|
699
807
|
Some filters are shared between queries
|
|
@@ -731,7 +839,7 @@ For example, if a response contains:
|
|
|
731
839
|
|
|
732
840
|
```json
|
|
733
841
|
{
|
|
734
|
-
"results": [],
|
|
842
|
+
"results": [...],
|
|
735
843
|
"pageInfo": {
|
|
736
844
|
"endCursor": "T2Zmc2V0Q29ubmVjdGlvbjox",
|
|
737
845
|
"hasNextPage": true,
|
|
@@ -746,8 +854,32 @@ calling the following will get the next page of results
|
|
|
746
854
|
```typescript
|
|
747
855
|
qn.nfts.getByWallet({
|
|
748
856
|
address: 'quicknode.eth',
|
|
749
|
-
|
|
750
|
-
|
|
857
|
+
after: 'T2Zmc2V0Q29ubmVjdGlvbjox', // Using the endCursor
|
|
858
|
+
});
|
|
859
|
+
```
|
|
860
|
+
|
|
861
|
+
You can do the same with `before` and return the results before the specified cursor if `hasPreviousPage` is true
|
|
862
|
+
|
|
863
|
+
For example, if the response contains the following:
|
|
864
|
+
|
|
865
|
+
```json
|
|
866
|
+
{
|
|
867
|
+
"results": [...],
|
|
868
|
+
"pageInfo": {
|
|
869
|
+
"endCursor": "T2Zmc2V0Q29ubmVjdGlvbjo2",
|
|
870
|
+
"hasNextPage": true,
|
|
871
|
+
"hasPreviousPage": true,
|
|
872
|
+
"startCursor": "T2Zmc2V0Q29ubmVjdGlvbjoy"
|
|
873
|
+
}
|
|
874
|
+
}
|
|
875
|
+
```
|
|
876
|
+
|
|
877
|
+
calling the following will get the previous page of results
|
|
878
|
+
|
|
879
|
+
```typescript
|
|
880
|
+
qn.nfts.getByWallet({
|
|
881
|
+
address: 'quicknode.eth',
|
|
882
|
+
before: 'T2Zmc2V0Q29ubmVjdGlvbjoy', // Using the startCursor
|
|
751
883
|
});
|
|
752
884
|
```
|
|
753
885
|
|