Docs · Turnstile
Cloudflare Turnstile
One call returns a Turnstile token and the User-Agent to send with it: send your API key, the page URL and its sitekey.
- Endpoint
POST /turnstile/getToken - Token 300 s, works once
- API as JSON
Docs · Turnstile
One call returns a Turnstile token and the User-Agent to send with it: send your API key, the page URL and its sitekey.
POST /turnstile/getTokenThree steps, no polling loop: getToken waits and returns the token. Copy, paste, replace the example values.
API keys are issued in our Telegram bot @mintprocheckerbot. Solver access is opening soon — follow @MINTBotUpdates for the launch.
Send your key as clientKey in every request, next to task. Keep it on your server.
POST it to /turnstile/getToken. The reply comes when the token is ready.
curl -X POST "https://solver.mintbin.xyz/turnstile/getToken" \
-H "Content-Type: application/json" \
-d '{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "TurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAAAAAA..."
}
}'websiteURL: the address of the page that shows the Turnstile widget.websiteKey: the 0x4… sitekey in the widget's data-sitekey.action / cData: send them only if the widget sets data-action / data-cdata.Put solution.token in the form's cf-turnstile-response field and submit it with the User-Agent from solution.userAgent. Each token works once and expires 300 s (5 minutes) after it is issued. Each call waits up to 60 s by default.
Expected reply
{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.RD7PWurbnU39z3XF...9a9d691",
"userAgent": "Mozilla/5.0 (...)"
},
"taskId": "3f2a...",
"elapsed_s": 8.29
}Submit it with the form
# TOKEN = solution.token, USER_AGENT = solution.userAgent from the getToken reply curl -X POST "https://example.com/login" \ -A "$USER_AGENT" \ --data-urlencode "email=you@example.com" \ --data-urlencode "cf-turnstile-response=$TOKEN"
$token = $res["solution"]["token"]; // $res: the getToken reply above
$ch = curl_init("https://example.com/login");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_USERAGENT => $res["solution"]["userAgent"], // the same User-Agent
CURLOPT_POSTFIELDS => http_build_query([
"email" => "you@example.com",
"cf-turnstile-response" => $token,
]),
]);
$page = curl_exec($ch);
import requests
token = res["solution"]["token"] # res: the getToken reply above
page = requests.post("https://example.com/login", data={
"email": "you@example.com",
"cf-turnstile-response": token,
}, headers={"User-Agent": res["solution"]["userAgent"]}) # the same User-Agent
const token = res.solution.token; // res: the getToken reply above
const page = await fetch("https://example.com/login", {
method: "POST",
headers: { "User-Agent": res.solution.userAgent }, // the same User-Agent
body: new URLSearchParams({ email: "you@example.com", "cf-turnstile-response": token }),
});
Every request carries a task.type. Pick one of these two.
| task.type | Use it when |
|---|---|
TurnstileTaskProxyLess | Recommended. Works with managed and non-interactive widgets. |
TurnstileTask | Same, through your own proxy. Proxied calls can take a few seconds longer. |
The request body is {"clientKey": "…", "task": {…}}. These go inside task.
| Body | Required | Type | What it is |
|---|---|---|---|
clientKey | yes | string | Your API key, in every request. |
task | yes | object | The task: the fields below. |
| Field | Required | Type | Default | What to send |
|---|---|---|---|---|
type | yes | string | — | TurnstileTaskProxyLess or TurnstileTask. |
websiteURL | yes | string | — | Full URL of the page that shows the widget, e.g. https://example.com/login. |
websiteKey | yes | string | — | The widget's sitekey (0x4AAAAAAA…) from data-sitekey. |
action | no | string | — | The widget's data-action, if set. |
cData | no | string | — | The widget's data-cdata, if set. |
timeout_s | no | number | 60 s | Most seconds to wait for a token: default 60, from 5 to 180. If no token arrives by then, you get ERROR_CAPTCHA_UNSOLVABLE: retry, or send a larger timeout_s. |
| proxy fields | no | strings, number | — | Only with TurnstileTask: see Advanced → Use your own proxy. Without them the task runs as ProxyLess. |
The values this service uses now.
| Limit | Value |
|---|---|
| New tasks per minute, per IP | 60 |
Default timeout_s | 60 s |
timeout_s range | 5–180 s |
| Token lifetime | 300 s, works once |
| Polled results kept | 10 minutes |
Poll getTaskResult | every 2 s |
| Your own proxy | Allowed |
Rate limits count per IP: 60 new tasks per minute. If you get ERROR_RATE_LIMIT, back off a few seconds and retry.
Pick your language, then replace YOUR_API_KEY and the example values. Run this on your server or in a script: browsers block calls to this API from web pages, and your key would be visible.
curl -X POST "https://solver.mintbin.xyz/turnstile/getToken" \
-H "Content-Type: application/json" \
-d '{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "TurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAAAAAA..."
}
}'
<?php
$ch = curl_init("https://solver.mintbin.xyz/turnstile/getToken");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 200,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode([
"clientKey" => "YOUR_API_KEY",
"task" => [
"type" => "TurnstileTaskProxyLess",
"websiteURL" => "https://example.com",
"websiteKey" => "0x4AAAAAAA..."
]
]),
]);
$res = json_decode(curl_exec($ch), true);
if (!is_array($res)) { // no JSON: a network error or HTTP 502/504; retry in a few seconds
throw new RuntimeException("No JSON reply (HTTP " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . ")");
}
if ($res["errorId"] !== 0) {
throw new RuntimeException($res["errorCode"]); // e.g. ERROR_CAPTCHA_UNSOLVABLE
}
echo $res["solution"]["token"] . PHP_EOL; // the token: submit it with the form
echo $res["solution"]["userAgent"] . PHP_EOL; // send this User-Agent when you submit
import requests
payload = {
"clientKey": "YOUR_API_KEY",
"task": {
"type": "TurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAAAAAA..."
}
}
res = requests.post("https://solver.mintbin.xyz/turnstile/getToken", json=payload, timeout=200).json()
if res["errorId"] != 0:
raise SystemExit(res["errorCode"]) # e.g. ERROR_CAPTCHA_UNSOLVABLE
print(res["solution"]["token"]) # the token: submit it with the form
print(res["solution"]["userAgent"]) # send this User-Agent when you submit
// Node 18+; save as .mjs (top-level await)
const res = await fetch("https://solver.mintbin.xyz/turnstile/getToken", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
clientKey: "YOUR_API_KEY",
task: {
type: "TurnstileTaskProxyLess",
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA..."
}
}),
}).then((r) => r.json());
if (res.errorId !== 0) throw new Error(res.errorCode); // e.g. ERROR_CAPTCHA_UNSOLVABLE
console.log(res.solution.token); // the token: submit it with the form
console.log(res.solution.userAgent); // send this User-Agent when you submitReplies are HTTP 200, failures included. Check errorId, not status, to tell success from failure.
| Field | Meaning |
|---|---|
errorId | 0 = success. Anything else = failure. |
status | "ready" when the token is in solution; "processing" while a polled task runs. Failures have no status. |
solution.token | The token. Put it in the form's cf-turnstile-response field. |
solution.userAgent | Send this User-Agent when you submit the token. |
taskId | The task's id. Treat it as an opaque string. |
elapsed_s | Seconds the call took. |
errorCode, errorDescription | On failure only: a stable code to branch on and a readable description. |
Success
{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.RD7PWurbnU39z3XF...9a9d691",
"userAgent": "Mozilla/5.0 (...)"
},
"taskId": "3f2a...",
"elapsed_s": 8.29
}Failure
{
"errorId": 12,
"errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
"errorDescription": "No token this time. Retry; a second attempt often succeeds.",
"taskId": "3f2a..."
}Errors answer HTTP 200 too, so check errorId first: 0 is success (or status:"processing" while a task runs); anything else comes with an errorCode and an errorDescription. Branch on errorCode. An HTTP 502 or 504 means the service is briefly unavailable: retry in a few seconds.
| Common codes | Meaning | What to do |
|---|---|---|
ERROR_KEY_DOES_NOT_EXIST → | The clientKey is missing or wrong. | Send your key as clientKey in the JSON body. |
ERROR_TASK_INVALID → | A field is missing or invalid (for example an empty websiteURL or websiteKey, or a non-numeric timeout_s), or the websiteKey does not work on websiteURL. | errorDescription names the problem. Fix it and send the task again. For a sitekey error, copy the data-sitekey value from that page. |
ERROR_RATE_LIMIT → | Too many new tasks from your IP in the last minute. | Back off for a few seconds, then retry. |
ERROR_NO_SLOT_AVAILABLE → | The service is busy or briefly unavailable. | Retry in a few seconds. |
ERROR_CAPTCHA_UNSOLVABLE → | No token this time. | Retry; a second attempt often succeeds. |
All paths are under /turnstile. Send clientKey in the JSON body of every POST.
| Method | Path | What it does |
|---|---|---|
| POST | /turnstile/getToken | One call: returns the token. Recommended. |
| POST | /turnstile/createTask | Starts a task and returns its taskId. |
| POST | /turnstile/getTaskResult | Send {clientKey, taskId}. Returns status:"processing" until the token is ready, then "ready" with the solution. Results stay readable for 10 minutes. |
| GET | /turnstile/health | Is the service up and ready? |
| GET | /turnstile/whoami | The IP address we see for you. Rate limits count per IP. |
Don't want to hold a connection open? POST the same body to /turnstile/createTask. It returns a taskId right away. Then POST {clientKey, taskId} to /turnstile/getTaskResult every 2 seconds until status is "ready". Stop as soon as errorId is not 0. Results stay readable for 10 minutes.
# createTask, then poll getTaskResult with the taskId
{ "errorId": 0, "taskId": "3f2a...", "status": "processing" }
{ "errorId": 0, "status": "processing" }
{ "errorId": 0, "status": "ready", "solution": { "token": "0.RD7PWurbnU39z3XF...", "userAgent": "Mozilla/5.0 (...)" }, "taskId": "3f2a..." }# 1) create the task
curl -X POST "https://solver.mintbin.xyz/turnstile/createTask" \
-H "Content-Type: application/json" \
-d '{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "TurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAAAAAA..."
}
}'
# 2) poll every 2 seconds until "status": "ready"
# (a non-zero errorId means the task failed: stop polling)
curl -X POST "https://solver.mintbin.xyz/turnstile/getTaskResult" \
-H "Content-Type: application/json" \
-d '{ "clientKey": "YOUR_API_KEY", "taskId": "TASK_ID_FROM_STEP_1" }'
<?php
function post($url, $payload) {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$out = json_decode(curl_exec($ch), true);
if (!is_array($out)) { // no JSON: a network error or HTTP 502/504; retry in a few seconds
throw new RuntimeException("No JSON reply (HTTP " . curl_getinfo($ch, CURLINFO_HTTP_CODE) . ")");
}
return $out;
}
$create = post("https://solver.mintbin.xyz/turnstile/createTask", [
"clientKey" => "YOUR_API_KEY",
"task" => [
"type" => "TurnstileTaskProxyLess",
"websiteURL" => "https://example.com",
"websiteKey" => "0x4AAAAAAA..."
]
]);
if ($create["errorId"] !== 0) throw new RuntimeException($create["errorCode"]);
$taskId = $create["taskId"];
do {
sleep(2);
$r = post("https://solver.mintbin.xyz/turnstile/getTaskResult", ["clientKey" => "YOUR_API_KEY", "taskId" => $taskId]);
if ($r["errorId"] !== 0) throw new RuntimeException($r["errorCode"]); // the task failed
} while ($r["status"] !== "ready");
echo $r["solution"]["token"] . PHP_EOL; // the token: submit it with the form
echo $r["solution"]["userAgent"] . PHP_EOL; // send this User-Agent when you submit
import time, requests
payload = {
"clientKey": "YOUR_API_KEY",
"task": {
"type": "TurnstileTaskProxyLess",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAAAAAA..."
}
}
create = requests.post("https://solver.mintbin.xyz/turnstile/createTask", json=payload, timeout=30).json()
if create["errorId"] != 0:
raise SystemExit(create["errorCode"])
task_id = create["taskId"]
while True:
time.sleep(2)
r = requests.post(
"https://solver.mintbin.xyz/turnstile/getTaskResult",
json={"clientKey": "YOUR_API_KEY", "taskId": task_id},
timeout=30,
).json()
if r["errorId"] != 0:
raise SystemExit(r["errorCode"]) # the task failed
if r["status"] == "ready":
break
print(r["solution"]["token"]) # the token: submit it with the form
print(r["solution"]["userAgent"]) # send this User-Agent when you submit
// Node 18+; save as .mjs (top-level await)
const post = (url, payload) =>
fetch(url, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),
}).then((r) => r.json());
const create = await post("https://solver.mintbin.xyz/turnstile/createTask", {
clientKey: "YOUR_API_KEY",
task: {
type: "TurnstileTaskProxyLess",
websiteURL: "https://example.com",
websiteKey: "0x4AAAAAAA..."
}
});
if (create.errorId !== 0) throw new Error(create.errorCode);
let r;
do {
await new Promise((s) => setTimeout(s, 2000));
r = await post("https://solver.mintbin.xyz/turnstile/getTaskResult", { clientKey: "YOUR_API_KEY", taskId: create.taskId });
if (r.errorId !== 0) throw new Error(r.errorCode); // the task failed
} while (r.status !== "ready");
console.log(r.solution.token); // the token: submit it with the form
console.log(r.solution.userAgent); // send this User-Agent when you submitUse TurnstileTask and add to the task: proxyType (http, https, or socks5 without a login), proxyAddress, proxyPort, proxyLogin, proxyPassword. The call then runs through your proxy. Proxied calls can take a few seconds longer. Some keys may not send a proxy (ERROR_PROXY_NOT_ALLOWED).
curl -X POST "https://solver.mintbin.xyz/turnstile/getToken" \
-H "Content-Type: application/json" \
-d '{
"clientKey": "YOUR_API_KEY",
"task": {
"type": "TurnstileTask",
"websiteURL": "https://example.com",
"websiteKey": "0x4AAAAAAA...",
"proxyType": "http",
"proxyAddress": "192.0.2.10",
"proxyPort": 8080,
"proxyLogin": "user",
"proxyPassword": "pass"
}
}'May we load Google reCAPTCHA? It sets a cookie and sends Google details of your device and this visit, which helps us test our service. The site works the same either way, and you can change this anytime under Privacy choices at the bottom of each page. Privacy