Documentation » Captcha

Overview

This page explains how to display and customize the Coinhive proof of work widget on your webpage. From a website owner's perspective the Coinhive captcha works exactly like a conventional captcha, such as Google's reCaptcha.

The captcha is embeded in an HTML form, runs client side in the user's browser and generates a token. The token is submitted together with the other form data. You can then validate this token on your server through our HTTP API.

Unlike with a conventional captcha however, the user does not have to “proof they're human”. Instead, the captcha is a “proof of work” – making it uneconomic for spammers to game your system.

Demo video showing the proof of work captcha

Embedding

To embed the Coinhive captcha, you have to load the captcha.min.js anywhere on your page and create a <div> with the coinhive-captcha class where you want to show the captcha.

<form action="?" method="post">
	<!-- other form fields -->

	<script src="https://coin-hive.com/lib/captcha.min.js" async></script>
	<div class="coinhive-captcha" data-hashes="1024" data-key="SITE_KEY"></div>

	<input type="submit" value="Submit"/>
</form>

When the captcha is completed, a field with the name coinhive-captcha-token will be filled with the token name. This field will be submitted with the rest of your form.

On the server side, you verify the received token through our HTTP API with /token/verify.

curl -X POST \
	-d "token=<coinhive-captcha-token>" \
	-d "hashes=1024" \
	-d "secret=<secret-key>" \
	"https://api.coin-hive.com/token/verify"

# {"success": true, "created": 1504205981, "hashes": 1024}

Note that you have to specify the number of hashes twice: once on the client side for the widget, so it knows when it's done, and once when verifying the token on the server, so the client can't cheat.

Options

You can specify various options as data- attributes with the div element. The data-key and data-hashes attributes are mandatory.

data-key Your public Site-Key. See Settings » Sites.
data-hashes The number of hashes that have to be accepted by the mining pool. Our pool uses a difficulty of 256, so your hashes goal should be a multiple of 256.
data-autostart Optional. Whether to automatically start solving the captcha (true|false). The default is false.
data-callback Optional. The name of a global JavaScript function that should be called when the goal is reached.
data-disable-elements Optional. A CSS selector for elements that should be disabled until the goal is reached. Usually this will be your form submit button.

Full example

<form action="?" method="post">
	<!-- other form fields -->

	<script src="https://coin-hive.com/lib/captcha.min.js" async></script>
	<script>
		function myCaptchaCallback(token) {
			alert('Hashes reached. Token is: ' + token);
		}
	</script>
	<div class="coinhive-captcha" 
		data-hashes="1024" 
		data-key="SITE_KEY"
		data-autostart="false"
		data-disable-elements="input[type=submit]"
		data-callback="myCaptchaCallback"
	></div>

	<!-- submit button will be automatically disabled and later enabled
		again when the captcha is solved -->
	<input type="submit" value="Submit"/>
</form>

Example of Token Verification Using PHP

$post_data = [
	'secret' => "SECRET-KEY", // <- Your secret key
	'token' => $_POST['coinhive-captcha-token'],
	'hashes' => 1024
];

$post_context = stream_context_create([
	'http' => [
		'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
		'method'  => 'POST',
		'content' => http_build_query($post_data)
	]
]);

$url = 'https://api.coin-hive.com/token/verify';
$response = json_decode(file_get_contents($url, false, $post_context));

if ($response && $response->success) {
	// All good. Token verified!
}

For a detailed explanation of the HTTP API including all possible error codes, please refer to the HTTP API documentation.

© 2017 coin-hive.com – ContactTerms of ServicePrivacyBlog