# Using a proxy provider with Solvecha

> Set a proxy in Playwright, Puppeteer or Selenium and let Solvecha solve the captcha images through the extension or the API. No proxy goes to 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.


> **Note:**
> You do not pass a proxy to Solvecha. The extension and your API calls reach `https://api.solvecha.com` directly, not through your session proxy. The challenge pictures are enough to solve the captcha.


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](https://solvecha.com/dashboard). The [free tier](https://solvecha.com/docs/plans-and-billing.md) is enough to test.
- For reCAPTCHA image grids: the unzipped [browser extension](https://solvecha.com/docs/browser-extension.md).

## 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`.


**Playwright (Node.js)**

```js
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.
```

**Playwright (Python)**

```python
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:

```bash
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](https://solvecha.com/docs/browser-extension.md#playwright-puppeteer-and-selenium) 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](https://solvecha.com/docs/api/create-text-captcha-job.md).

```python
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](https://solvecha.com/docs/best-practices.md).
- **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](https://solvecha.com/legal/acceptable-use).


> **Note:**
> We did not test these scripts with a specific proxy provider. They show where each setting goes. If a step fails, check the proxy alone, without Solvecha.


## 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](https://solvecha.com/partners/proxies).