On this page

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

Quick start: Turnstile

Three steps, no polling loop: getToken waits and returns the token. Copy, paste, replace the example values.

1

Get a key

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.

2

Send this request

POST it to /turnstile/getToken. The reply comes when the token is ready.

cURL
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.
3

Use the token

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

JSON
{
  "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"

Task types and fields →

Task types

Every request carries a task.type. Pick one of these two.

task.typeUse it when
TurnstileTaskProxyLessRecommended. Works with managed and non-interactive widgets.
TurnstileTaskSame, through your own proxy. Proxied calls can take a few seconds longer.

Fields

The request body is {"clientKey": "…", "task": {…}}. These go inside task.

BodyRequiredTypeWhat it is
clientKeyyesstringYour API key, in every request.
taskyesobjectThe task: the fields below.
FieldRequiredTypeDefaultWhat to send
typeyesstring—TurnstileTaskProxyLess or TurnstileTask.
websiteURLyesstring—Full URL of the page that shows the widget, e.g. https://example.com/login.
websiteKeyyesstring—The widget's sitekey (0x4AAAAAAA…) from data-sitekey.
actionnostring—The widget's data-action, if set.
cDatanostring—The widget's data-cdata, if set.
timeout_snonumber60 sMost 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 fieldsnostrings, number—Only with TurnstileTask: see Advanced → Use your own proxy. Without them the task runs as ProxyLess.

Limits & timeouts

The values this service uses now.

LimitValue
New tasks per minute, per IP60
Default timeout_s60 s
timeout_s range5–180 s
Token lifetime300 s, works once
Polled results kept10 minutes
Poll getTaskResultevery 2 s
Your own proxyAllowed
Shared service

Rate limits count per IP: 60 new tasks per minute. If you get ERROR_RATE_LIMIT, back off a few seconds and retry.

Code in your language

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..."
  }
}'

The reply

Replies are HTTP 200, failures included. Check errorId, not status, to tell success from failure.

FieldMeaning
errorId0 = success. Anything else = failure.
status"ready" when the token is in solution; "processing" while a polled task runs. Failures have no status.
solution.tokenThe token. Put it in the form's cf-turnstile-response field.
solution.userAgentSend this User-Agent when you submit the token.
taskIdThe task's id. Treat it as an opaque string.
elapsed_sSeconds the call took.
errorCode, errorDescriptionOn failure only: a stable code to branch on and a readable description.

Success

JSON
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "0.RD7PWurbnU39z3XF...9a9d691",
    "userAgent": "Mozilla/5.0 (...)"
  },
  "taskId": "3f2a...",
  "elapsed_s": 8.29
}

Failure

JSON
{
  "errorId": 12,
  "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
  "errorDescription": "No token this time. Retry; a second attempt often succeeds.",
  "taskId": "3f2a..."
}

Errors

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 codesMeaningWhat 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.
Advanced: polling, proxies and more

All endpoints

All paths are under /turnstile. Send clientKey in the JSON body of every POST.

MethodPathWhat it does
POST/turnstile/getTokenOne call: returns the token. Recommended.
POST/turnstile/createTaskStarts a task and returns its taskId.
POST/turnstile/getTaskResultSend {clientKey, taskId}. Returns status:"processing" until the token is ready, then "ready" with the solution. Results stay readable for 10 minutes.
GET/turnstile/healthIs the service up and ready?
GET/turnstile/whoamiThe IP address we see for you. Rate limits count per IP.

Polling instead of one call

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.

JSON
# 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" }'

Use your own proxy

Use 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
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"
    }
  }'

Next steps

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