Recaptcha v3 solver API: Call it and use the token

A recaptcha v3 solver API returns a token, not a score: you send the sitekey, page URL and exact action, and get back a token that you submit to the target form or endpoint. Google scores that token when the site’s backend calls siteverify, so no solver can promise a score. Wayfern’s endpoint is POST /api/captcha/solve, billed 1 credit only on success.

A solver can return a token without an error, and the site can still reject your request. The site’s backend decides what the token is worth after it checks it. This affects developers who test their own reCAPTCHA integration, run QA, or collect public data within a site’s terms.

Use a solver for lawful purposes only. After reading, you can find the inputs a v3 task needs, call the endpoint, handle the returned token, and decide when a real browser is the better tool.

Key Takeaways

• Send the exact action string the page passes to grecaptcha.execute; the action name matters as much as the sitekey.
• Google says tokens expire after two minutes and can be verified once, so request one per submission.
• A token is only as good as the session around it: keep IP, cookies and user-agent consistent.
• For multi-step flows, a real browser over CDP lets the page mint its own token.

How does a reCAPTCHA v3 solver API work, and what does the score mean?

A reCAPTCHA v3 solver API takes a sitekey, page URL and action, runs the v3 flow and returns a token, which Google later scores against the site’s threshold, which Google documents as 0.5 by default.

v3 has no checkbox and no image grid. The page calls grecaptcha.execute with the sitekey and an action name, and Google hands a token back to the browser.

The score appears one step later. The site’s backend sends the token and its secret key to siteverify, and Google answers with JSON. Here is a response shaped like the one in Google’s documentation, with illustrative values:

{
  "success": true,
  "score": 0.9,
  "action": "login",
  "challenge_ts": "2025-01-01T12:00:00Z",
  "hostname": "example.com"
}

Google documents the range this way: “reCAPTCHA v3 returns a score (1.0 is very likely a good interaction, 0.0 is very likely a bot).” Your solver never sees this response, because the secret key lives on the site’s server.

That splits the work in two. The solver controls the inputs it sends and the token it returns. It does not control the score Google computes, the threshold the site sets, or what the backend does when the score falls below it.

A task can therefore succeed and the token can verify with success: true while the site still rejects the request. A site can set its threshold higher than the default.

Wayfern’s captcha solving endpoint returns a token. We don’t guarantee a score, and we don’t claim to bypass anything. The score reflects the whole session, and the token is only one input to it.

How do you find the sitekey and action for a reCAPTCHA v3 task?

You find the sitekey and action by searching the page for the reCAPTCHA script URL and the grecaptcha.execute call, then checking whether the script is the Enterprise build.

1. Open the page that submits the protected action, not the homepage, then press Ctrl+Shift+F (Cmd+Option+F on macOS) in DevTools to search all loaded sources.

2. Search for render=. Google’s v3 docs load the library from api.js?render=reCAPTCHA_site_key, so the value after render= is the sitekey. Pages that bind v3 to a button put it in a data-sitekey attribute instead.

3. Search for grecaptcha.execute to read the action. Google’s documented pattern is grecaptcha.execute('reCAPTCHA_site_key', {action: 'submit'}). Copy the string as written. For a button binding, look for a data-action attribute.

4. Check for Enterprise: search for enterprise.js in script URLs and grecaptcha.enterprise.execute in code. If either appears, the sitekey belongs to the Enterprise flow, so choose your solver’s Enterprise v3 task type. A standard task type produces a token from the wrong flow.

5. Send the page URL where the challenge runs, plus the sitekey and the action.

This console snippet lists all three signals on the current page:

const scripts = [...document.scripts];
console.log(scripts.map(s => s.src).filter(s => s.includes('recaptcha')));
console.log(scripts.map(s => s.textContent).join('\n')
  .match(/grecaptcha(\.enterprise)?\.execute\([^)]*\)/g));
console.log([...document.querySelectorAll('[data-sitekey],[data-action]')]
  .map(e => ({ sitekey: e.dataset.sitekey, action: e.dataset.action })));

The snippet reads only inline code. If the call lives in an external bundle, use the Sources search from step 1.

Don’t assume the action is submit, because the site chooses its own action names. Captcha.fun’s reference describes the field as “The reCAPTCHA v3 action value the page passes to grecaptcha.execute” and rejects an empty one with a 400. Capzy puts it the same way: “the action name matters as much as the key.”

A wrong action gets rejected because Google’s siteverify response includes the action, described in the docs as “the action name for this request (important to verify)“. A backend that compares it will reject a mismatch even when the token is valid.

When you finish, you have one sitekey string, one exact action string, and a clear Enterprise or standard answer.

How do you call a reCAPTCHA v3 solver API with Wayfern?

You call the Wayfern captcha endpoint with one authenticated POST to https://api.wayfern.com/api/captcha/solve that carries a recaptcha_v3 task. The answer is in solution.token. The POST waits about 90 seconds; when the solve takes longer, it returns 202 with an id, and you read the result with GET /api/captcha/solve/{id}.

