ProxyHat Python SDK

The official Python 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.

Features

• One-call proxy connection — client.connection_url() turns your API key into a ready-to-use residential proxy URL
• Full coverage of the ProxyHat API
• Local gateway URL builder (build_connection_url) — no network needed
• Sync (ProxyHat) and async (AsyncProxyHat) clients
• Typed responses using dataclasses
• Comprehensive error handling with typed exceptions
• Pagination support for location endpoints

Installation

pip install proxyhat

Quick Start

from proxyhat import ProxyHat

client = ProxyHat(api_key="ph_your_api_key")

# List sub-users
users = client.sub_users.list()
for user in users:
    print(user.proxy_username, user.lifecycle_status)

# Create a sub-user
new_user = client.sub_users.create(
    proxy_password="secure_pass",
    is_traffic_limited=True,
    traffic_limit="5GB",
    name="Scraper",
)
print(new_user.uuid)

Async Usage

import asyncio
from proxyhat import AsyncProxyHat

async def main():
    async with AsyncProxyHat(api_key="ph_your_api_key") as client:
        users = await client.sub_users.list()
        for user in users:
            print(user.proxy_username)

asyncio.run(main())

Connecting to a proxy

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:

from proxyhat import ProxyHat

proxy = ProxyHat(api_key="ph_your_api_key")

# Rotating residential IP, US exit:
url = proxy.connection_url(country="us")
# → http://<user>-country-us:<pass>@gate.proxyhat.com:8080

# Sticky session (same IP for 30m), city-targeted, SOCKS5:
sticky = proxy.connection_url(country="de", city="berlin", sticky="30m", protocol="socks5")

# Use it with any HTTP client:
import httpx
resp = httpx.get("https://api.ipify.org", proxy=url)

Offline builder — if you already have a sub-user's credentials, build the URL with no network call:

from proxyhat import build_connection_url

url = build_connection_url(username="ph-8f2a1c", password="PxSecret123", country="gb", filter="high")

Server-built descriptor — let the API assemble it (validates the sub-user is active):

d = proxy.proxy_descriptors.create(
    sub_user_uuid=user.uuid,
    protocol="http",
    location={"country": "us", "city": "new_york"},
    session={"mode": "sticky", "ttl": "30m"},
)
print(d.url)

Authentication

Get your API key from the ProxyHat Dashboard.

See the Authentication Guide for details.

API Reference

Error Handling

from proxyhat import ProxyHat, ProxyHatError, NotFoundError, RateLimitError, ValidationError

client = ProxyHat(api_key="ph_your_api_key")

try:
    user = client.sub_users.get("nonexistent-id")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Validation failed: {e.errors}")
except ProxyHatError as e:
    print(f"API error {e.status_code}: {e.message}")

See the Error Handling Guide for the full list of error codes.

Documentation

• Getting Started
• API Reference
• Full Documentation

Links

• ProxyHat — Residential & mobile proxy network
• Dashboard — Manage proxies, sub-users, and API keys
• GitHub — Source code & issue tracker

License

MIT — see LICENSE for details.