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

# MoonPay Gateway

> Let customers buy DeFi tokens with fiat in one checkout. Learn how to integrate Gateway, where it's available, and how to enable it.

MoonPay Gateway is MoonPay's on-chain ramp. A customer pays with fiat, for
example with Apple Pay, and receives a DeFi token directly in their wallet,
inside your app. The token comes from on-chain decentralised exchange (DEX)
liquidity instead of a centralised exchange.

With the Platform API, you discover tokens, request quotes, and present payment
buttons the same way you do for standard assets.

## Choose an integration path

| Path | You build | Disclosures |
| - | - | - |
| Platform API | Your own checkout UI, with MoonPay's payment buttons and frames. Recommended for a native, in-app flow. | You display the slippage and the token disclosure, plus the swap fee when the quote includes it. See [Going Live](https://dev.moonpay.com/platform/overview/going-live.md#gateway-defi-tokens). |
| Widget | A link or webview that opens the MoonPay widget with the token preselected. | The widget renders them for you. |

This page covers the Platform API. For the widget, see the
[widget Gateway integration](https://dev.moonpay.com/widget/gateway-integration.md).

> [!WARNING]
>
> Gateway doesn't work with [guest checkout](https://dev.moonpay.com/platform/guides/guest-checkout.md) on
> the Platform API. Connect the customer with [hosted
> onboarding](https://dev.moonpay.com/platform/guides/connect-a-customer.md) or the [Customer
> API](https://dev.moonpay.com/platform/guides/customer-api.md) instead.

## Why use Gateway

* **Add a network, get its tokens.** Coverage is by network, not token by
  token. Once a network is live for you, every token on it that meets the
  [token safeguards](#token-safeguards) becomes buyable, including tokens that
  launch later. There is no per-token integration work.
* **No exchange listing.** Gateway doesn't wait for a centralised exchange to
  list a token.
* **One checkout.** Customers pick a token, pay, and receive it. They don't
  deposit funds or buy a bridge asset first.
* **In your UI.** The purchase happens inside your app, with MoonPay's payments,
  compliance, and settlement underneath.
* **Itemized fees.** The quote itemizes the fees for the purchase, including the
  swap fee when the quote itemizes it.

## Enable Gateway

A Platform integration doesn't include Gateway by default. Gateway is a separate
capability from your integration method. MoonPay enables it for your account, so
contact your MoonPay account team. Until Gateway is enabled, List assets still
returns DeFi tokens, but quoting one returns a `503`. See
[Capability enablement](https://dev.moonpay.com/api-reference/platform/documentation/using-the-api.md#capability-enablement).

## Integrate Gateway

Before you start, you need:

* Gateway enabled for your account. See [Enable Gateway](#enable-gateway).
* A customer in a [supported region](#networks-and-availability).
* A connected customer, not a guest. See [Choose an onboarding
  path](https://dev.moonpay.com/platform/guides/onboarding-paths.md).
* A server that can call the Platform API with your secret API key.

**1. Discover tokens (server)**

Call [List assets](https://dev.moonpay.com/api-reference/platform/endpoints/assets/list.md). Pass
`source=defi` to return only DeFi tokens. Each token has a `caip19`
identifier, its [CAIP-19](https://chainagnostic.org/CAIPs/caip-19) asset ID.

**2. Request a quote (server or client)**

Call [Get a quote](https://dev.moonpay.com/api-reference/platform/endpoints/quotes/get.md) with the
token's `destination.asset.caip19` and the amount in `source.amount`.
Quoting by destination amount isn't supported for DeFi tokens. The quote
includes the estimated token amount, fees, `slippageBps` (see
[Slippage](#slippage)), and the `gateway-token` disclosure in
`paymentDisclosures`. In the SDK, call
[`client.getQuote()`](https://dev.moonpay.com/platform/sdk-reference/web/get-quote).
The sample uses the SDK on the client. To quote from your server, send the
same fields to the endpoint.

```ts theme={null}
// Frontend, SDK client with a session token
const quoteResult = await client.getQuote({
  source: { asset: { code: "USD" }, amount: "100" },
  destination: {
    asset: {
      // caip19 from List assets; a DeFi token's code is not unique
      caip19:
        "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp/token:2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
    },
  },
  wallet: { address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin" },
  paymentMethod: { type: "apple_pay" },
});
```

**3. Show the required disclosures (client)**

Display the slippage and the `gateway-token` disclosure before the customer
confirms, plus the swap fee (`fees.defi`) when the quote includes it. See the [Gateway Going Live
requirements](https://dev.moonpay.com/platform/overview/going-live.md#gateway-defi-tokens).

**4. Present a payment button (client)**

Use an existing payment button: [Apple
Pay](https://dev.moonpay.com/platform/guides/pay-with-apple-pay.md), [Google
Pay](https://dev.moonpay.com/platform/guides/pay-with-google-pay.md), or the [buy
button](https://dev.moonpay.com/platform/guides/pay-with-buy-button.md). MoonPay completes the
purchase and the token arrives in the customer's wallet. You don't
build any on-chain infrastructure. The payment button needs a
[session](https://dev.moonpay.com/api-reference/platform/endpoints/sessions/create.md) for your
customer.

> [!NOTE]
>
> The Gateway catalog changes as tokens and networks evolve. Use List assets as
> the source of truth instead of hardcoding availability.

## Test your integration

Test mode doesn't support Gateway DeFi tokens. To test your checkout, use a
testnet asset from [Test mode](https://dev.moonpay.com/platform/overview/test-mode.md). Contact your
MoonPay account team about testing DeFi tokens before you go live.

## Networks and availability

Gateway supports tokens on:

* Ethereum
* Solana
* Base

To request another network, contact your MoonPay account team. EVM-compatible
networks are quicker to add than non-EVM networks. While you wait, integrate on
a supported network. Adding the new one later then needs no further integration
work.

Gateway is available wherever the Platform supports ramps, except the EEA,
Switzerland, Iceland, Liechtenstein, Norway, Australia, and New York. List
assets doesn't return DeFi tokens to customers in those regions. See
[Availability](https://dev.moonpay.com/platform/overview/availability.md).

## Slippage

Tokens come from on-chain liquidity, so the amount of token delivered can move
slightly between quote and settlement as market conditions change.
Slippage is the difference between the expected price and the final executed
price.

The quote returns the tolerance as `slippageBps` and promises a minimum amount
of the token based on it. The swap only executes if the final price stays within
that tolerance. Show `slippageBps` before the customer confirms.

See [Fees and slippage](https://dev.moonpay.com/platform/overview/going-live.md#fees-and-slippage) for
the exact text to show.

## Token safeguards

Gateway applies safeguards to filter out likely scam tokens. A token becomes
buyable once it has enough liquidity and trading volume and isn't flagged as a
likely scam.

A token missing from List assets is held back by these safeguards. Once it
clears them, it appears automatically.

List assets doesn't check whether a token can be routed. If a quote for a listed
token fails with a `400`, the token can't be bought right now.

## Payment methods and limits

* **Payment methods:** Gateway purchases work with Apple Pay, Google Pay, and
  card. Bank transfers don't support DeFi tokens. See
  [Payment methods](https://dev.moonpay.com/platform/guides/payment-methods.md).
* **KYC and limits:** Gateway adds no verification requirements or limits.
  Customers follow the limits of their
  [verification tier](https://dev.moonpay.com/platform/guides/verification-tiers.md), region, and payment
  method.
* **Asset types:** Gateway supports crypto tokens only.

## Frequently asked questions

> [accordion] Does Gateway use an exchange?
>
> No. The token comes from on-chain DEX liquidity instead of a centralised
> exchange.

> [accordion] What happens if the swap can't complete?
>
> The swap only executes if the final price stays within the slippage
> tolerance, so the customer doesn't receive less than the quoted minimum.
> Contact your MoonPay account team about how failed purchases are handled.

## Next steps

> [card] [Going Live requirements](https://dev.moonpay.com/platform/overview/going-live.md#gateway-defi-tokens)
>
> The disclosures and line items to show for Gateway purchases.

> [card] [Pay with the buy button](https://dev.moonpay.com/platform/guides/pay-with-buy-button.md)
>
> Present a payment button and handle the purchase events.