Skip to main content


The ThirdwebSDK is the entry point to all functionality of the TypeScript SDK.

You initialize the SDK on your desired chain and use the instance to access the different methods and properties of the SDK.


The SDK can be initialized in either read-only mode or read-write mode.

If you are using one of our default chains, provide the name of the chain as a string.

For non-default chains, see configuring chains or custom chains.

View default chains
  • Ethereum: "ethereum"
  • Goerli: "goerli"
  • Polygon: "polygon"
  • Mumbai: "mumbai"
  • Arbitrum One: "arbitrum"
  • Arbitrum Goerli: "arbitrum-goerli"
  • Optimism: "optimism"
  • Optimism Goerli Testnet: "optimism-goerli"
  • Binance SmartChain: "binance"
  • Binance SmartChain Testnet: "binance-testnet"
  • Fantom Opera: "fantom"
  • Fantom Testnet: "fantom-testnet"
  • Avalanche C Chain: "avalanche-fuji"
  • Avalanche Fuji Testnet: "avalanche-fuji-testnet"
  • Localhost: "localhost"

Using this method, you can only read data from the blockchain.

// Read-only mode
const readOnlySdk = new ThirdwebSDK("goerli", {
clientId: "YOUR_CLIENT_ID", // Use client id if using on the client side, get it from dashboard settings
secretKey: "YOUR_SECRET_KEY", // Use secret key if using on the server, get it from dashboard settings


Client ID or Secret Key(required)

To use the Typescript SDK, you need to obtain either the clientId or secretKey from an API key which you can obtain from the Dashboard. You can instatiate the SDK in two ways:

  • Client-side: Use the SDK in the browser or mobile app. In this instance, you would use the clientId prop.
  • Server-side: Use the SDK in a server environment. In this instance, you would use the secretKey prop.

Chain (required)

The chain you want your SDK instance to use.

There are 700+ chains available in the @thirdweb-dev/chains package. Import the chain you want to use from the package and pass it to the activeChain prop. If your chain is not included, see configuring custom chains.

Install Package

Install the @thirdweb-dev/chains package to use non-default chains.

npm install @thirdweb-dev/chains
import { ThirdwebSDK } from "@thirdweb-dev/sdk";
import { Gnosis } from "@thirdweb-dev/chains";

const sdk = new ThirdwebSDK(

Custom EVM Chains

If your chain is not included in the @thirdweb-dev/chains package, you can provide the chain information yourself.

import { ThirdwebSDK } from "@thirdweb-dev/sdk";

const sdk = new ThirdwebSDK({
// === Required information for connecting to the network === \\
chainId: 59140, // Chain ID of the network
// Array of RPC URLs to use
rpc: ["<your-rpc-url-here>"],

// === Information for adding the network to your wallet (how it will appear for first time users) === \\
// Information about the chain's native currency (i.e. the currency that is used to pay for gas)
nativeCurrency: {
decimals: 18,
name: "Consensys ETH",
symbol: "crETH",
shortName: "czkevm", // Display value shown in the wallet UI
slug: "consensys", // Display value shown in the wallet UI
testnet: true, // Boolean indicating whether the chain is a testnet or mainnet
chain: "ConsenSys", // Name of the network
name: "ConsenSys zkEVM Testnet", // Name of the network

Multiple Chains

The SDK also supports using multiple chains, using the supportedChains option to define which networks your app supports.

import { ThirdwebSDK } from "@thirdweb-dev/sdk";

const sdk = new ThirdwebSDK(
Polygon, // The currently active chain
supportedChains: [Polygon, Mumbai], // The chains you want to support

Local Nodes

If you are running a local node using a tool such as Hardhat or Anvil, provide "localhost" as the chain, (or Localhost imported from @thirdweb-dev/chains). Deploy or import your contracts to the dashboard to interact with them.

import { ThirdwebSDK } from "@thirdweb-dev/sdk";

const sdk = new ThirdwebSDK("localhost");

Override Default Values

Override the default values (such as an RPC URL) for any given chain.


By default, the SDK provides free-to-use RPCs. No configuration required!

View the default RPC URLs for each network.

Using the spread syntax, you can override any properties of a chain, such as the rpc field.

import { ThirdwebSDK } from "@thirdweb-dev/sdk";
import { Dogechain } from "@thirdweb-dev/chains";

const sdk = new ThirdwebSDK({
rpc: ["https://<your-rpc-to-use>.com"], // Override the "rpc" field.
// ... Override any other fields you want to customize.

gasless (optional)

Use gasless transactions to forward all transactions to a relayer.

Currently supports either OpenZeppelin Defender or Biconomy relayers.

import { ThirdwebSDK } from "@thirdweb-dev/sdk";

const sdk = new ThirdwebSDK("ethereum", {
gasless: {
// By specifying a gasless configuration - all transactions will get forwarded to enable gasless transactions
openzeppelin: {
relayerUrl: "<open-zeppelin-relayer-url>", // your OZ Defender relayer URL
relayerForwarderAddress: "<open-zeppelin-forwarder-address>", // the OZ defender relayer address (defaults to the standard one)
biconomy: {
apiId: "biconomy-api-id", // your Biconomy API Id
apiKey: "biconomy-api-key", // your Biconomy API Key
deadlineSeconds: 123, // your Biconomy timeout preference

gasSettings (optional)

The gas settings to use when sending transactions.

  • maxPriceInGwei: Maximum gas fee to pay for a transaction. Defaults to 300.
  • speed: The priority level to set for a transaction. Either "standard", "fast", or "fastest". Defaults to fastest.
import { ThirdwebSDK } from "@thirdweb-dev/sdk";

const sdk = new ThirdwebSDK("ethereum", {
gasSettings: {
maxPriceInGwei: 300,
speed: "fastest", // standard, fast, fastest

readOnlySettings (optional)

Override the RPC URL that is used for read operations on a given chain.

import { ThirdwebSDK, ChainId } from "@thirdweb-dev/sdk";

const sdk = new ThirdwebSDK("ethereum", {
readonlySettings: {
rpcUrl: "", // Use this RPC URL for read operations
chainId: ChainId.Mainnet, // On this chain ID