The official Node.js/TypeScript SDK for the ProxyHat residential proxy API.
Tip
Recommended proxies — ProxyHat residential IPs. Every feature in this package is tested end-to-end against ProxyHat and works great. First-class integration; also works with any proxy, or none.
- One-call proxy connection —
client.connectionUrl()turns your API key into a ready-to-use residential proxy URL - Full coverage of the ProxyHat API
- Local gateway URL builder (
buildConnectionUrl) — no network needed - TypeScript types for all API responses
- Native
fetch— no external HTTP dependencies - Comprehensive error handling with typed exceptions
- Pagination support for location endpoints
npm install proxyhatimport{ProxyHat}from"proxyhat";constclient=newProxyHat({apiKey: "ph_your_api_key"});// List sub-usersconstusers=awaitclient.sub_users.list();for(constuserofusers){console.log(user.proxy_username,user.lifecycle_status);}// Create a sub-userconstnewUser=awaitclient.sub_users.create({proxy_password: "secure_pass",is_traffic_limited: true,traffic_limit: "5GB",name: "Scraper",});console.log(newUser.uuid);From an API key to actually routing traffic in one call — the SDK looks up an active sub-user and builds the gateway URL for you:
import{ProxyHat}from"proxyhat";constproxy=newProxyHat({apiKey: "ph_your_api_key"});// Rotating residential IP, US exit:consturl=awaitproxy.connectionUrl({country: "us"});// → http://<user>-country-us:<pass>@gate.proxyhat.com:8080// Sticky session (same IP for 30m), city-targeted, SOCKS5:conststicky=awaitproxy.connectionUrl({country: "de",city: "berlin",sticky: "30m",protocol: "socks5",});Use the URL with any HTTP client (undici, axios, Playwright, curl…).
Offline builder — if you already have a sub-user's proxy_username / proxy_password, build the URL with no network call:
import{buildConnectionUrl}from"proxyhat";consturl=buildConnectionUrl({username: "ph-8f2a1c",password: "PxSecret123",country: "gb",filter: "high",// AI IP-quality tier});Server-built descriptor — let the API assemble it (validates the sub-user is active):
constd=awaitproxy.proxy_descriptors.create({sub_user_uuid: user.uuid,protocol: "http",location: {country: "us",city: "new_york"},session: {mode: "sticky",ttl: "30m"},});console.log(d.url);Get your API key from the ProxyHat Dashboard.
See the Authentication Guide for details.
| Resource | Methods |
|---|---|
client.auth | register, login, user, logout, supported_providers, social_accounts, disconnect_social, oauth_redirect |
client.sub_users | list, create, get, update, delete, reset_usage, bulk_delete, bulk_move_to_group |
client.sub_user_groups | list, create, get, update, delete |
client.locations | countries, regions, cities, isps, zipcodes |
client.analytics | traffic, traffic_total, requests, requests_total, domain_breakdown |
client.proxy_presets | list, create, get, update, delete |
client.proxy_descriptors | create |
client.connectionUrl(opts) | build a ready proxy URL from an active sub-user |
client.profile | get_preferences, update_preferences, list_api_keys, create_api_key, delete_api_key, regenerate_api_key |
client.two_factor | status, enable, confirm, disable, qr_code, recovery_codes, disable_by_recovery, change_password |
client.email | request_change, confirm_change, cancel_change, resend_verification |
client.coupons | validate, apply, redeem |
client.plans | list_regular, list_subscriptions, get_regular, get_subscription, pricing_regular, pricing_subscriptions |
client.payments | list, create, get, check, invoice, cryptocurrencies |
import{ProxyHat,ProxyHatError,NotFoundError,RateLimitError,ValidationError,}from"proxyhat";constclient=newProxyHat({apiKey: "ph_your_api_key"});try{constuser=awaitclient.sub_users.get("nonexistent-id");}catch(e){if(einstanceofNotFoundError){console.log(`Not found: ${e.message}`);}elseif(einstanceofRateLimitError){console.log(`Rate limited. Retry after ${e.retryAfter}s`);}elseif(einstanceofValidationError){console.log(`Validation failed: ${e.errors}`);}elseif(einstanceofProxyHatError){console.log(`API error ${e.statusCode}: ${e.message}`);}}See the Error Handling Guide for the full list of error codes.
- ProxyHat — Residential & mobile proxy network
- Dashboard — Manage proxies, sub-users, and API keys
- GitHub — Source code & issue tracker
MIT — see LICENSE for details.