> 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/workflow.md).

# Integration Workflow

The end-to-end MTCaptcha integration: send the sitekey and host, get the verified vt token, and submit.

The step-by-step implementation of the MTCaptcha flow. Each step describes what to do and why, with the actual requests against Apex. The full request and response reference lives in the **API reference**.

## Step 1: Get the sitekey and host

Every MTCaptcha deployment has a public sitekey. Find it in the widget iframe URL:

```
https://service.mtcaptcha.com/mtcv1/client/iframe.html?v=...&sitekey={site_key}&...
```

or in the page source where the MTCaptcha widget is initialized. You also need the **host** of the target page (its origin, e.g. `https://example.com`).

## Step 2: Solve through Apex

Call Apex with the `sitekey`, the `host`, and **your proxy** (always required):

{% tabs %}
{% tab title="Go" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"params": map[string]any{
			"sitekey": "{site_key}",
			"host":    "https://example.com",
		},
		"proxy": "http://user:pass@host:port",
	})

	req, _ := http.NewRequest("POST", "https://mtcaptcha.apexsolutions.lol/payload", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer your-api-key")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

resp = requests.post(
    "https://mtcaptcha.apexsolutions.lol/payload",
    headers={"Authorization": "Bearer your-api-key"},
    json={
        "params": {"sitekey": "{site_key}", "host": "https://example.com"},
        "proxy": "http://user:pass@host:port",
    },
)

print(resp.status_code, resp.json())
```

{% endtab %}

{% tab title="JS/TS" %}

```jsts
const resp = await fetch("https://mtcaptcha.apexsolutions.lol/payload", {
  method: "POST",
  headers: {
    "Authorization": "Bearer your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    params: {
      sitekey: "{site_key}",
      host: "https://example.com",
    },
    proxy: "http://user:pass@host:port",
  }),
});

const data = await resp.json();
console.log(data);
```

{% endtab %}
{% endtabs %}

The response gives you the verified `vt` token under `result`.

## Step 3: Submit the token

Put the `vt` value into the form's token field (the field MTCaptcha normally fills) and submit normally - the site's backend verifies it server-side:

```python
import requests

form = {"domain": "example.com", "token": vt}
resp = requests.post("https://{target}/form", data=form)
print(resp.status_code, resp.text)
```

## Important Notes

{% hint style="warning" %}
**A proxy is required.** The solver always runs through your proxy - never from Apex's servers. Omitting it returns an error.
{% endhint %}

{% hint style="info" %}
**The token is single-use and short-lived.** If the form rejects it, the token likely expired or was already used - solve again. **Internal retries are automatic**: each challenge is one-shot, so Apex retries with fresh challenges until the server verifies a token (up to `max_attempts`, default 4). Optional `hostname`/`lang` refine the target; nothing is assumed about the site.
{% endhint %}