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. We support both IPv4 and IPv6.

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.

Capture the IP address of the device that will open the widget, on the same request that generates the signed URL. Canonicalize it 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.

Rule	What to do
Source header	Use `True-Client-IP`. Avoid `CF-Connecting-IP` and the raw socket address.
IPv4 format	Use the dotted-quad form with no leading zeros, for example `203.0.113.42`.
IPv6 format	Use the RFC 5952 canonical form: lowercase, `::` compression, no leading zeros. For example, `2001:0DB8:0000:0000:0000:0000:0000:0001` becomes `2001:db8::1`.
IPv4-mapped IPv6	Unmap it to plain IPv4 first. Convert `::ffff:203.0.113.42` to `203.0.113.42`.
Ports and brackets	Strip both before hashing. Hash `2001:db8::1`, not `[2001:db8::1]:443`.
Cloudflare pseudo IPv4	If your Cloudflare configuration overwrites headers, read `CF-Connecting-IPv6` for the real address whenever `CF-Connecting-IP` returns a `240.0.0.0/4` placeholder.

IP matching is an exact string comparison of the hash, not a semantic comparison of the address.

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.
Parameter omitted	The signature is valid and the URL has no `allowedIpAddress`.	MoonPay skips IP enforcement for the session and still validates the signature. Use this only for sessions where you’ve detected Private Relay, not as a general way to skip IP matching.
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, and most integrations that follow the integration design guide are not affected. Some iOS integrations open the widget in SFSafariViewController instead, since it’s a simpler path to Apple Pay support. If that’s your integration, handle Private Relay as described below.

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.

Dual-stack devices

A device can reach your backend over one IP address family and the widget over the other. This can happen through carrier NAT64/464XLAT, or simply because the device picks a different address family for each separate connection it makes. A real IPv4 address and a real IPv6 address for the same device are two different addresses, not two notations of the same one, so a single allowedIpAddress hash can never match both.

Send both IP addresses

If your backend can capture both address families for the same device, hash each one and send them as a comma-separated list in allowedIpAddress. MoonPay matches against either hash, so the widget loads if the IP address it observes matches either one.

Node.js

import crypto from "crypto";

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

// Capture both address families your backend observes for this device.
const customerIpv4 = "203.0.113.42";
const customerIpv6 = "2001:db8::1";

const hash = (ip: string) =>
  crypto.createHmac("sha256", secretKey).update(ip).digest("base64");

const allowedIpAddress = [customerIpv4, customerIpv6].map(hash).join(",");

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

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

You can send just one IP (required) and it still works, but by sending both IPs (optional) you increase the chances of a successful match.

allowedIpAddress accepts at most two comma-separated hashes, one per IP family. If you send more, validation fails and the widget doesn’t load.

Other causes of a mismatch

iCloud Private Relay is the most common cause of a mismatch, but not the only one. Check these before you escalate a mismatch you can’t otherwise explain:

Dual-stack IPv4 and IPv6 you can’t capture both sides of. See Dual-stack devices above. If you can only ever capture one address family, confirm you’re not hashing an IPv4 address while the device connects to the widget over IPv6, or the reverse.
The IP address changing between signing and opening. Wi-Fi to cellular switches, VPN toggles, corporate networks, and carrier-grade NAT (CGNAT) rotation can all change a customer’s IP address after you generate the signed URL. Generate the URL as close as possible to when the customer opens the widget.
VPNs with split tunneling. The same shape as Private Relay: your app’s traffic and the widget’s traffic leave the customer’s device on different addresses.
A stale capture. Capturing the IP address at login, at app load, or from a cached session, rather than from the request that generates the signed URL.

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. IP matching behaves differently in each environment:

Environment	Behavior
Sandbox	IP matching is on by default. A mismatch shows the “Unverified Connection” error and blocks the customer, so you can verify both outcomes.
Production	Mismatches are logged only, until MoonPay turns on enforcement for your account as a manual step, so MoonPay can monitor the rollout with you.

Next steps

Verify both outcomes in sandbox: confirm the widget loads for a matching IP address and returns an error for a mismatch.
If you support iOS, test the Private Relay path. On a device with iCloud Private Relay turned on, confirm your detection step fires and the widget opens without allowedIpAddress. Then turn off Private Relay on the device and confirm the parameter is included again.
Notify your MoonPay integration contact once testing is complete.
MoonPay confirms enforcement is active on your account, and monitors the first days of traffic with you.

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

Dual-stack devices

Send both IP addresses

Other causes of a mismatch

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

​Dual-stack devices

​Send both IP addresses

​Other causes of a mismatch

​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

Dual-stack devices

Send both IP addresses

Other causes of a mismatch

Testing

Next steps