Project

sursolver

0.0
The project is in a healthy, maintained state
Solve reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge (cf_clearance), GeeTest, DataDome, AWS WAF, Akamai, Kasada and image captchas from Ruby with one call. Standard library only.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Dependencies

Runtime

>= 2.7
 Project Readme

SurSolver for Ruby — captcha solver API client

Solve reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest, DataDome, AWS WAF, Akamai, Kasada and image captchas from Ruby with the official SurSolver gem. One call submits the captcha and returns the token or cookie. Ruby 3.4+, standard library only.

gem install sursolver

Quick start

require "sursolver"

API_KEY = "YOUR_API_KEY"
USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"

client = SurSolver::Client.new(API_KEY)
result = client.solve(
  "type" => SurSolver::TaskTypes::TURNSTILE_TOKEN_PROXY_LESS,
  "websiteURL" => "https://example.com/login",
  "websiteKey" => "0x4AAAAAAA...",
  "userAgent" => USER_AGENT
)
puts result.solution["token"]

Send the same userAgent with the request that uses the result. Tokens and cookies are single-use, so use them right away. The examples below reuse client and USER_AGENT.

Examples

Solve reCAPTCHA v3 in Ruby

result = client.solve(
  "type" => SurSolver::TaskTypes::RE_CAPTCHA_V3_TOKEN_PROXY_LESS,
  "websiteURL" => "https://example.com/login",
  "websiteKey" => "6Le-wvkS...",
  "pageAction" => "login",
  "userAgent" => USER_AGENT
)
puts result.solution["gRecaptchaResponse"]

For reCAPTCHA v3 Enterprise use SurSolver::TaskTypes::RE_CAPTCHA_V3_ENTERPRISE_TOKEN_PROXY_LESS.

Solve Cloudflare Turnstile

result = client.solve(
  "type" => SurSolver::TaskTypes::TURNSTILE_TOKEN_PROXY_LESS,
  "websiteURL" => "https://example.com/signup",
  "websiteKey" => "0x4AAAAAAA...",
  "userAgent" => USER_AGENT
)
# Submit the token as the cf-turnstile-response form field.
puts result.solution["token"]

Bypass the Cloudflare Challenge page (cf_clearance)

result = client.solve(
  "type" => SurSolver::TaskTypes::CLOUDFLARE_CHALLENGE_COOKIE,
  "websiteURL" => "https://example.com/protected",
  "proxy" => "http://user:password@203.0.113.10:8000",
  "userAgent" => USER_AGENT
)
puts result.solution["cf_clearance"]

Replay the cookie through the same proxy and with the same userAgent.

Solve GeeTest v4

result = client.solve(
  "type" => SurSolver::TaskTypes::GEE_TEST_TOKEN_PROXY_LESS,
  "websiteURL" => "https://example.com/login",
  "captchaId" => "e392e1d7fd421dc63325744d5a2b9c73",
  "userAgent" => USER_AGENT
)
puts result.solution["lot_number"], result.solution["pass_token"]

GeeTest v3: send gt and a fresh challenge instead of captchaId.

Solve the DataDome slider

result = client.solve(
  "type" => SurSolver::TaskTypes::DATA_DOME_SLIDER_COOKIE,
  "websiteURL" => "https://example.com/",
  "captchaUrl" => "https://geo.captcha-delivery.com/captcha/?initialCid=...",
  "proxy" => "http://user:password@203.0.113.10:8000",
  "userAgent" => USER_AGENT
)
puts result.solution["datadome"]

Get an AWS WAF token (silent challenge)

result = client.solve(
  "type" => SurSolver::TaskTypes::AWS_CHALLENGE_COOKIE,
  "websiteURL" => "https://example.com/",
  "scriptUrl" => "https://example.token.awswaf.com/example/challenge.js",
  "userAgent" => USER_AGENT
)
puts result.solution["aws-waf-token"]

The visual AWS WAF CAPTCHA is SurSolver::TaskTypes::AWS_CAPTCHA_COOKIE and needs your proxy.

Solve an image captcha (image to text)

require "base64"

result = client.solve(
  "type" => SurSolver::TaskTypes::IMAGE_TO_TEXT_TASK,
  "module" => "1",
  "body" => Base64.strict_encode64(File.binread("captcha.png"))
)
puts result.solution["answer"]

Supported captchas

Captcha task.type Guide
reCAPTCHA v3 ReCaptchaV3TokenProxyLess recaptcha-v3
reCAPTCHA v3 Enterprise ReCaptchaV3EnterpriseTokenProxyLess recaptcha-v3-enterprise
Cloudflare Turnstile TurnstileTokenProxyLess turnstile
Cloudflare Challenge CloudflareChallengeCookie cloudflare-challenge
GeeTest v3 / v4 GeeTestTokenProxyLess geetest
DataDome DataDomeSliderCookie datadome
AWS WAF Challenge AwsChallengeCookie aws-challenge
AWS WAF CAPTCHA AwsCaptchaCookie aws-captcha
Akamai (_abck) AkamaiCookieProxyLess akamai
Akamai SBSD AkamaiSbsdCookie akamai-sbsd
Akamai BMP (Android) AkamaiBmpTask akamai-bmp
Kasada KasadaTokenProxyLess kasada
Shape ShapeCookieProxyLess shape
Imperva (reese84 / utmvc) ImpervaCookie, ImpervaUtmvcCookie imperva
Vercel Security Checkpoint VercelCookie vercel
FriendlyCaptcha FriendlyCaptchaTokenProxyLess friendlycaptcha
MTCaptcha MtCaptchaTokenProxyLess mtcaptcha
Prosopo ProsopoTokenProxyLess prosopo
CaptchaFox CaptchaFoxToken captchafox
Altcha AltchaTokenProxyLess altcha
Lemin LeminTokenProxyLess lemin
Castle (Android) CastleAndroidToken castle-android
Image to Text ImageToTextTask image-to-text

Each guide lists the fields to send and where to find them on the page. The live list is client.list_task_types; prices are client.list_services.

Errors

begin
  result = client.solve(task)
rescue SurSolver::NoSlotAvailableError
  # all your threads are busy: try again in a moment
rescue SurSolver::TaskFailedError
  # this captcha could not be solved; its charge is refunded
end

Other errors: SurSolver::AuthenticationError (wrong API key), SurSolver::InvalidTaskError (a field is missing or wrong), SurSolver::InsufficientBalanceError (top up), SurSolver::SolveTimeoutError (no result in time). All inherit from SurSolver::Error.

Links

License

MIT