Integration · Node.js
Use RoProxy with Node.js
A proxy from RoProxy is a username, a password, a gateway host and an HTTP port, plus a SOCKS5 port on the Pro and Business plans. Node's built-in fetch ignores proxies unless you hand it a dispatcher, so this guide shows the setups that work today: undici's ProxyAgent for fetch, https-proxy-agent for axios, socks-proxy-agent for the SOCKS5 port, and Node's own environment-variable support. It ends with a helper that asks the RoProxy API for a new IP when a target starts answering 403 or 429.
What you need
Copy the proxy's connection string from the dashboard: it comes as GATEWAY_HOST:HTTP_PORT:USERNAME:PASSWORD. Each proxy has its own credentials, so a worker that needs its own IP needs its own proxy.
Install only what your client needs: undici for fetch, https-proxy-agent for axios, socks-proxy-agent for the SOCKS5 port.
fetch
Use undici's own fetch with a ProxyAgent: the credentials in the proxy URL become the Proxy-Authorization header. HTTPS targets go through the HTTP port with a CONNECT tunnel.
// npm install undici
import { ProxyAgent, fetch } from "undici"
const proxy = new ProxyAgent("http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT")
const res = await fetch("https://api.ipify.org?format=json", { dispatcher: proxy })
console.log(await res.json())axios
Give axios an agent for HTTPS targets and turn off its own proxy handling, which would otherwise try to apply the proxy a second time.
// npm install axios https-proxy-agent
import axios from "axios"
import { HttpsProxyAgent } from "https-proxy-agent"
const agent = new HttpsProxyAgent("http://USERNAME:PASSWORD@GATEWAY_HOST:HTTP_PORT")
const { data } = await axios.get("https://api.ipify.org?format=json", {
httpsAgent: agent,
proxy: false,
})
console.log(data)SOCKS5
For tools that only speak SOCKS, use the SOCKS5 port of a Pro or Business proxy. It carries TCP connections only, and socks5h:// lets the proxy resolve hostnames.
// npm install socks-proxy-agent
import https from "node:https"
import { SocksProxyAgent } from "socks-proxy-agent"
const agent = new SocksProxyAgent("socks5h://USERNAME:PASSWORD@GATEWAY_HOST:SOCKS5_PORT")
https.get("https://api.ipify.org?format=json", { agent }, (res) => {
let body = ""
res.on("data", (chunk) => (body += chunk))
res.on("end", () => console.log(body))
})Rotate the IP from your code
Create an API key in the dashboard and ask for a new IP when a site starts blocking the current one. Free proxies cannot be rotated by hand: their IP changes every 10 minutes on its own. On Pro and Business a manual rotation waits 30 seconds after the previous one; calling earlier returns 429.
const API = "https://backend-api.ro-proxy.com"
async function rotate(sessionId) {
const res = await fetch(`${API}/api/session/${sessionId}/rotate`, {
method: "POST",
headers: { Authorization: "Bearer API_KEY" },
})
if (!res.ok) throw new Error(`rotate failed: ${res.status}`)
return (await res.json()).data.proxy_ip
}
console.log(await rotate(SESSION_ID))Errors and retries
407 Proxy Authentication Required
The username or password is wrong, or the proxy has expired. Copy the connection string again from the dashboard.
ECONNRESET and timeouts
Retry with exponential backoff; on a sticky proxy, rotate the IP after several failures in a row.
429 from the rotate endpoint
The plan's wait between manual rotations (30 seconds) has not passed yet. Wait, or switch the proxy to timed rotation.
403 from the rotate endpoint
The proxy is on the Free plan, which does not rotate by hand: its IP changes every 10 minutes on its own.
Frequently asked questions
Why not pass the proxy URL straight to fetch?
Node's built-in fetch ignores proxy settings unless you give it a dispatcher such as undici's ProxyAgent, or start Node with NODE_USE_ENV_PROXY=1 on a version that supports it.
Does HTTPS work through the HTTP port?
Yes. The client opens a CONNECT tunnel through the HTTP port, and TLS runs between your code and the website.
Can I keep the same IP across requests?
Yes. Put the proxy in sticky mode in the dashboard or with the API; the IP changes only when you rotate it, the proxy expires or the IP behind it stops working.
How do I use several IPs at once?
Use several proxies: each has its own credentials and IP, so give each worker its own ProxyAgent.