easycaptchas

easycaptchas is a high-performance, resilient Python wrapper for multiple captcha solving services. It provides a unified interface for Onyx, Void, and TeamAI, featuring automatic fallback mechanisms, consistent return payloads, and deep integration capabilities for enterprise-grade automation.

Features
Why easycaptchas?
Architecture Overview
Installation
Quick Start
Core API Reference
- CaptchaSolver Class
- The solve() Method
Provider Specifics
- Onyx Solver
- Void Solver
- TeamAI Solver
Advanced Configuration
- Custom Priority & Fallback
- API Key Discovery Logic
Input Contract
Return Contract
Integration Examples
- Selenium Integration
- Playwright Integration
- httpx/requests Integration
Error Handling & Resilience
- Normalized Error Payloads
- Retry Strategies
Proxies
Testing & Diagnostics
Performance Tuning
Developer Guide
- Adding New Solvers
- Contribution Guidelines
Frequently Asked Questions (FAQ)
Changelog
Roadmap
Security & Ethics
License

Features

Unified Interface: One method call to rule them all. No more provider-specific boilerplate.
Deterministic Fallback: Automatically tries the next configured provider if the first one fails.
Async-Ready Core: Built on top of httpx for modern, efficient I/O.
Intelligent Discovery: Automatically finds API keys in environment variables, .env files, or multiple config formats (JSON, YAML, TOML).
Rich CLI Output: Integrated with easygradients for beautiful, readable console logs and status updates.
Strict Validation: Validates inputs before making network requests to save time and credits.
Enterprise Ready: Designed for high-concurrency environments and complex captcha types (hCaptcha, reCaptcha, etc.).

Why easycaptchas?

Solving captchas in production environments is notoriously flaky. Providers go down, API keys run out of balance, or specific solvers struggle with certain site configurations.

easycaptchas solves this by:

Reducing Downtime: By chaining providers, your bot stays alive even if a primary service fails.
Simplifying Code: Your business logic only interacts with the CaptchaSolver abstraction.
Standardizing Responses: Whether it's Onyx or Void, the response format is identical, making your downstream processing logic trivial.

Architecture Overview

The package follows a "Manager-Worker" pattern:

Manager (CaptchaSolver): Orchestrates the solving flow, manages provider priority, and handles the fallback chain.
Workers (OnyxSolver, VoidSolver, etc.): Specialized modules that translate the unified request into provider-specific API calls.
Utilities (utils.py): Shared logic for key discovery, logging, and colorization.

graph TD
    A[User Code] --> B[CaptchaSolver]
    B --> C{Priority Queue}
    C -->|1st| D[OnyxSolver]
    C -->|2nd| E[VoidSolver]
    C -->|3rd| F[TeamAISolver]
    D -- Success --> G[Unified Response]
    D -- Failure --> E
    E -- Success --> G
    E -- Failure --> F
    F -- Success --> G
    F -- Failure --> H[Normalized Error]
    G --> A
    H --> A

Installation

From PyPI (Recommended)

pip install easycaptchas

From Source (Development)

git clone https://github.com/DraxonV1/easycaptchas.git
cd easycaptchas
pip install -e .

Requirements

Python 3.7+
httpx
toml
pyyaml
easygradients (optional, for colored output)

Quick Start

The fastest way to get started is to define your keys in a .env file:

ONYX_API_KEY=your_onyx_key
VOID_API_KEY=your_void_key

Then, run this minimal example:

from easycaptchas import CaptchaSolver

# Initialize (automatically finds keys in .env)
solver = CaptchaSolver()

# Solve a Discord captcha
result = solver.solve(
    sitekey="a9b5fb07-92ff-493f-86fe-352a2803b3df",
    siteurl="https://discord.com",
    captcha_details={"rqdata": "..."}
)

if result["success"]:
    print(f"Solved by {result['solver']}!")
    print(f"Token: {result['token']}")
else:
    print(f"Failure: {result['pretty_error']}")

Core API Reference

CaptchaSolver Class

CaptchaSolver(config=None)

The main entry point for the library.

Parameters:

config (dict, optional): A dictionary containing configuration options.
- default: The provider to try first (e.g., "void").
- onyx_key: Explicit API key for Onyx.
- void_key: Explicit API key for Void.
- teamai_key: Explicit API key for TeamAI.
- onyx_devid: Optional developer ID for Onyx.

The solve() Method

solver.solve(sitekey, siteurl, captcha_details, proxy=None)

Executes the solve logic across the provider chain.

Arguments:

sitekey (str): The target site's captcha key.
siteurl (str): The URL where the captcha is located.
captcha_details (dict): Provider-specific metadata. Usually contains rqdata.
proxy (str, optional): Proxy string in protocol://user:pass@host:port format.

Provider Specifics

Onyx Solver

Website: onyxsolver.com
Strengths: High reliability for hCaptcha Enterprise.
Key Format: clientKey (UUID-like).
Task Types: PopularCaptchaTask / PopularCaptchaTaskProxyless.

