> 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/api-reference/altcha.md).

# Altcha

Solve the ALTCHA proof-of-work challenge and get the altcha payload.

Solves an ALTCHA challenge (v1 SHA-256 hash-match or v2 key-derivation PoW) and returns the base64 `altcha` payload to drop into the site's form.

### What you get back

The response carries the `altcha` payload under `result`, plus the solved `number` (v1). Put the payload in the form's `altcha` hidden field and submit normally - the site verifies it server-side.

### v1 vs v2

The request is identical for both protocols: you pass the challenge and the provider detects the version automatically. The `altcha` payload you get back corresponds to the challenge version you submitted:

* **v1** (flat challenge with `algorithm: "SHA-256"`) -> a base64 payload of `{algorithm, challenge, number, salt, signature}`, and the response includes `number`.
* **v2** (challenge with a `parameters` object) -> a base64 payload of `{challenge, solution}`, with no `number`.

You do not need to choose a version - pass the challenge as captured from the widget or endpoint and the payload will match its format.

### Proxy

A **proxy is required** - the solver always runs through yours, never from Apex's servers.

## Solve the ALTCHA challenge

> Solves the ALTCHA proof-of-work for a challenge passed inline\
> (\`challenge\`) or fetched from a \`challenge\_url\` (optionally with an\
> \`action\` for WordPress \`admin-ajax.php\` endpoints), and returns the\
> \`altcha\` payload.<br>

```json
{"openapi":"3.0.3","info":{"title":"Altcha","version":"1.0.0"},"tags":[{"name":"Altcha","description":"Solves an ALTCHA challenge (v1 SHA-256 hash-match or v2 key-derivation\nPoW) and returns the base64 `altcha` payload to drop into the site's form.\n\n## What you get back\n\nThe response carries the `altcha` payload under `result`, plus the\nsolved `number` (v1). Put the payload in the form's `altcha` hidden\nfield and submit normally - the site verifies it server-side.\n\n## v1 vs v2\n\nThe request is identical for both protocols: you pass the challenge and\nthe provider detects the version automatically. The `altcha` payload you\nget back corresponds to the challenge version you submitted:\n\n- **v1** (flat challenge with `algorithm: \"SHA-256\"`) -> a base64 payload\n  of `{algorithm, challenge, number, salt, signature}`, and the response\n  includes `number`.\n- **v2** (challenge with a `parameters` object) -> a base64 payload of\n  `{challenge, solution}`, with no `number`.\n\nYou do not need to choose a version - pass the challenge as captured from\nthe widget or endpoint and the payload will match its format.\n\n## Proxy\n\nA **proxy is required** - the solver always runs through yours, never\nfrom Apex's servers.\n"}],"servers":[{"url":"https://altcha.apexsolutions.lol"}],"paths":{"/payload":{"post":{"tags":["Altcha"],"summary":"Solve the ALTCHA challenge","description":"Solves the ALTCHA proof-of-work for a challenge passed inline\n(`challenge`) or fetched from a `challenge_url` (optionally with an\n`action` for WordPress `admin-ajax.php` endpoints), and returns the\n`altcha` payload.\n","parameters":[{"name":"Content-Type","in":"header","required":true,"description":"The Content-Type of the request body.","schema":{"type":"string","enum":["application/json"]}},{"name":"Authorization","in":"header","required":true,"description":"Your API key for authentication.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AltchaSolveRequest"}}}},"responses":{"200":{"description":"Challenge solved. The altcha payload is under `result`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AltchaSolveResponse"}}}},"400":{"description":"Missing or invalid request. See the error envelope for the reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Proxy connection failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"AltchaSolveRequest":{"type":"object","required":["params","proxy"],"properties":{"params":{"type":"object","properties":{"challenge":{"description":"The ALTCHA challenge, as captured from the widget or endpoint.\nPass the v1 flat form or the v2 `parameters` form; the provider\ndetects the version automatically.\n","oneOf":[{"$ref":"#/components/schemas/AltchaV1Challenge"},{"$ref":"#/components/schemas/AltchaV2Challenge"}]},"challenge_url":{"type":"string","description":"Endpoint that returns the challenge (GET, or POST when `action` is set)."},"action":{"type":"string","description":"For WordPress `admin-ajax.php` endpoints, the action parameter (e.g. `tt_get_altcha_challenge`)."}}},"proxy":{"type":"string","description":"Required. Your proxy - the solver always routes through it, never from Apex's servers."}}},"AltchaV1Challenge":{"type":"object","required":["algorithm","challenge","salt"],"properties":{"algorithm":{"type":"string","description":"Always `SHA-256`.","enum":["SHA-256"]},"challenge":{"type":"string","description":"The target hash (hex) the solve must match."},"salt":{"type":"string","description":"The salt concatenated with the counter for hashing."},"signature":{"type":"string","description":"HMAC signature of the challenge."},"timestamp":{"type":"integer","description":"Optional expiry timestamp (seconds)."},"maxnumber":{"type":"integer","description":"Optional counter limit (defaults to 1,000,000)."}}},"AltchaV2Challenge":{"type":"object","required":["parameters"],"properties":{"parameters":{"type":"object","required":["algorithm","cost","keyLength","keyPrefix","nonce","salt"],"properties":{"algorithm":{"type":"string","enum":["PBKDF2/SHA-256","SCRYPT","ARGON2ID"]},"cost":{"type":"integer","description":"Algorithm-specific cost (iterations, time cost, etc.)."},"keyLength":{"type":"integer","description":"Derived key length in bytes."},"keyPrefix":{"type":"string","description":"Hex prefix the derived key must start with."},"nonce":{"type":"string"},"salt":{"type":"string"}}},"signature":{"type":"string","description":"HMAC signature of the challenge."}}},"AltchaSolveResponse":{"type":"object","properties":{"solve_id":{"type":"string","description":"Identifier of the solve."},"status":{"type":"string","description":"Always `succeeded` on a 200."},"provider":{"type":"string","description":"Always `altcha`."},"result":{"type":"object","properties":{"altcha":{"type":"string","description":"The base64 payload to drop into the form's `altcha` field."},"number":{"type":"integer","description":"The solved counter (v1)."}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}}}}}}}}
```