1. Mint a captcha-scoped token. Export it as WF_TOKEN and never paste it into source.
2. Build the task from the sitekey and exact action you found, and a minScore of 0.3, 0.7 or 0.9. For Enterprise, add "enterprise": true.
3. Send it with a timeout and a retry cap. Retry only on a timeout, a 429 or a 5xx. Any other 4xx means the task was refused, so fix the task instead of resending it.
4. Submit the returned token to the target right away.

import os, time
import requests

URL = "https://api.wayfern.com/api/captcha/solve"
HEADERS = {"Authorization": f"Bearer {os.environ['WF_TOKEN']}"}
BODY = {"task": {
    "type": "recaptcha_v3",
    "websiteURL": "https://example.com/login",
    "websiteKey": "SITEKEY_FROM_PAGE",
    "minScore": 0.7,
    "action": "login",
}}

def solve(attempts=2):
    for n in range(attempts):
        r = requests.post(URL, json=BODY, headers=HEADERS, timeout=120)
        while r.status_code == 202:
            r = requests.get(f"{URL}/{r.json()['id']}", headers=HEADERS, timeout=30)
        if r.ok:
            return r.json()["solution"]["token"]
        if r.status_code == 429 or r.status_code >= 500:
            time.sleep(3 * 2 ** n)
            continue
        raise RuntimeError(f"task refused: {r.json()['error']}: {r.json()['message']}")
    raise RuntimeError("no result within retry budget")

Billing is 1 credit per successful solve, charged only on success, so a refused or failed task costs nothing. Current rates are on our pricing page.

If you stop waiting, the task keeps running for up to 5 minutes. Read it again by its id instead of sending a new task.

The captcha limit is 20 requests a minute, published on the limits page. Queue requests on your side instead of retrying into a 429. Try the call against your own test page with a captcha-scoped token before you wire it into a pipeline.

What do you do with the token after the solver returns it?

After the solver returns a token, you submit it in the field or request parameter the page’s own JavaScript fills, and the site’s backend verifies it once with Google’s siteverify endpoint.

1. Find where the page puts the token: open DevTools, switch to the Network tab and submit the form by hand. Note the form field or JSON key that carries the token, then send the same key in your HTTP request.
2. Solve right before you submit. Google’s v3 documentation says “reCAPTCHA tokens expire after two minutes.” Never pre-solve a batch of tokens and let them sit in a queue.
3. Request a fresh token after any failed submit.
4. Keep the same proxy and user-agent from the page load to the submit. Wayfern solves recaptcha_v3 from the solver’s own network, so the solver can’t control that part of the session for you.

The backend decides what the token is worth by checking these siteverify response fields:

Field	What to check
success	Must be true. If not, read error-codes.
score	Compare it with your threshold constant.
action	Must equal the string you expect for that endpoint.
hostname	Must match your own domain.
challenge_ts	Log it to see how old the token was.
error-codes	Log the list on every failure.

If you own the site, call siteverify from a test backend and log all six fields. Google’s docs warn that “reCAPTCHA learns by seeing real traffic on your site. For this reason, scores in a staging environment or soon after implementing may differ from production.” Tune the threshold from your own production traffic.

import os, requests

THRESHOLD = 0.5
EXPECTED_ACTION = "login"
EXPECTED_HOST = "example.com"

def verify(token):
    r = requests.post(
        "https://www.google.com/recaptcha/api/siteverify",
        data={"secret": os.environ["RECAPTCHA_SECRET"], "response": token},
        timeout=10,
    ).json()
    print(r)  # log success, score, action, challenge_ts, hostname, error-codes
    return (
        r.get("success") is True
        and r.get("action") == EXPECTED_ACTION
        and r.get("hostname") == EXPECTED_HOST
        and r.get("score", 0) >= THRESHOLD
    )

To test the action check, send a token generated for signup to a login endpoint that expects login. siteverify returns success: true, score: 0.9, action: "signup", and verify still returns False because the action differs.

If that rejection never shows in your logs, your backend accepts tokens minted for the wrong action.

Why can a valid reCAPTCHA v3 token still score low or get rejected?

A valid reCAPTCHA v3 token can still score low or get rejected because token validity and session quality are separate, and a solver controls only the first.

Google describes v3 as “a score-based system to assess user interactions without interrupting their experience, allowing you to take appropriate actions based on risk levels.” The score is Google’s judgment of the session, and the site picks the threshold it accepts.

The solver mints the token on its side, from its own IP and browser. Your submit request leaves from your IP, with your user-agent and your cookies.

If the address that minted the token differs from the one that submits it, the site has a mismatch it can read. A cookie replayed from a new IP is the same kind of signal.

