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 sursolverQuick 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
endOther 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