Development

Node.js Proxy Setup

Add SotaProxy to any Node.js HTTP client - fetch, axios, or got.

Node.js does not support proxy configuration natively through environment variables for all HTTP clients. Most libraries require a proxy agent - a small package that handles the connection tunneling.

Setup guide

Install https-proxy-agent

bash

npm install https-proxy-agent

The https-proxy-agent package creates proxy-aware HTTP agents for Node.js.

Native fetch (Node 18+)

javascript

import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl = 'http://YOUR_USERNAME:YOUR_PASSWORD@proxy.sotaproxy.com:10000';
const agent = new HttpsProxyAgent(proxyUrl);

const response = await fetch('https://httpbin.org/ip', { agent });
const data = await response.json();
console.log(data);

Node 18+ includes native fetch. Pass the proxy agent in the options object.

axios

javascript

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl = 'http://YOUR_USERNAME:YOUR_PASSWORD@proxy.sotaproxy.com:10000';
const httpsAgent = new HttpsProxyAgent(proxyUrl);

const response = await axios.get('https://httpbin.org/ip', { httpsAgent });
console.log(response.data);

Pass the proxy agent as httpsAgent in the axios config object.

got

javascript

import got from 'got';
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyUrl = 'http://YOUR_USERNAME:YOUR_PASSWORD@proxy.sotaproxy.com:10000';
const agent = { https: new HttpsProxyAgent(proxyUrl) };

const response = await got('https://httpbin.org/ip', { agent });
console.log(response.body);

got uses an agent object with http and https keys. Pass the proxy agent under the https key.

Automate it with the SotaProxy API

Everything above works without opening the dashboard. With an API key, Node.js can pull fresh proxy credentials, buy new proxies, and renew expiring ones - straight from code.

javascript

const API = 'https://api.sotaproxy.com/api/v1'
const H = { Authorization: 'Bearer sk_live_your_key' }

// Every active proxy on your account - no copy-pasting credentials
const { proxies } = await (await fetch(`${API}/proxies`, { headers: H })).json()
const p = proxies[0]
const proxyUrl = `http://${p.login}:${p.password}@${p.ip}:${p.portHttp}`

// Buy more when you scale (price-check first with POST /quote)
await fetch(`${API}/orders`, {
  method: 'POST',
  headers: { ...H, 'Content-Type': 'application/json', 'Idempotency-Key': 'my-unique-order-id' },
  body: JSON.stringify({ product: 'ipv4', countryId: 565, periodId: '1m', quantity: 5 }),
})

Read the API docs

Agents, not settings

Node has no global proxy switch. Every HTTP client takes an agent, and the agent carries the address and the credentials:

Rotating residential

Pinned to a country

login_c_US:password@proxy.sotaproxy.com:10000

Sticky for 15 minutes

login_c_US_s_42_ttl_15m:password@proxy.sotaproxy.com:10000

Static address (ISP, datacenter)

https-proxy-agent covers HTTP and HTTPS targets. socks-proxy-agent covers SOCKS5, and its socks5h equivalent resolves DNS on our side.

An agent per identity

Build the agent once per session id and reuse it. Creating one per request throws away connection reuse and slows the run:

Node: pooled agents with fetch

import { HttpsProxyAgent } from 'https-proxy-agent';

const BASE = 'proxy.sotaproxy.com:10000';
const agents = new Map();

function agentFor(sessionId, country = 'US') {
  if (!agents.has(sessionId)) {
    const login = `login_c_${country}_s_${sessionId}_ttl_15m`;
    agents.set(sessionId, new HttpsProxyAgent(`http://${login}:password@${BASE}`));
  }
  return agents.get(sessionId);
}

const res = await fetch('https://example.com', {
  agent: agentFor(4),
  headers: { 'Accept-Encoding': 'gzip' },
  signal: AbortSignal.timeout(30000),
});

Node 18 fetch ignores the agent option. Use undici with a ProxyAgent, or node-fetch, or axios with httpsAgent.
Always pass a timeout signal. Node will otherwise wait indefinitely on a stalled route.
Keep agents in a map keyed by session id. Rebuilding them per request costs a TLS handshake every time.
For SOCKS5 with remote DNS use socks5h in the URL, the same rule as everywhere else.

Node specifics

Global fetch quietly ignores agents

It is the most common confusion in Node 18 and later. The request goes out directly and looks like a proxy failure.

Agent per request

Each new agent opens a new connection to us. Under load this alone can halve your throughput.

No timeout by default

A single hung request holds a worker forever. AbortSignal.timeout is one line and prevents it.

Credentials in logs

The proxy URL contains the password. Strip it before logging, or a crash report leaks the account.

Notes & tips

•For geo-targeting, append _c_XX to the username in the proxy URL.
•Rotating happens server-side - you do not need to change the proxy URL between requests for IP rotation.
•Test connectivity: node -e "require('https-proxy-agent').HttpsProxyAgent; const {fetch} = globalThis; ..."

FAQ

Do I need a proxy agent package for Node.js?

Yes. Node.js native fetch and most HTTP libraries do not support proxy configuration through simple URL parameters. The https-proxy-agent package handles CONNECT tunneling for HTTPS requests.

Can I set the proxy via environment variables in Node.js?

Some libraries (like undici, axios with proxy plugin) support HTTPS_PROXY environment variable. Check your library's documentation. Using the agent approach works across all libraries without environment dependency.

Related integrations

Development

Python

Development

Playwright

Development

Puppeteer

Learn more

Proxy Server HTTP Proxy SOCKS5 Proxy Rotating Proxy Proxy Authentication

Get your proxy credentials

Get started