PY
Languages & HTTP Clients

curl_cffi proxy

A curl_cffi proxy is a curl_cffi session that tunnels every HTTP and HTTPS call through an upstream gateway while impersonating a real browser TLS and HTTP/2 fingerprint. Pass the Aethyn URL on proxy or proxies, set impersonate="chrome", and the request exits from a household IP with a Chrome-shaped handshake instead of Python's.

Why a residential curl_cffi proxy

Python requests can send a Chrome User-Agent and still fail the handshake. Anti-bot systems hash the TLS Client Hello (JA3/JA4) and HTTP/2 SETTINGS; stock OpenSSL from requests or httpx does not match Chrome. curl_cffi is a Python binding for curl-impersonate: impersonate="chrome" aligns cipher order, extensions, and HTTP/2 frames with a current Chrome profile, and injects matching default headers unless you turn them off. That is the TLS layer. It is not a browser. It does not run JavaScript, hydrate a Shopping grid, or clear a JS challenge. Pair it with a residential exit so the ASN is a household ISP rather than AWS. Aethyn encodes country, optional Elite city or ISP, and sticky lifetime on the username. Omit a session id to rotate per request. Add -session-<id>-lifetime-<minutes> (1–1440, default 30) when a cookie must stay on the IP that earned it. HTTP CONNECT on port 2099 (Premium) or 5499 (Elite) covers HTTPS. SOCKS5 is 1099 / 3499 on the same pool. Python 3.10+.

Setup steps

  1. 1Install curl_cffi (Python 3.10+): pip install curl_cffi --upgrade.
  2. 2Grab your Aethyn username (aethyn-XXXXX) and password from the dashboard.
  3. 3Pass the proxy URL and impersonate="chrome" on the request or Session.
  4. 4Add targeting suffixes (-country-, optional -city- on Elite, -session-, -lifetime-) to the username.

Code

Rotating GET with Chrome impersonation
from curl_cffi import requests

proxy = "http://aethyn-XXXXX:PASSWORD@proxy.aethyn.io:2099"
proxies = {"http": proxy, "https": proxy}

r = requests.get(
    "https://httpbin.org/ip",
    proxies=proxies,
    impersonate="chrome",
    timeout=30,
)
print(r.json())  # fresh residential exit; Chrome-shaped TLS
Country targeting + sticky session (Elite)
from curl_cffi import requests

# Same rotating-pool IP for 30 minutes (lifetime-30) while a cookie lives
user = "aethyn-XXXXX-country-us-session-cffi1-lifetime-30"
proxy = f"http://{user}:PASSWORD@proxy.aethyn.io:5499"
proxies = {"http": proxy, "https": proxy}

with requests.Session() as s:
    r = s.get(
        "https://httpbin.org/ip",
        proxies=proxies,
        impersonate="chrome",
        timeout=30,
    )
    print(r.json())
SOCKS5 with remote DNS
from curl_cffi import requests

proxy = "socks5h://aethyn-XXXXX:PASSWORD@proxy.aethyn.io:1099"
proxies = {"http": proxy, "https": proxy}

r = requests.get(
    "https://httpbin.org/ip",
    proxies=proxies,
    impersonate="chrome",
    timeout=30,
)
print(r.json())  # socks5h = DNS at the proxy, no local leak
Session + fail-closed body check
from curl_cffi import requests

CHALLENGE = ("unusual traffic", "sorry/index", "verify you are human")
CONSENT = ("before you continue", "consent.google.com")

proxy = "http://aethyn-XXXXX-country-us:PASSWORD@proxy.aethyn.io:2099"
proxies = {"http": proxy, "https": proxy}

with requests.Session() as s:
    r = s.get(
        "https://example.com",
        proxies=proxies,
        impersonate="chrome",
        timeout=30,
    )
    low = r.text.lower()
    if r.status_code != 200:
        status = "http_error"
    elif any(m in low for m in CHALLENGE):
        status = "challenge"
    elif any(m in low for m in CONSENT):
        status = "consent"
    else:
        status = "ok"
    # Persist extracted fields only when status == "ok"
    print(r.status_code, status)

