> For the complete documentation index, see [llms.txt](https://docs.apexsolutions.lol/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apexsolutions.lol/altcha/getting-started.md).

# Getting Started

How ALTCHA works, how to tell a site uses it, and what the solve returns.

If you already know how ALTCHA works, skip to the **API reference**. This page explains what it is, how to tell a site uses it, and how the whole flow fits together - you do not need to reverse-engineer anything.

## Understanding ALTCHA

ALTCHA is an open-source, privacy-first proof-of-work challenge (MIT). It protects signups and forms by issuing a **challenge**: a target value plus a salt, and the client must find the counter whose hash matches. When the proof is accepted, the form submits with the solved **altcha payload**.

There are two protocol generations in the wild:

* **v1** (most sites): a flat challenge `{algorithm: "SHA-256", challenge, salt, signature, ...}`. The solve is `sha256(salt + number) == challenge` (exact hash match).
* **v2** (newer): a challenge wrapped in `parameters {algorithm: "PBKDF2/SHA-256"|"SCRYPT"|"ARGON2ID", cost, keyLength, keyPrefix, nonce, salt}`. The solve is a key-derivation proof-of-work.

Apex solves both. If the site escalates to the **Code Captcha** (an image you must read), that part is tracked separately - see the notes below.

## Identifying ALTCHA

Before solving, confirm the site actually uses ALTCHA:

1. **The widget.** The page renders an `<altcha-widget>` element (or a form with an `altcha` hidden field).
2. **The challenge.** The widget fetches a challenge from its `challengeurl`, or it is embedded inline (`challengejson`). The JSON is either flat (`algorithm: "SHA-256"`) for v1 or has a `parameters` object for v2.
3. **The payload.** The solved value is a base64 JSON sent in the form's `altcha` field.

You need the **challenge** (or its endpoint) to solve.

## How a session is built

There is no long-lived session. Apex receives the challenge (inline or by URL), computes the proof-of-work, and returns the base64 `altcha` payload. You drop that payload into the form's `altcha` field and submit - the site verifies it server-side.

## Solution Flow

1. **Get the challenge.** From the widget's `challengeurl` (e.g. a WordPress `admin-ajax.php` action) or from the page source.
2. **Solve through Apex.** Send the challenge (or the challenge URL + action) and your proxy (required). Apex returns the `altcha` payload (and the solved `number`). See the API reference for the exact request.
3. **Submit.** Put the payload in the form's `altcha` hidden field and submit normally.

## Important Notes

{% hint style="info" %}
**The payload goes into the form field, not your requests.** It is a base64 JSON that the site's backend verifies. A **proxy is required** - the solver always runs through yours, never from Apex's servers. The **Code Captcha** escalation (image code) is not yet covered - if the challenge includes a `codeChallenge` field, the solve currently returns the proof-of-work payload only.
{% endhint %}

{% hint style="info" %}
**v1 vs v2 payload.** You do not choose the version - the provider detects it from the challenge. Pass a flat challenge (`algorithm: "SHA-256"`) and you get a v1 payload (`{algorithm, challenge, number, salt, signature}` + `number` in the response); pass a challenge with `parameters` and you get the v2 payload (`{challenge, solution}`, no `number`). Just submit the returned `altcha` value to the form.
{% endhint %}