roamproxy — Python SDK

Lightweight Python client for the RoamProxy proxy gateway: rotating residential from $2/GB, static residential, and datacenter IPs across 190+ countries, all through one endpoint (gw.roamproxy.com:41080, HTTP and SOCKS5 on the same port).

Zero required dependencies. requests is only needed for the sticky-session context manager and SessionPool.get.

Install

pip install git+https://github.com/roamproxy/roamproxy-python.git
# with requests helpers:
pip install "roamproxy[requests] @ git+https://github.com/roamproxy/roamproxy-python.git"

Quickstart

Credentials are your account username and password from the dashboard.

import requests
from roamproxy import Client

client = Client("your-username", "your-password")

# Fresh rotating IP on every request
r = requests.get("https://api.ipify.org", proxies=client.proxies(country="us"))
print(r.text)

Sticky session (one exit IP, context manager)

with client.sticky(country="us") as s:      # s is a preconfigured requests.Session
    s.get("https://example.com/login")       # same exit IP
    s.get("https://example.com/dashboard")   # still the same IP

Need to change IP mid-flight? Keep the StickySession object around and call .rotate():

sticky = client.sticky(country="de")
print(sticky.proxies)   # use with any HTTP library
sticky.rotate()         # new exit IP, same targeting

Rotation pool with retries

Spread traffic across N stable IPs and retry failures on a fresh IP:

from roamproxy import SessionPool

pool = SessionPool(client, size=5, country="us")

for url in urls:
    r = pool.get(url, retries=3)   # round-robin; failing slots get a new IP
    process(r)

pool.get treats connection errors, timeouts, HTTP 5xx, and 429 as failures: the failing slot's exit IP is replaced, and the request is retried on the next slot.

Using another HTTP library? pool.next_proxies() just hands you the next proxies dict.

Targeting

Targeting works through username modifiers; the SDK builds them for you:

client.proxies(country="jp")                          # country (ISO alpha-2)
client.proxies(country="us", state="ca")              # US state (2-letter code)
client.proxies(country="us", state="ca", city="losangeles")
client.proxies(session="job42")                       # sticky by explicit id
client.proxies(country="us", socks=True)              # socks5h:// URLs instead

Or grab raw values for any tool:

client.modified_username(country="us", session="abc")  # "your-username-country-us-session-abc"
client.proxy_url(scheme="socks5h", country="gb")       # full proxy URL

For SOCKS with requests, install requests[socks] (the roamproxy[socks] extra pulls it in).

Links

• Website: https://roamproxy.com?utm_source=github&utm_medium=referral
• Locations: https://roamproxy.com/locations
• Guides: https://roamproxy.com/guides
• Copy-paste examples in other languages: roamproxy/proxy-examples

License

MIT — see LICENSE.