QuotaGuard and Mercury Integration Guide

QuotaGuard Static IPs let your app call the Mercury API from two fixed addresses you add to the IP whitelist on your Mercury token. Route your Mercury calls through QuotaGuard Static, set QUOTAGUARDSTATIC_URL, and add your two fixed IPs to the token’s whitelist on the Mercury token management page.

Scope: Mercury requires an IP whitelist on Read and Write tokens, and on Custom tokens with write scopes. Read Only tokens do not require a whitelist. This guide is for integrations that use a write-capable token.

Mercury Requires an IP Whitelist on Read and Write Tokens

Mercury requires you to whitelist the IP addresses you expect to use a Read and Write token from. Mercury’s own documentation states this and names QuotaGuard for Heroku-hosted apps. See Mercury’s API Token Security Policies. An app on a cloud platform egresses from an address that changes on deploys and scaling, so a write-capable token configured with a whitelist rejects requests from the rotating address. The fix is two static IPs you add once.

Getting Started

After creating a QuotaGuard account, you are redirected to your dashboard, where you can find your proxy credentials and two static IP addresses.

Choose the right proxy region: Select the QuotaGuard region closest to where your app runs. The region is set at sign-up. Changes after sign-up require contacting support.

QUOTAGUARDSTATIC_URL="http://username:password@<your-quotaguard-proxy-host>:9293"
MERCURY_API_TOKEN="secret-token:mercury_production_..."

Add Your QuotaGuard IPs to Your Mercury Token

Open the Mercury token management page, edit the Read and Write token your integration uses, and enter both QuotaGuard IP addresses in the token’s IP whitelist. Mercury supports individual IPs and CIDR ranges; enter your two QuotaGuard addresses as individual IPs. Once the whitelist is set, only requests from those addresses can use the token.

Authenticate and Route Calls Through the Proxy

The Mercury API is at https://api.mercury.com/api/v1. It uses HTTP basic authentication with your API token as the username and an empty password; a bearer header is also supported. Route your calls through the proxy so each request exits from your static IPs.

Python (requests)

import os, requests

proxies = {
    "http": os.environ["QUOTAGUARDSTATIC_URL"],
    "https": os.environ["QUOTAGUARDSTATIC_URL"],
}
token = os.environ["MERCURY_API_TOKEN"]

resp = requests.get(
    "https://api.mercury.com/api/v1/accounts",
    auth=(token, ""),
    proxies=proxies,
)
print(resp.status_code)

Node.js (undici)

import { ProxyAgent, fetch } from 'undici';

const dispatcher = new ProxyAgent(process.env.QUOTAGUARDSTATIC_URL);
const token = process.env.MERCURY_API_TOKEN;

const res = await fetch('https://api.mercury.com/api/v1/accounts', {
  dispatcher,
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
});
console.log(res.status);

Ruby (Net::HTTP)

require 'net/http'
require 'uri'

proxy = URI.parse(ENV['QUOTAGUARDSTATIC_URL'])
http = Net::HTTP.new('api.mercury.com', 443, proxy.host, proxy.port, proxy.user, proxy.password)
http.use_ssl = true

req = Net::HTTP::Get.new('/api/v1/accounts')
req.basic_auth(ENV['MERCURY_API_TOKEN'], '')
puts http.request(req).code

Testing Your Integration Is Using the Static IP

curl -x "$QUOTAGUARDSTATIC_URL" https://ip.quotaguard.com

Expected response:

{"ip":"<one of your two QuotaGuard static IPs>"}

The returned IP must be one of the two static IPs in your QuotaGuard dashboard, and both must be on your Mercury token’s whitelist. Run it more than once to confirm both (load-balanced).

Troubleshooting

401 or 403 after enabling the whitelist

Only one of your two QuotaGuard IPs is on the token’s whitelist, so requests through the other IP fail. Add both. If both are present, confirm the request is actually routing through the proxy with the verify step above.

It works with a Read Only token but fails with the Read and Write token

That is expected. Read Only tokens are exempt from the whitelist; Read and Write tokens are not. The whitelist must contain your two static IPs for the write-capable token.

407 Proxy Authentication Required

This is the QuotaGuard proxy, not Mercury. Your QUOTAGUARDSTATIC_URL credentials are wrong. Confirm them against your dashboard.

Wrong IP returned

The proxy is not attached to the request. Confirm you applied it to the specific Mercury call.

QuotaGuard Static vs QuotaGuard Shield

The whitelist requirement is a network-layer fix, so Static is the correct product. Your Mercury calls are outbound HTTPS tunneled through the proxy, so your payload and token stay encrypted end to end to Mercury. Choose QuotaGuard Shield when your security review additionally requires the first hop to the proxy encrypted, so the proxy credential is never sent in the clear.

Ready to Get Started?

Get in touch or create a free trial account.

Try QuotaGuard Now

View Mercury Integration Features

Mercury API Token Security Policies

Contact Support