# Aries Solver - full API reference

> A reCAPTCHA v3 solving API. One HTTP request returns a valid token together
> with the browser fingerprint that produced it. One credit per successfully
> solved token; failed solves are never charged.

This file is the complete specification. It is self-contained: everything
needed to write a working client is below.

- Base URL: `https://aries-solver.info`
- Every endpoint also exists under `/v1` (`/getRecaptchaV3` and
  `/v1/getRecaptchaV3` are the same endpoint).
- All requests and responses are JSON.
- Buy credits and obtain a key: https://t.me/Anxioussoul

---

## Authentication

Send your API key with every request. Keys are the literal prefix `ar_live_`
followed by 48 hexadecimal characters. Any one of these is accepted:

| Method | Example |
|---|---|
| Header (preferred) | `X-API-Key: ar_live_...` |
| Bearer token | `Authorization: Bearer ar_live_...` |
| Body field | `{"clientKey": "ar_live_..."}` |

Keys are issued by hand; there is no sign-up endpoint and no way to create a
key programmatically. A key spends real credits, so keep it server-side and
never ship it in browser or mobile code.

---

## POST /getRecaptchaV3

Solves a reCAPTCHA v3 and returns the token. The call blocks until the solve
finishes or the time budget is exhausted. There is nothing to poll and no task
id to track.

### Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | Full URL of the page containing the captcha, including scheme. Example: `https://example.com/login` |
| `sitekey` | string | yes | The reCAPTCHA v3 site key from the target page. Usually starts with `6L`. Charset `[A-Za-z0-9_-]`, 6-512 characters. |
| `proxy` | string | yes | Proxy the solve runs through. Must include scheme and port: `scheme://user:pass@host:port`. Scheme is one of `http`, `https`, `socks4`, `socks5`. Credentials are optional; the port is not. |
| `action` | string | no | The reCAPTCHA action the page expects, e.g. `login`, `submit`. Max 64 characters. Send it when known - scores frequently depend on it matching. |
| `enterprise` | boolean | no | `true` for reCAPTCHA Enterprise. Omit for standard v3. |
| `title` | string | no | Page title to present during the solve. Max 256 characters. Derived from the domain when omitted. |

Example:

```json
{
  "url": "https://example.com/login",
  "sitekey": "6LfCVLAUAAAAALFwwRnnCJ12",
  "proxy": "http://user:pass@198.51.100.10:8080",
  "action": "login",
  "enterprise": false
}
```

Valid proxy strings:

```
http://user:pass@198.51.100.10:8080
https://user:pass@198.51.100.10:8443
socks5://user:pass@198.51.100.10:1080
http://198.51.100.10:8080
```

Rejected: a bare `host:port`, or any scheme without a port.

### Success response - HTTP 200

```json
{
  "status": "success",
  "data": {
    "token": "03AFcWeA5_zX2...",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36",
    "sec_ch_ua": "\"Chromium\";v=\"145\", \"Google Chrome\";v=\"145\"",
    "sec_ch_ua_platform": "\"Windows\"",
    "sec_ch_ua_mobile": "?0",
    "accept_lang": "en-US,en;q=0.9"
  },
  "credits": 998
}
```

| Field | Type | Description |
|---|---|---|
| `status` | string | `success` on a solve, `error` otherwise |
| `data.token` | string | The reCAPTCHA v3 token to submit to the target site |
| `data.user_agent` | string | User agent of the solving browser |
| `data.sec_ch_ua` | string | Client-hint brand list of the solving browser |
| `data.sec_ch_ua_platform` | string | Client-hint platform, e.g. `"Windows"` |
| `data.sec_ch_ua_mobile` | string | Client-hint mobile flag, `?0` or `?1` |
| `data.accept_lang` | string | Accept-Language of the solving browser |
| `credits` | integer | Credits remaining after this solve was charged |

The `data` object contains exactly these six fields and no others.

### Using the token

The token is bound to the browser that produced it. On the request where you
submit the token, set:

- `User-Agent` from `data.user_agent`
- `Sec-CH-UA` from `data.sec_ch_ua`
- `Sec-CH-UA-Platform` from `data.sec_ch_ua_platform`
- `Sec-CH-UA-Mobile` from `data.sec_ch_ua_mobile`
- `Accept-Language` from `data.accept_lang`

and route it through the same proxy you passed to the solve. Tokens expire in
roughly two minutes, so request one at the moment you need it rather than
building a pool. An expired token is rejected by the target site, not by this
API.

---

## GET /balance

Returns the credits remaining on the key. `POST` behaves identically. Free.

```json
{ "status": "success", "credits": 998 }
```

Prefer reading the `credits` field returned by each solve over polling this
endpoint.

---

## GET /health

No authentication. `status` is `maintenance` while the service is paused, in
which case solves answer 503.

```json
{ "status": "success", "service": "Aries Solver" }
```

---

## Errors

Every failure returns `{"status": "error", "message": "..."}`. The message is
drawn from this fixed set - treat it as a closed enumeration.

