curl-cffi-proxyhat

Route curl_cffi requests through ProxyHat residential proxies — real browser TLS/JA3 impersonation plus a sticky residential IP, geo-targeting and rotation.

[!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.

Why

curl_cffi already wins half the anti-bot fight: it impersonates a real browser's TLS/JA3 and HTTP2 fingerprint, so servers see Chrome or Safari instead of Python. The other half is the exit IP — a datacenter address gives you away no matter how good the fingerprint is. This package plugs ProxyHat's residential IPs (50M+ across 148+ countries) into curl_cffi so the fingerprint and the IP both look like a real user. One pinned residential IP per session by default, so cookies and TLS stay coherent. No fork, no boilerplate.

Install

pip install curl-cffi-proxyhat

curl_cffi and the official proxyhat SDK come as dependencies.

Quick start

from curl_cffi_proxyhat import ProxyHatSession

# An API key auto-selects an active residential sub-user.
# Sticky by default: one pinned US IP for the whole session.
with ProxyHatSession(country="us", impersonate="chrome") as s:
    r = s.get("https://tls.browserleaks.com/json")
    print(r.json())          # residential IP + a Chrome TLS fingerprint

ProxyHatSession is a drop-in curl_cffi.requests.Session subclass: same get/post/request methods and the same impersonation, but every request exits through a ProxyHat residential IP.

Get an API key at proxyhat.com.

Just want the proxy dict for a plain curl_cffi call?

import curl_cffi
from curl_cffi_proxyhat import proxyhat_proxies

proxies = proxyhat_proxies(country="de", sticky="1h")
r = curl_cffi.get("https://example.com", impersonate="chrome", proxies=proxies)
# proxyhat_proxies(...) -> {"http": "http://...@gate.proxyhat.com:8080", "https": "..."}

Credentials

Pass them explicitly or via environment variables — options win over env:

Targeting

ProxyHatSession(
    protocol="http",       # or "socks5"
    country="us",          # ISO code or "any" (default)
    region="california",
    city="new_york",
    filter="high",         # AI IP-quality tier
    sticky="30m",          # session lifetime (default); sticky=False rotates every request
    impersonate="chrome",  # any curl_cffi browser target; default "chrome", None disables
    timeout=30,            # any extra kwarg is forwarded to curl_cffi's Session
)

The same knobs work on proxyhat_proxies(...) (everything except impersonate, which is a curl_cffi request option, not a proxy one).

Sticky IP per session (default)

A scraping session usually makes many requests against the same site — a search, then result pages, then details. If the exit IP changed mid-session the site would see a user teleporting between cities and block it. So this package is sticky by default: one residential IP is pinned for the whole session (sticky="30m", renewed as you work), keeping cookies and TLS fingerprint coherent.

Want a fresh IP on every request instead (e.g. many independent one-shot fetches)? Turn stickiness off:

with ProxyHatSession(country="us", sticky=False) as s:  # rotating residential IP per request
    for url in urls:
        s.get(url)

Set a custom lifetime with sticky="2h".

How it works

ProxyHatSession resolves your gateway credentials (via the official proxyhat SDK — an API key auto-picks an active sub-user, or pass username/password), then builds a ProxyHat connection URL with the SDK's targeting grammar (http://<user>-country-us-sid-<id>-ttl-30m:<pass>@gate.proxyhat.com:8080) and hands proxies={"http": url, "https": url} plus your impersonate choice to curl_cffi.requests.Session. From there it is a curl_cffi session: it speaks the impersonated browser handshake over ProxyHat's residential exit. A sticky username pins one IP; a rotating one makes the gateway hand out a fresh IP per connection. proxyhat_proxies(...) builds the same dict for a bare curl_cffi.get(...) when you don't need a session.

License

MIT © ProxyHat