Overview

With the QuickNode SDK, developers can effortlessly leverage QuickNode's Graph API to access a wide range of valuable data and insights. This includes querying market insights, trading data, wallet and contract transactions, cached NFT images, and much more. By abstracting away the complexities, the SDK streamlines the integration process and enables developers to access and utilize QuickNode's extensive features rapidly.

Quickstart

The following example uses the QuickNode SDK to easily grab the first 5 NFTs from a wallet:

import QuickNode from '@quicknode/sdk';

const qn = new QuickNode.API();

qn.nfts
  .getByWallet({
    address: 'quicknode.eth',
    first: 5,
  })
  .then((response) => console.log(response));

Configuration

Sign up for a QuickNode account to use the multi-chain QuickNode 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.

import QuickNode from '@quicknode/sdk';
// if you are using CommonJS, use this line instead:
// const QuickNode = require('@quicknode/sdk')

const qn = new QuickNode.API({
  graphApiKey: 'my-api-key', // which is obtained by signing up on https://www.quicknode.com/signup
  defaultChain: 'ethereum',
});

A defaultChain can be set to set the chain for all calls. Currently we support:

defaultChain	Supported Network
ethereum	Ethereum Mainnet
ethereumSepolia	Ethereum Sepolia
polygon	Polygon Mainnet

The defaultChain in the initializer can be overridden with the chain argument in functions. If no defaultChain is passed into the initializer or a chain argument to a function, ethereum is used by default.

Configuration Arguments

Property	Values	Required	Description	Example
graphApiKey	string	❌	The QuickNode GraphQL API Key	abcd1234
defaultChain	string	❌	The default chain to use for all functions (defaults to ethereum)	polygon

Error Handling

The input to API functions is validated at runtime in order to handle both untyped JavaScript input and user input. In short, this will help prevent you sending invalid Graph API queries because of bad input. The validation is done by zod under the hood and we expose the errors to you in a QNInputValidationError instance.

For example, you can handle these errors:

import QuickNode from '@quicknode/sdk';

const qn = new QuickNode.API({ graphApiKey: 'my-api-key' });

// Inside async function
try {
  const eventsByContract = await events.getByContract({
    contractAddress: userInput, // Input comes from the user, we don't know what will be here
  });
  return eventsByContract;
} catch (error) {
  if (error instanceof QNInputValidationError) {
    console.error(error.stack);
    return { errors: error.issues }; // Return formatted issues to handle as needed by UI or user
  } else {
    // handle unexpected errors here
  }
}

The QNInputValidationError instance has the following properties:

Property	Type	Description
messages	string[]	An array of concise error messages
zodError	ZodError	The full ZodError instance, see the Zod error handling docs for more information
issues	ZodIssue[]	An array of Zod Issue instances, which is a formatted error data structure

Pagination

For functions that support pagination, use the first property to specify the amount of results to return.

The returned data.tokensPageInfo.endCursor property in the response can be used to access subsequent results. This value can be passed in to the after property and will return the results after that endCursor.

hasNextPage can be used to determine the end of the results, where it will be false.

For example, if a response contains:

{
  "results": [...],
  "pageInfo": {
    "endCursor": "T2Zmc2V0Q29ubmVjdGlvbjox",
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "T2Zmc2V0Q29ubmVjdGlvbjow"
  }
}

calling the following will get the next page of results:

qn.nfts.getByWallet({
  address: 'quicknode.eth',
  after: 'T2Zmc2V0Q29ubmVjdGlvbjox', // Using the endCursor
});

You can do the same with before and return the results before the specified cursor if hasPreviousPage is true

For example, if the response contains the following:

{
  "results": [...],
  "pageInfo": {
    "endCursor": "T2Zmc2V0Q29ubmVjdGlvbjo2",
    "hasNextPage": true,
    "hasPreviousPage": true,
    "startCursor": "T2Zmc2V0Q29ubmVjdGlvbjoy"
  }
}

calling the following will get the previous page of results:

qn.nfts.getByWallet({
  address: 'quicknode.eth',
  before: 'T2Zmc2V0Q29ubmVjdGlvbjoy', // Using the startCursor
});

Filtering

For functions that support it, a filter parameter can be utilized to perform filtering. This parameter accepts an object with the desired filtering fields as keys. Each key is then associated with another object containing one or more of the following operations: eq, gt, gte, in, lt, lte, or notIn. Please note that the keys supported can vary between different filters. For complex filtering requirements, a filter can combine multiple filtering fields and keys.

Key	Description
eq	Equals
gt	Greater than
gte	Greater than or equal to
in	Inclusive array
lt	Less than
lte	Less than or equal to
notIn	Exclusive array

For example, to get the events for contract 0x2106C00Ac7dA0A3430aE667879139E832307AeAa and filter only the TRANSFER or MINT events sent from 0x10fa1c188eca954419a85112f975155f717ad8ea, you could do this:

qn.events.getByContract({
    contractAddress: '0x2106C00Ac7dA0A3430aE667879139E832307AeAa',
    filter: {
      fromAddress: {
        eq: '0x10fa1c188eca954419a85112f975155f717ad8ea',
      },
      type: {
        in: ['TRANSFER', 'MINT'],
      },
    }
  })

Or to get transactions that happened between block number 17573100 and 17573200, you could do this:

qn.transactions.getAll({
  filter: {
    blockNumber: {
      gt: 17573100,
      lt: 17573200,
    },
  },
}

API Functions

All of the supported functions from the API SDK module can be found on the left-hand side under "API Functions". These functions return data from the powerful QuickNode Graph API.