thirdwebDocs

Fiat-to-Crypto Onramp Integration

Learn how to integrate seamless fiat-to-crypto onramps using Payments. This guide covers integration with Stripe, Coinbase, and Transak providers, enabling your users to purchase crypto directly with fiat currency.

Payments's onramp functionality provides a unified interface across multiple providers, automatic routing to the best rates, and comprehensive status tracking.

  • Install the SDK

    npm i thirdweb

  • Setup and Configuration

    Configure your client and understand the available onramp providers:

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

  • Basic Onramp Integration

    Create a basic onramp experience for your users:

    import { Bridge, NATIVE_TOKEN_ADDRESS, toWei } from "thirdweb";
     
    const onrampSession = await Bridge.Onramp.prepare({
      client,
      onramp: "stripe",
      chainId: 1, // Ethereum
      tokenAddress: NATIVE_TOKEN_ADDRESS, // ETH
      receiver: userAddress,
      amount: toWei("0.1"), // 0.1 ETH
      currency: "USD",
      country: "US", // User's country - important for compliance
    });
     
    window.open(onrampSession.link);

  • Status Monitoring

    Monitor onramp transactions and handle completion:

    import { Bridge } from "thirdweb";
     
    // Monitor onramp status
    const status = await Bridge.Onramp.status({
      sessionId,
      client,
    });
     
    switch (status.status) {
      case "COMPLETED":
        console.log("Onramp completed successfully!");
        console.log("Transaction hash:", status.transactionHash);
        console.log("Amount received:", status.destinationAmount);
        // Update your UI to show success
        break;
     
      case "PENDING":
        console.log("Onramp in progress...");
        // Show loading state to user
        setTimeout(() => monitorOnrampStatus(sessionId), 10000); // Check again in 10s
        break;
     
      case "FAILED":
        console.log("Onramp failed:", status.error);
        // Show error message to user
        break;
     
      case "CANCELLED":
        console.log("Onramp was cancelled by user");
        // Handle cancellation
        break;
     
      default:
        console.log("Unknown status:", status.status);
    }

Next Steps