Integration · Node.js
Use RoProxy with Node.js
A RoProxy session 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 session's connection string from the dashboard: it comes as GATEWAY_HOST:HTTP_PORT:USERNAME:PASSWORD. Each session has its own credentials, so a worker that needs its own IP needs its own session.
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 session. 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 and Standard sessions have a short cooldown between manual rotations; 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 session has expired. Copy the connection string again from the dashboard.
ECONNRESET and timeouts
Retry with exponential backoff; on a sticky session, rotate the IP after several failures in a row.
429 from the rotate endpoint
The plan's cooldown between manual rotations has not passed yet. Wait, or switch the session to timed rotation.
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 session in sticky mode in the dashboard or with the API; the IP changes only when you rotate it, the session expires or the upstream proxy fails.
How do I use several IPs at once?
Use several sessions: each has its own credentials and IP, so give each worker its own ProxyAgent.