useOnramp

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Summary

This hook can be used to trigger an Onramp UI so that users can immediately buy crypto with fiat.

How it works

After setting up your onramp provider, you can use the useOnramp to prompt your user to fund their wallet.

For other funding methods, see usePayWithDynamic for unified payment flow.

The following attributes are exposed:

Method	Type	Description
enabled	boolean	Whether some onramp method is enabled and ready to use.
providers	OnrampOption[]	Array of available onramp providers with their configuration and URLs
open	(props: { address?: string; token?: string; onrampProvider: OnrampProviders }) => void	Trigger the onramp UI with required onrampProvider attribute and optional address and token attributes, returns a Promise that will resolve once the onramp UI is closed
getOnrampQrCode	(props: { address: string; token: string; onrampProvider: OnrampProviders }) => Promise<string>	Retrieve a QR code URL for the specified onramp provider. Currently supported for Crypto.com only.

Example

Custom onramp button:

import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'

const FundMyWalletButton = () => {
  const { enabled, open } = useOnramp()

  const onClick = () => {
    open({
      onrampProvider: OnrampProviders.Banxa,
      token: 'USDT',
      address: '0x1234567890123456789012345678901234567890',
    }).then(() => window.alert('Success!'))
  }

  return (
    <button onClick={onClick} disabled={!enabled}>
      Buy USDT
    </button>
  )
}

Example with Crypto.com

Crypto.com is currently in limited beta. Please contact support if you’re interested in early access.

import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'

const FundMyWalletButton = () => {
  const { enabled, open } = useOnramp()

  const onClick = () => {
    open({
      onrampProvider: OnrampProviders.CryptoDotCom,
      token: 'ETH',
      address: '0x1234567890123456789012345678901234567890',
    }).then(() => window.alert('Success!'))
  }

  return (
    <button onClick={onClick} disabled={!enabled}>
      Buy ETH with Crypto.com
    </button>
  )
}

Example with MoonPay

import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'

const FundMyWalletButton = () => {
  const { enabled, open } = useOnramp()

  const onClick = () => {
    open({
      onrampProvider: OnrampProviders.MoonPay,
    })
  }

  return (
    <button onClick={onClick} disabled={!enabled}>
      Buy with MoonPay
    </button>
  )
}

Opening MoonPay navigates the Dynamic widget to a token selector screen where the user picks a supported token before being forwarded to MoonPay’s hosted checkout. For a fully headless integration outside the widget, see the MoonPay guide.

Getting QR Codes for Onramp

You can retrieve QR codes for supported onramp providers using the getOnrampQrCode method:

import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'

const OnrampQrCode = () => {
  const { getOnrampQrCode } = useOnramp()
  const [qrCodeUrl, setQrCodeUrl] = React.useState<string | null>(null)

  const fetchQrCode = async () => {
    try {
      const url = await getOnrampQrCode({
        onrampProvider: OnrampProviders.CryptoDotCom,
        token: 'ETH',
        address: '0x1234567890123456789012345678901234567890',
      })
      setQrCodeUrl(url)
    } catch (error) {
      console.error('Failed to fetch QR code:', error)
    }
  }

  return (
    <div>
      <button onClick={fetchQrCode}>Generate QR Code</button>
      {qrCodeUrl && <img src={qrCodeUrl} alt="Onramp QR Code" />}
    </div>
  )
}

Accessing Provider Information

You can access available onramp providers and their configuration for custom UI implementations:

import { useOnramp } from '@dynamic-labs/sdk-react-core'
import { OnrampProviders } from '@dynamic-labs/sdk-api-core'

const ProviderList = () => {
  const { enabled, providers, open } = useOnramp()

  return (
    <div>
      {enabled && (
        <div>
          <h3>Available Providers</h3>
          {providers.map((provider) => (
            <div key={provider.id}>
              <img src={provider.iconUrl} alt={provider.displayName} />
              <h4>{provider.displayName}</h4>
              <p>{provider.description}</p>
              <button onClick={() => {
                open({
                  onrampProvider: provider.id as OnrampProviders,
                  token: 'ETH',
                  address: '0x1234567890123456789012345678901234567890',
                  tokenAmount: 0.1,
                })
              }}>
                Open {provider.displayName}
              </button>
            </div>
          ))}
        </div>
      )}
    </div>
  )
}

Provider Object Structure

Each provider in the providers array contains:

Property	Type	Description
id	string	Unique identifier (e.g., “coinbaseOnramp”, “cryptoDotCom”)
displayName	string	Human-readable name for display
iconUrl	string	URL to the provider’s icon/logo
url	string	Base URL with template parameters
openMode	’iframe’ | ‘popup’	How the provider should be opened
description	string	Optional description of the provider