Skip to main content
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.
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

ScenarioConditionResult
Matching IPThe signature is valid and the hash of the observed IP matches allowedIpAddress.The customer proceeds through the flow.
Non-matching IPThe 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.

​
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

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