ThirdwebSDKProvider

The ThirdwebSDKProvider is used when you want to provide your own wallet connection logic and just use the thirdweb SDK to interact with smart contracts and the blockchain. This means you can use everything in the SDK except for wallet connection-related components and hooks.

Wrap your app in the ThirdwebSDKProvider to access the SDK’s functionality from anywhere in your app. Provide a signer prop to inform the SDK of the wallet you want to use, among other configuration options.

Usage

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

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

You’ll likely want to provide a signer to enable the initiation of transactions.

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"

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";
import { ethers } from "ethers";

function MyApp() {
  return (
    <ThirdwebSDKProvider
      activeChain={"ethereum"}
      // Example: Use ethers to get the signer from the window.ethereum object
      signer={new ethers.providers.Web3Provider(window.ethereum).getSigner()}
      clientId="your-client-id"
    >
      <App />
    </ThirdwebSDKProvider>
  );
}

Configuration

signer (recommended)

A signer is an abstraction of an Ethereum Account, which can be used to sign messages and initiate transactions.

Since the ThirdwebSDKProvider is used when you want to provide your own wallet connection logic, you will need to provide a signer prop to inform the SDK of the wallet you want to use to sign transactions.

Libraries such as ethers.js, web3.js, wagmi, etc. all provide ways to get a signer.

To use this signer with the SDK, pass it to the signer prop. If the signer is connected, the SDK will use this wallet to sign transactions for all write operations on the blockchain.

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";
import { ethers } from "ethers";

function MyApp() {
  return (
    <ThirdwebSDKProvider
      activeChain={"ethereum"}
      // Example: Use ethers to get the signer from the window.ethereum object
      signer={new ethers.providers.Web3Provider(window.ethereum).getSigner()}
      clientId="your-client-id"
    >
      <App />
    </ThirdwebSDKProvider>
  );
}

clientId (recommended)

The clientId prop is required to use the thirdweb infrastructure services with the SDK. You can get a client ID by creating an API key on thirdweb dashboard.

function MyApp() {
  return (
    <ThirdwebSDKProvider
      activeChain={"ethereum"}
      // Example: Use ethers to get the signer from the window.ethereum object
      signer={new ethers.providers.Web3Provider(window.ethereum).getSigner()}
      clientId="your-client-id"
    >
      <App />
    </ThirdwebSDKProvider>
  );
}

activeChain (recommended)

The activeChain prop determines which chain you want your app to be operating on.

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

npm install @thirdweb-dev/chains

Yarn

yarn add @thirdweb-dev/chains

pnpm

pnpm add @thirdweb-dev/chains

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";
import { Gnosis } from "@thirdweb-dev/chains";

function MyApp() {
  return (
    <ThirdwebSDKProvider
      activeChain={Gnosis}
    >
      <YourApp />
    </ThirdwebSDKProvider>
  );
}

Custom EVM Chains

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

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";

const App = () => {
  return (
    <ThirdwebSDKProvider
      activeChain={{
        // === 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
      }}
    >
      <YourApp />
    </ThirdwebSDKProvider>
  );
};

Override Default Values

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

Optional

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 { ThirdwebSDKProvider } from "@thirdweb-dev/react";
import { Dogechain } from "@thirdweb-dev/chains";

const App = () => {
  return (
    <ThirdwebSDKProvider
      activeChain={{
        ...Dogechain,
        rpc: ["https://<your-rpc-to-use>.com"], // Override the "rpc" field.
        // ... Override any other fields you want to customize.
      }}
    >
      <YourApp />
    </ThirdwebSDKProvider>
  );
};

authConfig (optional)

The configuration object for setting up Auth; allowing users to sign in with their wallet.

Property	Type	Description
authUrl	string	The backend URL of the authentication endpoints. For example, if your endpoints are at /api/auth/login, /api/auth/logout, etc. then this should be set to /api/auth.
domain	string	The frontend domain used to generate the login payload. This domain should match the domain used on your auth backend.
secureStorage	ISecureStorage	Secure storage to use when working with JWT tokens. By default auth uses cookies so no need to set this unless you want to specifically use JWT tokens

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";

function MyApp() {
  return (
    <ThirdwebSDKProvider
      authConfig={{
        authUrl: "/api/auth",
        domain: "https://example.com",
      }}
    >
      <YourApp />
    </ThirdwebSDKProvider>
  );
}

sdkOptions (optional)

Override any of the default values for the SDK.

Gas settings, gasless transactions, RPC configuration, and more.

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";

function MyApp() {
  return (
    <ThirdwebSDKProvider
      sdkOptions={{
        readonlySettings: {
          rpcUrl: "<rpc-url>", // force read calls to go through your own RPC url
          chainId: 1, // reduce RPC calls by specifying your chain ID
        },
        gasSettings: {
          maxPriceInGwei: 123, // Maximum gas price for transactions (default 300 gwei)
          speed: "fastest", // the tx speed setting: 'standard'|'fast|'fastest' (default: 'fastest')
        },
        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
          },
        },
        infuraApiKey: "<infura-api-key>", // your Infura API key
        alchemyApiKey: "<alchemy-api-key>", // your Alchemy API key
      }}
    >
      <YourApp />
    </ThirdwebSDKProvider>
  );
}

storageInterface (optional)

Override the default Storage interface used by the SDK.

Allows you to create an instance of ThirdwebStorage with your own customized config, and pass it to the SDK.

Storage

This requires the @thirdweb-dev/storage package to be installed.

Learn more about Storage

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";
import {
  ThirdwebStorage,
  StorageDownloader,
  IpfsUploader,
} from "@thirdweb-dev/storage";

// Configure a custom ThirdwebStorage instance
const gatewayUrls = {
  "ipfs://": [
    "https://gateway.ipfscdn.io/ipfs/",
    "https://cloudflare-ipfs.com/ipfs/",
    "https://ipfs.io/ipfs/",
  ],
};
const downloader = new StorageDownloader();
const uploader = new IpfsUploader();
const storage = new ThirdwebStorage({ uploader, downloader, gatewayUrls });

// Provide the custom storage instance to the SDK
function MyApp() {
  return (
    <ThirdwebSDKProvider
      storageInterface={storage}
    >
      <YourApp />
    </ThirdwebSDKProvider>
  );
}

queryClient (optional)

If you are using React Query and have your own QueryClient, (or are using wagmi), you can pass it as the queryClient prop to use this client instead of the SDK's default client.

import { ThirdwebSDKProvider } from "@thirdweb-dev/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

function MyApp() {
  // Your React Query client (or client from other library such as wagmi)
  const queryClient = new QueryClient();

  return (
    <QueryClientProvider client={queryClient}>
      <ThirdwebSDKProvider
        queryClient={queryClient}
      >
        <YourApp />
      </ThirdwebSDKProvider>
    </QueryClientProvider>
  );
}