ProxyMonkey
DiscordStart with $5
Start $5
JavaScript · setup guide

Axios proxy setup

An Axios proxy can be set two ways: its own proxy option, or proxy: false with an agent from https-proxy-agent. The agent route behaves the same on every Axios release and gives you control of keep-alive, so this page uses it; the built-in option is in the tips.
You will need

Residentialresi.proxymonkey.io:8000

ISP or datacenterIP:PORT

CredentialsUSER:PASS

Copy your own from the dashboard, which also lists the host and port for every order. Where it differs from this page, the dashboard is right.

Install

Node.js 18 or newer. The examples are ES modules, so save them as .mjs files.

terminal
npm i axios https-proxy-agent

Rotating residential

An agent with keep-alive off opens a new CONNECT tunnel for every request, and each new tunnel through the residential gateway leaves from a new address. proxy: false stops Axios applying its own proxy handling, including any https_proxy in the environment, on top of the agent.

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

const client = axios.create({
  httpsAgent: new HttpsProxyAgent("http://USER:[email protected]:8000", { keepAlive: false }),
  proxy: false,
  timeout: 30000,
});

for (let i = 0; i < 3; i++) {
  const { data } = await client.get("https://httpbin.org/ip");
  console.log(data.origin);
}

A static datacenter or ISP IP

On a static datacenter IP, turn keep-alive on so requests reuse a tunnel, and cap the sockets the agent may open. For an ISP order, use the host and port from your dashboard.

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

const client = axios.create({
  httpsAgent: new HttpsProxyAgent("http://USER:PASS@IP:PORT", { keepAlive: true, maxSockets: 8 }),
  proxy: false,
  timeout: 30000,
});

for (const url of ["https://httpbin.org/ip", "https://httpbin.org/headers"]) {
  const res = await client.get(url);
  console.log(res.status, JSON.stringify(res.data).slice(0, 80));
}

Keeping one identity

Axios keeps no connection state of its own; the agent does. With keepAlive: true, sequential requests to one host reuse a tunnel and keep its address while the socket stays open, which covers a short burst. Axios in Node also keeps no cookies, so a login flow needs a cookie jar and a stable address: a static IP, or a residential sticky session whose setting for your account is in the dashboard.

Specific to Axios

Things worth knowing

The built-in Axios proxy option

Axios can also take the proxy as an object. Its current README says that for https:// targets it opens a CONNECT tunnel and runs TLS end to end with the site; older releases forwarded HTTPS requests in a way many gateways reject, which is where the agent advice comes from. Credentials go in auth, not in the host.

builtin.mjs
const res = await axios.get("https://httpbin.org/ip", {
  proxy: {
    protocol: "http",
    host: "resi.proxymonkey.io",
    port: 8000,
    auth: { username: "USER", password: "PASS" },
  },
});

Plain http:// targets need their own agent

httpsAgent only handles https:// URLs. An http:// URL goes through httpAgent, and with proxy: false and no agent there it leaves from your own address. http-proxy-agent is the matching package.

both.mjs
import { HttpProxyAgent } from "http-proxy-agent";
import { HttpsProxyAgent } from "https-proxy-agent";

const client = axios.create({
  httpAgent: new HttpProxyAgent("http://USER:[email protected]:8000"),
  httpsAgent: new HttpsProxyAgent("http://USER:[email protected]:8000"),
  proxy: false,
});

Tally request and response bytes

We meter request bytes plus response bytes, headers included. Ask Axios for the raw body with decompression off, then add the header sizes. _header is a Node internal holding the request head as sent: fine for a check, not for production code. TLS overhead makes our figure slightly higher.

bytes.mjs
const res = await client.get("https://example.com/", {
  responseType: "arraybuffer",
  decompress: false,
});
const sent = Buffer.byteLength(res.request._header);
const received =
  res.request.res.rawHeaders.reduce((n, s) => n + Buffer.byteLength(s) + 2, 0) +
  res.data.byteLength;
console.log(sent, received);
When it breaks

Common errors and fixes

  • AxiosError: Request failed with status code 407

    Why
    The gateway rejected the credentials. https-proxy-agent hands the proxy's 407 reply back as the response, so it surfaces like any other failed status.
    Fix
    Check the pair against the dashboard and wrap each part in encodeURIComponent before putting it in the URL.

  • AxiosError: Request failed with status code 400 on every HTTPS URL

    Why
    Usually an older Axios using its built-in proxy option, which forwarded the HTTPS request instead of tunnelling it.
    Fix
    Switch to proxy: false with an HttpsProxyAgent, or upgrade Axios.

  • AxiosError: timeout of 30000ms exceeded

    Why
    No response within timeout. Without one, Axios waits indefinitely on a stalled exit.
    Fix
    Keep timeout set, retry on ECONNABORTED and ETIMEDOUT, and on the rotating gateway the retry opens a new tunnel from a new address.

  • Error: unable to get local issuer certificate

    Why
    The target's certificate chain, or a corporate CA your system trusts and Node does not. TLS runs inside the tunnel; the proxy does not touch it.
    Fix
    Add the CA with NODE_EXTRA_CA_CERTS. Keep rejectUnauthorized: false out of anything you ship.

A failed connection that moved no data is not billed. Retries you send are billed like any other request, and each shows as its own line in your usage log.

Other setup guides

Start with $5All guides

Axios is named here only to say what this guide covers. We are not affiliated with its authors.

The community layer

Axios still misbehaving?

Paste the error and the few lines that set up the proxy into Discord, with the password taken out. Someone there has seen it before.

Join the Discord

4,200+monkeys in the Discord

  • Help from humans

    Post your error, get an answer. Usually in minutes, usually from someone who has hit the same wall.

  • A status bot that tells on us

    Pool health, incidents and maintenance posted automatically. Including the bad days.

  • Deals and free traffic

    Bonus GB drops, early access to new pools, and the occasional giveaway for a good bug report.

Join the Discord4,200+ monkeys, free to lurk