Overview

Use the REST API to retrieve user balances, verify tokens or get stats.

The REST API should only be called from the server, never from the client.

Errors

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.

Each API request may result in any of these global errors. Individual API requests may result in different errors, documented individually.

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 or viceversa.
not_found The API endpoint could not be found. Check the URL for your API call.
internal_error Something bad happened on Minero servers side.

Reference

Tokens
Users
Stats

/token/verify

Verify that a token from a Minero.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.

URL: https://api.minero.cc/token/verify
Method: POST
Parameters
secret Your private secret key. Find it in your dashboard.
token The name of the token you want to verify. This can be obtained directly from the miner, through miner.getToken().
hashes The number of hashes this token must have reached in order to be valid.
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
}
Errors
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.

/user/balance

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.

URL: https://api.minero.cc/user/balance
Method: GET
Parameters
secret Your private secret key. Find it in your dashboard.
name The user's name, analogous to the name specified for the Minero.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.
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
}
Errors
missing_input No name provided as GET parameter.
unknown_user The user name is not known (never submitted valid hashes).

/user/withdraw

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

URL: https://api.minero.cc/user/withdraw
Method: POST
Parameters
secret Your private secret key. Find it in your dashboard.
name The user's name, analogous to the name specified for the Minero.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.
amount The number of hashes to withdraw.
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
}
Errors
missing_input No name or amount provided as POST parameters.
unknown_user The user name is not known (never submitted valid hashes).
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.

/user/top

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

URL: https://api.minero.cc/user/top
Method: GET
Parameters
secret Your private secret key. Find it in your dashboard.
count Optional. The number of users to return. Default 128, min 1, max 1024.
Response
{
  "success": true|false,
  "users": [
    {
      "name": string,
      "total": number,
      "withdrawn": number,
      "balance": number
    },
    ...
  ],
  "error": string  // optional
}

/user/list

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.

URL: https://api.minero.cc/user/list
Method: GET
Parameters
secret Your private secret key. Find it in your dashboard.
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.
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
}
Errors
invalid_page The page of users could not be found.

/user/reset

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

URL: https://api.minero.cc/user/reset
Method: POST
Parameters
secret Your private secret key. Find it in your dashboard.
name The user's name whose total and withdrawn values will be reset to 0..
Response
{
  "success": true|false,  // whether the request succeeded; also true for
                          // non-existing users names
  "error": string         // optional
}
Errors
missing_input No name provided as POST parameter.

/stats/payout

Get the current payout rate and stats about the network.

URL: https://api.minero.cc/stats/payout
Method: GET
Parameters
secret Your private secret key. Find it in your dashboard.
Response
{
  "success": true|false,
  "globalDifficulty": number,
  "globalHashrate": number,
  "blockReward": number,
  "payoutPercentage": number,
  "payoutPer1MHashes": number,
  "xmrToUsd": number,
  "updated": number,
  "error": string  // optional
}

/stats/site

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

URL: https://api.minero.cc/stats/site
Method: GET
Parameters
secret Your private secret key. Find it in your dashboard.
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
}