Documentation » HTTP API

Overview

With the Coinhive HTTP API you can get the number of hashes solved for a user account on your website, withdraw hashes, verify tokens and programmatically create shortlinks.

Using this API requires a secret key (see Settings » Sites). As the name implies, this key should be kept secret and should never be exposed to your users. The HTTP API should only ever be called from the server side, i.e. from PHP, NodeJS, Ruby, Python scripts running on your own server.

You should never call the Coinhive HTTP API from the client side.

Your secret key can be passed with each API call as a GET or POST parameter, depending on the required method for the endpoints.

The API returns a JSON encoded object for each request. All responses contain a boolean success property. In case success is false, an error property will be present, describing why the operation failed.

Global Errors

Each API request may result in any of these global errors

API Reference

Tokens

• /token/verify

Users

• /user/balance
• /user/withdraw
• /user/top
• /user/list
• /user/reset
• /user/reset-all

Links

• /link/create

Stats

• /stats/payout
• /stats/site
• /stats/history

/token/verify

URL: https://api.coinhive.com/token/verify

Method: POST

Verify that a token from a CoinHive.Token miner has reached a number of hashes. Tokens are only valid for 1 hour. Note that a token can only be verified once. All subsequent requests to verify the same token will result in the invalid_token error.

Parameters

Response

{
	"success": true|false, 	// whether the token could be verified
	"hashes": number, 		// the number of hashes recorded for this token
	"created": number, 		// unix timestamp
	"error": string 		// optional
}

Possible Errors

In addition, any of the global errors might occur.

Example

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

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

/user/balance

URL: https://api.coinhive.com/user/balance

Method: GET

Get the total number of hashes, the withdrawn hashes and the current balance for a user name. Think of it as the balance of a bank account. Hashes can be paid in through mining, and withdrawn through /user/withdraw.

Parameters

Response

{
	"success": true|false, 	// whether the user's balance could be obtained
	"name": string, 		// the user's name
	"total": number, 		// the number of accepted hashes
	"withdrawn": number, 	// the number of withdrawn hashes
	"balance": number, 		// the number of (accepted - withdrawn) hashes
	"error": string 		// optional
}

Possible Errors

In addition, any of the global errors might occur.

Example

curl "https://api.coinhive.com/user/balance?name=johnd&secret=<secret-key>"

# {success: true, name: "johnd", total: 4096, withdrawn: 256, balance: 3840}

/user/withdraw

URL: https://api.coinhive.com/user/withdraw

Method: POST

Withdraw a number of hashes for a user name. If successful, the requested amount will be subtracted from the user's balance.

Parameters

Response

{
	"success": true|false, 	// whether the requested amount could be withdrawn
	"name": string, 		// the user's name
	"amount": number, 		// the number of hashes withdrawn (same as input)
	"error": string 		// optional
}

Possible Errors

In addition, any of the global errors might occur.

Example

curl -X POST \
	-d "name=johnd" \
	-d "amount=4096" \
	-d "secret=<secret-key>" \
	"https://api.coinhive.com/user/withdraw"

# {"success": true, "name": "johnd", "amount": 4096}

/user/top

URL: https://api.coinhive.com/user/top

Method: GET

Get a list of top users ordered by total number of hashes, balance or hashes withdrawn.

Parameters

Response

{
	"success": true|false,
	"users": [
		{
			"name": string, 
			"total": number, 
			"withdrawn": number, 
			"balance": number
		},
		…
	],
	"error": string // optional
}

Any of the global errors might occur.

/user/list

URL: https://api.coinhive.com/user/list

Method: GET

Get a paginated list of all users in alphabetical order. Note that this will only return users with a total number of hashes greater than 0.

Parameters

Response

{
	"success": true|false, 
	"users": [
		{
			"name": string, 
			"total": number, 
			"withdrawn": number, 
			"balance": number
		},
		…
	],
	"nextPage": string|null, // the name of the next page of users
	"error": string // optional
}

Possible Errors

In addition, any of the global errors might occur.

/user/reset

URL: https://api.coinhive.com/user/reset

Method: POST

Reset a user's total hashes and withdrawn amount to 0.

Parameters

Response

{
	"success": true|false, 	// whether the request succeeded; also true for
							// non-existing users names
	"error": string 		// optional
}

Possible Errors

In addition, any of the global errors might occur.

/user/reset-all

URL: https://api.coinhive.com/user/reset-all

Method: POST

Reset the hashes and withdrawn amount for all users for this site to 0.

Parameters

Response

{
	"success": true|false, 	// whether the request succeeded
	"affected": number,		// the number of users affected
	"error": string 		// optional
}

Possible Errors

Any of the global errors might occur.

/link/create

URL: https://api.coinhive.com/link/create

Method: POST

Create a new shortlink. You can also do this by hand, directly from your dashboard.

Parameters

Response

{
	"success": true|false, 	// whether the link could be created
	"url": string, 			// the resulting URL of the shortlink
	"error": string 		// optional
}

Possible Errors

In addition, any of the global errors might occur.

Example

curl -X POST \
	-d "url=https://en.wikipedia.org/wiki/Monero_(cryptocurrency)" \
	-d "hashes=1024" \
	-d "secret=<secret-key>" \
	"https://api.coinhive.com/link/create"

# {success: true, url: "https://cnhv.co/6bk"}

/stats/payout

URL: https://api.coinhive.com/stats/payout

Method: GET

Get the current payout rate and stats about the network.

Parameters

Response

{
	"success": true|false,
	"globalDifficulty": number,
	"globalHashrate": number,
	"blockReward": number,
	"payoutPercentage": number,
	"payoutPer1MHashes": number,
	"xmrToUsd": number,
	"updated": number,
	"error": string // optional
}

Possible Errors

Any of the global errors might occur.

/stats/site

URL: https://api.coinhive.com/stats/site

Method: GET

Get the current hashrate, total hashes, paid & pending xmr, and the hourly history for the past seven days for the site.

Parameters

Response

{
	"success": true|false,
	"hashesPerSecond": number,
	"hashesTotal": number,
	"xmrPending": number,
	"xmrPaid": number,
	"name": string,
	"history": [
		{
			"time": number, // unix timestamp
			"hashesTotal": number,
			"hashesPerSecond": number
		},
		…
	],
	"error": string // optional
}

Possible Errors

Any of the global errors might occur.

/stats/history

URL: https://api.coinhive.com/stats/history

Method: GET

Get the hourly history of total hashes and hashes/s for a time period for the site.

Parameters

Response

{
	"success": true|false,
	"history": [
		{
			"time": number, // unix timestamp
			"hashesTotal": number,
			"hashesPerSecond": number
		},
		…
	],
	"error": string // optional
}

Possible Errors

Any of the global errors might occur.