How to bypass captcha using Go

Introduction

Need to add CAPTCHA solving to your Go project? The official 2captcha-go library is the fastest way to integrate the 2Captcha API without manually writing HTTP requests.

In this guide, you'll learn why this module is worth using, how to set it up in under a minute, and what capabilities it offers for automating virtually any CAPTCHA-related workflow.

Overview

2captcha-go is the official Go client for the 2Captcha API. The library provides a simple interface for submitting CAPTCHA-solving tasks and retrieving results.

Why Use This Library?

• Unified interface for all CAPTCHA types — no need to memorize different endpoints and parameters; the library abstracts away the complexity
• Type safety — dedicated Go structs for each CAPTCHA type with compile-time validation
• Flexible configuration — customize timeouts, polling intervals, and callback notifications to fit your use case
• Built-in error handling — typed exceptions instead of raw server responses
• Native proxy support — pass proxy settings directly in the CAPTCHA request object
• Actively maintained — the library evolves alongside the API, with support for new CAPTCHA types added promptly

Environment Setup

Minimum requirements:

• Go 1.16 or later
• An API key from your 2Captcha account dashboard 2Captcha

Install the library with a single command:

go get -u github.com/2captcha/2captcha-go

Then import it into your project:

import "github.com/2captcha/2captcha-go"

How the Library Works

Core Class: Client

All interactions with the service are performed through a client instance:

client := api2captcha.NewClient("YOUR_API_KEY")

Flexible Configuration

You can customize the client's behavior using the available struct fields:

client := api2captcha.NewClient("YOUR_API_KEY")
client.SoftId = 123
client.Callback = "https://your.site/result-receiver"
client.DefaultTimeout = 120
client.RecaptchaTimeout = 600
client.PollingInterval = 10

Configuration Options

Important: If Callback is configured, methods return only the task ID and do not poll the API. The result will be delivered via a separate POST request to the specified URL.

Basic Usage Pattern

Regardless of the CAPTCHA type, the workflow remains the same:

package main

import (
    "fmt"
    "log"
    "github.com/2captcha/2captcha-go"
)

func main() {
    client := api2captcha.NewClient("YOUR_API_KEY")
    
    // 1. Create a CAPTCHA task
    // 2. Configure the required parameters
    // 3. Submit the task and retrieve the result
    
    captcha := api2captcha.Normal{
        File: "/path/to/captcha.jpg",
    }
    
    code, err := client.Solve(captcha.ToRequest())
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Solution: " + code)
}

This pattern works for every CAPTCHA type—the only thing that changes is the struct name and its configuration parameters.

Supported CAPTCHA Types

The library supports all major CAPTCHA formats:

• Text-based: Normal, Text, Audio
• Google: reCAPTCHA v2, reCAPTCHA v3, reCAPTCHA Enterprise
• Cloudflare: Turnstile
• Other providers: GeeTest, GeeTest V4, FunCaptcha, KeyCaptcha, Capy, Lemin, MTCaptcha, DataDome, Amazon WAF, Tencent, CyberSiARA, Yandex, VK Captcha, VK Image, Altcha, Binance, Prosopo, CaptchaFox, Temu, Cutcaptcha, Friendly Captcha, atbCAPTCHA

For a complete list and parameter examples, see the CAPTCHA Types Documentation.

Advanced Features

Callback Mode

If you don't want your application to wait for the result, configure a callback URL:

client := api2captcha.NewClient("YOUR_API_KEY")
client.Callback = "https://your.site/webhook"

captcha := api2captcha.Normal{
    File: "/path/to/captcha.jpg",
}

id, err := client.Solve(captcha.ToRequest())
// id contains only the task ID; the result will be sent to your server

Manual Workflow Control

For more advanced scenarios, low-level control is also available:

id, err := client.Send(captcha.ToRequest())
if err != nil {
    log.Fatal(err)
}

time.Sleep(10 * time.Second)

code, err := client.GetResult(id)
if err != nil {
    log.Fatal(err)
}

if code == nil {
    log.Fatal("Not ready yet")
}

fmt.Println("Solution: " + *code)

Using Proxies

Many CAPTCHA challenges require requests to originate from a specific IP address. You can configure a proxy directly in the request:

captcha := api2captcha.ReCaptcha{
    SiteKey: "6Le-wvkS...",
    Url:     "https://example.com",
}

req := captcha.ToRequest()
req.SetProxy("HTTPS", "login:password@123.123.123.123:8000")

code, err := client.Solve(req)

Additional CAPTCHA Parameters

For image CAPTCHAs and certain other types, you can provide additional hints:

captcha := api2captcha.Normal{
    File:          "/path/to/captcha.jpg",
    Numeric:       4,
    MinLen:        4,
    MaxLen:        20,
    Phrase:        true,
    CaseSensitive: true,
    Lang:          "en",
    HintText:      "Enter uppercase letters only",
}

Reporting Results

You can report whether a solution was correct or incorrect:

// Correct solution
err := client.Report(id, true)

// Incorrect solution
err := client.Report(id, false)

Error Handling

The library returns typed exceptions. Always use type assertions when handling errors:

code, err := client.Solve(captcha.ToRequest())
if err != nil {
    switch e := err.(type) {
    case *api2captcha.ValidationException:
        log.Fatalf("Validation error: %v", e)
    case *api2captcha.NetworkException:
        log.Fatalf("Network error: %v", e)
    case *api2captcha.ApiException:
        log.Fatalf("API error: %v", e)
    case *api2captcha.TimeoutException:
        log.Fatalf("Timeout: %v", e)
    default:
        log.Fatalf("Unknown error: %v", err)
    }
}

Common Error Codes

Integration Best Practices

• Store API keys securely — use environment variables or libraries such as godotenv; never hardcode credentials
• Configure sensible timeouts — complex CAPTCHAs can take longer to solve, so avoid overly aggressive limits
• Add logging — store task IDs and response times for troubleshooting and auditing
• Test before deployment — validate your integration in a testing environment before going live
• Monitor your balance — configure low-balance alerts to prevent service interruptions
• Use proxies when required — many websites expect CAPTCHA requests to originate from a specific IP address

Additional Resources

• GitHub Repository: https://github.com/2captcha/2captcha-go — source code, examples, issues, and releases
• Go Examples: https://github.com/2captcha/2captcha-go/tree/master/examples — ready-to-use snippets for every CAPTCHA type
• Full API Documentation: /api-docs — complete endpoint and parameter reference
• Error Reference: /api-docs/error-codes — explanation of all API response codes
• Support: /support — get help when something goes wrong

Pre-Launch Checklist

1. Library installed via go get
2. API key obtained and stored in an environment variable
3. Correct CAPTCHA type selected and all required parameters configured
4. Timeouts and polling intervals adjusted for your workload
5. Error handling implemented using typed exceptions
6. Integration tested against real target-site parameters
7. Callback endpoint and/or proxy settings configured if required

Conclusion

The 2captcha-go library provides a reliable and developer-friendly way to add CAPTCHA solving to any Go project. It hides API complexity behind a clean interface, offers type safety, supports extensive configuration options, and covers all major CAPTCHA types.

Start with a basic client configuration, choose the appropriate CAPTCHA type, and implement proper error handling—that's enough to build a stable integration. As your requirements grow, the library scales with you through support for callback notifications, manual workflow control, proxy configuration, and advanced logging.

The 2Captcha documentation, code examples, and support resources make it easy to handle even the most advanced use cases.

Automate CAPTCHA solving efficiently and with minimal effort using 2captcha-go.