Metadata-Version: 2.4
Name: tls-impersonate-proxy
Version: 0.1.0
Summary: Fetch URLs with a browser-matched TLS/JA3 fingerprint (via curl_cffi) through rotating authenticated proxies, with automatic anti-bot block detection and retry.
Author-email: JiBao Proxy <support@jibaoproxy.com>
License: MIT
Project-URL: Homepage, https://jibaoproxy.com
Project-URL: JA3 web tool, https://check.jibaoproxy.com
Project-URL: Source, https://github.com/jibaoproxyofficial-pixel/tls-impersonate-proxy
Keywords: ja3,tls-fingerprint,curl-cffi,impersonate,anti-bot,web-scraping,cloudflare,datadome,proxy,rotating-proxy,bot-detection
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: curl_cffi>=0.7
Dynamic: license-file

# tls-impersonate-proxy

Fetch URLs with a **real browser's TLS/JA3 fingerprint** (via [`curl_cffi`](https://github.com/lexiforest/curl_cffi)) through **rotating authenticated proxies**, with automatic anti-bot block detection and retry.

[![PyPI](https://img.shields.io/pypi/v/tls-impersonate-proxy)](https://pypi.org/project/tls-impersonate-proxy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Why your scraper gets blocked before it even sends a request

Most "the proxies don't work" problems aren't an IP problem — they're a **TLS problem**.

Before a single byte of your HTTP request is parsed, the server sees *how* your client negotiates TLS: the cipher suites, extensions and curve order. It hashes that into a **JA3/JA4 fingerprint**. Python `requests`, `httpx`, `aiohttp`, `curl` and Go's `net/http` each produce a handshake **no real Chrome or Safari ever sends** — so you can be on a pristine residential IP, with perfect headers, and still get fingerprinted as a bot on the first packet.

`tls-impersonate-proxy` fixes the layer that rotating more proxies never touches:

- **Browser-matched JA3** — borrows real Chrome / Safari / Edge TLS profiles from `curl_cffi`, so the handshake lines up with your `User-Agent`.
- **Proxy rotation** — round-robins a list of authenticated proxies (HTTP / SOCKS5).
- **Block detection + retry** — a `403`/`429`/`503` or a Cloudflare / DataDome / PerimeterX / Akamai challenge page triggers a real retry on a *fresh* exit instead of silently returning garbage.

## Install

```bash
pip install tls-impersonate-proxy
```

## CLI

```bash
# Fetch with a rotating browser fingerprint through a residential proxy
tls-fetch https://example.com -x socks5h://USERNAME:PASSWORD@us.jibaoproxy.com:913

# Pin a specific browser, print status + headers only
tls-fetch https://tls.browserleaks.com/json --impersonate chrome -i

# Rotate across several exits, retry up to 6 times on a block
tls-fetch https://target.site \
  -x socks5h://USERNAME:PASSWORD@us.jibaoproxy.com:913 \
  -x socks5h://USERNAME:PASSWORD@de.jibaoproxy.com:913 \
  --retries 6
```

## Library

```python
from tls_impersonate_proxy import ImpersonateClient, BlockedError

client = ImpersonateClient(
    proxies=[
        "socks5h://USERNAME:PASSWORD@us.jibaoproxy.com:913",
        "socks5h://USERNAME:PASSWORD@de.jibaoproxy.com:913",
    ],
    impersonate=None,   # None = rotate chrome/safari/edge fingerprints
    max_retries=4,
)

try:
    resp = client.get("https://target.site")
    print(resp.status_code, len(resp.text))
except BlockedError as e:
    print("still blocked:", e)
```

One-shot helper:

```python
from tls_impersonate_proxy import fetch
html = fetch("https://target.site",
             proxies=["socks5h://USERNAME:PASSWORD@us.jibaoproxy.com:913"]).text
```

## The fingerprint has to match the exit

A browser-matched JA3 gets you past the TLS check, but the **exit IP still has to read as a real person**. A datacenter ASN is scored as automation no matter how perfect the handshake is — the two signals have to agree.

- **Verify the JA3 your client actually sends** (and the exit ASN) with the free tool: **[check.jibaoproxy.com](https://check.jibaoproxy.com)**
- **Residential exits with clean ASNs and sticky sessions:** [jibaoproxy.com](https://jibaoproxy.com) — `$5/GB` residential, `$0.8/GB` datacenter, `$5` free credit on signup.

## Further reading

- [JA3/TLS fingerprint detection, explained](https://jibaoproxy.com/blog/ja3-tls-fingerprint-detection-explained.html)
- [Bypassing DataDome & PerimeterX in 2026](https://jibaoproxy.com/blog/datadome-perimeterx-bypass-2026.html)
- [Headless browser detection & CDP leaks](https://jibaoproxy.com/blog/headless-browser-detection-2026.html)

## License

MIT — see [LICENSE](LICENSE). Use responsibly and respect target sites' terms and `robots.txt`.
