Developed by Infosimples, a brazilian company that offers data extraction solutions and Ruby on Rails development.

We suggest you to also check for a cheaper service. You can find it's gem fully compatible with the deathbycaptcha gem at

Contact us if you need enterprise services for CAPTCHAs solving or Internet automation.


DeathByCaptcha is a Ruby API for DeathByCaptcha -


Add this line to your application's Gemfile:

gem 'deathbycaptcha', '~> 5.0.0'

And then execute:

$ bundle

Or install it yourself as:

$ gem install deathbycaptcha


  1. Create a client
  # Create a client (:socket and :http clients are available)
  client ='myusername', 'mypassword', :http)
  1. Solve a captcha

There are two methods available: decode and decode! * decode doesn't raise exceptions. * decode! may raise a DeathByCaptcha::Error if something goes wrong.

If the solution is not available, an empty captcha object will be returned.

  captcha = client.decode!(url: '')
  captcha.text        # Solution of the captcha          # Numeric ID of the captcha solved by DeathByCaptcha
  captcha.is_correct  # true if the solution is correct

You can also specify path, file, raw and raw64 when decoding an image.

  client.decode!(path: 'path/to/my/captcha/file')

  client.decode!(file:'path/to/my/captcha/file', 'rb'))

  client.decode!(raw:'path/to/my/captcha/file', 'rb').read)

  client.decode!(raw64: Base64.encode64('path/to/my/captcha/file', 'rb').read))

Internally, the gem will always convert any image to raw64 (binary base64 encoded).

  1. Retrieve a previously solved captcha
  captcha = client.captcha('130920620') # with 130920620 as the captcha id
  1. Report incorrectly solved captcha for refund
  captcha =!('130920620') # with 130920620 as the captcha id

Warning: do not abuse on this method, otherwise you may get banned

  1. Retrieve your user information (which has the current credit balance)
  user = client.user()
  user.is_banned  # true if the user is banned
  user.balance    # Credit balance in US cents
  user.rate       # Captcha rate, i.e. charges for one solved captcha in US cents         # Numeric ID of your account
  1. Retrieve DeathByCaptcha server status
  status = client.status()
  status.todays_accuracy        # Current accuracy of DeathByCaptcha
  status.solved_in              # Estimated seconds to solve a captcha right now
  status.is_service_overloaded  # true if DeathByCaptcha is overloaded/unresponsive


It's currently available only with the :http client.

To solve captchas similar to reCAPTCHA v2, you can use both the DeathByCaptcha's Coordinates API or Image Group API.

Please, read the oficial documentation at

Using the Coordinates API

# Read above all the instructions on how to solve a captcha.
captcha = client.decode!(type: 2, url: '')

You should specify arguments with type = 2 and an image similar to a screenshot of the captcha. See an example:

Captcha (screenshot)

the argument is passed as url, path, file, raw or raw64

Example of a captcha based on image clicks

The response will be an array containing coordinates (x, y) where the human clicked to solve the captcha. For the captcha above it should look something like:

# captcha.text

# captcha.coordinates
[[30, 143], [241, 325]]

Using the Image Group API

# Read above all the instructions on how to solve a captcha.
captcha = client.decode!(
  type: 3,
  url: '', # single image with the clickable grid
  banner: { url: '' }, # the banner image
  banner_text: 'Click all images with bananas' # the banner text

You should specify arguments with type = 3 and the decomposed captcha as seen in the example below:

Captcha: images grid

the argument is passed as url, path, file, raw or raw64

Example of a grid of a captcha based on image clicks

Captcha: banner

Example of a banner of a captcha based on image clicks

Captcha: banner text

Click all images with bananas

The response will be an array containing the indexes for each image that should be clicked counting from left to right. For the captcha above it should look something like:

# captcha.text

# captcha.indexes
[1, 9]



The API is thread-safe, which means it is perfectly fine to share a client instance between multiple threads.

HTTP and Socket clients

The API supports HTTP and socket-based connections, with the latter being recommended for having faster responses and overall better performance. The two clients have the same methods/interface.

When using the socket client, make sure that outgoing TCP traffic to to the ports in range 8123-8130 is not blocked by your firewall.

We are currently suggesting developers to use HTTP connection because Socket seems to be unstable with older Ruby versions. While we are investigating, consider using only HTTP connection.

Ruby dependencies

DeathByCaptcha >= 5.0.0 don't require specific dependencies. That saves you memory and avoid conflicts with other gems.

Input image format

Any format you use in the decode method (url, file, path, raw, raw64) will always be converted to a raw64, which is a binary base64 encoded string. So, if you already have this format available on your side, there's no need to do convertions before calling the API.

Our recomendation is to never convert your image format, unless needed. Let the gem convert internally. It may save you resources (CPU, memory and IO).


We no longer follow the versioninig system of the official clients of DeathByCaptcha. We have bumped to version 5.0.0 and will use Semantic Versioning from now on.

Upgrade from 4.x to 5.x

Any 5.x version is incompatible with any 4.x version. Please, review your code before upgrading.

Ruby versions

This gem has been tested on the following versions of Ruby:

  • MRI 2.2.0
  • MRI 2.1.5
  • MRI 2.0.0
  • MRI 1.9.3



  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Run/add tests (RSpec)
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request
  7. Yay. Thanks for contributing :)

All contributors:


MIT License. Copyright (C) 2011-2015 Infosimples.