How to Solve ALTCHA in PHP Inside a Synchronous Request

To solve ALTCHA in PHP you need one call and no browser. ALTCHA is proof of work rather than recognition: the site issues a challenge and the client has to hash until it finds the counter that satisfies it. There is nothing to look at, so no WebDriver and no headless browser are involved, and the answer is computed rather than guessed. CapSkip added the type in version 1.2.6 and the PHP package exposes it as a single method. PHP is the one SDK of the four with no concurrency story at all, and that is what shapes this guide: the call blocks your request while it runs, so the thing to get right is making sure PHP’s own limits do not cut the request off before the solver answers.

What you need

• CapSkip 1.2.6 or later running on a Windows machine. ALTCHA support arrived in that release.
• PHP 8.0 or newer with the curl and json extensions, which ship with most installs. The package has no other runtime dependencies, so it drops into a plain script, Laravel or Symfony alike.
• The URL of the page the widget sits on, and the endpoint the widget asks for its challenge.
• An address for the solver. Local mode answers on 127.0.0.1 for that device only; Server mode listens on your network address or public IP so another machine can reach it. Step 4 covers which one applies, and both live under connection settings.

# composer require capskip/capskip
composer require capskip/capskip

Step 1: the solve call, and where the challenge comes from

One method, two arguments: the page URL, then an options array carrying the challenge. Hand it the endpoint and CapSkip fetches the challenge itself.

// composer require capskip/capskip
require 'vendor/autoload.php';

use CapSkip\CapSkip;

$solver = new CapSkip(['host' => '127.0.0.1', 'port' => 8080]);

// CapSkip fetches the challenge, then hashes until the counter fits.
$result = $solver->altcha('https://example.com/signup', [
    'challenge_url' => 'https://example.com/altcha/challenge',
]);

echo $result['token'];   // base64 payload for the form field
echo $result['number'];  // the counter that satisfied it

Two keys on the returned array belong to ALTCHA alone. The token is the base64 payload the form wants, and the number is the counter that solved the challenge. The code key carries the same string as the token, so either one works, but the token is named for the field it goes into and reads better at the call site. The GeeTest keys and the Turnstile user agent are absent here.

The number is worth logging. It is reported for both ALTCHA generations even though their payloads differ: a legacy token carries the counter at the top level, while a proof-of-work v2 token does not, keeping it inside a solution object instead. CapSkip reads it out of the solution object in the server’s own reply, so both generations are reported the same way.

Find the endpoint the widget asks for

Open DevTools, go to the Network tab and reload the page the widget sits on. The widget makes one request for its challenge, usually to a path with altcha in it. That request URL is what you pass, and the JSON it returns is the challenge document, which you can pass instead.

Do not guess the attribute that names it, because it changed between widget generations. Read the page source.

The three display styles, native, checkbox and switch, are purely visual. They submit the same payload and the difference never reaches the solver, so you do not have to work out which one you are looking at. ALTCHA documents the attributes in its own integration guide.

Passing the challenge document instead

If your code already fetched the challenge, pass the document and no network request happens at all. This is the path to use when the challenge arrives embedded in the page rather than from an endpoint, or when fetching it needs cookies your script has and the solver does not.

// No fetch happens: the document is already here.
$result = $solver->altcha('https://example.com/signup', [
    'challenge_json' => [
        'algorithm' => 'SHA-256',
        'challenge' => 'YOUR_CHALLENGE_HASH',
        'salt'      => 'YOUR_SALT',
        'signature' => 'YOUR_SIGNATURE',
        'maxnumber' => 1000000,
    ],
]);

That option takes an array, which is serialised for you, or a JSON string if you already have one. Sending both the endpoint and the document is allowed and the inline document wins, because fetching would only re-obtain what you just supplied. The two paths behave differently under load, though. An inline challenge that has already expired is refused straight away rather than hashed pointlessly, while an endpoint lets the solver fetch a fresh challenge if the first one died while the job sat in the queue.

