Where do I find the publishable key (pk)?

Inspect the page source or Network tab. The pk appears in the Castle SDK script URL as a query parameter (e.g. cdn.castle.io/v2/castle.js?pk_XXXX) or in a Castle.configure() call in the page's own JavaScript. It always starts with pk_.

What is the config_json field?

It is the object passed to Castle.configure() on the target site. The pk field is the minimum requirement. Some sites add wUrl / swUrl (custom CDN paths for Castle's worker scripts) or avoidCookies: true. Copy these values from the site's source — they vary per site and are required for the solver to replicate the exact Castle context.

The site doesn't expose window.Castle — does the solver still work?

Yes. Modern sites bundle Castle as an ES module and call Castle.configure(...).createRequestToken() in module scope, so there is no window.Castle global. The solver detects this and loads the Castle browser SDK itself, configuring it with your config_json (pk plus any wUrl/swUrl), and also captures the x-castle-request-token the page mints on its own requests as a fallback. If a specific bundled site needs a particular SDK build, pass config_json.sdkUrl with its URL.

Do I really need to send the __cuid cookie?

Yes, unless the site set avoidCookies: true in its Castle config. Castle's server-side validation checks that the __cuid cookie in the request matches the one embedded in the token. Sending the token without the matching cookie causes InvalidRequestTokenError on Castle's API, which the site treats as a suspected bot.

How do I use the token on my follow-up request?

Set three things on the same HTTP request that submits the form or calls the API: (1) the header x-castle-request-token: , (2) Cookie: __cuid= , (3) User-Agent: . Using a matching TLS stack (curl_cffi or a real browser) helps keep the full fingerprint coherent.

Can I reuse the token?

No. Castle tokens are single-use and expire after 120 seconds. Call us fresh for each protected request.

Why does the ProxyLess variant use a residential pool?

Castle's risk score (0-100) includes IP-reputation signals baked in at token-generation time. Datacenter IP ranges score higher risk, which raises the chance the site's policy returns challenge or deny. Our residential pool keeps scores in the allow range for the vast majority of solves.

Before you submit — these must be correct

If any of these are wrong, your token may be accepted by our solver but rejected or scored poorly by the target site.

Send all three values together: token as x-castle-request-token, __cuid as a cookie, and match the returned User-Agent. Sending the token without the cuid cookie triggers InvalidRequestTokenError server-side.
Tokens expire in 120 seconds and are single-use. Generate a fresh one for each protected request — do not cache or reuse.

Castle Bot Defense

CastleTaskProxyLess

Castle Bot Defense Solver, solved in 5.0s.

Generate Castle Bot Defense request tokens automatically. Pass your publishable key and website URL — get back the x-castle-request-token and matching __cuid cookie.

Get API Key Try Demo Examples

Avg Speed~5.0s

Success99%+

Cost / 1k$2.00

Throughput12/m

Castle (castle.io) is an account-security and fraud-prevention SDK used by gaming platforms, fintech, and e-commerce sites. It is not a traditional captcha — there is no visible puzzle. Instead, Castle's JavaScript SDK silently collects behavioral fingerprints and device signals, then exposes a createRequestToken() method that produces a short-lived risk-scored token. The token is sent from the client to the site's backend as the HTTP header x-castle-request-token or the hidden form field castle_request_token. The backend validates it against Castle's API, which returns a risk action: allow, challenge, or deny. Castle is commonly used at login, signup, checkout, and password-reset flows on gaming, fintech, and e-commerce sites. Tokens expire after 120 seconds and are single-use. They are bound to the __cuid session cookie — a persistent 16-byte random device identifier Castle stores in the browser. You must send both the token and the __cuid cookie together, or Castle's server-side validation will flag the session as spoofed.

Quick Integration

solve.py

import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Step 1: Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "CastleTaskProxyLess",
        "websiteURL": "https://your-target-site.com/signup",
        "config_json": "{\"pk\":\"pk_XXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"wUrl\":\"https://cdn.your-target-site.com/castle/cw.js\",\"swUrl\":\"https://cdn.your-target-site.com/castle/csw.js\",\"avoidCookies\":true}",
        "ip": "203.0.113.10"
    }
}).json()

task_id = task["taskId"]
print(f"Task created: {task_id}")

# Step 2: Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        print("Solved!", result["solution"])
        break
    elif result["status"] == "failed":
        print("Failed:", result.get("errorDescription"))
        break

    time.sleep(1)

Using the result

use_result.py

# Step 3: Use the result — paste the token into the site's captcha form field
token = result["solution"]["token"]
# Browser side: set the textarea value or the hidden input. Then submit.
# Server-to-server: post the token alongside the form fields you normally send.
resp = requests.post("https://target.example.com/submit", data={
    "username": "...",
    "captcha_response": token,   # <-- replace with the field name your site uses
})
print(resp.status_code)

1. Send Payload

Dispatch your CastleTaskProxyLess to our processing cluster via the secure API endpoint.

2. Solving Engine

