IP matching

IP matching is a security upgrade for the on-ramp widget, and is mandatory for going live. On top of signing your widget URLs, you bind each URL to a hash of the customer’s IP address at the point you generate it. When the widget loads, MoonPay hashes the IP address it observes and compares it to the value signed into the URL. If the observed IP address does not match the hash, the widget shows an error and does not load. This protects against intercepted or stolen URLs being used by anyone other than the intended customer.

IP matching is required to go live with the on-ramp widget. Build and test your integration in sandbox first. MoonPay confirms enforcement is active on your account before you go live.

Requirements

A widget URL passes IP matching when both of the following are true:

The URL is signed with your secret key. See URL signing.
The URL includes an allowedIpAddress parameter set to a hash of the customer’s IP address, and that hash is part of the signed query string.

Before you begin

Get your secret key from the Developers > API Keys page of your MoonPay dashboard. Keep it on your backend and never expose it client-side.
Make sure your backend can capture the customer’s live, public IP address at the point of URL generation.

How it works

Generate a signed URL with IP matching

Build the URL on your backend in two steps: hash the customer’s IP address and add it as allowedIpAddress, then sign the full query string.

Step 1: Hash the customer’s IP address

Capture the customer’s public IP address, hash it with your secret key using HMAC-SHA256, and append the result to the widget URL as the allowedIpAddress parameter.

Node.js

import crypto from "crypto";

const secretKey = "sk_live_key"; // Use your secret key

// The customer's public IP, captured and canonicalized on your backend.
const customerIp = "203.0.113.42";

const ipHash = crypto
  .createHmac("sha256", secretKey)
  .update(customerIp)
  .digest("base64");

const baseUrl =
  "https://buy.moonpay.com?apiKey=pk_live_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae";

const urlWithIp = `${baseUrl}&allowedIpAddress=${encodeURIComponent(ipHash)}`;

A mismatch blocks the widget from loading. A customer’s IP address can change between the point you generate the URL and the point they open it, for example on a VPN, a proxy, a corporate network, or a mobile device switching between Wi-Fi and cellular. Generate the signed URL as close as possible to when the customer opens the widget. On iOS, iCloud Private Relay causes a guaranteed mismatch for widgets opened in Safari-based views.

To capture the right IP address:

Use the IP address of the device that will open the widget, such as the True-Client-IP header or the left-most X-Forwarded-For value behind your proxy or CDN.
Do not use a server-side or internal address.
Canonicalize the IP address to a stable string before hashing. HMAC is sensitive to any formatting difference, so the value you hash must exactly match the value MoonPay observes.

Step 2: Sign the URL

Sign the full query string, including allowedIpAddress, with the same secret key. Append the result as the signature parameter.

Node.js

const signature = crypto
  .createHmac("sha256", secretKey)
  .update(new URL(urlWithIp).search)
  .digest("base64");

const urlWithSignature = `${urlWithIp}&signature=${encodeURIComponent(signature)}`;

console.log(urlWithSignature);

For the full signing flow, including SDK-based signing and PHP examples, see URL signing.

What to expect

Scenario	Condition	Result
Matching IP	The signature is valid and the hash of the observed IP matches `allowedIpAddress`.	The customer proceeds through the flow.
Non-matching IP	The signature is valid but the hashes do not match.	The widget fails to load and the customer cannot continue. MoonPay logs the observed client IP to help with debugging.

When the IP address does not match, the customer sees an “Unverified Connection” error in place of the widget:

Unverified Connection We couldn’t verify this request. If this continues, contact support through the official MoonPay app or website.

iCloud Private Relay

iCloud Private Relay is an iCloud+ feature, on by default for iCloud+ subscribers, that routes Safari traffic through an Apple relay. When a customer with Private Relay opens the widget in a Safari-based view, MoonPay observes an Apple relay egress IP address instead of the customer’s real IP address. Your backend captures the real IP address from your app’s own traffic, so the two never match and the widget fails to load for every Private Relay user. Whether your integration is affected depends on how you open the widget:

