Fiat Ramps

Launch a fiat on-ramp (or off-ramp) from your own UI with the useInitiateFiatRamp hook.

The Para Modal’s built-in Buy/Withdraw flow lets users on- and off-ramp without any code. If you’d rather drive the ramp from your own UI — a “Buy” button, a funding CTA, a checkout step — use the useInitiateFiatRamp hook to launch the same flow with the amount, asset, and provider you choose.

useInitiateFiatRamp requires @getpara/react-sdk 3.18 or later.

Which providers, assets, and networks are available — and their API keys — are configured in the Developer Portal, not in code. Set those up first: see Set Up Fiat Onramps (and the Coinbase-specific steps on that page). The hook only launches the flow; it can’t offer a provider or asset you haven’t enabled.

Basic usage

useInitiateFiatRamp returns a mutation-style handle. Call initiateFiatRamp(params) from a click handler to launch the flow:

import { useInitiateFiatRamp, OnRampProvider } from "@getpara/react-sdk";

function BuyButton() {
  const { initiateFiatRamp, isPending } = useInitiateFiatRamp();

  return (
    <button
      disabled={isPending}
      onClick={() =>
        initiateFiatRamp({
          symbol: "USDC",
          chainId: "8453", // Base
          fiatQuantity: 25,
          provider: OnRampProvider.STRIPE,
        })
      }
    >
      Buy $25 USDC
    </button>
  );
}

Providers open in a popup, so initiateFiatRamp must be called within the user’s click gesture (as above) — calling it later, e.g. from a useEffect or a timeout, will be blocked by the browser’s popup blocker.

Choosing the destination wallet

By default the ramp targets the user’s active wallet. Pass a wallet explicitly to target a different one.

Active wallet (default)

Omit the wallet fields — the on-ramp funds whichever wallet is currently active.

initiateFiatRamp({
  symbol: "ETH",
  chainId: "1", // Ethereum mainnet
  fiatQuantity: 50,
});

A specific Para wallet

Pass walletId to fund a specific Para (or connected) wallet. Its ecosystem is looked up for you.

initiateFiatRamp({
  walletId: wallet.id,
  symbol: "USDC",
  chainId: "8453", // Base
  fiatQuantity: 25,
});

An external address

Pass a raw externalWalletAddress to fund an address that isn’t a Para wallet. walletType is required here so the asset resolves in the right ecosystem.

initiateFiatRamp({
  externalWalletAddress: "0x1234...abcd",
  walletType: "EVM",
  symbol: "USDC",
  chainId: "8453",
  fiatQuantity: 25,
});

Choosing the provider

Omit provider to let Para pick the first enabled provider that serves the asset + amount, or name one explicitly. Use the OnRampProvider enum:

initiateFiatRamp({ symbol: "USDC", chainId: "8453", fiatQuantity: 25, provider: OnRampProvider.MOONPAY });

For Coinbase, pass provider: OnRampProvider.COINBASE and pick the surface with method:

// Coinbase hosted widget
initiateFiatRamp({
  symbol: "USDC",
  chainId: "8453",
  fiatQuantity: 25,
  provider: OnRampProvider.COINBASE,
  method: "WIDGET",
});

// Coinbase inline Apple Pay (web only, US-only guest checkout)
initiateFiatRamp({
  symbol: "USDC",
  chainId: "8453",
  fiatQuantity: 25,
  provider: OnRampProvider.COINBASE,
  method: "APPLE_PAY",
});

Selling (off-ramp)

Pass type: OnRampPurchaseType.SELL to launch a withdrawal instead of a purchase (for providers that support selling — see provider support):

import { useInitiateFiatRamp, OnRampPurchaseType } from "@getpara/react-sdk";

initiateFiatRamp({
  symbol: "USDC",
  chainId: "8453",
  fiatQuantity: 25,
  type: OnRampPurchaseType.SELL,
});

Handling the result

Use initiateFiatRampAsync (or read data/isPending/error off the hook) to observe what happened. The result’s outcome tells you whether the ramp launched directly or fell back to the modal’s prefilled form:

const { initiateFiatRampAsync } = useInitiateFiatRamp();

const result = await initiateFiatRampAsync({
  symbol: "USDC",
  chainId: "8453",
  fiatQuantity: 25,
});

if (result.outcome === "direct") {
  // Everything was valid — the provider widget / Apple Pay launched.
} else {
  // Something was missing or out of range (result.reason). The modal opened its
  // Buy form prefilled with what you passed, so the user can finish there — or you
  // can handle result.reason yourself (e.g. show your own "minimum is $X" message).
  console.log(result.reason);
}

Parameters

Field	Type	Notes
symbol	string	Asset ticker, e.g. "USDC", "ETH". Resolved against your enabled catalog.
chainId	string	Narrows a symbol to a network (e.g. EVM chain id "8453" for Base). Needed for multi-network assets.
contractAddress	string	Narrows a symbol to a specific token contract.
fiatQuantity	string | number	USD amount. If omitted or out of range, the prefilled form opens instead of launching directly.
provider	OnRampProvider	Preferred provider. Omit to auto-select. For Coinbase, use COINBASE + method.
method	"WIDGET" | "APPLE_PAY"	Coinbase surface: hosted widget or inline Apple Pay.
type	OnRampPurchaseType	BUY (default) or SELL.
walletId	string	Target a specific Para/connected wallet. Defaults to the active wallet.
externalWalletAddress	string	Target a raw address (pass walletType too).
walletType	TWalletType	Ecosystem of the target — required with externalWalletAddress.
testMode	boolean	Force test mode (widget providers only; defaults to the environment/config).

useInitiateFiatRamp is the low-level entry point behind the Para Modal’s own Buy button, so it works with the same Developer Portal configuration and the same in-modal Buy/Withdraw UI. See initiateOnRampTransaction for the underlying core method.