Using a proxy provider with Solvecha

A scraper or an agent often needs two things: a proxy for the session and a captcha solver for the challenge. They do different jobs, and you set them up apart.

• The proxy belongs to your browser or HTTP client. The target site sees the proxy address.
• Solvecha gets the challenge images and sends back the answer. It solves images: reCAPTCHA v2 image grids, text captchas, GeeTest sliders and FunCAPTCHA images. It does not return tokens.

This page is a template. Replace the generic proxy values with those of your provider: the server address, the user name and the password.

#What you need

• A proxy from any provider, as a server address (for example http://host:port), a user name and a password.
• A Solvecha API key from the dashboard. The free tier is enough to test.
• For reCAPTCHA image grids: the unzipped browser extension.

#Browser with the extension

Set the proxy when you start the browser. Load the extension in the same start. The extension works inside the page and talks to https://api.solvecha.com on its own.

Extensions need a headed browser or a virtual display such as xvfb-run.

import { chromium } from "playwright";

const ext = "/path/to/solvecha-extension"; // the unzipped folder

const context = await chromium.launchPersistentContext("./profile", {
  headless: false,
  args: [`--disable-extensions-except=${ext}`, `--load-extension=${ext}`],
  proxy: {
    server: process.env.PROXY_SERVER, // for example http://host:port
    username: process.env.PROXY_USERNAME,
    password: process.env.PROXY_PASSWORD,
  },
});

// Save the Solvecha key once. It stays in the profile folder.
let [worker] = context.serviceWorkers();
worker ??= await context.waitForEvent("serviceworker");
await worker.evaluate((key) => chrome.storage.local.set({ apiKey: key }), process.env.SOLVECHA_API_KEY);

const page = await context.newPage();
await page.goto("https://www.google.com/recaptcha/api2/demo");
// The extension solves the challenge. Wait for the result you need.

import os
from playwright.sync_api import sync_playwright

EXT = "/path/to/solvecha-extension"  # the unzipped folder

with sync_playwright() as p:
    context = p.chromium.launch_persistent_context(
        "./profile",
        headless=False,
        args=[f"--disable-extensions-except={EXT}", f"--load-extension={EXT}"],
        proxy={
            "server": os.environ["PROXY_SERVER"],  # for example http://host:port
            "username": os.environ["PROXY_USERNAME"],
            "password": os.environ["PROXY_PASSWORD"],
        },
    )

    # Save the Solvecha key once. It stays in the profile folder.
    workers = context.service_workers
    worker = workers[0] if workers else context.wait_for_event("serviceworker")
    worker.evaluate("key => chrome.storage.local.set({ apiKey: key })", os.environ["SOLVECHA_API_KEY"])

    page = context.new_page()
    page.goto("https://www.google.com/recaptcha/api2/demo")
    # The extension solves the challenge. Wait for the result you need.
    context.close()

Set the values in the shell first:

export PROXY_SERVER="http://host:port"
export PROXY_USERNAME="your-proxy-user"
export PROXY_PASSWORD="your-proxy-password"
export SOLVECHA_API_KEY="YOUR_API_KEY"

Other tools take the same values:

• Puppeteer: start Chromium with --proxy-server=host:port and call page.authenticate({ username, password }) before the first goto. Load the extension as shown on the browser extension page.
• Selenium: add --proxy-server=host:port to the Chrome options. Chrome does not accept a user name and password in this flag. Use a proxy that allows your IP address, or a helper such as selenium-wire.

#HTTP client with the API

For text captchas you do not need a browser extension. Fetch the page through the proxy. Send the captcha picture to Solvecha without the proxy. This is the same call as in the text captcha reference.

import base64
import os
import time

import requests

API = "https://api.solvecha.com"
HEADERS = {"Authorization": f"Bearer {os.environ['SOLVECHA_API_KEY']}"}
PROXY = os.environ["PROXY_SERVER"].replace("://", f"://{os.environ['PROXY_USERNAME']}:{os.environ['PROXY_PASSWORD']}@")
PROXIES = {"http": PROXY, "https": PROXY}

# 1. The session goes through the proxy.
session = requests.Session()
session.proxies.update(PROXIES)
picture = session.get("https://example.com/captcha.png").content

# 2. The picture goes to Solvecha directly. No proxy.
image = base64.b64encode(picture).decode()
job = requests.post(f"{API}/v1/recognition/textcaptcha", headers=HEADERS, json={"image_data": [image]}).json()

for _ in range(30):
    time.sleep(1)
    r = requests.get(f"{API}/v1/recognition/textcaptcha", headers=HEADERS, params={"id": job["data"]})
    if r.status_code == 409:  # error 14: not ready yet
        continue
    r.raise_for_status()
    answer = r.json()["data"][0]
    break
else:
    raise TimeoutError("no answer after 30 seconds")

# 3. Send the answer in the same proxied session.
session.post("https://example.com/form", data={"captcha": answer})

Replace the example URLs with those of your target.

#Tips

• Keep one proxy address per session. A site that sees the address change in the middle of a challenge can reject the answer.
• Match time zone and language to the proxy location. See Best practices.
• Check the proxy first. Open an IP check page through it before you open the target site.
• Read your provider's terms. Use proxies and captcha solving only where automation is allowed. See the Acceptable Use Policy.

#Are you a proxy provider?

You can join the partner program and get a co-written guide like this one for your customers. See Proxy partners.