Node.js (axios, got, fetch)

Configuring a Node.js proxy is different from most languages: most Node HTTP libraries reach a proxy through a connection agent (for axios, got, and node-fetch) or a dispatcher (for native fetch/undici). Node.js 24.5+ (and 22.21+ on the 22.x line) also includes built-in proxy support for HTTP and HTTPS proxy URLs (--use-env-proxy, NODE_USE_ENV_PROXY=1, or a proxyEnv option on http.Agent), which Node still marks as active development and which does not cover SOCKS5. The examples below configure each client explicitly, with an agent or, for native fetch, a dispatcher; the agent examples also cover SOCKS5. This page shows how to route axios, got, native fetch, and node-fetch through your ColdProxy gateway with username/password auth, plus the SOCKS5 path and the IP-whitelist alternative. New to proxy auth? See username/password vs IP whitelisting.

Your gateway host is gw-{service-id}.coldproxy.com; every example uses gw-2312.coldproxy.com (replace 2312 with your service/package ID) and a port in the 30000-34999 range (we use 30000 below). Your full proxy string is:

gw-2312.coldproxy.com:30000:USERNAME:PASSWORD

#Install the Node.js proxy agents

ColdProxy auto-detects HTTP, HTTPS, and SOCKS5 on the same gateway port, so the package you install depends only on the client and protocol you prefer.

# HTTP/HTTPS proxying for axios, got, and node-fetch
npm install https-proxy-agent

# got's preferred keep-alive proxy agent
npm install hpagent

# SOCKS5 (works with axios and node-fetch)
npm install socks-proxy-agent

# native fetch dispatcher (undici's ProxyAgent)
npm install undici

These examples need Node.js 22.19 or later, because undici 8 requires it. They use ES modules and top-level await, and got 16, https-proxy-agent 9, socks-proxy-agent 10, and node-fetch 3 ship as ES modules only, so save the examples as .mjs files or set "type": "module" in your package.json.

Node's global fetch needs no install, but to set a proxy per request you import ProxyAgent from undici, which must be installed explicitly. Node bundles undici internally to power fetch, yet does not expose ProxyAgent for application imports.

#axios with https-proxy-agent

axios 1.16.1 and later tunnel HTTPS targets through the built-in proxy option with an HTTP CONNECT request; older versions do not. The approach below works on every axios version: build an HttpsProxyAgent, pass it as httpsAgent, and set proxy: false so axios does not also try to apply its own proxy logic. The current package uses a named export.

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

const proxyUrl =
  "http://USERNAME:PASSWORD@gw-2312.coldproxy.com:30000"
const agent = new HttpsProxyAgent(proxyUrl)

const { data } = await axios.get("https://api.vipv6proxy.com/api/checker/my-ip", {
  httpsAgent: agent,
  httpAgent: agent, // also route plain-HTTP targets through the proxy
  proxy: false, // let the agent own proxying
})

console.log(data.ip) // the response is JSON: { ip, version, country, city, ... }

#Rotating vs sticky (axios)

ColdProxy encodes geo-targeting and session behavior in the username using a tag grammar: user-key-value-key-value... (full reference: Username tag scheme). With no session tag, each request can exit from a fresh IP (rotating). To hold one IP, add both a session tag and a time/duration tag together.

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

const HOST = "gw-2312.coldproxy.com"
const PORT = 30000
const PASS = "PASSWORD"

// Rotating: US exit, new IP per request
const rotatingUser = "user-country-us"
const rotating = new HttpsProxyAgent(
  `http://${rotatingUser}:${PASS}@${HOST}:${PORT}`
)

// Sticky: US exit, same IP held for 10 minutes (session + time together)
const stickyUser = "user-country-us-session-481516-time-10m"
const sticky = new HttpsProxyAgent(
  `http://${stickyUser}:${PASS}@${HOST}:${PORT}`
)

await axios.get("https://api.vipv6proxy.com/api/checker/my-ip", { httpsAgent: rotating, proxy: false })
await axios.get("https://api.vipv6proxy.com/api/checker/my-ip", { httpsAgent: sticky, proxy: false })

#got with hpagent

got takes proxy support through its agent option, with separate entries for http and https targets. hpagent is the recommended keep-alive agent and uses a named HttpsProxyAgent export with a proxy field.

import got from "got"
import { HttpProxyAgent, HttpsProxyAgent } from "hpagent"

const proxyUrl =
  "http://USERNAME:PASSWORD@gw-2312.coldproxy.com:30000"

const response = await got("https://api.vipv6proxy.com/api/checker/my-ip", {
  agent: {
    http: new HttpProxyAgent({ proxy: proxyUrl }),
    https: new HttpsProxyAgent({ proxy: proxyUrl }),
  },
}).json()

