Axios proxy setup in Node.js with auth

Steps

1. Install axios and the agent

   npm ls shows which versions landed in node_modules. Note the axios number: it decides whether the built-in option in step 4 is safe to use for https.

   npm i axios https-proxy-agent
   npm ls axios https-proxy-agent

2. Pass the agent as httpsAgent, with proxy: false

   HttpsProxyAgent sends a CONNECT to the proxy with your login and runs TLS to the site inside that tunnel, so the proxy passes the page along without reading it. proxy: false tells axios to leave routing to the agent. Leave it out and an HTTPS_PROXY variable in your shell wins over the agent, which happened on both axios versions tested.

   import axios from 'axios';
   import { HttpsProxyAgent } from 'https-proxy-agent';
   
   const client = axios.create({
     httpsAgent: new HttpsProxyAgent('http://USERNAME:PASSWORD@HOST:PORT'),
     proxy: false,
     timeout: 30000,
   });
   
   const { data } = await client.get('https://api.ipify.org?format=json');
   console.log(data.ip);

3. Run the script and read the address

   node check-ip.mjs prints the ip field from api.ipify.org. It should match a proxy exit and differ from the address your own connection shows.

4. Use the built-in proxy option on axios 1.16.1 or newer

   Since 1.16.1, axios opens a CONNECT tunnel for https URLs by itself, with the login in auth. Up to 1.16.0 it sent the https request to the proxy as a plain GET carrying the full URL, which the proxy could read and which works only if the proxy agrees to fetch it. With an older axios, stay with the agent from step 2.

   import axios from 'axios';
   
   const { data } = await axios.get('https://api.ipify.org?format=json', {
     proxy: {
       protocol: 'http',
       host: 'HOST',
       port: PORT,
       auth: { username: 'USERNAME', password: 'PASSWORD' },
     },
     timeout: 30000,
   });
   console.log(data.ip);

5. Rotate over your static IPs, with a timeout that holds

   Save one proxy URL per line in proxies.txt, each built as http://USERNAME:PASSWORD@HOST:PORT for one of your IPs, and every request goes to the next client in turn. The axios timeout starts once the tunnel is up. When a proxy accepted the connection and then never answered the CONNECT, it did not fire in testing, so AbortSignal.timeout puts a ceiling on the whole request.

   import { readFileSync } from 'node:fs';
   import axios from 'axios';
   import { HttpsProxyAgent } from 'https-proxy-agent';
   
   const clients = readFileSync('proxies.txt', 'utf8')
     .split('\n')
     .map((line) => line.trim())
     .filter(Boolean)
     .map((proxy) =>
       axios.create({ httpsAgent: new HttpsProxyAgent(proxy), proxy: false, timeout: 30000 }),
     );
   
   const urls = Array(6).fill('https://api.ipify.org');
   
   for (const [i, url] of urls.entries()) {
     const client = clients[i % clients.length];
     try {
       const { data } = await client.get(url, { signal: AbortSignal.timeout(45000) });
       console.log(i, data);
     } catch (err) {
       console.log(i, err.code ?? err.message);
     }
   }

Common errors and fixes

Which line to pick

Axios jobs that call APIs or read pages from sites that accept server traffic run cheapest on datacenter IPs, and the rotation loop shares the load across every IP you rent. When a site starts refusing data-centre ranges, move that job to residential. If a script signs in to the same account day after day, give it an ISP IP.

Other setup guides

Not sure what a word means? The glossary explains it in plain English.