Void Solver

Website: voidsolver.tech
Strengths: Fast solving times and competitive pricing.
Key Format: Bearer token.
Endpoint: Supports both legacy and current API structures.

TeamAI Solver

Website: Discord-based access.
Strengths: Specialized in Discord-specific bypasses.
Key Format: Custom API Key.
Endpoint: solve_basic.

Advanced Configuration

Custom Priority & Fallback

You can override the default order (Onyx -> Void -> TeamAI) by specifying the default key:

solver = CaptchaSolver({
    "default": "void",
    "void_key": "...",
    "onyx_key": "..."
})

This will try Void first, then Onyx if Void fails.

API Key Discovery Logic

The library uses a tiered discovery system:

Explicit Config: Passed to CaptchaSolver({...}).
Environment Variables: ONYX_API_KEY, VOID_API_KEY, TEAMAI_API_KEY.
Local .env File: Parsed for the same variables.
Config Files: Searches for config.json, config.toml, config.yaml in the current directory.

Input Contract

Validation is performed before any network request:

Parameter	Type	Required	Description
`sitekey`	`str`	Yes	The captcha sitekey (e.g. from `data-sitekey`)
`siteurl`	`str`	Yes	The full URL of the page
`captcha_details`	`dict`	Yes	Metadata like `rqdata`, `rqd`, `rqtoken`
`proxy`	`str`	No	Proxy string if required by the solver

Return Contract

Success Payload

{
    "success": true,
    "token": "P1_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "rqtoken": "...",
    "user_agent": "Mozilla/5.0...",
    "solver": "Onyx",
    "message": "[Onyx] Solved successfully"
}

Failure Payload

{
    "success": false,
    "error": "All solvers failed",
    "provider": "CaptchaSolver",
    "detail": [
        {"provider": "Onyx", "error": "Insufficient balance"},
        {"provider": "Void", "error": "Connection Timeout"}
    ],
    "pretty_error": "[CaptchaSolver] All solvers failed"
}

Integration Examples

Selenium Integration

from selenium import webdriver
from easycaptchas import CaptchaSolver

driver = webdriver.Chrome()
solver = CaptchaSolver()

driver.get("https://example.com/captcha-page")

# Extract sitekey using Selenium
sitekey = driver.find_element("css selector", ".h-captcha").get_attribute("data-sitekey")

# Solve
result = solver.solve(sitekey, driver.current_url, {"rqdata": "..."})

if result["success"]:
    # Inject token into the hidden field
    driver.execute_script(f'document.getElementsByName("h-captcha-response")[0].value = "{result["token"]}";')
    driver.find_element("id", "submit-btn").click()

Playwright Integration

from playwright.sync_api import sync_playwright
from easycaptchas import CaptchaSolver

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://target-site.com")
    
    solver = CaptchaSolver()
    result = solver.solve(
        sitekey="sitekey_here",
        siteurl=page.url,
        captcha_details={"rqdata": "..."}
    )
    
    if result["success"]:
        page.evaluate(f'document.querySelector("[name=h-captcha-response]").value = "{result["token"]}"')
        page.click("#login")

Error Handling & Resilience

Normalized Error Payloads

easycaptchas catches multiple exception types:

httpx.TimeoutException: Handled as a provider failure.
httpx.ConnectError: Handled as a network issue.
JSONDecodeError: Handled as an invalid provider response.

Retry Strategies

While the library handles fallbacks, you might want to wrap the unified solve() in a retry loop:

import time

def robust_solve(solver, **kwargs):
    for attempt in range(3):
        res = solver.solve(**kwargs)
        if res["success"]:
            return res
        print(f"Attempt {attempt+1} failed, retrying...")
        time.sleep(2)
    return res

Proxies

When passing a proxy to solve(), ensure it follows this format: http://username:password@ip:port

Note: Some providers (like Onyx) automatically switch to "Proxy" task types if a proxy is detected in the payload.

Testing & Diagnostics

The package includes a built-in diagnostic tool to verify your environment:

import easycaptchas
easycaptchas.testsolvers()

This will check:

Which API keys are discovered.
If the keys are valid by checking balances.
If the provider endpoints are reachable.

Performance Tuning

Poll Interval: Modify poll_interval in individual solver instances if you need faster results (defaults to 3s).
Timeouts: Use the timeout parameter to cap how long you're willing to wait for a solution (defaults to 120s).

from easycaptchas.onyxsolver import OnyxSolver

# Specialized low-latency instance
fast_onyx = OnyxSolver(api_key="...", poll_interval=1, timeout=45)

Developer Guide

Adding New Solvers

Create easycaptchas/newsolver.py.
Implement the solve(sitekey, siteurl, captcha_details, proxy=None) method.
Ensure the return matches the Return Contract.
Register the solver in easycaptchas/__init__.py.