How you open the widget	Affected	Why
`SFSafariViewController`, or a handoff to the Safari app	Yes	Apple treats this traffic as Safari browsing and routes it through the relay.
`WKWebView` or Android WebView	No	The widget loads over your app’s own networking stack. Private Relay does not route native app HTTPS traffic, so MoonPay observes the same IP address your backend captures.

MoonPay recommends a WebView on iOS and Android, so integrations that follow the integration design guide are not affected. Handle Private Relay only if you open the widget in SFSafariViewController, for example for Apple Pay.

Handle Private Relay sessions

Detect Private Relay before you generate the widget URL, and omit allowedIpAddress from the signed URL when it is active. MoonPay skips IP enforcement for that session but still validates the signature, so the URL cannot be tampered with. In this configuration, you assume responsibility for verifying the customer’s IP address. To detect Private Relay, compare two observations of the customer’s IP address:

The IP address your backend observes from your app’s own HTTPS traffic. This traffic bypasses the relay.
The IP address your backend observes from a request made inside the Safari view, for example a lightweight endpoint the view loads once and that redirects back to your app with the observed IP address.

If the two match, Private Relay is not active and you include allowedIpAddress as usual. If they differ, omit it:

Node.js

import crypto from "crypto";

const secretKey = "sk_live_key"; // Use your secret key

// appIp:    the IP your backend observes from the app's own HTTPS traffic
// safariIp: the IP your backend observes from a request made inside the Safari view
function buildWidgetUrl({ walletAddress, currencyCode, appIp, safariIp }) {
  const params = new URLSearchParams({
    apiKey: "pk_live_key",
    currencyCode,
    walletAddress,
  });

  // The IP addresses match: Private Relay is not active, so include allowedIpAddress.
  if (appIp && safariIp && appIp === safariIp) {
    const ipHash = crypto
      .createHmac("sha256", secretKey)
      .update(appIp)
      .digest("base64");
    params.append("allowedIpAddress", ipHash);
  }
  // The IP addresses differ: Private Relay is active, so omit allowedIpAddress.
  // MoonPay skips IP enforcement for the session but still validates the signature.

  const signature = crypto
    .createHmac("sha256", secretKey)
    .update(`?${params.toString()}`)
    .digest("base64");
  params.append("signature", signature);

  return `https://buy.moonpay.com?${params.toString()}`;
}

Do not sign the relay IP address instead of omitting allowedIpAddress. Relay egress IP addresses are only stable per destination website, so the relay IP your backend observes can differ from the relay IP MoonPay observes. Canonicalization does not help here either: it normalizes different textual forms of the same address, not two genuinely different addresses.

Testing

Test your implementation in sandbox before you turn it on in production, using your sandbox API key from the Developers > API Keys page of your MoonPay dashboard.

Next steps

Test your implementation in sandbox and confirm the widget loads for matching IP addresses and returns an error for mismatches.
Notify your MoonPay integration contact once testing is complete.
MoonPay confirms enforcement is active on your account before you go live.

Get Started

On-Ramp

Off-Ramp

Requirements

Before you begin

How it works

Generate a signed URL with IP matching

Step 1: Hash the customer’s IP address

Step 2: Sign the URL

What to expect

iCloud Private Relay

Handle Private Relay sessions

Testing

Next steps

​Requirements

​Before you begin

​How it works

​Generate a signed URL with IP matching

​Step 1: Hash the customer’s IP address

​Step 2: Sign the URL

​What to expect

​iCloud Private Relay

​Handle Private Relay sessions

​Testing

​Next steps

Requirements

Before you begin

How it works

Generate a signed URL with IP matching

Step 1: Hash the customer’s IP address

Step 2: Sign the URL

What to expect

iCloud Private Relay

Handle Private Relay sessions

Testing

Next steps