Our solver navigates the real target URL so Castle's SDK initialises in its native context, with the site's own worker scripts, service workers, and behavioral collection active. Modern sites bundle Castle as an ES module (Castle.configure(...).createRequestToken()) so there is no window.Castle global — we handle both integrations: we mint from the page's own SDK when a global is present, otherwise we load the Castle browser SDK ourselves and configure it with your config_json (worker URLs included), and as a final fallback capture the x-castle-request-token the page mints itself. We return the token, the matching __cuid cookie value, and the User-Agent string. You attach the token as x-castle-request-token, set Cookie: __cuid=<cuid>, and match the User-Agent we return. Designed for authorized security testing, QA automation, and bot-detection research.

3. Get Result

Poll getTaskResult for the validated token, then finalize your automated request.

Using your own proxy

Use CastleTask instead of CastleTaskProxyLess to route the solve through your own proxy — useful when the target site checks that the solving IP matches the submitting IP.

solve_proxy.py

import requests, time

API = "https://api.capzy.ai"
KEY = "capzy_your_key_here"

# Step 1: Create task
task = requests.post(f"{API}/createTask", json={
    "clientKey": KEY,
    "task": {
        "type": "CastleTask",
        "websiteURL": "https://your-target-site.com/signup",
        "config_json": "{\"pk\":\"pk_XXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\"wUrl\":\"https://cdn.your-target-site.com/castle/cw.js\",\"swUrl\":\"https://cdn.your-target-site.com/castle/csw.js\",\"avoidCookies\":true}",
        "proxyType": "http",
        "proxyAddress": "123.45.67.89",
        "proxyPort": "8080",
        "proxyLogin": "user",
        "proxyPassword": "pass"
    }
}).json()

task_id = task["taskId"]
print(f"Task created: {task_id}")

# Step 2: Poll for result
while True:
    result = requests.post(f"{API}/getTaskResult", json={
        "clientKey": KEY,
        "taskId": task_id
    }).json()

    if result["status"] == "ready":
        print("Solved!", result["solution"])
        break
    elif result["status"] == "failed":
        print("Failed:", result.get("errorDescription"))
        break

    time.sleep(1)

Additional proxy parameters

fieldtyperequireddescription

proxyTypetypestringreqrequiredProxy protocol: http, https, socks4, or socks5

proxyAddresstypestringreqrequiredProxy IP address or hostname

proxyPorttypenumberreqrequiredProxy port number

proxyLogintypestringreqoptionalProxy username (if auth required)

proxyPasswordtypestringreqoptionalProxy password (if auth required)

userAgenttypestringreqoptionalUser-Agent string to use. Must match the UA you use when submitting the token

Task Parameters

API Spec

fieldtyperequireddescription

typetypestringreqrequiredCastleTaskProxyLess or CastleTask

websiteURLtypestringreqrequiredThe exact page URL where Castle is active (e.g. the login or signup page). Castle's SDK must load on this page.

config_jsontypeobjectreqrequiredThe Castle.configure() object for this site. The pk field (publishable key, starts with pk_) is required. Other site-specific fields such as wUrl, swUrl, and avoidCookies are passed through as-is.

config_json.sdkUrltypestringreqoptionalOptional. Direct URL to the Castle browser SDK to inject on sites that bundle Castle as a module (no window.Castle global). Tried before our built-in candidates. Only needed if a bundled site's token minting fails; most sites work without it.

backendtypestringreqoptionalOptional. Leave unset for the default fast engine (~1s). Pass "browser" to force a full real-browser solve instead — slower, only needed in rare cases where the fast path can't mint a token.

iptypestringreqoptionalRecommended. The IP address you will submit the token from. Castle scores the token's timezone against the geo of the request IP — we look up the timezone for your IP and mint the token to match, so no proxy is needed. Pass this for the fastest, most reliable solve. If you send a proxy instead, we use the proxy's exit geo automatically.

Response Shape

fieldtypedescription

tokentypestringThe Castle request token. Set this as the x-castle-request-token header (or castle_request_token form field) on your follow-up request. 120-second TTL, single-use.

cuidtypestringValue of the __cuid cookie bound to the token. You must send Cookie: __cuid=<cuid> on the same request as the token, or Castle will flag it as spoofed. Empty when the site uses avoidCookies: true.

userAgenttypestringThe User-Agent of the browser that generated the token. Set this on your follow-up request to keep the fingerprint coherent.

Example response

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdWlkIjoiYWJjMTIzZGVmNDU2Nzg5MCIsImlhdCI6MTcyMDAwMDAwMCwiZXhwIjoxNzIwMDAwMTIwfQ.SigPlaceholder",
    "cuid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
  }
}

Error response

{
  "errorId": 1,
  "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
  "errorDescription": "Solver gave up."
}

Features

Navigates the real target page so Castle's SDK initialises exactly as for a real user

Works on modern bundled integrations (no window.Castle global), not just legacy global-SDK sites

Passes your full config_json including custom wUrl/swUrl worker scripts

Returns token, __cuid cookie, and matching User-Agent as a ready-to-use triple

Average solve time ~1 second

Works on all Castle-protected flows: login, signup, checkout, password reset

Pricing & Stats

Per 1,000 solves$2.00

Avg solve time~5.0s

Success rate99%+