Contribution Guidelines

Fork the repo.
Create a feature branch (git checkout -b feature/amazing-solver).
Commit your changes.
Push to the branch.
Open a Pull Request.

Frequently Asked Questions (FAQ)

Q: Which provider is the cheapest? A: Prices vary weekly. We recommend checking the respective websites listed in the Provider Specifics section.

Q: Does this support reCAPTCHA v3? A: Yes, as long as the underlying provider supports it. Pass the necessary action and min_score in captcha_details.

Q: Why am I getting "No solvers configured"? A: This means the library couldn't find any API keys. Check your environment variables or ensure your .env file is in the root directory.

Q: Can I use this for scraping? A: This tool is intended for legal automation and testing. Please ensure you comply with the Terms of Service of the sites you are interacting with.

Q: How do I handle rqdata? A: rqdata is often found in the get_captcha or check_site requests made by hCaptcha. You can intercept these using a proxy like MitmProxy or by using browser developer tools.

Q: Is there an async version? A: While the internal calls use httpx, the public API is currently synchronous for ease of use. Async support is on the roadmap.

Q: How do I rotate API keys? A: You can re-instantiate the CaptchaSolver with new keys or implement a custom key rotation logic that passes different keys to the constructor.

Q: What happens if a provider is down? A: easycaptchas will catch the connection error and immediately move to the next provider in the chain.

Q: Can I use this on AWS Lambda? A: Yes, the package is lightweight and has minimal dependencies, making it perfect for serverless environments.

Q: Does it support enterprise-grade proxies? A: Yes, any proxy that works with httpx will work here.

Q: How do I get a TeamAI key? A: You usually need to join their Discord community or contact their support team.

Changelog

v1.0.0 (2026-02-14)

Initial public release.
Unified Onyx, Void, and TeamAI.
Automatic fallback mechanism.
Advanced key discovery system.

v0.9.0 (Beta)

Internal testing and architecture refinement.
Added easygradients support.

Roadmap

Async Support: Full async/await implementation for high-concurrency bots.
More Solvers: Integration with 2Captcha, CapMonster, and Anti-Captcha.
Dynamic Load Balancing: Automatically pick the fastest provider based on recent history.
Browser Extension: Export solved tokens directly to browser instances.
Custom Task Types: Support for specialized tasks like FunCaptcha and DataDome.

Security & Ethics

The developers of easycaptchas are not responsible for any misuse of this library. Users must comply with all local laws and the Terms of Service of the websites they interact with. Never store API keys in public repositories. Use environment variables or secret managers.

Acknowledgments

Thanks to the developers of httpx for the amazing networking library.
Thanks to the Onyx, Void, and TeamAI teams for providing high-quality solving services.
Special thanks to all contributors who have helped refine the fallback logic.

Detailed Technical Specifications

Memory Usage

easycaptchas is designed to be extremely lightweight. In a typical execution environment:

Baseline Memory: ~15MB (Python runtime + imports)
Per Solve Request: < 1MB additional overhead.
Dependency Footprint: Minimal (httpx, toml, yaml).

Network Footprint

Request Headers: Mimics standard browser-like headers where possible.
Payload Size: Optimized JSON payloads to minimize bandwidth.
Concurrent Requests: Supported via multiple CaptchaSolver instances or thread-safe execution.

Timeout Logic

The default timeout is 120 seconds. This includes:

Initial Connection: 30s.
Task Creation: 30s.
Polling Phase: Up to 60s total. These values can be tuned in the Solver constructor if your use case requires stricter SLAs.

Troubleshooting Guide

Issue	Potential Cause	Solution
`401 Unauthorized`	Invalid API Key	Check your `.env` or environment variables for typos.
`Connection Timeout`	Firewall or Proxy issue	Ensure your network allows outbound traffic to the provider's API.
`Task ID not found`	Provider rejected sitekey	Verify that the `sitekey` and `siteurl` match exactly what is on the target site.
`Empty Token`	Solver timed out	Increase the `timeout` parameter or try a different provider.
`ImportError`	Missing dependencies	Run `pip install httpx toml pyyaml easygradients`.

Glossary

Sitekey: A public identifier for a captcha instance.
rqdata: "Request Data" - a dynamic token required for some enterprise hCaptcha instances.
Fallback: The process of switching to a backup provider when the primary fails.
Proxyless: Solving captchas using the provider's IP address rather than your own.

Community and Support

GitHub Issues: For bug reports and feature requests.
Discord: Join our developer community (link in GitHub).
Documentation: Full Docs Site (Coming soon).

Final Notes

easycaptchas is built by developers, for developers. We believe that automation should be accessible, resilient, and simple. If you find this library useful, please consider giving it a star on GitHub!

Built with ❤️ by DraxonV1 and the open-source community.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
easycaptchas		easycaptchas
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
verify_solvers.py		verify_solvers.py

Folders and files

Latest commit

History

Repository files navigation