ThirdwebProvider

The ThirdwebProvider is a wrapper component that provides access to all of the SDK’s hooks and UI components. It utilizes the Provider Pattern to share data with all of the components that are nested within it.

Wrap your app in the ThirdwebProvider to access the SDK’s functionality from anywhere in your app.

Usage

API Keys

You will require an API key to use thirdweb's infrastructure services with the SDK, you need to first obtain an API key from the dashboard and then copy the clientId to pass as a prop to the ThirdwebPovider.

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.

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 { ThirdwebProvider } from "@thirdweb-dev/react";

function App() {
  return (
    <ThirdwebProvider activeChain="ethereum" clientId="your-client-id">
      <YourApp />
    </ThirdwebProvider>
  );
}

Configuration

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
Yarn
pnpm

npm install @thirdweb-dev/chains

yarn add @thirdweb-dev/chains

pnpm add @thirdweb-dev/chains

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

function MyApp() {
  return (
    <ThirdwebProvider
      activeChain={Gnosis}
      clientId="your-client-id"
    >
      <YourApp />
    </ThirdwebProvider>
  );
}

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.

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

function MyApp() {
  return (
    <ThirdwebProvider
      activeChain="ethereum"
      clientId="your-client-id"
    >
      <YourApp />
    </ThirdwebProvider>
  );
}

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 { ThirdwebProvider } from "@thirdweb-dev/react";

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

Local Nodes

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

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

function MyApp() {
  return (
    <ThirdwebProvider
      activeChain="localhost"
    >
      <YourApp />
    </ThirdwebProvider>
  );
}

Override Default Values

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

Optional

By default, the @thirdweb-dev/chains 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 { ThirdwebProvider } from "@thirdweb-dev/react";
import { Dogechain } from "@thirdweb-dev/chains";

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

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 { ThirdwebProvider } from "@thirdweb-dev/react";

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

supportedWallets (optional)

An array of wallets that your app supports.

Wallets provided here appear in the ConnectWallet Modal and allow you to use the wallet connection hooks.

Learn more about connecting wallets and the options available.

import {
  ThirdwebProvider,
  metamaskWallet,
  coinbaseWallet,
  walletConnect,
} from "@thirdweb-dev/react";

function MyApp() {
  return (
    <ThirdwebProvider
      supportedWallets={[metamaskWallet(), coinbaseWallet(), walletConnect()]}
      activeChain="ethereum"
      clientId="your-client-id"
    >
      <App />
    </ThirdwebProvider>
  );
}

supportedChains (optional)

An array of chains supported by your app.

If not provided, defaults to defaultChains

import { ThirdwebProvider } from "@thirdweb-dev/react";
import { Ethereum, Polygon } from "@thirdweb-dev/chains";

function MyApp() {
  return (
    <ThirdwebProvider
      activeChain={Ethereum}
      supportedChains={[Ethereum, Polygon]}
    >
      <App />
    </ThirdwebProvider>
  );
}

autoconnect (optional)

When the user has connected their wallet to your site before, this flag determines whether or not you want the SDK to automatically connect to the wallet on page load (requires the user to be logged in to the wallet).

Defaults to true.

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

function MyApp() {
  return (
    <ThirdwebProvider
      autoConnect={false}
    >
      <YourApp />
    </ThirdwebProvider>
  );
}

dAppMeta (optional)

This Metadata is passed to the wallet. Some wallets use this information to display the metadata of the app to the user when a user is connecting the wallet to your app.

Defaults to { name: "thirdweb powered dApp", url: "https://thirdweb.com" }.

Property	Type	Description
`name`	string	the name of your app
`description`	string	optional - a description of your app
`logoUrl`	string	optional - a URL that points to a logo (or favicon) of your app
`url`	string	optional - the URL where your app is hosted
`isDarkMode`	boolean	optional - whether to show the connect dialog in dark mode or not

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

function MyApp() {
  return (
    <ThirdwebProvider
      dAppMeta={{
        name: "My App",
        description: "My app description",
        logoUrl: "https://example.com/logo.png",
        url: "https://example.com",
        isDarkMode: true,
      }}
    >
      <YourApp />
    </ThirdwebProvider>
  );
}

sdkOptions (optional)

Override any of the default values for the SDK.

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

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

function MyApp() {
  return (
    <ThirdwebProvider
      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 />
    </ThirdwebProvider>
  );
}

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 { ThirdwebProvider } 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 (
    <ThirdwebProvider
      storageInterface={storage}
    >
      <YourApp />
    </ThirdwebProvider>
  );
}

queryClient (optional)

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

import { ThirdwebProvider } 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}>
      <ThirdwebProvider
        queryClient={queryClient}
      >
        <YourApp />
      </ThirdwebProvider>
    </QueryClientProvider>
  );
}

Usage​

Configuration​

activeChain (recommended)​

clientId (recommended)​

Custom EVM Chains​

Local Nodes​

Override Default Values​

authConfig (optional)​

supportedWallets (optional)​

supportedChains (optional)​

autoconnect (optional)​

dAppMeta (optional)​

sdkOptions (optional)​

storageInterface (optional)​

queryClient (optional)​