Documentation

Quick start

1. 1Open the console and create an account number. Every account comes with an API key.
2. 2Top up your balance.
3. 3Send the request below with your key; the token comes back in the response.

curl -G "https://resolver.guru/v1/api" \
  --data-urlencode "key=xxxxxxxxxxxx" \
  --data-urlencode "sitekey=0x4AAAAAAA..." \
  --data-urlencode "url=https://example.com/login"

Authentication

Send your API key as the key parameter on every request, in the query string with the other parameters. Create and revoke keys under API keys in the console.

Because the key is part of the URL, it can show up in tools that record request URLs (logs, error tracking). Do not share those records; if you think a key has leaked, revoke it in the console and create a new one.

https://resolver.guru/v1/api?key=xxxxxxxxxxxx&sitekey=…&url=…

Never put your key in code that runs in the browser (frontend). Always send requests from your own server.

Token request

Requests are sent with GET; parameters go in the query string. Remember to URL-encode the values (the libraries in the examples do this for you).

curl -G "https://resolver.guru/v1/api" \
  --data-urlencode "key=xxxxxxxxxxxx" \
  --data-urlencode "sitekey=0x4AAAAAAA..." \
  --data-urlencode "url=https://example.com/login" \
  --data-urlencode "action=login" \
  --data-urlencode "cdata=abc123"

Where do I find the sitekey?

Look at the target page’s HTML for an element with the cf-turnstile class or a turnstile.render(…) call:

<div class="cf-turnstile"
     data-sitekey="0x4AAAAAAA..."   // → sitekey
     data-action="login"            // → action
     data-cdata="abc123"></div>     // → cdata

Response

A successful response returns 200:

{
  "status": "success",
  "token": "0.Rk9aXw3QpL7mT2vB8nYc...",
  "solve_time": 1.21
}

Every response includes your remaining balance (USD) in the X-Balance header.

On failure you get status: "error", a machine-readable error code and a message:

{
  "status": "error",
  "error": "insufficient_balance",
  "message": "Your balance is too low. Top up in the console."
}

Error codes

Examples

Copy your real key from the console and replace xxxxxxxxxxxx.

import requests

def solve(sitekey, url, action=None, cdata=None):
    params = {"key": "xxxxxxxxxxxx", "sitekey": sitekey, "url": url}
    if action: params["action"] = action
    if cdata: params["cdata"] = cdata

    res = requests.get(
        "https://resolver.guru/v1/api",
        params=params,
        timeout=100,
    )
    data = res.json()
    if data["status"] != "success":
        raise RuntimeError(data["error"])
    return data["token"]

token = solve("0x4AAAAAAA...", "https://example.com/login")

Using the token

Put the token in the field the target site’s form uses for Turnstile. The default field name is cf-turnstile-response.

Turnstile tokens are valid for about 300 seconds and can be used only once. Use the token right after you get it, and request a new one for every submission.

Pricing and limits

• Price: $0.30 per 1,000 tokens ($0.00030 per token). No subscription.
• Only successful solves are billed. Requests that return an error never touch your balance.
• Up to 20 requests per account are processed at the same time; more return 429.
• A solve can take up to 90 seconds. Set your client timeout to at least 100 seconds.
• For solve_failed, timeout and 429, wait a few seconds and retry 2–3 times.