How to use proxies in Node.js with fetch and axios

• An active CleanProxies plan: static ISP proxies for fixed US IPs, or rotating residential / mobile proxies for pools. The trial works too.
• Your credential line from the dashboard's proxy manager: host (or IP), port, username and password.
• Node.js 20 or later (22.21+ or 24+ for the built-in environment-variable proxy support).
• npm install undici for fetch, or npm install axios (add socks-proxy-agent for SOCKS5).

New to proxies? For the overview, read Using proxies with cURL, Python and Node.js and SOCKS5 vs HTTP proxies. This guide goes deeper on Node.js only.

Most tools want the same details as a URL: http://USERNAME:PASSWORD@HOST:PORT for HTTP(S) or socks5://USERNAME:PASSWORD@HOST:PORT for SOCKS5. The examples on this page use those placeholders; copy the host, port, username and password from your CleanProxies dashboard. To convert a whole list at once, paste it into the proxy list formatter.

1. 1

   Install the client

   Run npm install undici (and/or axios). Import fetch from undici too, so the agent and fetch come from the same version.
2. 2

   Create the proxy agent

   Pass http://USERNAME:PASSWORD@HOST:PORT to new ProxyAgent(...). Credentials in the URL are sent as Proxy-Authorization.
3. 3

   Send the request

   Call fetch(url, { dispatcher }), or set it globally with setGlobalDispatcher(dispatcher).
4. 4

   Check the exit IP

   Fetch https://api.ipify.org and log the text.

import { fetch, ProxyAgent } from "undici";

const dispatcher = new ProxyAgent("http://USERNAME:PASSWORD@HOST:PORT");

const res = await fetch("https://api.ipify.org", { dispatcher });
console.log("Exit IP:", await res.text());

export HTTPS_PROXY="http://USERNAME:PASSWORD@HOST:PORT"
export NO_PROXY="localhost,127.0.0.1"
NODE_USE_ENV_PROXY=1 node app.mjs

With NODE_USE_ENV_PROXY=1 (or the --use-env-proxy flag on newer releases), Node's own http, https and global fetch read HTTP_PROXY, HTTPS_PROXY and NO_PROXY. Node marks the feature as under active development, so the explicit agent is the safer choice for production.

import axios from "axios";

const { data } = await axios.get("https://api.ipify.org", {
  proxy: {
    protocol: "http",
    host: "HOST",
    port: PORT,
    auth: { username: "USERNAME", password: "PASSWORD" },
  },
  timeout: 30_000,
});
console.log(data);

import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const agent = new HttpsProxyAgent("http://USERNAME:PASSWORD@HOST:PORT");
const { data } = await axios.get("https://api.ipify.org", { httpsAgent: agent, proxy: false });

Before 1.16.1, axios could send https:// requests to an HTTP proxy without a proper CONNECT tunnel. Upgrade, or use an agent with proxy: false as shown.

axios has no SOCKS support of its own; hand it an agent. Use socks5h:// so the proxy resolves hostnames.

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

const agent = new SocksProxyAgent("socks5h://USERNAME:PASSWORD@HOST:PORT");
const { data } = await axios.get("https://api.ipify.org", {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false,
});
console.log(data);

Recent undici releases also accept socks5:// URLs in ProxyAgent through an experimental SOCKS5 agent; it prints an ExperimentalWarning, so prefer HTTP(S) with fetch in production.

Run node proxy-fetch.mjs. It prints the exit IP, which should match your dashboard line (ISP) or a residential IP in the location you generated.

Open What is my IP? through the proxy to see the address and headers a website receives, or paste up to ten lines into the free proxy checker to test connectivity, latency and exit IP before you start.

Still stuck? Our 24/7 support team answers fast: contact us with the error and the line you used (leave the password out).