thirdwebDocs

Get Started

Learn how to integrate Universal Bridge into your application for cross-chain payments, bridging, swapping, and fiat onramps. This guide covers the core SDK modules and practical implementation examples.

Installation

  • Install the SDK

    npm i thirdweb

  • Get Your Client ID

    Log in to the thirdweb dashboard. Navigate to the Settings page and create an API key to get your Client ID. You'll need your Client ID to interact with the Universal Bridge.

  • Initialize the Client

    import { createThirdwebClient } from "thirdweb";
     
    const client = createThirdwebClient({
      clientId: "your_client_id",
    });

  • Prepare a Swap

    Get a quote and prepare your first cross-chain swap:

    import { Bridge, NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb";
     
    const prepared = await Bridge.Buy.prepare({
      originChainId: 1,
      originTokenAddress: NATIVE_TOKEN_ADDRESS,
      destinationChainId: 137,
      destinationTokenAddress: NATIVE_TOKEN_ADDRESS,
      amount: toWei("0.1"),
      sender: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
      receiver: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
      client,
    });

Recipes

Use the Buy module to purchase tokens on any supported chain using tokens from another chain:

import { Bridge, NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb";
 
// Step 1: Get a quote for the purchase
const quote = await Bridge.Buy.quote({
  originChainId: 1, // Ethereum
  originTokenAddress: NATIVE_TOKEN_ADDRESS, // ETH
  destinationChainId: 137, // Polygon
  destinationTokenAddress: NATIVE_TOKEN_ADDRESS, // MATIC
  amount: toWei("0.1"), // 0.1 MATIC
  client,
});
 
console.log(`Need ${quote.originAmount} origin tokens`);
 
// Step 2: Prepare a Swap
const prepared = await Bridge.Buy.prepare({
  originChainId: 1,
  originTokenAddress: NATIVE_TOKEN_ADDRESS,
  destinationChainId: 137,
  destinationTokenAddress: NATIVE_TOKEN_ADDRESS,
  amount: toWei("0.1"),
  sender: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
  receiver: "0x2a4f24F935Eb178e3e7BA9B53A5Ee6d8407C0709",
  client,
});
 
// Step 3: Execute transactions
for (const step of prepared.steps) {
  for (const transaction of step.transactions) {
    const result = await sendTransaction({
      transaction,
      account: wallet.account,
    });
    console.log("Transaction sent:", result.transactionHash);
  }
}

Best for: NFT purchases, token swaps across chains, DeFi interactions

Transaction Status Tracking

Monitor the progress of your Universal Bridge transactions:

import { Bridge } from "thirdweb";
 
// Check transaction status
const status = await Bridge.status({
  transactionHash:
    "0x5959b9321ec581640db531b80bac53cbd968f3d34fc6cb1d5f4ea75f26df2ad7",
  chainId: 137,
  client,
});
 
switch (status.status) {
  case "COMPLETED":
    console.log("Bridge completed!");
    console.log("Final amount:", status.destinationAmount);
    break;
  case "PENDING":
    console.log("Still processing...");
    break;
  case "FAILED":
    console.log("Transaction failed");
    break;
  case "NOT_FOUND":
    console.log("Transaction not found");
    break;
}

Error Handling

Universal Bridge functions throw ApiError for failed requests:

import { Bridge, ApiError } from "thirdweb";
 
try {
  const quote = await Bridge.Buy.quote({
    originChainId: 1,
    originTokenAddress: NATIVE_TOKEN_ADDRESS,
    destinationChainId: 999999, // Invalid chain
    destinationTokenAddress: NATIVE_TOKEN_ADDRESS,
    amount: toWei("0.1"),
    client,
  });
} catch (error) {
  if (error instanceof ApiError) {
    console.log("API Error:", error.message);
    console.log("Status Code:", error.statusCode);
    console.log("Correlation ID:", error.correlationId);
  }
}

Next Steps