Skip to main content

CAPTCHA guide

ARCaptcha

Hosted checkbox widget that can stay invisible or open a slider puzzle.

Difficulty: Medium
Risk engine
Exploded concept drawing of how the ARCaptcha challenge is built

ARCaptcha is a hosted CAPTCHA and bot-protection service for websites and mobile apps. Its widget can run either an interactive challenge or an invisible flow, and the provider decides whether a given visitor needs to see anything. What the visitor actually sees depends on how the site configured it.

The default widget is a white box with a border, placed in the form. It holds a rounded checkbox outlined in purple, the bold label "I'm not robot", and on the right the purple cloud-and-fingerprint logo above the word ARCaptcha. Ticking the box either succeeds quietly or opens a challenge pop-up. There is a dark theme, and labels come in Persian (fa) and English (en).

Challenge modesLink to Challenge modes

  • Interactive widget: the visitor goes through whatever verification the site configured.
  • Invisible mode: detection kicks in at a protected action. It can finish without interrupting the visitor, or escalate to an interactive challenge.

Those two modes come from the official docs. The docs don't say every integration uses a specific puzzle, so the look of a challenge alone isn't enough to identify ARCaptcha.

How to identifyLink to How to identify

  • ARCaptcha branding: an "I'm not robot" checkbox beside the purple cloud and fingerprint logo.
  • Documented integrations use a container with the arcaptcha class and a public data-site-key attribute.
  • A successful submission may carry a form field called arcaptcha-token.
  • In invisible mode, nothing may be shown until the visitor starts the protected action.

Treat these as hints rather than proof. Only inspect pages you own or have permission to assess. A public site key is neither a secret nor a licence to use someone else's service.

How the integration worksLink to How the integration works

  1. The site loads the ARCaptcha client widget and configures it with its public site key.
  2. The visitor goes through the normal widget flow. An invisible setup may finish silently or ask for an interactive step.
  3. On success, the client receives a challenge token, usually submitted as arcaptcha-token.
  4. The site's backend sends that token to ARCaptcha's official Verify API, together with the expected site key and the account's secret key.
  5. The protected action is allowed only if this server-side check passes. The secret key never leaves the server, and a client-side callback on its own proves nothing.

Completing a challenge as a visitorLink to Completing a challenge as a visitor

  • Follow the widget's instructions using its own controls. Don't try to automate or get around a site's verification.
  • If it fails to load, allow the page's JavaScript and network requests, make sure the browser is up to date, and try once more.
  • If the widget can't be used, keeps failing or blocks something legitimate, contact the site through its accessibility or support channel. Only the site owner can offer another way to verify.

Free bypass methodsLink to Free bypass methods

On the public demo, the checkbox leads to a slider puzzle. A workable setup pairs Patchright (or DrissionPage) for the browser with PuzzleCaptchaSolver for gap detection. Patchright drives the page, captures the exact images the widget showed and performs the drag. PuzzleCaptchaSolver takes those two images and returns where the gap is.

Tool Role Link
Patchright Stealth Playwright fork: controls the browser, captures images and drags naturally Kaliiiiiiiiii-Vinyzu/patchright-python
PuzzleCaptchaSolver Finds the gap with OpenCV from the background and piece images vsmutok/PuzzleCaptchaSolver
DrissionPage Another Chromium controller that can stand in for Patchright g1879/DrissionPage
OpenCV The image-processing library the solver relies on opencv/opencv-python
ddddocr A fallback for simple slider and click tasks sml2h3/ddddocr

How the flow worksLink to How the flow works

  1. Fill in the form first. Put demo / demo into #email and #password before touching the widget.
  2. Tick the box like a person would. The visible target is #input-checkbox, and a bare locator click often doesn't wake the widget. Move the mouse over, press, hold for a short random moment, then release.
  3. Read the puzzle layout. When .arc-puzzle shows up, locate the background (img.tw-object-contain), the piece (img.puzzle) and the slider handle (.draggable). Work out the display scale from the rendered width and naturalWidth.
  4. Keep the exact images. Download both src URLs through the browser session and save them to temporary files, so the solver sees the same pixels as the page.
  5. Locate the gap. PuzzleCaptchaSolver(...).discern() trims empty borders, runs Canny edge detection on both images and uses template matching to return the gap's x position in natural image pixels.
  6. Drag the slider. The distance is gap_x * scale - piece_left. Move with cubic easing and short pauses, then wait for #checked-in-the-box and read #arcaptcha-token.
  7. Submit the form and check what /api/login returns.

