Cloudflare Turnstile solver

Cloudflare Turnstile solver: get a valid Cloudflare Turnstile token for any page and sitekey from the ZeroCaptcha API. A zero-dependency Node.js CLI, the REST and createTask formats, and links to tested examples for Python, Node.js, Go, PHP, Java, C#, Rust, Playwright, Puppeteer and Selenium.

Website · Docs · Quickstart · API reference · Pricing

What it does

Cloudflare Turnstile is Cloudflare's CAPTCHA: a widget on a site's form that gives the browser a token, which the site checks with Cloudflare before it accepts the form. When you automate, test or monitor a site you are allowed to, the widget stands between your script and the form.

ZeroCaptcha is an API that solves it: send the page's URL and the widget's sitekey, get a valid Cloudflare Turnstile token back, and submit it as the browser would. This repository is the starting point:

• solve-turnstile.mjs, a command-line solver with no dependencies (Node.js 20 or later);
• a map of the tested examples for every language and browser tool, the SDKs, and the API formats.

Quickstart

1. Create an account on the ZeroCaptcha website, create an API key on the dashboard and add funds (crypto, from $10). A task is charged only when it succeeds.

2. Set the API's address and your key:

   export ZEROCAPTCHA_API=https://api.zerocaptcha.io
   export ZEROCAPTCHA_KEY=zc_live_...

3. Read the widget's data-sitekey, data-action and data-cdata from the page (or the sitekey, action and cData options of its turnstile.render() call), then:

   node solve-turnstile.mjs --url https://shop.example.com/login --sitekey 0x4AAAAAAAB1cD2eF3gH4iJ5 \
     --action login --cdata session-7f3a9c2e

   Many sites check the action and cData when they verify the token and refuse one solved without them, so pass both whenever the widget sets them, and leave them out when it does not.

   It prints the token. --json prints JSON, --proxy http://user:pass@proxy.example.net:8080 solves through your proxy, and --challenge --url <page> --proxy <url> passes a Cloudflare challenge page instead and prints its cf_clearance cookie and user agent.

4. Send the token in the form's cf-turnstile-response field, within 300 seconds.

The same call with curl:

# action and cdata are the widget's data-action and data-cdata; leave out any it does not set. For
# your own proxy, make the type TurnstileTask and add "proxy"; to be called when the task ends, add
# "callbackUrl". The reply is the task, or a problem document whose code says why it was refused.
curl -sS --fail-with-body "$ZEROCAPTCHA_API/v1/tasks" \
  -H "Authorization: Bearer $ZEROCAPTCHA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type": "TurnstileTaskProxyless", "websiteURL": "https://shop.example.com/login", "websiteKey": "0x4AAAAAAAB1cD2eF3gH4iJ5", "action": "login", "cdata": "session-7f3a9c2e"}'
# then GET $ZEROCAPTCHA_API/v1/tasks/<id> every 2 seconds until "status" is "succeeded" (or failed, with its errorCode)

Examples in your language

Each is a small, working project with its own tests against a stand-in API.

Language or tool	Repository	Guide on the website
Python	cloudflare-turnstile-solver-python	Python
Node.js and TypeScript	cloudflare-turnstile-solver-nodejs	Node.js
Go	cloudflare-turnstile-solver-go	Go
PHP	cloudflare-turnstile-solver-php	PHP
Java	cloudflare-turnstile-solver-java	Java
C# and .NET	cloudflare-turnstile-solver-csharp	C#
Rust	cloudflare-turnstile-solver-rust	Quickstart
Playwright	cloudflare-turnstile-solver-playwright	Playwright
Puppeteer	cloudflare-turnstile-solver-puppeteer	Puppeteer
Selenium	cloudflare-turnstile-solver-selenium	Selenium
curl	this README	curl

The official SDKs are zerocaptcha-js, zerocaptcha-python and zerocaptcha-go, and zerocaptcha-mcp lets an AI assistant solve tasks.

How it works

1. Create a task with the page's URL and the widget's sitekey, plus its action and cData if it sets them. The task's price is held on your balance, and you get its ID at once.
2. Wait for it: ask for the task every 2 seconds, or give a callbackUrl and receive it, signed, when it ends.
3. Use the token: a succeeded task carries solution.token, and only then is the price charged. A failed or expired task costs nothing.

The API speaks three formats on one host, so existing clients work unchanged:

• REST: POST /v1/tasks and GET /v1/tasks/{id}, with Idempotency-Key and RFC 9457 errors. The SDKs use it. Reference.
• createTask: createTask, getTaskResult and getBalance, as CapSolver, Anti-Captcha and 2Captcha clients send them. Docs.
• in.php and res.php: 2Captcha's original format, method=turnstile. Docs.

Moving from another service? See createtask-api-migration.

Honest limits

• A token works once, for 300 seconds. That is Cloudflare's rule, not ours: solve right before you submit.
• The action and cData must match the widget's, or the site's siteverify check can refuse the token.
• Cloudflare Turnstile and Cloudflare challenge pages only. ZeroCaptcha does not solve reCAPTCHA, hCaptcha or other CAPTCHAs.
• Proxies are http or https. SOCKS is not supported. A challenge page always needs your proxy.
• Prepaid, per solved task: there is no subscription, and nothing is charged for a task that fails. Top-ups are in crypto, from $10, and final.
• Only for sites you own or are allowed to automate. The Acceptable Use Policy applies to every task, and any site owner can opt out.

FAQ

What is Cloudflare Turnstile, exactly? A CAPTCHA replacement that mostly runs without a puzzle: the widget checks the browser and issues a token. The explainer covers how it works, and the token article covers the token's format, lifetime and siteverify.

Where do I find the sitekey? Usually in the widget's data-sitekey attribute; sometimes in a turnstile.render call. The sitekey guide shows every place.

How fast is it, and how often does it succeed? The status page shows the live figures for the last 24 hours, read from the API; we publish no other numbers.

What does it cost? The pricing page lists the price per 1,000 solved tasks. Only a task that succeeds is charged.

How does it compare with other solvers? The comparison of Cloudflare Turnstile solvers is sourced and dated.

Run the tests

node --test

The tests run the command against a stand-in API on your machine: no key, no real task, nothing spent.

More from ZeroCaptcha

• The website: ZeroCaptcha, the docs, the guides, the blog and the status page
• Start here: zerocaptcha, cloudflare-turnstile-solver, cloudflare-challenge-solver
• Examples by language: cloudflare-turnstile-solver-python, cloudflare-turnstile-solver-nodejs, cloudflare-turnstile-solver-go, cloudflare-turnstile-solver-php, cloudflare-turnstile-solver-java, cloudflare-turnstile-solver-csharp, cloudflare-turnstile-solver-rust
• Browser automation: cloudflare-turnstile-solver-playwright, cloudflare-turnstile-solver-puppeteer, cloudflare-turnstile-solver-selenium
• SDKs, MCP server and migration: zerocaptcha-js, zerocaptcha-python, zerocaptcha-go, zerocaptcha-mcp, createtask-api-migration
• Lists: awesome-cloudflare-turnstile

Licence

MIT: see LICENSE.

Disclaimer

ZeroCaptcha is an independent service, not affiliated with or endorsed by Cloudflare. Cloudflare and Turnstile are trademarks of Cloudflare, Inc. Use ZeroCaptcha only on sites you own or are allowed to automate, as the Acceptable Use Policy says; any site owner can opt out.