Node.js proxy setup with fetch, axios and got

Your first Node.js request through a home IP

Two minutes, start to finish. If you see a JSON answer with a residential IP, your Node.js proxy works. Pick your client once: every code block on this page follows it.

1. Copy your proxy login

   The dashboard’s Generate page shows it. The username (lx_k3m9q2p7xa) is yours on every plan; in the URL it gets the prefix of the product: resi- for Residential, premi- for Residential Premium. The password is the plan’s own, 16 hex characters. Everything you can add to it: proxy authentication.

2. Install your HTTP client

   Built-in fetchundiciaxiosgot

   install_fetch.shCOPY

   # nothing to install: Node.js 24 or later
   # macOS and Linux (Windows PowerShell: $env:HTTPS_PROXY = "...")
   export HTTPS_PROXY="http://resi-lx_k3m9q2p7xa:[email protected]:7777"

3. Run this

   Built-in fetchundiciaxiosgot

   first_request_fetch.mjsCOPY

   // run with: NODE_USE_ENV_PROXY=1 node first_request_fetch.mjs
   // (set HTTPS_PROXY first, as in the install step)
   const r = await fetch("https://api.ludaxproxy.com/whoami");
   console.log(await r.json());

   You should see something like this, with your own exit IP:

   output

   { ip: '203.0.113.24', country: 'United States', type: 'residential', tls_profile: null, latency_ms: 412 }

   That is a real home connection in the United States, picked by -country-us in the password. tls_profile is null because the site sees Node’s own handshake (why that matters). Change us to de, jp or any code from the locations directory.

   Official docs: Node.js: NODE_USE_ENV_PROXY · undici: ProxyAgent · axios: request config

fetch, undici, axios or got: how each one treats the proxy

They all reach the same gateway, but they differ in the two things that matter with residential proxies: whether a request gets a new connection (so a new IP), and how a refused login reaches your code. Measured by counting the connections the gateway received.

So: for a new IP on every request, axios and got do it out of the box; with undici or fetch, make a new agent per request (recipe 01). For one IP across many requests, every client needs a session token (recipe 02). The four clients reach the TLS ports the same way: start Node with NODE_EXTRA_CA_CERTS=ludax-ca.crt.

Generate Node.js proxy code for your plan

Choose the product, the country and whether the IP should stay the same, and copy the code for your client. Type your own username and password to get code you can run as is: they stay in this browser tab and are never sent anywhere.

The TLS gateways need the Ludax CA once: download ludax-ca.crt, keep it next to your script and run NODE_EXTRA_CA_CERTS=ludax-ca.crt node ludax.mjs. Why?

Six Node.js proxy patterns you will need

Each one runs on its own: paste it, put in your username and password, run. Where two clients are shown they follow the one you picked above.

import { fetch, ProxyAgent } from "undici";

const PROXY = "http://resi-lx_k3m9q2p7xa:[email protected]:7777";

// undici keeps a connection open and reuses it, and one connection is one IP:
// a new ProxyAgent per request opens a new connection, so a new IP
async function getWithNewIp(url) {
  const proxy = new ProxyAgent(PROXY);
  try {
    const r = await fetch(url, { dispatcher: proxy });
    return await r.json();
  } finally {
    await proxy.close();
  }
}

for (let i = 0; i < 3; i++) {
  console.log((await getWithNewIp("https://api.ludaxproxy.com/whoami")).ip);
}

import axios from "axios";

const proxy = {
  protocol: "http",
  host: "gw.ludaxproxy.com",
  port: 7777,
  auth: { username: "resi-lx_k3m9q2p7xa", password: "YOUR_PASSWORD-country-us" },
};

// axios opens a new connection for every request, so every request gets a new IP
for (let i = 0; i < 3; i++) {
  const r = await axios.get("https://api.ludaxproxy.com/whoami", { proxy });
  console.log(r.data.ip);
}

203.0.113.24
198.51.100.7
192.0.2.66

import { fetch, ProxyAgent } from "undici";
import { randomBytes } from "node:crypto";

// one token = one IP, kept for 30 minutes; a new token = a new IP
const token = randomBytes(4).toString("hex");
const proxy = new ProxyAgent(
  `http://resi-lx_k3m9q2p7xa:YOUR_PASSWORD-session-${token}[email protected]:7777`,
);

for (const step of ["login", "search", "checkout"]) {
  const r = await fetch("https://api.ludaxproxy.com/whoami", { dispatcher: proxy });
  console.log(step, (await r.json()).ip);
}
await proxy.close();

import axios from "axios";
import { randomBytes } from "node:crypto";

