✨ Multi-Captcha Solver Adapter ✨

A powerful and easy-to-use NodeJS library that unifies multiple captcha-solving services under a single, elegant, and robust interface.

---

🚀 Key Features

• 🧩 Multi-Provider Support: Built-in support for the most popular captcha services.
• 🛡️ Unified Interface: Use the same code to talk to different services. Switch providers by changing just one line!
• 🦾 Resilient & Robust: Automatic retry system with exponential backoff and custom error handling.
• 🌐 Modern Support: Solves ImageToText, reCAPTCHA v2/v3, hCaptcha and more.
• 🕵️ Proxy Support: Send your proxies to solving services for complex scraping tasks.
• 💯 Strictly Typed: Developed 100% in TypeScript for safer and more predictable code.

🛠️ Supported Services

• [x] 2Captcha
• [x] Anti-Captcha
• ... and more coming soon!

📦 Installation

npm install multi-captcha-solver-adapter
Copy

👨‍💻 Usage Examples

Basic Usage: Solving an Image Captcha

import { MultiCaptchaSolver, ECaptchaSolverService } from 'multi-captcha-solver-adapter';

const imageBase64 = '...'; // your captcha image in base64

async function solveImage() {
  const solver = new MultiCaptchaSolver({
    apiKey: 'YOUR_PROVIDER_API_KEY',
    captchaService: ECaptchaSolverService.TwoCaptcha,
  });

  try {
    const solution = await solver.solveImageCaptcha(imageBase64);
    console.log(`🎉 The solution is: ${solution}`);
  } catch (error) {
    console.error('😱 An error occurred:', error);
  }
}

solveImage();
Copy

Advanced Usage: reCAPTCHA v3 with Proxies and Error Handling

import {
  MultiCaptchaSolver,
  ECaptchaSolverService,
  // Import custom errors for detailed handling!
  InvalidApiKeyError,
  InsufficientBalanceError,
  CaptchaServiceError,
  ProxyOptions
} from 'multi-captcha-solver-adapter';

async function solveAdvanced() {
  const solver = new MultiCaptchaSolver({
    apiKey: 'YOUR_PROVIDER_API_KEY',
    captchaService: ECaptchaSolverService.AntiCaptcha,
    retries: 3, // Optional: number of retries
  });

  const proxy: ProxyOptions = {
    type: 'http',
    uri: '127.0.0.1:8888',
    username: 'proxy_user', // optional
    password: 'proxy_pass', // optional
  };

  try {
    const balance = await solver.getBalance();
    console.log(`Current balance: $${balance}`);

    const token = await solver.solveRecaptchaV3(
      'https://my-target-website.com',
      'google-site-key-here',
      0.7, // minScore
      'homepage_action', // pageAction
      proxy
    );
    console.log(`reCAPTCHA v3 token obtained: ${token.substring(0, 30)}...`);

  } catch (error) {
    if (error instanceof InvalidApiKeyError) {
      console.error(`API Key is invalid for ${error.service}.`);
    } else if (error instanceof InsufficientBalanceError) {
      console.error(`Insufficient balance in ${error.service}.`);
    } else if (error instanceof CaptchaServiceError) {
      console.error(`API error from ${error.service}: ${error.message}`);
    } else {
      console.error('😱 An unexpected error occurred:', error);
    }
  }
}

solveAdvanced();
Copy

🎯 Supported Captcha Types

Image Captcha

Solve traditional image-based captchas:

const solution = await solver.solveImageCaptcha(base64ImageString);
Copy

reCAPTCHA v2

Solve Google's reCAPTCHA v2 challenges:

const token = await solver.solveRecaptchaV2(
  'https://example.com',  // Website URL
  'site-key-here',        // Google site key
  proxy                   // Optional: proxy configuration
);
Copy

reCAPTCHA v3

Solve Google's reCAPTCHA v3 challenges:

const token = await solver.solveRecaptchaV3(
  'https://example.com',  // Website URL
  'site-key-here',        // Google site key
  0.7,                    // Minimum score (0.1 to 0.9)
  'submit',               // Page action
  proxy                   // Optional: proxy configuration
);
Copy

