> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  `useInitiateFiatRamp` requires **`@getpara/react-sdk` 3.18 or later**.
</Info>

<Note>
  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](/v3/react/guides/customization/developer-portal-payments) (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.
</Note>

## Basic usage

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

```tsx theme={null}
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>
  );
}
```

<Warning>
  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.
</Warning>

## Choosing the destination wallet

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

<Tabs>
  <Tab title="Active wallet (default)">
    Omit the wallet fields — the on-ramp funds whichever wallet is currently active.

    ```tsx theme={null}
    initiateFiatRamp({
      symbol: "ETH",
      chainId: "1", // Ethereum mainnet
      fiatQuantity: 50,
    });
    ```
  </Tab>

  <Tab title="A specific Para wallet">
    Pass `walletId` to fund a specific Para (or connected) wallet. Its ecosystem is looked up for you.

    ```tsx theme={null}
    initiateFiatRamp({
      walletId: wallet.id,
      symbol: "USDC",
      chainId: "8453", // Base
      fiatQuantity: 25,
    });
    ```
  </Tab>

  <Tab title="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.

    ```tsx theme={null}
    initiateFiatRamp({
      externalWalletAddress: "0x1234...abcd",
      walletType: "EVM",
      symbol: "USDC",
      chainId: "8453",
      fiatQuantity: 25,
    });
    ```
  </Tab>
</Tabs>

## 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:

```tsx theme={null}
initiateFiatRamp({ symbol: "USDC", chainId: "8453", fiatQuantity: 25, provider: OnRampProvider.MOONPAY });
```

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

```tsx theme={null}
// 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](/v3/react/guides/customization/developer-portal-payments#provider-asset-support)):

```tsx theme={null}
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:

```tsx theme={null}
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).                          |

<Note>
  `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`](/v3/references/core/initiateonramptransaction) for the underlying core method.
</Note>