// one token = one IP, kept for 30 minutes; a new token = a new IP
const token = randomBytes(4).toString("hex");
const client = axios.create({
  proxy: {
    protocol: "http",
    host: "gw.ludaxproxy.com",
    port: 7777,
    auth: {
      username: "resi-lx_k3m9q2p7xa",
      password: `YOUR_PASSWORD-session-${token}-time-30-country-us`,
    },
  },
});

for (const step of ["login", "search", "checkout"]) {
  const r = await client.get("https://api.ludaxproxy.com/whoami");
  console.log(step, r.data.ip);
}

login 203.0.113.24
search 203.0.113.24
checkout 203.0.113.24

import { fetch, ProxyAgent } from "undici";

// country, then state, then city: an IP in Munich, Germany
const proxy = new ProxyAgent(
  "http://resi-lx_k3m9q2p7xa:YOUR_PASSWORD-session-muc01-time-10-country-de-state-by-city-munich@gw.ludaxproxy.com:7777",
);

const r = await fetch("https://api.ludaxproxy.com/whoami", { dispatcher: proxy });
console.log(await r.json());
await proxy.close();

{ ip: '203.0.113.81', country: 'Germany', ... }

import axios from "axios";

const proxy = {
  protocol: "http",
  host: "gw.ludaxproxy.com",
  port: 7777,
  auth: { username: "resi-lx_k3m9q2p7xa", password: "YOUR_PASSWORD-country-us" },
};
const urls = Array.from({ length: 20 }, (_, n) => `https://api.ludaxproxy.com/whoami?page=${n}`);

// 5 requests at a time; each one leaves from its own IP
const ips = [];
for (let i = 0; i < urls.length; i += 5) {
  const batch = urls.slice(i, i + 5).map((url) => axios.get(url, { proxy, timeout: 30000 }));
  for (const r of await Promise.all(batch)) ips.push(r.data.ip);
}
console.log(ips.length, "requests from", new Set(ips).size, "IPs");

20 requests from 20 IPs

npm install axios socks-proxy-agent

import axios from "axios";
import { SocksProxyAgent } from "socks-proxy-agent";

// socks5h: the gateway resolves the hostname, so no DNS query leaves your machine
// Residential Premium over SOCKS5 (Residential: gw.ludaxproxy.com:7575)
const agent = new SocksProxyAgent(
  "socks5h://premi-lx_k3m9q2p7xa:[email protected]:1080",
);

const r = await axios.get("https://api.ludaxproxy.com/whoami", {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false,
});
console.log(r.data);

import { fetch, ProxyAgent } from "undici";

const PROXY = "http://resi-lx_k3m9q2p7xa:[email protected]:7777";

// the real reason sits at the end of the error's cause chain
function proxyStatus(error) {
  for (let e = error; e; e = e.cause) {
    const m = /Proxy response \((\d{3})\)/.exec(e.message ?? "");
    if (m) return Number(m[1]);
  }
  return null;
}

// retry a dropped exit (502), stop at once on a refused login (407)
async function get(url, tries = 3) {
  for (let attempt = 1; ; attempt++) {
    const proxy = new ProxyAgent(PROXY);
    try {
      return await (await fetch(url, { dispatcher: proxy })).json();
    } catch (error) {
      if (proxyStatus(error) === 407 || attempt === tries) throw error;
      await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** (attempt - 1)));
    } finally {
      await proxy.close();
    }
  }
}

console.log(await get("https://api.ludaxproxy.com/whoami"));

import axios from "axios";

const proxy = {
  protocol: "http",
  host: "gw.ludaxproxy.com",
  port: 7777,
  auth: { username: "resi-lx_k3m9q2p7xa", password: "YOUR_PASSWORD-country-us" },
};

// retry a dropped exit (502) or a timeout, stop at once on a refused login (407)
async function get(url, tries = 3) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await axios.get(url, { proxy, timeout: 30000 });
    } catch (error) {
      const status = error.response?.status;
      const retry = status === 502 || error.code === "ECONNABORTED" || error.code === "ECONNRESET";
      if (!retry || attempt === tries) throw error;
      await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** (attempt - 1)));
    }
  }
}

console.log((await get("https://api.ludaxproxy.com/whoami")).data);

Node.js proxy errors, client by client

The exact message each client shows, what it means and the one thing to do. All gateway answers: status codes.

Questions Node.js developers ask about proxies

Short answers. The full option list is in proxy authentication.

Other ways to use Ludax

The products behind the code, and guides for the jobs Node.js developers run on them.

• Residential proxiesReal home IPs in 137 countries, rotating or sticky.
• Residential TLS proxiesHome IPs plus 139 browser TLS fingerprints, made at the gateway.
• Puppeteer guideThe same proxies in a headless Chrome, for pages that need JavaScript.
• Playwright guideOne IP per browser context, in Node.js and three more languages.
• Proxy authenticationThe username and password format, and every 407.
• Web scraping with residential proxiesRotation, sessions and plans for scrapers at scale.