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.
We developed a tiny PHP class to make using our HTTP API a bit easier.
Download the CoinHiveAPI
class from github
The class has just two methods for get
and post
requests. You can use it like this:
// Instantiate the class with your secret key $coinhive = new CoinHiveAPI('YOUR_SECRET_KEY'); // Make a simple get request without additional parameters $stats = $coinhive->get('/stats/site'); echo $stats->hashesTotal; // Make a get request that requires an extra parameter $user = $coinhive->get('/user/balance', ['name' => 'john-doe']); echo $user->balance; // Make a post request $link = $coinhive->post('/link/create', [ 'url' => 'http://google.com', 'hashes' => 1024 ]); if ($link->success) { echo $link->url; }
Each API request may result in any of these global errors
invalid_secret | The secret provided as GET or POST parameter is invalid. |
bad_request | A malformed request was received. |
wrong_method | The API expected a POST request but a GET request was performed. |
not_found | The API endpoint could not be found. Check the URL for your API call. |
internal_error | Something bad happened on our side. Contact us if the issue persists. |
https://api.coinhive.com/token/verify
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.
secret | Your private Secret-Key. See Settings » Sites. |
token | The name of the token you want to verify. This can be obtained directly from the miner, through miner.getToken(). For the captcha, the token name will be submitted together with the form as coinhive-captcha-token . |
hashes | The number of hashes this token must have reached in order to be valid. |
{ "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 }
missing_input | No token or hashes provided as POST parameters. |
invalid_token | The token could not be verified. Either the token name was not found, or the token hasn't reached the requested number of hashes. |
In addition, any of the global errors might occur.
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}
https://api.coinhive.com/user/balance
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.
secret | Your private Secret-Key. See Settings » Sites. |
name | The user's name, analogous to the name specified for the Coinhive.User miner. This can be anything that is unique to the user on your website. E.g. a user name, id, the md5 hash of their name or their email address. |
{ "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 }
missing_input | No name provided as GET parameter |
unknown_user | The user name is not known (has never connected to the pool). |
In addition, any of the global errors might occur.
curl "https://api.coinhive.com/user/balance?name=johnd&secret=<secret-key>" # {success: true, name: "johnd", total: 4096, withdrawn: 256, balance: 3840}
https://api.coinhive.com/user/withdraw
POST
Withdraw a number of hashes for a user name. If successful, the requested amount will be subtracted from the user's balance.
secret | Your private Secret-Key. See Settings » Sites. |
name | The user's name, analogous to the name specified for the Coinhive.User miner. |
amount | The amount of hashes to withdraw. |
{ "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 }
missing_input | No name or amount provided as POST parameters. |
unknown_user | The user name is not known (has never connected to the pool). |
invalid_amount | The specified amount to withdraw is invalid (e.g. negative). |
insufficent_funds | The user doesn't have enough hashes to withdraw the specified amount. |
In addition, any of the global errors might occur.
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}
https://api.coinhive.com/user/top
GET
Get a list of top users ordered by total number of hashes, balance or hashes withdrawn.
secret | Your private Secret-Key. See Settings » Sites. |
count | Optional. The number of users to return. Default 128, min 1, max 1024\. |
order | Optional. Either total , balance or withdrawn . The default is total . |
{ "success": true|false, "users": [ { "name": string, "total": number, "withdrawn": number, "balance": number }, … ], "error": string // optional }
Any of the global errors might occur.
https://api.coinhive.com/user/list
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.
secret | Your private Secret-Key. See Settings » Sites. |
count | Optional. The number of users to return. Default 4096, min 32, max 8192. |
page | Optional. The page of users to return, obtained from the previous request's nextPage property. Leave out or specify an empty string for the first page. |
{ "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 }
invalid_page | The page of users could not be found. |
In addition, any of the global errors might occur.
https://api.coinhive.com/user/reset
POST
Reset a user's total hashes and withdrawn amount to 0.
secret | Your private Secret-Key. See Settings » Sites. |
name | The user's name whose total and withdrawn values will be reset to 0. |
{ "success": true|false, // whether the request succeeded; also true for // non-existing users names "error": string // optional }
missing_input | No name provided as POST parameter |
In addition, any of the global errors might occur.
https://api.coinhive.com/user/reset-all
POST
Reset the hashes and withdrawn amount for all users for this site to 0.
secret | Your private Secret-Key. See Settings » Sites. |
{ "success": true|false, // whether the request succeeded "affected": number, // the number of users affected "error": string // optional }
Any of the global errors might occur.
https://api.coinhive.com/link/create
POST
Create a new shortlink. You can also do this by hand, directly from your dashboard.
secret | Your private Secret-Key. See Settings » Sites. |
url | The target URL for the shortlink. Max 255 chars. |
hashes | The number of hashes that have to be solved, before the user is redirected to the target URL. |
{ "success": true|false, // whether the link could be created "url": string, // the resulting URL of the shortlink "error": string // optional }
missing_input | No url or hashes provided as POST parameters. |
invalid_url | The provided target URL is not a valid http:// or https:// URL. |
In addition, any of the global errors might occur.
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"}
https://api.coinhive.com/stats/payout
GET
Get the current payout rate and stats about the network.
secret | Your private Secret-Key. See Settings » Sites. |
{ "success": true|false, "globalDifficulty": number, "globalHashrate": number, "blockReward": number, "payoutPercentage": number, "payoutPer1MHashes": number, "xmrToUsd": number, "updated": number, "error": string // optional }
Any of the global errors might occur.
https://api.coinhive.com/stats/site
GET
Get the current hashrate, total hashes, paid & pending xmr, and the hourly history for the past seven days for the site.
secret | Your private Secret-Key. See Settings » Sites. |
{ "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 }
Any of the global errors might occur.
https://api.coinhive.com/stats/history
GET
Get the hourly history of total hashes and hashes/s for a time period for the site.
secret | Your private Secret-Key. See Settings » Sites. |
begin | Unix timestamp of the begin of the period you want to retreive. |
end | Unix timestamp of the end of the period you want to retreive. |
{ "success": true|false, "history": [ { "time": number, // unix timestamp "hashesTotal": number, "hashesPerSecond": number }, … ], "error": string // optional }
Any of the global errors might occur.