Docs · Node.js 18+

Node.js residential proxies by US city

Name: US residential proxies (city-level)
Brand: MetroProxies
Availability: InStock

Examples with undici (the library behind Node's fetch) and Playwright, syntax-checked with node --check.

Last updated: October 18, 2026

Quick answer

How do I use a US city proxy in Node.js?

Create an undici ProxyAgent for http://gw.metroproxies.com:7777 with a city username such as USERNAME-country-us-state-fl-city-orlando, and pass it as the dispatcher of fetch; Playwright takes the same values in its proxy option. MetroProxies includes city, ZIP and ASN targeting on every plan from $0.50/GB (October 2026). No KYC; crypto.

1. fetch through a city IP (save as city.mjs)

import { ProxyAgent, fetch } from 'undici';

const user = 'USERNAME-country-us-state-fl-city-orlando';
const agent = new ProxyAgent({
  uri: 'http://gw.metroproxies.com:7777',
  token: 'Basic ' + Buffer.from(`${user}:PASSWORD`).toString('base64'),
});

const res = await fetch('https://ipinfo.io/json', { dispatcher: agent, signal: AbortSignal.timeout(30000) });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());
await agent.close();

2. Several cities, one agent each (save as cities.mjs)

import { ProxyAgent, fetch } from 'undici';

const cities = [['fl', 'orlando'], ['fl', 'tampa'], ['ga', 'atlanta']];

for (const [state, city] of cities) {
  const user = `USERNAME-country-us-state-${state}-city-${city}`;
  const agent = new ProxyAgent({
    uri: 'http://gw.metroproxies.com:7777',
    token: 'Basic ' + Buffer.from(`${user}:PASSWORD`).toString('base64'),
  });
  try {
    const res = await fetch('https://ipinfo.io/json', { dispatcher: agent, signal: AbortSignal.timeout(30000) });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const info = await res.json();
    console.log(city, '->', info.ip, info.city, info.region);
  } catch (err) {
    console.log(city, 'failed:', err.message);
  } finally {
    await agent.close();
  }
}

3. Playwright with a sticky city IP (save as browser.mjs)

import { chromium } from 'playwright';

const browser = await chromium.launch({
  proxy: {
    server: 'http://gw.metroproxies.com:7777',
    username: 'USERNAME-country-us-state-fl-city-miami-session-mia01-ttl-15',
    password: 'PASSWORD',
  },
});
const context = await browser.newContext({ timezoneId: 'America/New_York', locale: 'en-US' });
const page = await context.newPage();
await page.goto('https://ipinfo.io/json', { timeout: 60000 });
console.log(await page.textContent('body'));
await browser.close();

What should I watch for in Node.js?

Keep-alive: one ProxyAgent reuses connections, so in rotating mode it keeps the same exit IP while a connection stays open. Create one agent per city, or close it, to get a new IP.
Time zone and locale: Playwright's timezoneId and locale options make the browser match the city; each city page gives its IANA zone (Miami: America/New_York).
SOCKS5: Chromium does not send a username to SOCKS5 proxies; use the HTTP port in browsers.
Timeouts: AbortSignal.timeout() in fetch, timeout in Playwright.
Rate: keep requests to each site modest and follow its robots.txt and terms.

Where should I go next?

Start from the five-minute setup, compare with the Python and curl examples, and check exits with the proxy location checker. All docs: documentation.

What else do people ask about Node.js?

Which Node.js version do I need?

Node.js 18 or later for AbortSignal.timeout and top-level await in .mjs files. Install undici with npm install undici and Playwright with npm install playwright.

Does Puppeteer work too?

Yes: launch with --proxy-server=http://gw.metroproxies.com:7777 and call page.authenticate({ username, password }) before the first navigation.

Were these examples run against the gateway?

They are syntax-checked with node --check, with USERNAME and PASSWORD as placeholders. Run them with your own credentials.