API Reference

Complete guide for integrating with the Solvium API.

Looking for API key? Message our bot — @solvium_crypto_bot

Working with the API consists of two main parts: creating a task and getting the task status. Let's look at the first step — creating a task.

Step 1. Creating a Task

To create a task, you need to use one of the methods for your required task. You can see the methods below.

Cloudflare

GET

Create Turnstile Task

The server responds with a task identifier that can be used to check the solution status.

Turnstile

URL

https://captcha.solvium.io/api/v1/task/turnstile

Parameters

Name	Type	Required	Description	Default	Example
url	Query	Yes	URL where the captcha is located.	—	https://testnet.monad.xyz
sitekey	Query	Yes	Key that can be found in the page's source code.	—	0x4AAAAAAA-3X4Nd7hf3mNGx

Headers

Name	Type	Required	Description	Default	Example
authorization	Header	Yes	Your API key, available at @solvium_crypto_bot	—	Bearer IE0B81Vn...

Responses

Google

GET

Create reCAPTCHA V2 Task

The server responds with a task identifier that can be used to check the solution status.

Turnstile

URL

https://captcha.solvium.io/api/v1/task/recaptcha-v2

Parameters

Name	Type	Required	Description	Default	Example
url	Query	Yes	URL where the captcha is located.	—	https://example.com
sitekey	Query	Yes	Key that can be found in the page's source code.	—	6Lc4jRkrAAAAAA...
action	Query	No	This parameter is specified during reCAPTCHA call.	—	SIGNUP
enterprise	Query	No	Indicates that the Enterprise version of reCAPTCHA needs to be solved.	false	true
proxy	JSON	Yes	Proxy through which the solution will be obtained.	—	http://user:password@address:port

Headers

Name	Type	Required	Description	Default	Example
authorization	Header	Yes	Your API key, available at @solvium_crypto_bot	—	Bearer IE0B81Vn...

Responses

Examples

Noname

GET

Create Noname Task

The server responds with a task identifier that can be used to check the solution status.

Turnstile

URL

https://captcha.solvium.io/api/v1/task/noname

Parameters

Name	Type	Required	Description	Default	Example
url	Query	Yes	URL where the captcha is located.	—	https://example.com
sitekey	Query	Yes	Key that can be found in the page's source code.	—	0x4AAAAAAA-...

Headers

Name	Type	Required	Description	Default	Example
authorization	Header	Yes	Your API key, available at @solvium_crypto_bot	—	Bearer IE0B81Vn...

Responses

Vercel

GET

Create Vercel Task

The server responds with a task identifier that can be used to check the solution status.

Turnstile

URL

https://captcha.solvium.io/api/v1/task/vercel

Parameters

Name	Type	Required	Description	Default	Example
challengeToken	Query	Yes	Token obtained from the protected site.	—	2.1743847465.60.MGY1Y2JjYWNlZD...

Headers

Name	Type	Required	Description	Default	Example
authorization	Header	Yes	Your API key, available at @solvium_crypto_bot	—	Bearer IE0B81Vn...

Responses

Examples

Step 2. Getting Status

Now that you've created a task, you have a unique task identifier — task_id. You can use it to check the solution readiness status and then get the solution itself.

GET

Get Task Status

This method gets the task status.

URL

https://captcha.solvium.io/api/v1/task/status/{task_id}

Parameters

Name	Type	Required	Description	Default	Example
task_id	URL	Yes	Unique task identifier to check its status.	—	01959e02-08fd-7000-...

Headers

Name	Type	Required	Description	Default	Example
authorization	Header	Yes	Your API key, available at @solvium_crypto_bot	—	Bearer IE0B81Vn...

Responses

Errors

When a task finishes but couldn't be solved, the status endpoint returns status: "failed" and the error field is set to one of the codes below.

JSON

{
  "id": "01959e02-08fd-7000-8cbe-f682a959b3c1",
  "status": "failed",
  "type": "turnstile",
  "error": "ERROR_RENDER",
  "result": null
}

Category	Code	How to fix
Input validation	`INVALID_PARAMS`	Re-check the endpoint's required fields; make sure none are empty or the wrong type.
Input validation	`MISSING_PARAM`	Send both `url` and `body` in the POST body.
Input validation	`INVALID_BASE64`	Re-encode the raw HTML bytes with standard base64 — e.g. Python `base64.b64encode(html).decode()`.
Input validation	`NO_PROXY`	Always pass a `proxy` parameter for reCAPTCHA v3.
Challenge rendering	`ERROR_RENDER`	Verify the `sitekey` matches what the target site actually uses and that the URL still serves a Turnstile widget.
Challenge rendering	`CHALLENGE_ERROR`	The sitekey is probably not authorised for that domain. Confirm the sitekey/URL pair is still valid.
Challenge rendering	`INVALID_CHALLENGE`	Fetch a fresh `x-vercel-challenge-token` right before submitting — they expire in seconds.
Challenge rendering	`WRONG_CHALLENGE_PAYLOAD`	Re-download the protected page from scratch and submit the new body.
Proxy & IP	`PROXY_BLOCKED`	Rotate to a cleaner (preferably residential) IP.
Proxy & IP	`PROXY_ERROR`	Check credentials and latency; make sure the proxy supports HTTPS and isn't dead.
Proxy & IP	`IP_BLOCKED_BY_CLOUDFLARE`	Switch to a fresh IP and refetch the protected page.
Proxy & IP	`BOT_DETECTED_BY_CLOUDFLARE`	Use a static residential proxy and the exact `User-Agent` documented for `cf-clearance`.
Solve failure	`TOO_MANY_ATTEMPTS_SOLVING`	The proxy is flagged; rotate to a cleaner (residential) IP.
Solve failure	`RECAPTCHA_TIMEOUT`	Retry once. If persistent, switch proxies.
Solve failure	`HCAPTCHA_TIMEOUT`	Retry. Persistent timeouts usually mean the sitekey distrusts your IP — rotate.
Solve failure	`SOLVE_TIMEOUT`	Proxy is too slow or the challenge is abnormally heavy. Retry with a faster proxy.
Solve failure	`UPSTREAM_TIMEOUT`	Transient; retry once.
Solve failure	`UPSTREAM_ERROR`	Usually the target site changed its challenge flow. Fetch a new token and retry.
Token & output	`EMPTY_TOKEN`	Retry. If it repeats, double-check the sitekey / domain pair.
Token & output	`NO_TOKEN`	Retry — usually a mid-solve proxy drop.
Lifecycle	`CANCELLED`	Resubmit the task.
Lifecycle	`GENERAL_ERROR`	Open a ticket with the `task_id` so we can investigate.