| HTTP | message | Cause | What to do |
|---|---|---|---|
| 400 | `Missing required fields` | `url` or `sitekey` empty | Provide all required fields |
| 400 | `Invalid URL format` | Malformed URL, or a scheme other than http/https | Use a full URL with scheme |
| 400 | `Invalid sitekey format` | Site key is not a plausible key | Copy the key from the target page |
| 400 | `Missing required field: proxy` | No proxy provided | Provide a valid proxy |
| 400 | `Invalid proxy format` | Malformed proxy URL, or missing scheme/port | Use `scheme://user:pass@host:port` |
| 400 | `Bad proxy` | The proxy did not work | Use a different proxy |
| 401 | `Invalid API key` | Missing, unknown, disabled or revoked key | Check the API key |
| 402 | `Insufficient credits` | Balance is zero | Add credits |
| 429 | `Service Overloaded` | Per-minute rate limit or concurrent-solve cap reached | Honour `Retry-After` and back off |
| 500 | `Error fetching token` | The solve failed | Retry with exponential backoff |
| 503 | `Service temporarily at capacity` | All solvers busy, or maintenance mode | Retry shortly |

Retry policy:

- Retry `429`, `500`, `503` with exponential backoff.
- Never retry `400` or `401` unchanged; the same request will fail again.
- `402` means top up before retrying.

---

## Rate limits

Every account has a requests-per-minute ceiling and a cap on concurrent
solves. Both are per-account and can be raised on request.

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Requests allowed per minute |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `X-RateLimit-Reset` | Seconds until the window resets |
| `Retry-After` | Sent with 429. Wait this many seconds. |

Exceeding either limit returns 429 `Service Overloaded`.

---

## Billing

- One credit per successfully solved token.
- A failed solve costs nothing, ever.
- Credits are whole numbers and never expire.
- $2 per 1000 solves ($0.002 each). Larger volumes priced on request.
- At zero credits, solves answer 402 `Insufficient credits`.

---

## Examples

### cURL

```bash
curl -X POST https://aries-solver.info/getRecaptchaV3 \
  -H "X-API-Key: ar_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com/login",
        "sitekey": "6LfCVLAUAAAAALFwwRnnCJ12",
        "proxy": "http://user:pass@host:8080",
        "action": "login"
      }'
```

### Python

```python
import requests

API = "https://aries-solver.info/getRecaptchaV3"
KEY = "ar_live_YOUR_KEY"

def solve(url, sitekey, proxy, action=None):
    payload = {"url": url, "sitekey": sitekey, "proxy": proxy}
    if action:
        payload["action"] = action

    r = requests.post(API, headers={"X-API-Key": KEY}, json=payload, timeout=180)
    data = r.json()
    if data["status"] != "success":
        raise RuntimeError(f"{r.status_code}: {data['message']}")
    return data["data"], data["credits"]

solution, credits = solve(
    "https://example.com/login",
    "6LfCVLAUAAAAALFwwRnnCJ12",
    "http://user:pass@host:8080",
    action="login",
)

# Reuse the solving browser's fingerprint wherever the token is submitted.
headers = {
    "User-Agent": solution["user_agent"],
    "Sec-CH-UA": solution["sec_ch_ua"],
    "Sec-CH-UA-Platform": solution["sec_ch_ua_platform"],
    "Sec-CH-UA-Mobile": solution["sec_ch_ua_mobile"],
    "Accept-Language": solution["accept_lang"],
}
token = solution["token"]
```

### Node.js

```javascript
const API = "https://aries-solver.info/getRecaptchaV3";
const KEY = "ar_live_YOUR_KEY";

async function solve({ url, sitekey, proxy, action }) {
  const res = await fetch(API, {
    method: "POST",
    headers: { "X-API-Key": KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ url, sitekey, proxy, action }),
    signal: AbortSignal.timeout(180_000),
  });

  const data = await res.json();
  if (data.status !== "success") {
    throw new Error(`${res.status}: ${data.message}`);
  }
  return { solution: data.data, credits: data.credits };
}

const { solution } = await solve({
  url: "https://example.com/login",
  sitekey: "6LfCVLAUAAAAALFwwRnnCJ12",
  proxy: "http://user:pass@host:8080",
  action: "login",
});

const headers = {
  "User-Agent": solution.user_agent,
  "Sec-CH-UA": solution.sec_ch_ua,
  "Sec-CH-UA-Platform": solution.sec_ch_ua_platform,
  "Sec-CH-UA-Mobile": solution.sec_ch_ua_mobile,
  "Accept-Language": solution.accept_lang,
};
```

### Retry wrapper (recommended shape)

```python
import time, requests

RETRYABLE = {429, 500, 503}

def solve_with_retry(payload, attempts=4):
    delay = 2
    for i in range(attempts):
        r = requests.post(API, headers={"X-API-Key": KEY}, json=payload, timeout=180)
        data = r.json()
        if data["status"] == "success":
            return data["data"]
        if r.status_code not in RETRYABLE:
            raise RuntimeError(f"{r.status_code}: {data['message']}")   # 400/401/402
        if i < attempts - 1:
            time.sleep(int(r.headers.get("Retry-After", delay)))
            delay *= 2
    raise RuntimeError("solve failed after retries")
```

---

## Best practices

- Solve just in time; tokens last about two minutes.
- Always send the returned fingerprint headers with the token.
- Use the same proxy for the solve and the submission.
- Pass `action` when the target page uses one.
- Back off on 429 and 5xx rather than retrying in a tight loop.
- Track your balance from the `credits` field of each solve response.
- Set a client timeout of at least 180 seconds.
- Keep the API key server-side.