Build a Custom Fiat Experience
Learn how to enable your users to purchase your application’s token with any fiat payment method with our headless flow.
In this guide, we'll show you how to purchase 0.01 Base ETH from USD in Typescript.
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 Connect SDK.
Buying with fiat can require one or two steps depending on your destination token:
If the destination token can be bought directly with fiat, your users can onramp directly to their destination token.
If the destination token can not be bought directly with fiat, your users will need to onramp to an intermediate token, then convert the onramp token to the destination token.
For example, when Buying Base ETH:
- Users will receive Avalance AVAX ( native token ) in exchange for USD
- Users will be prompted to convert Avalanche AVAX to Base ETH

This process requires your user's wallet address. Refer to this guide to learn how to connect a wallet.
The quote
object contains detailed transaction information including the estimated time, processing fees, amount of fiat currency required, and more that you can display in your application.
The quote
object contains quote.onRampToken
and quote.toToken
objects containing intermediate and detination token information.
If quote.onRampToken
is not the same as quote.toToken
, then your users will need to onramp to intermediary token before arriving at their destination token.
You can use isSwapRequiredPostOnramp
to check this
Once you have a quote
from getBuyWithFiatQuote
, you can open a new tab with quote.onRampLink
to show the onramp experience. This onramp experience handles all regulatory requirements, know your customer (KYC) verifications, and sanctions screening.
After they've KYC'd (if required), customers have the option of saving payment methods, KYC data, and wallet information in the onramp, which makes the returning onramp experience much faster.
Your users will be able to purchase the quote.onRampToken
with the specified fiat currency.
When you open the quote.onRampLink
in a new tab, you can begin polling for the onramp transaction status in your app by calling getBuyWithFiatStatus
.
getBuyWithFiatStatus
requires an intentId
which you can get from quote
object.
getBuyWithFiatStatus
requires passing an intentId
which you can get from quote
object.
There are a number of transactions statuses:
This step is only relevant when a crypto-to-crypto purchase is required after perfmorming an onramp to an intermediary token.
In this case, you can use getPostOnRampQuote
to get a quote to convert the intermediary token to the destination token.
Executing Buy With Crypto may involve either a single step or 2 steps
If your source token is an ERC-20 token, an approval step is required before executing the Buy With Crypto transaction.
You can check if approval is required by checking quote.approval
Once you've initiated your Buy With Crypto transaction, you'll want to track the status. You can notify users throughout this journey by checking for the following statuses:
If you are using React, we provide Hooks for each of the functions mentioned above: