> ## 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.

# Gateway integration

> MoonPay Gateway provides upgraded ramps capabilities so users can buy DeFi tokens on Ethereum, Solana, and Base directly on your website or app through a single checkout for the intended destination token. Gateway provides a shorter user journey and faster ecosystem coverage as tokens emerge and evolve.

> [!NOTE]
>
> Learn how to enable Gateway in the [MoonPay Gateway
> overview](https://dev.moonpay.com/platform/overview/gateway.md). MoonPay enables Gateway per account, so
> contact your account team.

If you haven't already, sign up for your [MoonPay partner
account](https://dashboard.moonpay.com/login) and complete the KYB (Know Your
Business) requirements. Once completed, sandbox and production API keys will
available in [the partner
dashboard](https://dashboard.moonpay.com/developers/api-keys).

## MoonPay widget integration

Load the MoonPay widget URL within your in-app webview or browser for web apps. This is used by partners like Moonshot, Jupiter, and Uniswap.

* Testing (Sandbox): The sandbox environment doesn't support Gateway, so you'll need to test in production. If you need to use the sandbox environment, you can test with alternative testnets e.g. ETH Sepolia or SOL.\
  `https://buy.moonpay.com/?apiKey=pk_test_INSERT_TEST_API_KEY`
* Production: `https://buy.moonpay.com/?apiKey=pk_live_INSERT_PRODUCTION_API_KEY`

### Widget parameters

| Widget parameter | Definition |
| :- | :- |
| `contractAddress` | The contract address of the token to purchase (e.g. YOUR\_TOKEN\_ADDRESS) |
| `networkCode` | The network of the token: `ethereum`, `solana`, or `base` |
| `walletAddress` | The user's wallet address (i.e. public key) |
| `baseCurrencyAmount` (optional) | The fiat purchase amount (e.g. 100) that will be pre-filled in the widget |
| `email` (optional) | The user's email that will be pre-filled in the widget. Highly recommended. |
| `signature` | The [URL signature](https://dev.moonpay.com/widget/on-ramp/customization/url-signing.md) that's required when passing sensitive information like `walletAddress`. |

### Example URL

Below is an example widget URL that uses the parameters above:

```sh wrap theme={null}
https://buy.moonpay.com/v2/buy?apiKey=pk_live_INSERT_YOUR_API_KEY&contractAddress=AdxNrCntq6YkYC2qVffF2Fw7WC1UatKhV8J6G4ekgNx3&networkCode=solana&baseCurrencyAmount=100&baseCurrencyCode=usd&walletAddress=Dt2B4YsybCtF8z5qQH1Mg9yGcLEXbaWLaTSGmf8xHVRv&email=satoshinakamoto%40gmail.com&theme=light&redirectURL=https%3A%2F%2Fbuy.son.meme%2Fpayment-success&signature=E2Y7O4ymU%2BzmfqPq4fefDRgA5liGjvcwNjOx%2BQ9JAzg%3D
```

### Widget UX customizations

Go to the [Dashboard → Theme settings](https://dashboard.moonpay.com/theme) to set widget colors (button, background, initial loading screen). Match your brand so the widget feels native and improves conversions.

## Optional API usage

Use our APIs to provide individual asset details and a list of assets available for purchase before directing users to the widget. This allows for a smooth transition between your app and the widget.

You can use the following endpoints:

1. [`GET /v1/defi/token`](https://dev.moonpay.com/api-reference/widget/getdefitoken): Retrieve token details for a specific `contractAddress` and `networkCode`.
2. [`GET /v1/defi/tokens`](https://dev.moonpay.com/api-reference/widget/getdefitokens): Search and retrieve a paginated list of defi tokens.

These endpoints belong to the widget API at `https://api.moonpay.com` and use your API key. They're separate from the Platform API's [List assets](https://dev.moonpay.com/api-reference/platform/endpoints/assets/list.md) endpoint.

## Troubleshooting

* **Webview KYC requirements**: If loading the MoonPay widget within a mobile application webview, follow these configurations to make sure the KYC and user camera will function correctly. [See requirements](https://dev.moonpay.com/widget/on-ramp/design-guide.md#app-requirements-for-kyc).
* **Third-party cookies / iframe blockers**: Some browsers/extensions block widget flows. Test in a clean profile or incognito mode with extensions disabled. **Apple Pay will not work within iframes**.
* **Invalid or missing params**: Make sure `apiKey`, `contractAddress`, a supported `networkCode`, and a valid `walletAddress` and `signature` are all present.
* **Ad blockers / privacy settings**: Ad blockers and privacy settings can break widget scripts.
* CORS / Referrer policies: If embedding the widget in an iframe, add the parent domain(s) to the [allowlist in the partner dashboard](https://dashboard.moonpay.com/developers/general).
* **Rate limits / throttling**: Avoid rapid programmatic opens; all opens must be user-initiated.
* **Wallet infrastructure**If you need help setting up wallet infrastructure, MoonGate lets users sign in with Google, Apple, or Ethereum and auto-creates a wallet. Reach out to your MoonPay representative for more details.