Example: Patchright + PuzzleCaptchaSolverLink to Example: Patchright + PuzzleCaptchaSolver

import tempfile
from pathlib import Path

from patchright.sync_api import sync_playwright
from main import PuzzleCaptchaSolver  # module name from your PuzzleCaptchaSolver checkout

URL = "https://demo.arcaptcha.co/"

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto(URL, wait_until="domcontentloaded")

    page.fill("#email", "demo")
    page.fill("#password", "demo")

    # Press and hold the checkbox briefly, like a person
    box = page.locator("#input-checkbox").bounding_box()
    page.mouse.move(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2, steps=10)
    page.mouse.down()
    page.wait_for_timeout(120)
    page.mouse.up()

    page.locator(".arc-puzzle").wait_for(state="visible", timeout=20_000)

    bg = page.locator(".arc-puzzle img.tw-object-contain")
    piece = page.locator(".arc-puzzle img.puzzle")
    slider = page.locator(".arc-puzzle .draggable")

    bg_box = bg.bounding_box()
    piece_box = piece.bounding_box()
    slider_box = slider.bounding_box()
    scale = bg_box["width"] / bg.evaluate("el => el.naturalWidth")

    # Download the images exactly as the page showed them
    tmp = Path(tempfile.mkdtemp())
    bg_path, piece_path = tmp / "bg.png", tmp / "piece.png"
    bg_path.write_bytes(page.request.get(bg.get_attribute("src")).body())
    piece_path.write_bytes(page.request.get(piece.get_attribute("src")).body())

    gap_x = PuzzleCaptchaSolver(
        gap_image_path=str(piece_path),
        bg_image_path=str(bg_path),
        output_image_path=str(tmp / "result.png"),
    ).discern()

    distance = gap_x * scale - (piece_box["x"] - bg_box["x"])

    # Drag the handle with cubic easing
    start_x = slider_box["x"] + slider_box["width"] / 2
    start_y = slider_box["y"] + slider_box["height"] / 2
    page.mouse.move(start_x, start_y, steps=8)
    page.mouse.down()
    steps = max(20, int(abs(distance) / 6))
    for i in range(1, steps + 1):
        progress = 1 - (1 - i / steps) ** 3
        page.mouse.move(start_x + distance * progress, start_y)
        page.wait_for_timeout(12)
    page.mouse.up()

    page.wait_for_selector("#checked-in-the-box", timeout=10_000)
    print("token:", page.locator("#arcaptcha-token").input_value())
    browser.close()

DrissionPage can take over the browser side (open the page, click #arc-checkbox, read the image URLs), while gap detection and the drag stay unchanged. Patchright remains the better default because its patched fingerprints get through the widget's checks more consistently.

Practical tipsLink to Practical tips

  • Do the whole sequence (checkbox, puzzle, token, submit) in one browser session. Reloading the widget can void the token.
  • Work from the images the page actually displayed, fetched through the browser session, not from a fresh download in another context.
  • How you press and hold the checkbox matters more than the click itself.
  • When the checkbox passes without a puzzle, skip the slider and go straight to the form.
  • Try the demo with a visible browser first, since headless mode gets caught more often.

Official demoLink to Official demo

ARCaptcha publishes a demo at demo.arcaptcha.co: a sample login form (demo / demo) with the standard "I'm not robot" widget. It is the safest place to see how the widget looks, how the checkbox and the pop-up behave, and what the arcaptcha-token field contains, without going near a real site. The example above targets this page.

Testing an integration you ownLink to Testing an integration you own

  • Work on a staging site with its own credentials, and keep the secret key in server-side configuration.
  • Test accepted and rejected submissions through the official API, including missing, malformed, expired and already-used tokens.
  • Make sure the protected action is never granted on the strength of a browser callback, a hidden field or a success flag sent by the client.
  • When verification fails, check the configured domain, the site key, how the script loads, your Content Security Policy and server-to-server connectivity.
  • See the current ARCaptcha installation guide and the Verify API reference for the exact request format and error codes.

ReferencesLink to References

This guide covers ordinary use, authorised integration testing and documented research methods. Apply it only to systems you own or are allowed to test, and respect the law, people's privacy and the terms of the services involved.

Skip the solver: let BrowserSolver handle ARCaptcha

Website AntiBot runs a real browser session with matching TLS, headers, cookies and IP, clears the challenge, and returns the page. You send a URL, you get HTML back.

For education and authorized testing only. Respect the law, privacy, and the terms of the sites you work with. Difficulty labels are editorial estimates. Adapted from the CC0 community field guide on GitHub.