Back to SDK Overview
PyPILanguages & HTTP ClientsMIT

Python proxy SDK

A tiny, dependency-free Python SDK for aethyn.io residential proxies. Build correct proxy URLs with country / city / sticky-session / lifetime targeting and hand them straight to requests, httpx, Playwright, or Selenium — without hand-assembling fragile username strings.

Install

Add proxy-builder-sdk to your project.

Install
pip install proxy-builder-sdk
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 requests
from proxy_builder_sdk import AethynClient

client = AethynClient(username="aethyn-XXXXX", password="PASSWORD")
# or set AETHYN_USERNAME / AETHYN_PASSWORD

p = client.proxy(country="us")
r = requests.get("https://api.ipify.org?format=json", proxies=p.proxies)
print(r.json())

See Authentication & credentials

Sticky sessions
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).
  • Leave session off for per-request rotation (the default).

See Sticky sessions glossary

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

See Targeting reference

httpx
import httpx

p = client.proxy(country="gb")
with httpx.Client(proxy=p.url) as http:
    http.get("https://example.com")

See Python (Requests) integration

Playwright
from playwright.sync_api import sync_playwright

p = client.session(country="fr", session="s1", ttl=15, tier="elite")
with sync_playwright() as pw:
    browser = pw.chromium.launch(proxy=p.for_playwright())
    # ...

See Playwright integration

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

See HTTP vs SOCKS5 protocols

Selenium (via SeleniumWire)
# pip install selenium-wire
from seleniumwire import webdriver

p = client.proxy(country="us")
options = {"proxy": {"http": p.url, "https": p.url}}
driver = webdriver.Chrome(seleniumwire_options=options)

See Selenium integration

Return value reference
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.for_playwright() # {"server": ..., "username": ..., "password": ...}
str(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)
from proxy_builder_sdk import ProxyClient

# Oxylabs — the SDK emits customer-...-cc-us-sessid-run1-sesstime-10
p = 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.
  • str(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.
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 raises 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. Leave session off for per-request rotation — that is the default when you call client.proxy().
Does it work with Scrapy?
Yes. Build p.url or p.proxies and pass them to Scrapy's proxy middleware. See the Scrapy integration guide for a full example.
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 Python?

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

Docs, integrations & blog

All SDKs

License: MIT