hCaptcha

Solve hCaptcha challenges:

const token = await solver.solveHCaptcha(
  'https://example.com',  // Website URL
  'site-key-here',        // hCaptcha site key
  proxy                   // Optional: proxy configuration
);
Copy

🔄 Retry Logic

The library includes automatic retry logic with exponential backoff:

const solver = new MultiCaptchaSolver({
  apiKey: 'YOUR_API_KEY',
  captchaService: ECaptchaSolverService.TwoCaptcha,
  retries: 5, // Will retry up to 5 times (default: 3)
});

// The solver will automatically retry failed requests with increasing delays
const token = await solver.solveRecaptchaV2('https://example.com', 'site-key');
Copy

🕵️ Proxy Support

Configure proxies for solving web-based captchas:

import { ProxyOptions } from 'multi-captcha-solver-adapter';

const proxyConfig: ProxyOptions = {
  type: 'http',           // 'http', 'https', 'socks4', or 'socks5'
  uri: '127.0.0.1:8080',  // proxy host:port
  username: 'user',       // optional authentication
  password: 'pass',       // optional authentication
};

// Use proxy with any web-based captcha
const token = await solver.solveRecaptchaV2(
  'https://example.com',
  'site-key',
  proxyConfig
);
Copy

🛡️ Error Handling

The library provides specific error types for better error handling:

import {
  MultiCaptchaError,        // Base error class
  CaptchaServiceError,      // General API errors
  InvalidApiKeyError,       // Invalid API key
  InsufficientBalanceError, // Not enough balance
  IpBlockedError,          // IP address blocked
} from 'multi-captcha-solver-adapter';

try {
  const token = await solver.solveRecaptchaV2('https://example.com', 'site-key');
} catch (error) {
  if (error instanceof InvalidApiKeyError) {
    console.error(`Invalid API key for ${error.service}`);
  } else if (error instanceof InsufficientBalanceError) {
    console.error(`Insufficient balance in ${error.service}`);
  } else if (error instanceof IpBlockedError) {
    console.error(`IP blocked by ${error.service}`);
  } else if (error instanceof CaptchaServiceError) {
    console.error(`API error in ${error.service}: ${error.message}`);
  } else if (error instanceof MultiCaptchaError) {
    console.error(`Library error: ${error.message}`);
  }
}
Copy

🔧 API Reference

MultiCaptchaSolver

Constructor

new MultiCaptchaSolver(options: IMultiCaptchaSolverOptions)
Copy

Options:

• apiKey: string - Your captcha service API key
• captchaService: ECaptchaSolverService - The service to use
• retries?: number - Number of retries (default: 3)

Methods

• getBalance(): Promise<number> - Get account balance
• solveImageCaptcha(base64string: string): Promise<string> - Solve image captcha
• solveRecaptchaV2(websiteURL: string, websiteKey: string, proxy?: ProxyOptions): Promise<string> - Solve reCAPTCHA v2
• solveRecaptchaV3(websiteURL: string, websiteKey: string, minScore: number, pageAction: string, proxy?: ProxyOptions): Promise<string> - Solve reCAPTCHA v3
• solveHCaptcha(websiteURL: string, websiteKey: string, proxy?: ProxyOptions): Promise<string> - Solve hCaptcha

Supported Services

• ECaptchaSolverService.TwoCaptcha - 2Captcha service
• ECaptchaSolverService.AntiCaptcha - Anti-Captcha service

📚 Examples

Check out the examples directory for complete working examples:

• Basic Example - Basic usage for all captcha types
• Proxy Example - Advanced usage with proxy configuration

💖 Contributing

Contributions are the heart of the open-source community! We are delighted to accept your help. Please check out our Contribution Guide to get started.

📄 License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

---

Author

Neyib Alexander Daza Guerrero

• Email: dev.alexander.daza@gmail.com
• GitHub: @devalexanderdaza