Some vendors handle this with a proxy-based task type. Capsolver, for example, says its “ReCaptchaV3Task is a task type that requires your own proxies to work.” Wayfern solves recaptcha_v3 from the solver’s own network, also when one of your browser sessions has the page open. Its API reference lists the inputs the task accepts, so send only the fields documented there.

You control four parts of the flow:

• Exit IP: keep one stable exit from the page load to the final submit.
• User-agent: send the same string on every request in the flow.
• Timing: solve right before you submit, and use each token once.
• Action: pass the exact string the page gives to grecaptcha.execute.

You don’t control Google’s score model, the site’s threshold, or what the site does with the cookies around the token.

If the session itself has to look consistent, a plain HTTP call may be the wrong tool. Driving a real browser over CDP lets the page run grecaptcha.execute inside your own session. Our comparison of anti-detect browsers covers that trade-off.

reCAPTCHA v3 solver API or a real browser: which do you need?

You need the reCAPTCHA v3 solver API when your code already speaks HTTP and you control the submit step, as in one-shot form posts or tests of your own integration. You need a real browser when the page must mint its own token inside a consistent, multi-step session.

Criterion	Token API (/api/captcha/solve)	Real browser over CDP
Who runs grecaptcha.execute	The solver	The target page
Where the token is minted	Solver side	Inside the browser you drive
State across steps	Yours to carry in HTTP code	Cookies and storage live while the socket is open
Setup time	One POST	Browser cold start
Billing unit	1 credit per successful solve	Credits per open-page hour

Drive a real browser when the page must run grecaptcha.execute itself, cookies and storage must stay consistent, or the flow has several steps. The browser path costs more time and credits than a token call.

In the browser version of a login flow, the page’s own script mints the token when you click submit:

const browser = await chromium.connectOverCDP("wss://api.wayfern.com/ws?token=LINK_TOKEN");
const page = await browser.contexts()[0].newPage();
await page.goto("https://example.com/login");
await page.click("#submit");

The HTTP version posts the sitekey, URL and action to /api/captcha/solve, then attaches the returned token to your own request.

Playwright’s docs say connectOverCDP attaches Playwright to an existing browser instance using the Chrome DevTools Protocol.

The browser has limits. Wayfern has no persistent customer profiles, so save and restore cookies in your own code. A hosted browser also doesn’t remove the need to respect the site’s terms. For multi-step sessions, see our guides to anti-detect browser sessions and authenticated scraping.

The two approaches combine. Wayfern says search, captchas and MCP share one balance, so a hybrid flow can use the browser for the session and the endpoint for a hard challenge without a second account.

Frequently asked questions

Can a reCAPTCHA v3 solver API guarantee a score?

No. The token carries no score. Google calculates the score when the site’s backend calls siteverify, and the site sets its own threshold. A solver can return a valid token, but the result depends on the session that submits it, including the IP and user-agent, so no vendor can honestly promise a score.

How long is a reCAPTCHA v3 token valid, and can I reuse it?

Google says a token is valid for two minutes and can be verified only once. Request a fresh token for each submission, right before you send the form. A reused token fails verification.

What is the difference between reCAPTCHA v3 and v3 Enterprise tasks?

The difference follows the script the page loads. If the page loads enterprise.js and calls grecaptcha.enterprise.execute(), send a recaptcha_v3 task with "enterprise": true. Otherwise send a plain recaptcha_v3 task. Both go to POST /api/captcha/solve.

Am I charged when a solve fails?

No. Wayfern charges 1 credit only for a successful solve, so a failed solve costs nothing. Current rates are on the pricing page.

Is using a reCAPTCHA solver legal?

It depends on what you use it for and where. Keep it to your own site, QA of your own integration, and public data collected within a site’s terms. Ask a lawyer about your specific case.

How to start testing a reCAPTCHA v3 solver API today

Today, open your target page and read the sitekey and the exact action string from the grecaptcha.execute call. Then decide whether a token API or a browser you drive over CDP fits the flow.

This week, run the full request lifecycle with a client timeout and a bounded retry. Log success, score, action and hostname from every siteverify response.

After that, tune your thresholds from your own traffic, and keep your request volume under the captcha rate limit.

To test a recaptcha v3 solver api against your own integration, or against public data within a site’s terms, create a Wayfern account and mint a captcha-scoped wf_ token. Send your first task to POST /api/captcha/solve; the quickstart in the Wayfern docs shows the request. There’s no free tier, but credit packs work without a plan.

Sources

reCAPTCHA v3: Score & Action Solver API | Capzy · reCAPTCHA v3 | Google for Developers · API Reference - CDP, Web Data & Search | Wayfern · Pricing - Credits for Browsers & the Web Data API | Wayfern · Verifying the user’s response | reCAPTCHA | Google for… · reCAPTCHA v3 Solver API Reference | Captcha.fun · Wayfern limits · reCAPTCHA v3 Solver - Fast & Auto reCAPTCHA v3 Recognition…. Every other source is linked where the article cites it.