cloudflare-turnstile-solver README

The project's README from github.com/biusberline/cloudflare-turnstile-solver. As one markdown file: README.md.

Peak - solve Cloudflare Turnstile & the 5s challenge in ~1s

Cloudflare Turnstile Solver — Get a Turnstile Token in Python

The Cloudflare Turnstile Solver package makes it easy to work with Cloudflare Turnstile from Python: it finds the Turnstile sitekey on any page, creates a valid Turnstile token via the Peak API, and hands you a cf-turnstile-response token you can inject into a form or request. It is a small, dependency-free library plus a CLI — designed for CI pipelines, QA automation, and integration engineering.

Table of Contents:

What this package does

Cloudflare Turnstile protects pages with a widget that issues a token. Two things are always needed: find the sitekey the page is using, and create a token for that sitekey. This package provides both:

  1. find_sitekey() — scan a page for its data-sitekey.
  2. create_token() — submit a solve task to the Peak API and get a valid token.
  3. token_for_page() — do both in one call.

It has no browser dependency. A single Python file, standard library only, works on headless servers and CI runners.

Quick start

$ export PEAK_API_KEY=pk_your_api_key
$ python -m cloudflare_turnstile_solver --url https://example.com/
0.AgAAABBqzz...

Or find the sitekey first, then create the token:

from cloudflare_turnstile_solver import find_sitekey, create_token

sitekey = find_sitekey("https://example.com/")
token = create_token("pk_...", sitekey, "https://example.com/")
print(token)  # -> "0.AgAAABBqzz..."

Finding a Turnstile sitekey

Turnstile widgets expose the sitekey in the markup:

<div class="cf-turnstile" data-sitekey="0x4AAAAAAAxxxx"></div>

find_sitekey() reads it for you:

from cloudflare_turnstile_solver import find_sitekey

sitekey = find_sitekey("https://example.com/")
print(sitekey)  # -> "0x4AAAAAAAxxxx"

It also finds data-action when present, so tokens are scoped correctly.

Creating a Turnstile token

A token is tied to the sitekey, the page URL, and optionally the action. To create one with the Peak API:

from cloudflare_turnstile_solver import create_token

result = create_token("pk_...", "0x4AAAAAAAxxxx", "https://example.com/",
                      proxy="http://u:[email protected]:8080")
print(result.token)

Submit the returned token as cf-turnstile-response:

cf-turnstile-response: 0.AgAAABBqzz...

⚠️ If the token is rejected, check the basics. The token is bound to the page URL and environment that created it. Use the same proxy and a matching user agent for the request.

Python API reference

Function Description
find_sitekey(url, html=None) Scan a page for its Turnstile sitekey.
find_action(html) Find an optional data-action value.
create_token(api_key, sitekey, url, proxy=None, action=None, cdata=None, ...) Create a valid token via the Peak API.
token_for_page(api_key, url, proxy=None, html=None) Find the sitekey and create a token in one call.

All functions raise TurnstileTokenError on failure. create_token retries transient failures automatically.

CLI usage

$ python -m cloudflare_turnstile_solver --url https://example.com/ --output json
{
  "sitekey": "0x4AAAAAAAxxxx",
  "token": "0.AgAAABBqzz...",
  "success": true
}

Flags: --url (required), --sitekey, --proxy, --api-key, --output {text,json}, --retries.

Examples

In a script with requests

import requests
from cloudflare_turnstile_solver import token_for_page

result = token_for_page("pk_...", "https://example.com/")
resp = requests.post("https://example.com/submit",
                     data={"cf-turnstile-response": result.token})
print(resp.status_code)

In CI / shell

TOKEN=$(python -m cloudflare_turnstile_solver --url https://example.com/)
curl -X POST https://example.com/submit \
  -H "cf-turnstile-response: $TOKEN" \
  -d "payload=..."

Powered by Peak

This package uses Peak to solve Turnstile.

Get your free API key • Docs • Pricing

FAQ

Does it run headless / without a browser?

Yes. The whole package is a single Python file on the standard library - no browser, no webdriver, no Node. It runs the same on a headless CI runner as it does locally.

How do I use a proxy?

Pass it to create_token / token_for_page with the proxy argument, or use --proxy on the CLI:

$ python -m cloudflare_turnstile_solver --url https://example.com/ --proxy http://u:[email protected]:8080

Can I use it for multiple pages on the same site?

Yes - call token_for_page per page URL. Each token is bound to the page URL it was created for, so don't reuse one token across different pages.

License

MIT

cloudflare-turnstile-solver (biusberline/cloudflare-turnstile-solver)

captcha
Searching Database…

346 ·GitHub
Cloudflare-turnstile-solver
What is this?A small Python library and CLI for Cloudflare Turnstile on your own pages: it reads the sitekey from a page, gets a valid token via the Peak API, and hands you a cf-turnstile-response to inject into a form or request.
Is it a Python library or a command-line tool?Both — import it as a Python library or run the bundled CLI, and point either at the page you are working with. The actual solving is delegated to the Peak API service.
How do I start getting tokens for my page?Nothing to install beyond Python itself — it is one standard-library file. Get a Peak API key, then call tokenforpage(api_key, url) or run the CLI with --url and --api-key (--proxy, --output json, --retries for CI runs).
Do I need a browser or webdriver for any of this?Just Python — no browser, webdriver, or Node. The package is a single standard-library file, so it runs the same on a headless CI runner as locally; solving needs a Peak API key.
Why might a token get rejected or stop working?Tokens are tied to their environment: each is bound to the page URL it was created for, so call tokenforpage per page instead of reusing one, and rejected tokens usually mean the proxy or user agent did not match.
What are the main functions in the Python API?Three calls cover everything: findsitekey() scans a page for its data-sitekey, createtoken() submits a solve task to the Peak API, and tokenforpage() does both in one call. Failures raise TurnstileTokenError, and transient errors are retried automatically.
Is it free to use?The library itself is MIT and free. Solving runs through the Peak API: 1,000 free solves to start without a card, then from $0.8 per 1,000 successful solves, with each solve taking about a second.
Can I route the solve through a proxy?Yes — pass it as the proxy argument to createtoken() or tokenforpage(), or use --proxy on the CLI when the token must be created from the same network environment.
What are similar projects?cloudflare-turnstile-bypass, captcha-api, undetected-chromedriver, nopecha-extension, testsprite-cli, patchright-enhanced, botasaurus, assay
Which topics is it in?qa, captcha, bypass, headless, python3, python-library, cloudflare, browser-automation, http, ci, testing, command-line-tool
Creator
biusberline
Size
0.5 MB
Stars
346
Updated
CommitOct 12
Age
1mo
Commits · 90 Days