LLM Guidance For Configuring The Repliers API Firewall
Repliers API IP Firewall: Forwarding the Real Client IP
What this solves
The Repliers API supports an IP-based firewall. When you proxy requests through a backend server, the Repliers API sees your server's IP — not your end users'. To enforce per-client IP rules, you must extract the real client IP and forward it in the x-repliers-forwarded-for header on every Repliers API request made on behalf of an end user (person or bot).
Background jobs, health checks and internal tooling have no end user behind them. Run them on a separate API key and do not send the x-repliers-forwarded-for header on those requests.
Why use the Repliers firewall
- Meet MLS compliance requirements. MLSs require you to protect listing data. The firewall handles this for you by detecting and blocking threats before they reach listing data.
- Lower your costs. Blocked requests don't count toward your quota, and neither do requests from popular bots. Without the firewall, all of that traffic counts against you and can lead to overage charges.
- Get higher, fairer rate limits. Protected requests are throttled per user and less aggressively than unprotected requests, and rate limit increases are only available once all user traffic is protected. See Rate limits: protected vs. unprotected requests below.
- Gain usage insights. Because every request carries the real client IP, you get visibility into how listings are being accessed.
- API protection built in. Repliers detects and blocks abusive traffic to the Repliers API; you forward the real client IP on each end-user request. This does not protect your own pages: bots that load your pages still need bot protection at your edge. See Protect your own pages from bots below.
The firewall only works when every end-user request reaches it with the real client's IP, so follow the implementation and best practices below closely.
How it works
Your backend sits between the browser and Repliers. The browser's IP arrives via the X-Forwarded-For header (populated by your load balancer / CDN / reverse proxy). Your server reads that chain, finds the first public (non-private) IP, and forwards it to Repliers.
Browser → CDN/Load Balancer → Your API Server → Repliers API
(real IP) (appends to XFF) (reads XFF) (enforces firewall)
Implementation (TypeScript / Express)
1. Trust the proxy chain
In your Express app setup, tell Express to trust the upstream proxy so X-Forwarded-For is populated correctly:
// app.ts
app.set("trust proxy", true);
Warning: Only set this if your server is actually behind a trusted proxy (load balancer, CDN, Render, Railway, Fly.io, etc.). Do not set it if the server is directly internet-facing — a client could spoof the header.
2. Create the IP extraction utility
// lib/repliers-headers.ts
import type { Request } from "express";
const IPV4 = /^(\d{1,3}\.){3}\d{1,3}$/;
const IPV6 = /^([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$/;
function isValidIp(ip: string): boolean {
return IPV4.test(ip) || IPV6.test(ip);
}
function isPrivateIp(ip: string): boolean {
return (
/^10\./.test(ip) ||
/^172\.(1[6-9]|2\d|3[01])\./.test(ip) ||
/^192\.168\./.test(ip) ||
ip === "127.0.0.1" ||
ip === "::1"
);
}
export function getRepliersHeaders(req: Request): Record<string, string> {
// X-Forwarded-For is a comma-separated chain: client, proxy1, proxy2, ..., edge
const forwardedFor = (req.headers["x-forwarded-for"] as string | undefined ?? "")
.split(",")
.map((ip) => ip.trim())
.filter(Boolean);
// Take the first public IP — private IPs are always internal proxy hops.
const realIp =
forwardedFor.find((ip) => isValidIp(ip) && !isPrivateIp(ip)) ??
forwardedFor[0] ??
req.socket.remoteAddress?.replace(/^::ffff:/, "") ??
"";
return { "x-repliers-forwarded-for": realIp };
}
IP selection priority:
- First valid, public IP in the
X-Forwarded-Forchain - First IP in the chain (fallback when all are private — unusual, but safe)
req.socket.remoteAddress(direct connection, no proxy)- Empty string (should never happen in practice)
Private ranges filtered out: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.1, ::1
Warning: In production, fallbacks 2 and 3 can resolve to your load balancer's or proxy's IP rather than the end user's. If that happens, every request will appear to come from one IP and it will be banned quickly (see Never send your backend or proxy IP below). Log the forwarded value in production and confirm it is the real client IP.
3. Spread the headers into every Repliers API call
// routes/listings.ts
import { getRepliersHeaders } from "../lib/repliers-headers";
router.get("/listings", async (req, res) => {
const apiKey = process.env["REPLIERS_API_KEY"];
const response = await fetch("https://api.repliers.io/listings", {
headers: {
"repliers-api-key": apiKey,
"Content-Type": "application/json",
...getRepliersHeaders(req), // ← always spread this
},
});
// ...
});
Apply ...getRepliersHeaders(req) to every route that calls the Repliers API — listings, listing detail, locations, statistics, etc.
Firewall behavior and best practices
Rate limits: protected vs. unprotected requests
A request is protected when it carries the x-repliers-forwarded-for header and unprotected when it does not. The two are rate-limited differently:
- Unprotected requests are throttled more aggressively. Repliers can't tell where unprotected traffic is coming from, so it is pooled and throttled across your whole API key. One abusive visitor, bot, or runaway job can get every user of your application throttled at once.
- Protected requests are throttled per user. If one user is abusive, only that user is throttled or blocked, and everyone else keeps being served normally.
- Allowed bots get higher limits. Well-known search engine and advertising crawlers get higher rate limits than a regular user. Repliers can only recognise them when their real IP is forwarded in the header.
- Rate limit increases require full protection. Before you ask Repliers for a higher rate limit, make sure all user traffic is routed through the Repliers firewall (check the Protected/Unprotected split under Security Insights at login.repliers.com). After that, you can request increases as needed when demand for your application grows. Background jobs on a separate, unforwarded key don't count against this.
Don't retry blocked or throttled requests
Treat a 403 Forbidden (blocked by the firewall) or 429 Too Many Requests (throttled) response as final for that client. Do not retry it; handle it gracefully in your UI. A throttled user is throttled because of their own request pattern, and retrying on their behalf only adds to it.
Never resend the request without the x-repliers-forwarded-for header to get around a block or throttle. Dropping the header circumvents the firewall, defeats its purpose, and removes the protection it provides.
Pass 429 responses through to the client
Requests usually reach Repliers through your application's backend, so a 429 from Repliers only reaches the client if your backend passes it on. When Repliers returns a 429, return a 429 from your own route too, with the Retry-After header if one was sent. Don't turn it into a 200 with an empty page, a 500, or a different 4xx.
This matters most for ethical bots such as Googlebot, which treat a 429 as a signal to slow down. If they never see it, they keep crawling at the same rate. Other 4xx codes such as 403 or 404 don't slow them down and can get your pages dropped from search results.
For people, pair the 429 with a challenge. Instead of a dead end, serve the 429 page with a CAPTCHA or your bot-management service's challenge, and use the Retry-After value to tell the visitor when they can continue. Let them resume browsing only once they have passed the challenge and the Retry-After period has elapsed. Passing the challenge confirms a person is there, but it does not lift the throttle at Repliers, so resuming early will just produce another 429. The visitor chooses when to continue; your application doesn't retry on their behalf. Don't challenge verified search engine and advertising crawlers: send them the plain 429 with Retry-After.
Don't cache Repliers content
Don't cache responses from the Repliers API. Caching has performance benefits, but a listing request to Repliers takes under 50ms on average, so there's little to gain. More importantly, requests served from a cache never reach the Repliers firewall, which removes its ability to detect and block threats. Every client request should result in a live Repliers API call carrying the x-repliers-forwarded-for header.
Never fall back to cached content when a visitor is blocked. If Repliers blocks or throttles a request, serving that visitor a cached copy delivers content to someone the firewall has determined shouldn't receive it. A blocked response should result in no listing content for that visitor.
Protect your own pages from bots
The Repliers firewall protects the Repliers API, but it only sees a request once your application has decided to call Repliers. A bot that loads your pages directly causes those calls to be made on its behalf. Because you can't cache Repliers responses, every page a bot loads turns into Repliers calls against your allowance. Put your own bot protection in front of your application:
- Use a bot-management or challenge service at your edge. Most CDNs, hosting platforms, and web application firewalls offer bot detection, CAPTCHA-style or invisible challenges, and IP or ASN reputation filtering. Apply it to the pages and routes that trigger Repliers calls, such as search, map, and listing-detail pages.
- Protect your own API routes as well as your pages. If your front end calls an internal endpoint that proxies to Repliers, scrapers will often call that endpoint directly. Challenge or authenticate those routes, and check that the challenge was actually passed before calling Repliers.
- Rate-limit at your edge. Per-IP or per-session limits on your own routes stop a single client from generating bursts of upstream calls.
- Allow the crawlers you want. Make sure verified search engine and advertising crawlers are not challenged, or your search visibility and ad quality scores can suffer.
Edge protection works alongside the Repliers firewall rather than replacing it. Keep forwarding x-repliers-forwarded-for on every end-user request, so that anything your edge lets through can still be assessed and throttled per client. For more detail, see Protect your own pages from bots in the Repliers 403/429 troubleshooting article.
Blocked requests don't count toward your quota
Requests blocked by the firewall do not count toward your quota. Without the firewall, this traffic counts against you and you are subject to overage charges.
Popular bot traffic doesn't count toward your quota
When the firewall is in place, requests from popular bots don't count toward your quota either. Without the firewall, bot traffic counts against you like any other request and can push you into overage charges. This is another reason to forward the real client IP on every end-user request, bots included.
Your own team's IPs may get blocked
It's common for your own IP, or your team's, to get blocked. You're power users, and the firewall is correctly detecting higher-than-normal activity from you. Ask Repliers support to whitelist your team's IP addresses.
Never send your backend or proxy IP
Make sure the header never contains a backend, proxy, or load balancer IP. Because all requests are routed through that IP, it will be banned quickly, blocking every user at once. The IP in the header should always be the real end user's IP, whether that user is a person or a bot.
Gotchas
CDN/proxy strips or rewrites X-Forwarded-For
Some platforms (Cloudflare, Render) use their own header variants (CF-Connecting-IP, X-Real-IP). If X-Forwarded-For is empty or always shows the edge IP, check your platform's docs and adjust the extraction logic accordingly.
Multiple proxies append IPs left-to-right
The format is client, proxy1, proxy2. The leftmost entry is the original client. The rightmost entries are internal/edge hops. This utility correctly picks the leftmost public IP.
IPv6-mapped IPv4 addresses
Node.js sometimes returns ::ffff:1.2.3.4 from req.socket.remoteAddress. The .replace(/^::ffff:/, "") strip handles this.
trust proxy and spoofing
With trust proxy: true, Express trusts the entire X-Forwarded-For chain. If an attacker sends a crafted X-Forwarded-For header and your CDN/load balancer appends to it (rather than replacing it), the real IP is still at the right end of the chain — but this utility picks the leftmost public IP, which could be spoofed. For high-security environments, use trust proxy: N (a count) to trust only the N rightmost IPs, or validate against your known edge IP ranges.
Testing locally
When running locally without a proxy, X-Forwarded-For is absent and req.socket.remoteAddress is 127.0.0.1 or ::1. The header sent to Repliers will be an empty string or a loopback address — this is fine for local development, as the firewall rules apply in production.
To simulate a real IP in local dev:
curl -H "X-Forwarded-For: 203.0.113.42" http://localhost:3000/api/listings?locationId=...
Updated on: 04/11/2026
Thank you!
