Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt

Use this file to discover all available pages before exploring further.

An example React On-Ramp integration can be found on our Github here.

​
Install

To integrate MoonPay in your React app, you can use MoonPay’s moonpay-react package. 
npm install @moonpay/moonpay-react
Once you’ve installed this, you’re ready to set up your project to integrate the MoonPay widget.

​
Add the provider

The first thing to do is add the MoonPay provider to the root of your React application. This will provide context throughout your app to allow you to use the MoonPay widget components.
setup.ts
import { MoonPayProvider } from "@moonpay/moonpay-react";

export default function App() {
  return (
    <MoonPayProvider apiKey="pk_test_123" debug>
      <Home />
    </MoonPayProvider>
  );
}
The provider abstracts the complexity of loading the SDK into your app. Now, use your desired component, passing variant and any parameters related to Buy, Sell, or Swap as props. The environment is set based on which API key you use. Use the following keys:
  • Sandbox environment: pk_test...
  • Production environment: pk_live...
import { MoonPayBuyWidget } from '@moonpay/moonpay-react';

export default function Home() {
  return (
    {/*... other components */}
    <MoonPayBuyWidget
      variant="overlay"
      baseCurrencyCode="usd"
      baseCurrencyAmount="100"
      defaultCurrencyCode="eth"
      onLogin={async () => console.log("Customer logged in!")}
      visible
    />
    {/* ... other components*/}
  )
}

​
For Next.js

For Next.js, it’s recommended to dynamically import the MoonPay components as shown below. This ensures efficient loading of the components and prevents server-side rendering (SSR). Otherwise you will see an error message: ReferenceError: window is not defined 
import dynamic from "next/dynamic";

const MoonPayProvider = dynamic(
  () => import("@moonpay/moonpay-react").then((mod) => mod.MoonPayProvider),
  { ssr: false },
);

const MoonPayBuyWidget = dynamic(
  () => import("@moonpay/moonpay-react").then((mod) => mod.MoonPayBuyWidget),
  { ssr: false },
);

​
Variants

​
Embedded

The embedded variant shows the MoonPay widget will show as part of your page, wherever you place the component. This option lets you fine-tune the placement of the widget and allows you to integrate it into a specific part of your layout. This can minimize context switching for the user.

​
Overlay

The overlay variant shows the widget as an iframe on top of your website. This option directs the user’s attention towards completing their purchase while keeping them on your website.

​
New tab

The newTab variant opens the widget in a new browser tab. This option lets the user complete their purchase in a full-screen experience. When using this option, we recommend you tell the user they’ll be taken to MoonPay in a new tab. This provides guidance to the user that this is intended and part of the purchase flow.

​
New window

The newWindow variant opens the widget in a new browser window with a fixed size. This variant is ideal if you want to provide a more controlled experience for the user while they complete their purchase.

​
Display

You might want to control whether the SDK is showing based on some application state. This is there the visible prop comes into play. Using the visible prop ensures that the widget is properly shown and cleaned up as necessary. As a light example, here is how one could add a button to toggle the SDK embedded variant. 
import { MoonPayBuyWidget } from "@moonpay/moonpay-react";

export default function Home() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <MoonPayBuyWidget
        variant="overlay"
        baseCurrencyCode="usd"
        baseCurrencyAmount="100"
        defaultCurrencyCode="eth"
        visible={visible}
      />
      <button onClick={() => setVisible(!visible)}>Toggle widget</button>
    </>
  );
}

​
URL signing

If you’re using the walletAddress or walletAddresses query param, you need to sign your widget URL before you can display the widget. Learn more about URL signing. Each of our React components provides an onUrlSignatureRequested prop that takes an asynchronous function which is called whenever the URL is updated. It takes an argument of the current URL and the return value should be your generated signature, acquired by some means from your backend by signing the given URL. The widget then takes this returned signature and updates its URL to include it. 
import { MoonPayBuyWidget } from "@moonpay/moonpay-react";

const handleGetSignature = async (url: string): Promise<string> => {
  const signature = await fetch(
    `https://YOUR_API_DOMAIN.com/sign-url?url=${url}`,
  );
  return signature;
};

export default function Home() {
  return (
    <>
      <MoonPayBuyWidget
        variant="overlay"
        baseCurrencyCode="usd"
        baseCurrencyAmount="100"
        defaultCurrencyCode="eth"
        onUrlSignatureRequested={handleGetSignature}
        visible
      />
    </>
  );
}