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

Implementation Guides

SDK Reference

Recommended: JavaScript SDK with React Hooks

Summary

How it works

Example

Example with Crypto.com

Example with MoonPay

Getting QR Codes for Onramp

Accessing Provider Information

Provider Object Structure

Recommended: JavaScript SDK with React Hooks

​Summary

​How it works

​Example

​Example with Crypto.com

​Example with MoonPay

​Getting QR Codes for Onramp

​Accessing Provider Information

​Provider Object Structure

Summary

How it works

Example

Example with Crypto.com

Example with MoonPay

Getting QR Codes for Onramp

Accessing Provider Information

Provider Object Structure