Replace aethyn-XXXXX and PASSWORD with your dashboard credentials. See the full targeting reference and protocol/port list.

Troubleshooting

The failures that look like “curl_cffi is broken” are usually a Python JA3 you did not impersonate, a 407, a header/TLS mismatch, or a 200 that is still a challenge page. If you omit impersonate, curl_cffi is just another HTTP client — add impersonate="chrome" (rolling alias; pin chrome131 only to freeze a basket — profiles change as the library updates). A 407 means the username or password is wrong, or a targeting suffix landed on the password side of the URL. If you override User-Agent or Sec-CH-UA while impersonating, keep them in lockstep with the TLS profile or use default_headers=False and own the whole set. HTTP 200 with unusual-traffic, /sorry/, or Before you continue is not success — classify the body before you store it. If curl_cffi and requests fail identically through a clean residential exit but Playwright returns the grid, you need JavaScript, not more IPs. See the vs-Playwright protocol. Timeouts belong on every call; residential hops are slower than a local CDN fetch.

Tips

  • Always pass impersonate="chrome" (or a pinned chromeNNN). Without it, curl_cffi still ships a library TLS fingerprint.
  • Use a Session() so cookies survive. Sticky -session- on the username is the exit IP, not the cookie jar.
  • Prefer socks5h:// over socks5:// so DNS resolves at the proxy.
  • HTTP 200 is not success. Classify challenge and consent HTML before you insert a row.
  • When the page hydrates in JavaScript, switch to Playwright — same Aethyn username, different client.
  • AsyncSession works the same way under asyncio; impersonate and proxy still belong on every call.

curl_cffi proxy FAQ

Is impersonate the same as setting a Chrome User-Agent?
No. A User-Agent is a header. impersonate changes the TLS Client Hello and HTTP/2 frames to match a browser profile, and curl_cffi also injects matching default headers. Spoofing User-Agent on requests does not change JA3. Keep Sec-CH-UA in lockstep with the impersonated profile, or leave the defaults on.
How do I set an Aethyn proxy in curl_cffi?
Build http://aethyn-XXXXX:PASSWORD@proxy.aethyn.io:2099 (Premium HTTP) or :5499 (Elite HTTP) and pass it as both keys of proxies, or as proxy=. Targeting suffixes go on the username. The HTTP port tunnels HTTPS via CONNECT.
Should I use a Session or a sticky proxy session?
Both, when a cookie must stay on the IP that earned it. requests.Session() is the HTTP cookie jar. Aethyn -session-<id>-lifetime-N (1–1440 minutes, default 30) holds the rotating-pool exit. A Session on a rotating IP will send cookies from identity A out of IP B.
What does 407 mean with curl_cffi?
The proxy rejected authentication. Rebuild the URL from the dashboard: username is aethyn-XXXXX plus targeting suffixes, password matches, and -country- / -session- tokens are not on the password side.
When should I switch from curl_cffi to Playwright?
When the document is a JavaScript application, a JS challenge, or a sensor that never runs in an HTTP client. curl_cffi impersonates the handshake; it does not execute scripts. Same residential username, new Playwright context. Protocol: /blog/curl-cffi-vs-requests-vs-playwright-web-scraping-2026.
HTTP or SOCKS5?
Same residential pool. HTTP CONNECT on Premium 2099 or Elite 5499 is the usual path. SOCKS5 on 1099 or 3499 with socks5h:// if the client needs it. SOCKS5 does not hide TLS — impersonate still matters.

Ready to wire up Python (curl_cffi)?

Get your credentials and route your first Python (curl_cffi) request through residential IPs in minutes.

Docs, solutions & blog

Related integrations

All integrations