Back to SDK Overview
npmLanguages & HTTP ClientsMIT

Node.js & TypeScript proxy SDK

A tiny, dependency-free Node/TypeScript SDK for aethyn.io residential proxies. Build correct proxy URLs with country / city / sticky-session / lifetime targeting and hand them straight to got, axios, fetch, Playwright, or Puppeteer — without hand-assembling fragile username strings. Ships types; works in ESM and CommonJS.

Install

Add proxy-builder-sdk to your project.

Install
npm install proxy-builder-sdk
npm alias
npm install aethyn-proxy

Same package, re-exported for backward compatibility. import { AethynClient } from "aethyn-proxy" still works.

Ports

The SDK picks the correct port from your tier and protocol automatically.

TierHTTPSOCKS5
Premium20991099
Elite54993499

White-label? Pass host: "gate.example.com" to the client constructor.

Usage

Copy-paste examples for common patterns.

Quickstart
import { AethynClient } from "proxy-builder-sdk";

const client = new AethynClient({ username: "aethyn-XXXXX", password: "PASSWORD" });
// or set AETHYN_USERNAME / AETHYN_PASSWORD

const p = client.proxy({ country: "us" });

// rotating residential exit in the US
const res = await fetch("https://api.ipify.org?format=json", {
  // node fetch via undici ProxyAgent, got { proxy: p.url }, axios, etc.
});

See Authentication & credentials

Sticky sessions
const p = client.session({ country: "de", session: "cart42", ttl: 10 }); // same IP for 10 min
// p.username -> "aethyn-XXXXX-country-de-session-cart42-lifetime-10"
  • ttl is minutes (1–1440).
  • Omit session for per-request rotation (the default).

See Sticky sessions glossary

Elite targeting (city / ISP)
const p = client.session({ country: "us", city: "chicago", isp: "comcast", session: "run1", ttl: 30, tier: "elite" });
// city, state, isp, and zip are Elite-only — SDK throws a clear error if you pass them on Premium

See Targeting reference

got / axios
import got from "got";

const p = client.proxy({ country: "gb" });
await got("https://example.com", { proxy: p.url });

See Node.js (Axios) integration

Playwright / Puppeteer
import { chromium } from "playwright";

const p = client.session({ country: "fr", session: "s1", ttl: 15, tier: "elite" });
const browser = await chromium.launch({ proxy: p.forPlaywright() });

See Playwright integration

SOCKS5
const p = client.proxy({ country: "jp", protocol: "socks5" });
// socks5://...@proxy.aethyn.io:1099

See HTTP vs SOCKS5 protocols

Return value reference
const p = client.session({ country: "us", session: "run1", ttl: 10 });

p.username;          // "aethyn-XXXXX-country-us-session-run1-lifetime-10"
p.host; p.port;      // "proxy.aethyn.io", 2099
p.url;               // "http://aethyn-XXXXX-...:PASSWORD@proxy.aethyn.io:2099"
p.proxies;           // { http, https }
p.forPlaywright();   // { server, username, password }
String(p);           // password-redacted, safe to log

Other providers

Aethyn is the default, but the same clean API drives other big residential providers too — use ProxyClient with a provider:

Other providers (ProxyClient)
import { ProxyClient } from "proxy-builder-sdk";

// Oxylabs — the SDK emits customer-...-cc-us-sessid-run1-sesstime-10
const p = new ProxyClient({ username: "customer-me", password: "pw", provider: "oxylabs" })
  .session({ country: "us", session: "run1", ttl: 10 });
ProviderGatewayNotes
aethyn (default)proxy.aethyn.ioPremium/Elite tiers, city/ISP/state/zip
brightdatabrd.superproxy.iopass brd-customer-<id>-zone-<zone> as the username
oxylabspr.oxylabs.iocc/sessid/sesstime; state as us_california
smartproxy / decodogate.decodo.comsessionduration (minutes)
iproyalgeo.iproyal.comtargeting goes in the password
soaxproxy.soax.com⚠️ community-verified; lifetime in seconds
netnutgw.netnut.netcountry + sticky session only

Every non-Aethyn dialect was verified against the provider's official docs (each provider file records the source URL and a confidence level). SOAX is medium confidence — sanity-check it against SOAX's current docs before you lean on it. Each provider maps the same semantic call (country, city, state, session, ttl) to its own username/password format and throws a clear error for anything it can't express.

Tips
  • Set AETHYN_USERNAME and AETHYN_PASSWORD env vars instead of hardcoding credentials.
  • String(p) is safe to log — the password is redacted.
  • Self-hosting or white-labeling? Pass host: "gate.example.com" to the client constructor.

FAQ

Do I need the SDK to use Aethyn?
No. Aethyn speaks standard username:password@host:port proxy auth. The SDK is optional — it builds correct targeting strings for you so you don't hand-assemble fragile usernames.
What's the difference between proxy-builder-sdk and aethyn-proxy?
aethyn-proxy is a thin npm alias that re-exports proxy-builder-sdk. Install either one; new code should prefer proxy-builder-sdk.
Which port does the SDK pick?
Premium HTTP 2099, Premium SOCKS5 1099, Elite HTTP 5499, Elite SOCKS5 3499. The SDK selects the right port from your tier and protocol.
Can I use city or ISP targeting on Premium?
No. city, state, isp, and zip are Elite-only. The SDK validates this and throws a clear error if you pass them on Premium.
What is the ttl range for sticky sessions?
ttl is in minutes, from 1 to 1440. Omit session for per-request rotation — that is the default when you call client.proxy().
Does it support other proxy providers?
Yes. Use ProxyClient with a provider param (oxylabs, brightdata, smartproxy, iproyal, soax, netnut). Aethyn is the default.

Ready to ship with Node.js & TypeScript?

Get your credentials and route your first proxied request through residential IPs in minutes.

Docs, integrations & blog

All SDKs

License: MIT