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

# Set up the consumer onramp modal

> Open the consumer onramp modal with useDepositFunds in React or useFundWallet in React Native

**React**

Privy provides a `useDepositFunds` hook in `@privy-io/react-auth` that opens the [consumer onramp modal](https://docs.privy.io/wallets/funding/consumer-onramp-modal/overview.md).

Your app can use this hook to let authenticated users fund a destination wallet with fiat, crypto, or both. A crypto-only call opens the crypto deposit flow directly. A call that includes fiat shows a method picker first.

## Prerequisites

For fiat, enable card and bank funding methods on the [Account Funding](https://dashboard.privy.io/apps?page=funding) page. See the [deposit configuration guide](https://docs.privy.io/financial-flows/deposits/configuration.md).

For crypto, enable app-pays gas sponsorship as described in [crypto deposit setup](https://docs.privy.io/wallets/funding/crypto-deposits/setup.md). Crypto deposits require a Privy wallet. The hook builds the [create-deposit-account](https://docs.privy.io/wallets/funding/crypto-deposits/create-deposit-account.md) request and signs it with the user's signer.

The [Stripe Embedded Components onramp](https://docs.privy.io/wallets/funding/consumer-onramp-modal/overview.md#stripe-embedded-components-onramp) requires `@privy-io/react-auth` version **3.33.1** or later. Install the `@stripe/crypto` package as a required dependency:

```bash theme={"system"}
pnpm install @stripe/crypto
```

## Access the hook

Import and initialize `useDepositFunds`:

```tsx {skip-check} theme={"system"}
import {useDepositFunds} from '@privy-io/react-auth';

const {depositFunds} = useDepositFunds();
```

## Start a deposit flow

Call `depositFunds` with a destination and at least one funding method.

```tsx {skip-check} theme={"system"}
await depositFunds({
  destination: {
    asset: 'pathusd',
    chain: 'tempo'
  },
  crypto: {
    source: {
      mode: 'all'
    },
    depositAddressStrategy: 'prefer_destination'
  }
});
```

The crypto-only call opens the crypto deposit flow. The user picks a source token and network. Privy then creates a [deposit account](https://docs.privy.io/wallets/funding/crypto-deposits/create-deposit-account.md) and shows the address with an indicative quote. This example uses the destination wallet's own address as the deposit address where possible. Omit `depositAddressStrategy` to use a separate source wallet.

> [!NOTE]
>
> `destination.chain` and `destination.asset` accept aliases or raw identifiers. Omit
> `destination.wallet` to use the user's first embedded wallet on that chain.

Pass both `fiat` and `crypto` to show a method picker:

```tsx {skip-check} theme={"system"}
await depositFunds({
  destination: {
    asset: 'usdc',
    chain: 'tempo'
  },
  fiat: {
    source: {
      assets: ['usd', 'eur'],
      defaultAsset: 'usd'
    },
    environment: 'production',
    defaultAmount: '50'
  },
  crypto: {
    source: {
      mode: 'all'
    }
  }
});
```

## Parameters

`depositFunds` accepts an object with the following fields:

**destination** `object` *required*

Wallet and asset that receive the funds.

**properties**

**destination.asset** `string` *required*

Asset alias or token contract address, such as `usdc` or
`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.

**destination.chain** `string` *required*

Chain alias or CAIP-2 identifier, such as `base` or `eip155:8453`. Must match the destination wallet's `chain_type` for crypto deposits.

**destination.wallet** `string`

Privy wallet ID or linked wallet address. When omitted, Privy uses the user's first embedded
wallet on `destination.chain`. Crypto deposits require a Privy wallet. Fiat needs a resolvable
address.

**crypto** `object`

Enables the crypto deposit flow. Required unless `fiat` is provided. Pass `{source: {mode:
      'all'}}` to accept every supported source.

**properties**

**crypto.source** `object`

Assets the modal lets the user send. Defaults to `{mode: 'all'}`.

**properties**

**crypto.source.mode** `'all' | 'include' | 'exclude'` *required*

`include` accepts only the listed assets. `exclude` accepts all except the listed assets.
`all` accepts every supported source.

**crypto.source.values** `object[]`

Asset specs for `include` and `exclude`. Omit when `mode` is `all`.

**properties**

**crypto.source.values.asset** `string`

Asset alias or token contract address, such as `usdc` or
`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.

**crypto.source.values.chain** `string`

Chain alias or CAIP-2 identifier, such as `base` or `eip155:8453`. Omit to match every supported chain for that asset.

**crypto.slippageBps** `number`

Maximum slippage tolerance for the deposit route, in basis points. If omitted, Privy uses the
default for the route.

**crypto.depositAddressStrategy** `'dedicated' | 'prefer_destination' | 'require_destination'`

Where the crypto deposit address lives. Defaults to `dedicated`, which always uses a separate
source wallet. Use `prefer_destination` to use the destination wallet's own address for its
chain family, or a separate source wallet if the destination was exported. Use
`require_destination` to fail instead when the destination was exported. Using the destination
wallet detaches other automations attached to it. See [where deposit addresses
live](https://docs.privy.io/wallets/funding/crypto-deposits/overview.md#where-deposit-addresses-live) and [deposit
address
behavior](https://docs.privy.io/wallets/funding/crypto-deposits/create-deposit-account.md#deposit-address-behavior).

**fiat** `object`

Enables fiat funding with the card and bank onramp flow. Required unless `crypto` is provided.

**properties**

**fiat.source.assets** `SupportedFiatCurrency[]`

Fiat source currencies your app allows. Defaults to all [supported
currencies](https://docs.privy.io/wallets/funding/consumer-onramp-modal/overview.md#supported-fiat-currencies). When
provided, must be non-empty.

**fiat.source.defaultAsset** `SupportedFiatCurrency`

Source currency selected when the flow opens. If omitted or set to a supported currency
outside `fiat.source.assets`, uses the locale currency if allowed, otherwise the first allowed
currency.

**fiat.environment** `'sandbox' | 'production'`

Onramp environment for provider APIs.

**fiat.defaultAmount** `string`

Initial fiat amount displayed in the amount step.

**fiat.preferredProvider** `'meld' | 'moonpay' | 'coinbase' | 'stripe'`

Onramp provider to prefer when Privy selects the initial quote. If the provider has no quote
for the selected payment method, Privy uses its first quote. If no quote matches, Privy
ignores this option.

At least one of `fiat` or `crypto` must be provided.

## Return value

`depositFunds` returns a Promise with one of the following results:

| Result | Meaning |
| - | - |
| `{method: 'fiat', status: 'submitted'}` | The user completed the provider flow, then exited before Privy finished confirmation. |
| `{method: 'fiat', status: 'confirmed'}` | The fiat flow reached provider confirmation, and the user completed the success step. |
| `{method: 'crypto', status: 'address_shown'}` | The user viewed the crypto deposit address and closed the modal. |
| `{method: 'crypto', status: 'completed'}` | Privy detected the crypto deposit and finished the flow. |

## Error handling

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

* the call omits `destination.chain` or `destination.asset`
* the call omits both `fiat` and `crypto`
* the call sends an empty `fiat.source.assets` list
* `fiat.source.assets` or `fiat.source.defaultAsset` contains an unsupported currency code (rejects with `<code> is an unsupported currency` in React SDK 3.51.3 and later)
* the user has no authenticated session
* `destination.wallet` is not a Privy wallet on a crypto call
* another funding flow is already in progress
* the user cancels the flow
* app-pays gas sponsorship is not enabled
* no source tokens match `crypto.source`
* `crypto.depositAddressStrategy` is `require_destination` and the destination wallet was exported
* provider session, quote, or deposit account requests fail

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

## Complete example

```tsx {skip-check} theme={"system"}
import {useState} from 'react';
import {useDepositFunds} from '@privy-io/react-auth';

export const DepositFundsButton = ({walletId}: {walletId: string}) => {
  const {depositFunds} = useDepositFunds();
  const [isLoading, setIsLoading] = useState(false);

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

    try {
      const result = await depositFunds({
        destination: {
          wallet: walletId,
          asset: 'usdc',
          chain: 'tempo'
        },
        fiat: {
          source: {
            assets: ['usd', 'eur', 'gbp'],
            defaultAsset: 'usd'
          },
          environment: 'production',
          defaultAmount: '50'
        },
        crypto: {
          source: {
            mode: 'all'
          }
        }
      });

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

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

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

## Test in sandbox mode

Pass `fiat.environment: 'sandbox'` to `depositFunds` to run the flow against Stripe's test environment. No real funds move, and you can complete an end-to-end purchase with the test values below.

| Field | Test value |
| - | - |
| Onramp amount | Less than \$200 |
| Phone number | A US or EU phone number |
| Phone verification code | `000000` |
| Card number | `4242 4242 4242 4242` |
| CVC | Any three digits |
| Expiry date | Any date in the future |

Set `destination.chain` to a mainnet chain. Stripe's onramp does not support testnets, so testnet chains fail even in sandbox mode.

| Chain | Mainnet CAIP-2 |
| - | - |
| Tempo | `eip155:4217` |
| Base | `eip155:8453` |
| Solana | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` |
| Ethereum | `eip155:1` |
| Arbitrum | `eip155:42161` |
| Polygon | `eip155:137` |

**React Native**

> [!TIP]
>
> Make sure `<PrivyElements />` is mounted first, by following [this
> guide](https://docs.privy.io/authentication/user-authentication/ui-component.md).

Privy provides `useFundWallet` and `useFundSolanaWallet` hooks in `@privy-io/expo/ui` that start a card-based fiat onramp flow in the Privy modal on React Native.

Your app can use these hooks to let authenticated users buy crypto via MoonPay or Coinbase. `useFundWallet` funds EVM wallets, and `useFundSolanaWallet` funds Solana wallets.

## Start a fiat onramp flow

> [tab] EVM
>
> Use `useFundWallet` to fund an EVM wallet. Call `fundWallet` with the destination address, chain, amount, and optional asset configuration.
>
> ```tsx theme={"system"}
> import {useFundWallet} from '@privy-io/expo/ui';
> import {base} from 'viem/chains';
>
> const {fundWallet} = useFundWallet();
>
> await fundWallet({
>   address: '<wallet_address>',
>   chain: base,
>   amount: '50',
>   asset: 'USDC'
> });
> ```
>
> ### Parameters
>
> | Parameter | Type | Description |
> | - | - | - |
> | `address` | `string` | Required. The destination wallet address to fund. |
> | `chain` | [`Chain`](https://viem.sh/docs/chains/introduction) | Optional. A `viem/chains` object for the network on which to fund. Defaults to the chain configured in the Dashboard. |
> | `asset` | `'native-currency'` \| `'USDC'` \| `{tokenAddress: string}` | Optional. The asset to fund with. Defaults to `'native-currency'`. |
> | `amount` | `string` | Required if `asset` is set, optional otherwise. The amount to fund as a decimal string. |
> | `defaultPaymentMethod` | `'card'` \| `'exchange'` | Optional. Skip payment method selection and trigger the specified flow directly. |
> | `card.preferredProvider` | `'coinbase'` \| `'moonpay'` | Optional. The preferred card onramp provider. |
> | `moonpay.useSandbox` | `boolean` | Optional. Use MoonPay sandbox mode for testing. |
> | `moonpay.uiConfig.accentColor` | `string` | Optional. Accent color for the MoonPay UI (hex value). |
> | `moonpay.uiConfig.theme` | `'light'` \| `'dark'` | Optional. Theme for the MoonPay UI. |

> [tab] Solana
>
> Use `useFundSolanaWallet` to fund a Solana wallet. Call `fundWallet` with the destination address, cluster, and amount.
>
> ```tsx theme={"system"}
> import {useFundSolanaWallet} from '@privy-io/expo/ui';
>
> const {fundWallet} = useFundSolanaWallet();
>
> await fundWallet({
>   address: '<wallet_address>',
>   cluster: {name: 'mainnet-beta'},
>   amount: '1',
>   asset: 'native-currency'
> });
> ```
>
> ### Parameters
>
> | Parameter | Type | Description |
> | - | - | - |
> | `address` | `string` | Required. The destination Solana wallet address to fund. |
> | `cluster` | `SolanaCluster` | Optional. The Solana cluster to fund on. Defaults to `mainnet-beta`. |
> | `asset` | `'native-currency'` \| `'USDC'` | Optional. The asset to fund with. Defaults to `'native-currency'`. |
> | `amount` | `string` | Required if `asset` is set, optional otherwise. The amount to fund as a decimal string. |
> | `defaultPaymentMethod` | `'card'` \| `'exchange'` | Optional. Skip payment method selection and trigger the specified flow directly. |
> | `card.preferredProvider` | `'coinbase'` \| `'moonpay'` | Optional. The preferred card onramp provider. |
> | `moonpay.useSandbox` | `boolean` | Optional. Use MoonPay sandbox mode for testing. |
> | `moonpay.uiConfig.accentColor` | `string` | Optional. Accent color for the MoonPay UI (hex value). |
> | `moonpay.uiConfig.theme` | `'light'` \| `'dark'` | Optional. Theme for the MoonPay UI. |

> [!NOTE]
>
> The React Native fiat onramp supports MoonPay and Coinbase as card providers. Stripe, Meld, and
> the multi-provider routing available in the React `useDepositFunds` flow are not yet supported on
> React Native.

## Related

> [card] [Crypto deposits](https://docs.privy.io/wallets/funding/crypto-deposits/overview.md)
>
> Persistent deposit addresses, setup, and headless React or React Native.
