Skip to content

Adapter SDK

The public adapter contract. BaseAdapter is the abstract base every adapter implements; AntiCaptchaCompatAdapterBase is the shared implementation base for the Anti-Captcha-compatible createTask/getTaskResult JSON protocol family; Endpoints declares the request paths an adapter uses.

The public adapter SDK contract (ADR-0041, ADR-0053).

BaseAdapter is the abstract base class every shipped and third-party adapter implements; Endpoints declares the request paths an adapter uses (ADR-0073). This module is part of the public surface and never imports unicaptcha._internal.

Endpoints dataclass

Operation-keyed request paths (ADR-0073).

All fields are required: an adapter either inherits the JSON-family default on BaseAdapter.endpoints or declares a complete set — no per-field merging.

BaseAdapter

Bases: ABC

The adapter SDK contract.

Adapters are pure translators: they build request payloads, parse provider responses, and map provider errors into the library hierarchy. Required declarations (provider, challenges, default_base_url) are enforced at subclass creation.

The concrete constructor wraps a plain str api_key into SecretStr (ADR-0063), defaults base_url to default_base_url, and stores the trinary referral flag (ADR-0072) — the base embeds nothing; shipped adapters serialize their provider's affiliate field.

build_payload abstractmethod 

build_payload(challenge)

Build the provider request body for a challenge.

parse_submit_response abstractmethod 

parse_submit_response(raw)

Parse a createTask response (ADR-0075).

parse_task_status abstractmethod 

parse_task_status(raw)

Parse a getTaskResult response into a four-state ParsedTask (ADR-0058).

parse_balance abstractmethod 

parse_balance(raw)

Parse a balance response into an exact Decimal (the amount is in the adapter's declared currency, ADR-0040).

build_task_status 

build_task_status(task_id)

Build a getTaskResult request body (JSON-family default, ADR-0001). Overridable by adapters for divergent protocols.

build_balance 

build_balance()

Build a getBalance request body (JSON-family default, ADR-0001). Overridable by adapters for divergent protocols.

map_provider_error abstractmethod 

map_provider_error(raw)

Map a provider error body to (ErrorKind, message).

report_bad_supported 

report_bad_supported(challenge_type)

Whether the provider accepts bad reports for this kind.

report_good_supported 

report_good_supported(challenge_type)

Whether the provider accepts good reports for this kind (ADR-0068).

AntiCaptchaCompatAdapterBase

Bases: BaseAdapter

Shared implementation base for the Anti-Captcha-compatible createTask/getTaskResult JSON protocol family (2Captcha's modern JSON API, Anti-Captcha, CapMonster Cloud, Capsolver).

Provides the response-parsing pipeline (decode -> error mapping -> submit/status/balance parsing) and the shared field/payload helpers; subclasses declare json_provider, error_kinds, and unknown_task_codes and supply the per-provider task builders (_build_task) and solution dispatch (_solution_from).

Public so third-party adapters speaking the Anti-Captcha-compatible protocol can reuse it without touching unicaptcha._internal (ADR-0041 boundary).