console.log(response)

For a sticky session with got, build the proxy URL with the session and time tags in the username, exactly as in the axios rotating-vs-sticky example above:

import got from "got"
import { HttpsProxyAgent } from "hpagent"

const stickyUrl =
  "http://user-country-us-session-481516-time-10m:PASSWORD@gw-2312.coldproxy.com:30000"

const body = await got("https://api.vipv6proxy.com/api/checker/my-ip", {
  agent: { https: new HttpsProxyAgent({ proxy: stickyUrl }) },
}).json()

#Native fetch (undici ProxyAgent)

Node's built-in fetch (available without a flag since Node 18, stable since Node 21) is backed by undici. Route it through a proxy with a ProxyAgent dispatcher. Pass credentials with the token option as an HTTP Basic header; an explicit token avoids URL-encoding mistakes in usernames that carry tags.

import { ProxyAgent } from "undici"

const auth = Buffer.from("USERNAME:PASSWORD").toString("base64")

const proxyAgent = new ProxyAgent({
  uri: "http://gw-2312.coldproxy.com:30000",
  token: `Basic ${auth}`,
})

const res = await fetch("https://api.vipv6proxy.com/api/checker/my-ip", {
  dispatcher: proxyAgent,
})

console.log(await res.json())

For rotating vs sticky, change the username you encode into the token:

import { ProxyAgent } from "undici"

function proxyAgentFor(username, password) {
  const token = Buffer.from(`${username}:${password}`).toString("base64")
  return new ProxyAgent({
    uri: "http://gw-2312.coldproxy.com:30000",
    token: `Basic ${token}`,
  })
}

const rotating = proxyAgentFor("user-country-us", "PASSWORD")
const sticky = proxyAgentFor("user-country-us-session-481516-time-10m", "PASSWORD")

await fetch("https://api.vipv6proxy.com/api/checker/my-ip", { dispatcher: rotating })
await fetch("https://api.vipv6proxy.com/api/checker/my-ip", { dispatcher: sticky })

#node-fetch via agent

If you are still on node-fetch, it does not accept undici dispatchers. Use the agent option with https-proxy-agent instead.

import fetch from "node-fetch"
import { HttpsProxyAgent } from "https-proxy-agent"

const agent = new HttpsProxyAgent(
  "http://USERNAME:PASSWORD@gw-2312.coldproxy.com:30000"
)

const res = await fetch("https://api.vipv6proxy.com/api/checker/my-ip", { agent })
console.log(await res.json())

#SOCKS5 with socks-proxy-agent

The same ColdProxy gateway port serves SOCKS5 (over TCP and UDP). Use socks-proxy-agent and the socks5h:// scheme so DNS is resolved at the proxy exit, which keeps your real resolver out of the request. The agent works as both httpAgent and httpsAgent in axios and as the agent in node-fetch.

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

// socks5h:// = remote DNS resolution at the proxy exit
const agent = new SocksProxyAgent(
  "socks5h://USERNAME:PASSWORD@gw-2312.coldproxy.com:30000"
)

const { data } = await axios.get("https://api.vipv6proxy.com/api/checker/my-ip", {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false, // let the agent own proxying
})

console.log(data)

Sticky and geo tags work identically over SOCKS5; they live in the username, so socks5h://user-country-us-session-481516-time-10m:PASSWORD@gw-2312.coldproxy.com:30000 pins a US exit for the session. See SOCKS5 vs HTTPS proxies and TCP vs UDP transport support to choose the right transport.

#IP whitelist (no credentials in code)

Instead of putting USERNAME:PASSWORD in your source, you can authorize the server's public IP. Add up to 50 IPs to your authorized list in the client area (or through the plan API), and ColdProxy will accept unauthenticated requests from those IPs. Drop the credentials from any example above:

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

// No user:pass — the request source IP is whitelisted
const agent = new HttpsProxyAgent(
  "http://gw-2312.coldproxy.com:30000"
)

const { data } = await axios.get("https://api.vipv6proxy.com/api/checker/my-ip", {
  httpsAgent: agent,
  proxy: false,
})

#Next steps

• Confirm a working proxy and its exit location with the proxy checker and my IP.
• Getting a 407 Proxy Authentication Required? The credentials were rejected or omitted: re-check the username tags and password, then see Common errors & fixes.
• Using IPv6? Many sites are IPv4-only; check a target with the IPv6 checker before relying on an IPv6 plan.
• Learn the tag grammar in depth: geo-targeting with proxies and rotating vs sticky sessions.
• Choose or upgrade a plan on the pricing and proxy product pages.