Which algorithms the solver covers

The same method handles both generations. The legacy scheme is covered with SHA-1, SHA-256, SHA-384 and SHA-512, and proof-of-work v2 is covered with PBKDF2 and iterative SHA. PBKDF2 is the default that ALTCHA itself recommends, so that covers the large majority of live sites.

Argon2id and scrypt are the exceptions, and they are refused rather than attempted: a task using one comes back in about a third of a second with ERROR_CAPTCHA_UNSOLVABLE and is never retried. That is deliberate. A memory-hard function is not something a retry fixes, so failing immediately beats looking busy. For ALTCHA that result points at the algorithm rather than at an unreadable image, and the error code has a guide of its own.

Step 2: keep the solve inside your execution limit

This is the PHP-specific part, and it is the one that produces a confusing failure. The call blocks. PHP has no background task here and the async client in the package is only an alias kept for parity with the other SDKs, so while the solver works your request sits there. Two clocks are now running against each other, and they fail very differently.

A happy ALTCHA solve takes milliseconds, so in normal operation neither clock matters. They matter on the bad path: the solver is busy behind a queue of reCAPTCHA jobs, and the call waits. The client’s own ceiling for ALTCHA is the default polling timeout of 120 seconds, and ALTCHA uses that one rather than the longer reCAPTCHA timeout because it is CPU work and not a browser session.

Against that, PHP’s own max_execution_time defaults to 30 seconds on a web request and to zero, meaning no limit, on the command line. Whether it fires during a solve depends on the platform, which is why this catches people out. On Unix-like systems it does not count time the script spends waiting on a socket, so a long solver wait can slip past it entirely. On Windows the same setting is measured as real time, so it fires. Either way there are other ceilings above it that do not care: PHP-FPM has request_terminate_timeout, and the web server in front has a read timeout of its own.

The difference that matters is what you get when each one wins. If the SDK’s timeout is reached first you get a TimeoutException, which your catch block handles and turns into a sensible response. If either of the other two wins, the script is killed outright and no catch block runs. Those two are not the same either: PHP’s own limit ends the request with a fatal error that lands in your error log and still runs your shutdown functions, while a process manager or web server that kills the worker runs nothing and leaves the visitor a 502 or 504 with nothing useful in it. So set the client’s ceiling deliberately, under whatever will cut the request off.

// Keep the client's ceiling under whatever kills the request.
$solver = new CapSkip([
    'host'           => '127.0.0.1',
    'port'           => 8080,
    'defaultTimeout' => 20,   // ALTCHA and image CAPTCHA polling
]);

Twenty seconds is generous for a type that normally finishes in milliseconds, and it leaves room under a default 30 second web limit for the rest of the request to run. On the command line, where there is no execution limit, leave the default alone. If a solve regularly gets near any of these numbers the problem is not the timeout, it is that the solver is not reachable or is saturated, and raising the ceiling only makes the request hang for longer before saying so.

Step 3: post the token back unchanged, before it expires

The widget submits its payload in a form field named altcha, so that is where your token goes. This is the step that quietly breaks.

// Send it exactly as it came back: no trimming,
// no re-encoding, no reordering.
$body = http_build_query([
    'email'  => '[email protected]',
    'altcha' => $result['token'],
]);

$ch = curl_init('https://example.com/signup');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

The token is base64 of a JSON document whose fields are covered by the server’s own HMAC signature. Any modification invalidates it, so anything that looks like tidying up will break the submit: trimming whitespace, decoding and re-encoding it, or rebuilding the JSON with the keys in a different order. Watch out for well-meaning input filters in a framework, since a sanitiser applied to outgoing form data will happily strip a character and leave you with a payload that no longer matches its signature. Some integrations read the payload out of a JSON body field rather than a form field, so check what the page’s own submit sends and mirror that.

