Captcha Solver Client

A powerful TypeScript/JavaScript client library for interacting with Captcha Solver API. Supports multiple captcha types including Turnstile, reCAPTCHA, hCaptcha, FunCaptcha, GeeTest, and more.

Features

- 🚀 Full TypeScript Support - Complete type definitions for all API methods
- 🔧 Multiple Build Formats - CommonJS, ES Modules, and UMD builds
- 🎯 All Captcha Types - Support for Turnstile, reCAPTCHA, hCaptcha, and more
- ⚡ Promise-based API - Modern async/await support
- 🔄 Automatic Polling - Built-in result polling with customizable intervals
- 🛡️ Error Handling - Comprehensive error types and handling
- 📦 Lightweight - Minimal dependencies (only axios)
- 🌐 Universal - Works in Node.js and browsers

Installation

``bash
npm install captcha-solver-client
`

`bash
yarn add captcha-solver-client
`

`bash
pnpm add captcha-solver-client
`

Quick Start

$3

`typescript
import CaptchaSolverClient, { createTurnstile } from 'captcha-solver-client';

const client = new CaptchaSolverClient({
apiKey: 'your-api-key-here',
baseURL: 'https://your-api.com/api', // optional
});

// Solve a Turnstile captcha
const solution = await client.solveCaptcha({
type: 'turnstile',
sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
pageurl: 'https://faucets.chain.link/',
});

console.log('Solution:', solution);
`

$3

`javascript
const { CaptchaSolverClient } = require('captcha-solver-client');

const client = new CaptchaSolverClient({
apiKey: 'your-api-key-here',
});

async function solveCaptcha() {
try {
const solution = await client.solveCaptcha({
type: 'turnstile',
sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
pageurl: 'https://faucets.chain.link/',
});

console.log('Solution:', solution);
} catch (error) {
console.error('Error:', error.message);
}
}

solveCaptcha();
`

$3

`html




`

API Reference

$3

`typescript
const client = new CaptchaSolverClient({
apiKey: string; // Required: Your API key
baseURL?: string; // Optional: API base URL (default: http://localhost:3000/api)
timeout?: number; // Optional: Request timeout in ms (default: 30000)
retries?: number; // Optional: Number of retries (default: 3)
retryDelay?: number; // Optional: Delay between retries in ms (default: 1000)
});
`

$3

#### submitCaptcha(data: SubmitCaptchaRequest): Promise

Submit a captcha for solving.

`typescript
const task = await client.submitCaptcha({
type: 'turnstile',
sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
pageurl: 'https://example.com',
});

console.log('Task ID:', task.taskId);
console.log('Cost:', task.cost);
`

#### getTaskResult(taskId: string): Promise

Get the result of a submitted task.

`typescript
const result = await client.getTaskResult('task-id-here');

if (result.status === 'completed') {
console.log('Solution:', result.solution);
} else if (result.status === 'failed') {
console.log('Error:', result.error);
} else {
console.log('Status:', result.status); // 'pending' or 'processing'
}
`

#### waitForResult(taskId: string, options?): Promise

Wait for task completion with automatic polling.

`typescript
const result = await client.waitForResult('task-id-here', {
maxAttempts: 60, // Maximum polling attempts (default: 60)
pollInterval: 5000, // Polling interval in ms (default: 5000)
onProgress: (attempt, status) => {
console.log(Attempt ${attempt}: ${status});
},
});

console.log('Final solution:', result.solution);
`

#### solveCaptcha(data: SubmitCaptchaRequest, options?): Promise

Convenience method that submits captcha and waits for result.

`typescript
const solution = await client.solveCaptcha(
{
type: 'turnstile',
sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
pageurl: 'https://example.com',
},
{
maxAttempts: 60,
pollInterval: 5000,
onProgress: (attempt, status) => {
console.log(Solving... ${attempt}/60 - ${status});
},
}
);

console.log('Solution:', solution);
`

#### getBalance(): Promise

Get your account balance.

`typescript
const balance = await client.getBalance();
console.log(Balance: ${balance.balance} ${balance.currency});
`

#### getTasks(options?): Promise>

Get your task history.

`typescript
const tasks = await client.getTasks({
page: 1,
limit: 20,
status: 'completed', // optional filter
});

console.log(Found ${tasks.pagination.total} tasks);
tasks.items.forEach(task => {
console.log(${task.id}: ${task.status} - ${task.type});
});
`

#### reportIncorrect(taskId: string): Promise

Report an incorrect solution.

`typescript
await client.reportIncorrect('task-id-here');
console.log('Reported as incorrect');
`

Supported Captcha Types

$3

`typescript
await client.solveCaptcha({
type: 'turnstile',
sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
pageurl: 'https://faucets.chain.link/',
action: 'login', // optional
userAgent: 'Mozilla/5.0...', // optional
});
`

$3

`typescript
await client.solveCaptcha({
type: 'recaptcha_v2',
sitekey: 'your-site-key',
pageurl: 'https://example.com',
invisible: false, // optional
enterprise: false, // optional
});
`

$3

`typescript
await client.solveCaptcha({
type: 'recaptcha_v3',
sitekey: 'your-site-key',
pageurl: 'https://example.com',
action: 'submit', // optional
minScore: 0.3, // optional
});
`

$3

`typescript
await client.solveCaptcha({
type: 'hcaptcha',
sitekey: 'your-site-key',
pageurl: 'https://example.com',
invisible: false, // optional
});
`

Helper Functions

The library provides helper functions for creating captcha requests:

`typescript
import {
createTurnstile,
createRecaptchaV2,
createHCaptcha,
getCaptchaCost,
validateApiKey,
} from 'captcha-solver-client';

// Using helper functions
const turnstileRequest = createTurnstile({
sitekey: '0x4AAAAAAAa0Ic88byebJ1dj',
pageurl: 'https://example.com',
});

const solution = await client.solveCaptcha(turnstileRequest);

// Utility functions
const cost = getCaptchaCost('turnstile'); // 1.0
const isValid = validateApiKey('your-api-key'); // true/false
`

Error Handling

The library provides specific error types for different scenarios:

`typescript
import {
CaptchaSolverError,
AuthenticationError,
InsufficientBalanceError,
RateLimitError,
TimeoutError,
ValidationError,
} from 'captcha-solver-client';

try {
const solution = await client.solveCaptcha({
type: 'turnstile',
sitekey: 'invalid-key',
pageurl: 'https://example.com',
});
} catch (error) {
if (error instanceof AuthenticationError) {
console.error('Invalid API key');
} else if (error instanceof InsufficientBalanceError) {
console.error('Not enough balance');
} else if (error instanceof ValidationError) {
console.error('Invalid request data');
} else if (error instanceof TimeoutError) {
console.error('Request timed out');
} else {
console.error('Unknown error:', error.message);
}
}
`

Development

$3

`bash


Build development version

npm run build

Build minified version

npm run build:min

Build both versions

npm run build:all
`

$3

| Format | Original | Minified | Reduction |
| ------------- | -------- | -------- | --------- |
| CommonJS | 15.4 KB | 7.0 KB | 54.3% |
| ES Module | 14.5 KB | 6.9 KB | 52.0% |
| UMD (Browser) | 17.7 KB | 7.1 KB | 60.1% |

$3

`bash
npm test
npm run test:watch
`

$3

`bash
npm run lint
npm run lint:fix
``

License

MIT License - see LICENSE file for details.

Support

For support, please contact [your-email@example.com] or create an issue on GitHub.