> 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/mtcaptcha/getting-started.md).

# Getting Started

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

If you already know how MTCaptcha 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 MTCaptcha

MTCaptcha is a commercial image-captcha service. It protects signups, logins and forms by serving a **distorted-image challenge**: a 5-7 lowercase-letter code rendered with a noisy background and wavy distortion. The client must read the code from the image and send it back together with the proof the site requires. The server verifies both before issuing a one-time **vt token**.

The challenge is served from the MTCaptcha domain inside an iframe, so a plain HTTP client cannot read the image or produce the required proof.

## Identifying MTCaptcha

Before solving, confirm the site actually uses MTCaptcha:

1. **The widget.** The page renders an MTCaptcha iframe (`mtcv1/client/iframe.html?...&sitekey=...`).
2. **The sitekey.** Every deployment has a **public sitekey** (format `MTPublic-...`), visible in the iframe URL or the page source.
3. **The token.** On success the widget fills the form's hidden token field with the verified `vt` value.

You need the **sitekey** and the **site host** to solve.

## How a session is built

There is no long-lived session. Apex reads the distorted image, produces the required proof, and verifies against the server - then returns the one-time **vt token**. You drop that token into the form's token field and submit - the site accepts it server-side.

{% hint style="info" %}
**The token is single-use and short-lived.** Each `vt` is issued for exactly one verified solve; if the form rejects it, request a new solve. Because each challenge is one-shot (a wrong guess invalidates it), Apex retries internally with fresh challenges until it gets a verified token (up to `max_attempts`, default 4).
{% endhint %}

## Solution Flow

1. **Get the sitekey and host.** The sitekey from the MTCaptcha iframe URL; the host from the page's origin (e.g. `https://example.com`).
2. **Solve through Apex.** Send the `sitekey`, the `host`, and **your proxy** (always required). Apex returns the verified `vt` token. See the API reference for the exact request.
3. **Submit.** Put the `vt` value in the form's token field and submit normally.

## Important Notes

{% hint style="warning" %}
**A proxy is required.** The solver always runs through **your** proxy - never from Apex's servers. Pass it in the `proxy` field of the request.
{% endhint %}

{% hint style="info" %}
**What you get back.** The response carries the verified `vt` under `result`. Pass `host`/`hostname`/`lang` for your target alongside the `sitekey` - no site is assumed.
{% endhint %}