The other way this step fails is timing. Challenge windows are short and some sites close them inside two minutes. When one expires, the site refuses the answer with a bare verification failure that looks exactly like a wrong answer, and there is nothing in the response to tell you which of the two happened. Three habits avoid it: fetch the challenge immediately before solving rather than at the top of a long run, submit the token in the same request that solved it, and never hold a token in a session while a person fills in a form.

Step 4: where the solver runs, and which connection mode that needs

The samples above use 127.0.0.1 because that is right when PHP and the solver share a machine. As soon as the code runs somewhere else, such as a container, a web host, a VPS or a CI runner, loopback no longer points at the solver, and the first solve throws a NetworkException.

Switch CapSkip to Server mode and it listens on your network address or public IP instead, so any of those can reach it over the same HTTP API. A static public IP is recommended when the route goes over the internet, with a firewall rule that allows only the addresses you expect. Server mode changes where the solver listens and nothing else: it is still your hardware, and it is still unmetered. Read the host and port from the environment so one deployment works in both places. The client does not read CAPSKIP_HOST or CAPSKIP_PORT by itself, so pass them to the constructor, as the full example below does.

One ALTCHA-specific note on proxies. A proxy is supported here, but it is used only for the challenge fetch. There is no browser session to route, so it has no effect on the proof of work itself.

Full working example

// composer require capskip/capskip
require 'vendor/autoload.php';

use CapSkip\CapSkip;
use CapSkip\Exceptions\ApiException;
use CapSkip\Exceptions\NetworkException;
use CapSkip\Exceptions\TimeoutException;

$solver = new CapSkip([
    'host'           => getenv('CAPSKIP_HOST') ?: '127.0.0.1',
    'port'           => (int) (getenv('CAPSKIP_PORT') ?: 8080),
    'defaultTimeout' => 20,
]);

try {
    // Fetch, solve and submit inside the one request.
    $result = $solver->altcha('https://example.com/signup', [
        'challenge_url' => 'https://example.com/altcha/challenge',
    ]);

    $body = http_build_query([
        'email'  => '[email protected]',
        'altcha' => $result['token'],
    ]);
    // POST $body to the form here, while the challenge is still fresh.

    echo 'solved at counter ' . $result['number'];
} catch (ApiException $e) {
    // ERROR_CAPTCHA_UNSOLVABLE here means Argon2id or scrypt.
    echo 'refused: ' . $e->getMessage();
} catch (TimeoutException $e) {
    echo 'gave up waiting, before anything could kill the request';
} catch (NetworkException $e) {
    echo 'solver unreachable: check the host and the connection mode';
}

All four exceptions extend a common base class, so catching that one instead handles every failure the SDK can raise in a single block. Catch the specific ones when the response differs, as above, and the base class when it does not.

The other types are the same shape with a different method. The reCAPTCHA call takes a sitekey and a page URL, Turnstile works the same way, GeeTest takes a gt value and a challenge alongside the page URL, and image solving takes a file path, a URL or base64. The full method list is on the PHP CAPTCHA solver page.

Turnstile is the one type that needs more than a sitekey when it arrives as a full challenge page. Its extra values are covered in the PHP Turnstile guide.

Common errors and what they mean

FAQ

The short version

Read the challenge endpoint off the widget, pass it to the one ALTCHA method along with the page URL, and post the token back into the field named altcha without touching it. Set the client’s default timeout under whatever will kill the request first, because a TimeoutException you can catch is worth a great deal more than a request the process manager terminates. Keep the fetch, the solve and the submit in the same request, since the challenge window can close inside two minutes and an expired challenge looks exactly like a wrong answer. Switch to Server mode the moment PHP stops sharing a machine with the solver.

• What the challenge is and how the type works: the ALTCHA solver page.
• Every other method the PHP package exposes: the PHP solver page.

One last thing that changes how you design the retry. Because this route to captcha bypass computes the proof of work on a machine you already own, retrying an expired challenge costs a few milliseconds of your own CPU and nothing else, so you can afford to fetch a fresh challenge rather than nursing a stale one.