Onramp modal

Privy provides a useAddFunds hook in @privy-io/react-auth that opens the onramp modal, a single flow covering every configured funding method. Your app can use this hook to let authenticated users fund a destination wallet with fiat, crypto, or both. When both methods are configured, Privy shows a method picker before starting the selected flow. When only one method is configured, Privy starts that flow directly.

useAddFunds is currently only available on React. For React Native apps, use useFundWallet or useFundSolanaWallet from @privy-io/expo/ui for card-based fiat onramp flows. For crypto deposits, use the crypto deposits API.

Prerequisites

Enable card and bank funding methods on the Account Funding page in the Privy Dashboard. See the configuration guide for details.

Access the hook

Import and initialize useAddFunds:

import {useAddFunds} from '@privy-io/react-auth';

const {addFunds} = useAddFunds();

Call addFunds with a destination wallet and at least one funding method config.

await addFunds({
  destination: {
    address: '<wallet_address>',
    chain: 'eip155:8453',
    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  },
  fiat: {
    source: {
      assets: ['usd', 'eur'],
      defaultAsset: 'usd'
    },
    environment: 'production',
    defaultAmount: '50'
  },
  crypto: {
    slippageBps: 100
  }
});

destination.chain accepts a CAIP-2 identifier (for example, eip155:8453 for Base or solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp for Solana mainnet). destination.asset is the token address on that destination chain.

Parameters

addFunds accepts an object with the following fields:

Parameter	Type	Description
`destination.address`	`string`	Required. Wallet address to receive funds.
`destination.chain`	`${string}:${string}`	Required. Destination chain in CAIP-2 format.
`destination.asset`	`string`	Required. Token address on the destination chain (for example, Base USDC: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`).
`fiat`	`AddFundsFiatOptions`	Required unless `crypto` is provided. Enables fiat funding with the `useFiatOnramp` flow.
`fiat.source.assets`	`SupportedFiatCurrency[]`	Optional. The list of fiat source currencies your app allows. Defaults to all supported currencies. When provided, must be non-empty.
`fiat.source.defaultAsset`	`SupportedFiatCurrency`	Optional. The source currency selected when the flow opens. Falls back to the locale currency, then to the first item in `fiat.source.assets`.
`fiat.environment`	`'sandbox' \| 'production'`	Optional. Onramp environment for provider APIs.
`fiat.defaultAmount`	`string`	Optional. Initial fiat amount displayed in the amount step.
`crypto`	`AddFundsCryptoOptions`	Required unless `fiat` is provided. Enables crypto funding with a deposit address flow.
`crypto.refundAddress`	`string`	Optional. Refund address used if a crypto deposit cannot be completed.
`crypto.slippageBps`	`number`	Optional. Maximum slippage tolerance for the crypto deposit route, in basis points. If omitted, Privy uses the default for the route.

At least one of fiat or crypto must be provided. Provide both to show the method picker.

Return value

addFunds returns a Promise with one of the following results:

Result	Meaning
`{method: 'fiat', status: 'submitted'}`	The user completed the provider flow, then exited before final confirmation finished in Privy.
`{method: 'fiat', status: 'confirmed'}`	The fiat flow reached provider confirmation, and the user completed the success step.
`{method: 'crypto', status: 'completed'}`	The crypto deposit flow completed successfully.

Error handling

addFunds rejects on invalid configuration or incomplete flows. Common error cases include:

destination.address, destination.chain, or destination.asset is missing
neither fiat nor crypto is provided
fiat.source.assets is empty
the user is not authenticated
another add funds flow is already in progress
the user cancels the flow
provider session, quote, or deposit address requests fail

Your app should wrap calls in try/catch and show clear UI feedback.

Complete example

import {useState} from 'react';
import {useAddFunds} from '@privy-io/react-auth';

export const AddFundsButton = ({address}: {address: string}) => {
  const {addFunds} = useAddFunds();
  const [isLoading, setIsLoading] = useState(false);

  const onAddFunds = async () => {
    setIsLoading(true);

    try {
      const result = await addFunds({
        destination: {
          address,
          chain: 'eip155:8453',
          asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        },
        fiat: {
          source: {
            assets: ['usd', 'eur', 'gbp'],
            defaultAsset: 'usd'
          },
          environment: 'production',
          defaultAmount: '50'
        },
        crypto: {
          slippageBps: 100
        }
      });

      if (result.method === 'fiat') {
        // Handle submitted or confirmed fiat purchases.
      }

      if (result.method === 'crypto') {
        // Handle completed crypto deposits.
      }
    } catch (error) {
      // Show retry UI or an error banner.
      console.error(error);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <button type="button" onClick={onAddFunds} disabled={isLoading}>
      {isLoading ? 'Starting funding…' : 'Add funds'}
    </button>
  );
};

Fiat-to-crypto onramps

Fund wallets with fiat via card, Apple Pay, or Google Pay.

Crypto deposits

Fund wallets by letting users transfer crypto from another wallet.

Funding

Deposits

Payouts

Prerequisites

Access the hook

Parameters

Return value

Error handling

Complete example

Fiat-to-crypto onramps

Crypto deposits

​Prerequisites

​Access the hook

​Start an onramp modal flow

​Parameters

​Return value

​Error handling

​Complete example

​Related

Fiat-to-crypto onramps

Crypto deposits

Prerequisites

Access the hook

Start an onramp modal flow

Parameters

Return value

Error handling

Complete example

Related