Introduction

This guide will help you get started with MoonPay NFT Widget. With just a few lines of code, you can allow your users to purchase NFTs.

Step 1: Initialize the widget

Try out the widget in test mode using the following URL:
https://buy-sandbox.moonpay.com/nft?apiKey=pk_test_KJUrRjPuvAkVBasIgyMH9Yfe2FfVWw&contractAddress=0xMoonPayShowcase&tokenId=1

Choose your method of integration

Recommended. Use our web SDK to customize and display the widget. This provides an enhanced customer experience that can be closely integrated with your website for a seamless user journey. Learn more about our SDK.

You can show the widget in several ways:

On desktop: Using a modal, iframe, new window, or new tab.
On mobile: Using SFSafariViewController on iOS and Chrome Custom Tabs on Android.

If you're embedding the widget in an iframe, you must provide a comma-separated list of domains containing the widget. You can add this list on the Settings page of your MoonPay dashboard under Domain(s) of your app or website. The widget will not work on any other domain.

The URL for the widget must be signed for the widget to work.

Step 2: Customize the widget

You are required to pass several arguments as params argument to our SDK to initialize the widget. You may pass several parameters to customize the widget further:

Parameter	Description
apiKey	Your publishable API key. This is used to assign customers and transactions to your MoonPay account.
contractAddress	NFT contract address for the NFT the customer wants to buy.
tokenId	The token ID of the NFT the customer wants to buy.
signature	The signature of the widget URL. Learn more about signing URLS.
listingId	The listing ID of the NFT the customer wants to buy.
email	The customer's email address. Passing this parameter will pre-fill the email address in the form, streamlining your customer's journey.
externalTransactionId	An identifier associated with the transaction that is provided by you.
baseCurrencyCode	The fiat currency used by the customer for purchasing the NFT.
redirectURL	An optional URL. You can pass a URL in this parameter and the MoonPay widget will link to it on the transaction tracker page.
walletAddress	Your customer's NFT wallet address to which the NFT will be delivered. Passing this parameter will pre-fill the wallet address in the form, streamlining your customer's journey.
quantity	The quantity of NFTs the customer wants to buy. This parameter refers to multiples of the same NFT. If you pass quantity, you must also return the correct available quantity in your /asset_info response.
dynamicAssetInfo	If you pass dynamicAssetInfo=true and walletAddress, the wallet address will be included in the request MoonPay makes to your /asset_info endpoint. This will also be used in gas price estimation step. So if your smart contract has an allowlist of any kind please be sure to use this query param. If you pass dynamicAssetInfo=true but no walletAddress, the widget will prompt the user to enter a wallet address at the beginning of the widget journey. Values are: true, false.
metadata	The 'metadata' query parameter is a JSON-encoded object that can hold any type of data. Although MoonPay does not directly utilize this data, it forwards it to the `/asset_info` endpoint in the query string. This allows for flexible data transmission without any specific usage constraints within the MoonPay system.

Step 3: Sign the URL server-side

The use of the signature parameter is mandatory in production. Please note that all query parameter values need to be URL-encoded to generate a valid signature.

You can generate a signature of the URL server-side and append it to the URL. If the signature is provided (you might wish not to include it in the sandbox), we'll check the validity of the query string to make sure it has not been altered. You can use our NFT tools to check what signature we expect.

Learn more about signing URLs when using our Web SDK and browser integration.