Leverage Cross-Chain Swaps with Universal Bridge

Learn how to enable your users to swap from any asset to any other with thirdweb's Universal Bridge.

In this guide, we'll show you how to purchase 10 USDC on Optimism in Typescript.


  • Install the Connect SDK

    npm i thirdweb
  • Get Your Client ID

    Log in to the thirdweb dashboard. Click on Create New > Project to get your Client ID. You'll need your Client ID to interact with the Connect SDK.

  • Find available routes

    Before your user can select which tokens they'd like to swap, they'll need to find available routes.

    You can do this using the routes function in our Bridge namespace. You or your users can filter by origin and destination chains and/or tokens. Pagination is also built-in to the function.

    import { Bridge, NATIVE_TOKEN_ADDRESS } from "thirdweb";
    // Get all available routes
    const allRoutes = await Bridge.routes({
    client: thirdwebClient,
    });
    // Filter routes for a specific token or chain
    const filteredRoutes = await Bridge.routes({
    originChainId: 1, // From Ethereum
    originTokenAddress: NATIVE_TOKEN_ADDRESS,
    destinationChainId: 10, // To Optimism
    client: thirdwebClient,
    });
    // Paginate through routes
    const paginatedRoutes = await Bridge.routes({
    limit: 10,
    offset: 0,
    client: thirdwebClient,
    });

    This will return an array of Route objects, which will include information such as symbol, address, and chainId for both the origin and destination tokens.

  • Get a quote

    Once you know which routes are available, you can retrieve a quote to show the user how much they can expect to pay for a given swap.

    In this example, we'll use the Buy.quote function to get a quote for buying 10 USDC on Optimism for Base ETH.

    Quote allows us to get an expected amount before the user has connected their wallet. This quote won't come with executable transactions, and won't be a guaranteed price.

    import { Bridge, NATIVE_TOKEN_ADDRESS } from "thirdweb";
    const buyQuote = await Bridge.Buy.quote({
    originChainId: 8453, // Base
    originTokenAddress: NATIVE_TOKEN_ADDRESS,
    destinationChainId: 10, // Optimism
    destinationTokenAddress:
    "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", // Optimism USDC
    buyAmountWei: 10000000n, // 10 USDC
    client: thirdwebClient,
    });
    console.log(
    `To get ${buyQuote.destinationAmount} wei on destination chain, you need to pay ${buyQuote.originAmount} wei`,
    );

    This will return a Quote object, which will include the originAmount and destinationAmount in wei, along with some more useful information about the predicted quote.

  • Get the prepared transaction

    Now that we know how much the user can expect to pay, we can have them connect their wallet and execute the swap.

    To get a prepared quote, we'll use the Buy.prepare function. The key difference with this function is it requires a sender and receiver to be specified.

    import { Bridge, NATIVE_TOKEN_ADDRESS } from "thirdweb";
    const preparedBuy = await Bridge.Buy.prepare({
    originChainId: 8453, // Base
    originTokenAddress: NATIVE_TOKEN_ADDRESS,
    destinationChainId: 10, // Optimism
    destinationTokenAddress:
    "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", // Optimism USDC
    buyAmountWei: 10000000n, // 10 USDC
    sender: "0x...", // Your user's wallet address
    receiver: "0x...", // Recipient address (can be the same as sender)
    client: thirdwebClient,
    });
    // The prepared quote contains the transactions you need to execute
    console.log(
    `Transactions to execute: ${preparedBuy.transactions.length}`,
    );

    This will return a PreparedQuote object. It will look very similar to the Quote you received in the previous step, but it will include a transactions array. This array will contain the transactions you need to execute to complete the swap.

  • Execute the swap

    To execute the swap, we'll need to send all transactions in the transactions array one after the other.

    import { sendTransaction, waitForReceipt } from "thirdweb";
    const preparedBuy = await Bridge.Buy.prepare({
    originChainId: 8453, // Base
    originTokenAddress: NATIVE_TOKEN_ADDRESS,
    destinationChainId: 10, // Optimism
    destinationTokenAddress: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", // Optimism USDC
    buyAmountWei: 10000000n, // 10 USDC
    sender: "0x...", // Your user's wallet address
    receiver: "0x...", // Recipient address (can be the same as sender)
    client: thirdwebClient,
    });
    };
    for (const transaction of preparedBuy.transactions) {
    const tx = prepareTransaction({
    to: transaction.to as string,
    value: BigInt(transaction.value ?? 0n),
    data: transaction.data,
    chain: defineChain(transaction.chainId),
    client
    });
    const result = await sendAndConfirmTransaction({ transaction: tx, account });
    let swapStatus;
    do {
    swapStatus = await Bridge.status({
    transactionHash: result.transactionHash,
    client,
    });
    } while (swapStatus.status !== "COMPLETED");
    };
  • Getting the swap status

    You'll notice in the previous step we call Bridge.status to get the status of the swap. We can get the status of any past swap using just the transaction hash and chain ID of its origin transaction.

    When sending the transactions in a prepared quote, you must use Bridge.status to get the COMPLETED status before moving on to the next transaction. This is because status waits for both the origin and destination transactions to complete. Waiting for the origin transaction receipt is not sufficient since the funds might not have arrived on the destination chain yet.

    The status will also return all transactions (origin and destination) involved in the swap.

    import { Bridge } from "thirdweb";
    // Check the status of a bridge transaction
    const bridgeStatus = await Bridge.status({
    transactionHash:
    "0xe199ef82a0b6215221536e18ec512813c1aa10b4f5ed0d4dfdfcd703578da56d",
    chainId: 8453, // The chain ID where the transaction was initiated
    client: thirdwebClient,
    });
    // The status will be one of: "COMPLETED", "PENDING", "FAILED", or "NOT_FOUND"
    if (bridgeStatus.status === "completed") {
    console.log(`
    Bridge completed!
    Sent: ${bridgeStatus.originAmount} wei on chain ${bridgeStatus.originChainId}
    Received: ${bridgeStatus.destinationAmount} wei on chain ${bridgeStatus.destinationChainId}
    `);
    } else if (bridgeStatus.status === "pending") {
    console.log("Bridge transaction is still pending...");
    } else {
    console.log("Bridge transaction failed");
    }