API Documentation
Migrate from Faucethub.io

Our API is designed to be compatible with faucets and website using Faucethub.io

Download the library below by clicking the button below and replace it with your current faucethub.php

Basic usage example

How to quickly get started

The library provides 2 classes: FaucetHub and FaucetBOX. The FaucetHub class is the main class you will be using to integrate your application. The FaucetBOX class is a compatibility class which allows you to simply replace the traditional Faucetbox.com PHP library with our one without needing to edit any other code in your script, and functionality will work the same.

If you use a custom script make sure you respond correctly to status code 456 when making a payout. More information on this on the Migration guide.

# Credits to FaucetBOX.com for the original code example
$api_key = "YOUR_API_KEY";
$currency = "BTC"; # or LTC or any other supported by FaucetHub
$faucethub = new FaucetHub($api_key, $currency);

# To send 500 satoshi to address
$result = $faucethub->send("bitcoinaddresshere", 500);

if($result["success"] === true) {   # you can check if it was successful
    echo $result["html"];           # there's example html ready for you
} else {                            # something went wrong :(
    log_error($result["response"]); # you can log whole response from server
    echo $result["html"];           # and display error message to user
}
                

Keep your application running smooth

In order to keep the service running smooth, and for your users to have an enjoyable experience, we ask that you limit the number of API requests sent from your website/application. Below are a few tips and tricks for doing this.

Don't send a request for data you alredy have/was given

The best example of this is getbalance. There's no need to call it excessively, as the balance is returned in the send API result. The best way to use this is to store it in your database each time you made a payout to avoid sending another getbalance request.

example fields for your database: address, valid_result, time_checked, user_hash

Don't send requests from public-facing pages

This means, don't use code which calls the API from a page that the user has control of e.g. withdraw, home page, etc. This is the most common cause for using up your API request limit very quickly.

Again getbalance and send come to mind here, as most faucet scripts tend to place a getbalance call on their home page causing a lot of API requests to be sent. This is a bad practise and should be avoided. A better way is to follow the example from the previous section and store the balance in the database after a payout has been made.

Use background processes/cron jobs

The better way to make API calls is via background processes, also known as cron jobs. These tasks can be set up to run once per minute (or any interval you like) and run a command or PHP script. We highly recommend the use of them for the following tasks:

  • Storing the faucet balance in the database with a getbalance call.
  • Bulk processing a withdraw queue of user payouts instead of sending directly from the withdraw page. This is much more secure and prevents spam/race conditions/double pays.

The above tips and tricks will help you to limit the amount of API requests that your script/website/application makes, resulting in a more secure and faster website for your users.

All methods and usage explained

Using our API is easy, as every request you make is a HTTP POST request with a set of parameters such as your API key and currency and returned in JSON format.
If the request was successful, the JSON object will contain a status attribute equal to 200 along with an optional message attribute. If the request failed you will get a separate code and message attribute explaining the problem/error in further detail.

In the parameters list for each method there are REQUIRED parameters and OPTIONAL ones

NOTE A full list of status codes and errors with further explanation and suggestions is available at the bottom of this page in the Troubleshooting section.

Use this method to get your account balance in any supported currency.

Request URL(s)
  • https://api.microwallet.co/v1/balance
  • https://api.microwallet.co/v1/getbalance
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
  • currency A valid currency acronym, defaults to BTC
Return Values
  • currency The valid currency you made the request for
  • balance Your non-decimal balance, which is your coin balance multiplied by 10^8 (100000000)
  • balance_bitcoin Regular balance in coin value
Request Example
https://api.microwallet.co/v1/balance?api_key=YOUR_API_KEY_HERE¤cy=DOGE
Example Response
{
  "status": 200,
  "message": "OK",
  "currency": "DOGE",
  "balance": 1000000000000,
  "balance_bitcoin": 10000
}

Use this method to get a list of all the currencies we support on our platform and their status.

Request URL(s)
  • https://api.microwallet.co/v1/currencies
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
Return Values
  • currency The valid currency you made the request for
  • currencies_names A full array including the acronym, name and wallet/payout status (enabled true or false)
Request Example
https://api.microwallet.co/v1/currencies?api_key=YOUR_API_KEY_HERE
Example Response
{
  "status": 200,
  "message": "OK",
  "currencies": [
    "BTC",
    "LTC",
    "DOGE"
  ],
  "currencies_names": [
    {
      "name": "Bitcoin",
      "acronym": "BTC",
      "enabled": true
    },
    {
      "name": "Litecoin",
      "acronym": "LTC",
      "enabled": true
    },
    {
      "name": "Dogecoin",
      "acronym": "DOGE",
      "enabled": true
    }
  ]
}

If your site has manual payouts and you are unable to show the user a message real-time, then you can use this method to check if their currency address belongs to an account.

Request URL(s)
  • https://api.microwallet.co/v1/checkaddress
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
  • address The coin address you checking.
  • currency Currency of the address, defaults to BTC.
Return Values

This method will return status as 200 for a valid address, and 456 for an address that does not belong to an account.

  • payout_user_hash A unique hash corresponding to the individual user on FaucetHub. Store this value and use it to check how much was paid to each user to prevent fraud on your faucet.
Request Example
https://api.microwallet.co/v1/checkaddress?api_key=YOUR_API_KEY_HERE&address=CURRENCY_ADDRESS_HERE
Example Response
{
  "status": 200,
  "message": "OK",
  "payout_user_hash": "SOME_HASH"
}

Use this method to send coins to an address, the main method of our API.

Request URL(s)
  • https://api.microwallet.co/v1/send
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
  • to The coin address, username or email you are sending to, which must be valid and belonging to an existing account. An error will be returned if it's not valid. As of 18th July 2019 username and email address are supported.
  • amount The amount to send in satoshi (e.g. 100, 500)
  • currency A valid currency acronym, defaults to BTC
  • referral Set this value to true, 1, or simply leave it blank. Use it to indicate that this payout is a referral earning
  • ip_address Include the user's IP address to help contribute to the fight against bots and malicious users. Only send this IP if you are certain that it belongs to the user
Return Values
  • currency The valid currency you made the request for
  • balance Your non-decimal balance after the payout, which is your coin balance multiplied by 10^8 (100000000)
  • balance_bitcoin Regular balance in coin value
  • rate_limit_remaining If you enabled Rate Limiting on this faucet, you will get this value which indicates how much can still be paid out with the set rate limits
  • payout_id A unique value representing the payout ID of this sending transaction, useful for keeping track internally
  • payout_user_hash A unique hash corresponding to the individual user on FaucetHub. Store this value and use it to check how much was paid to each user to prevent fraud on your faucet.
Request Example
https://api.microwallet.co/v1/send?api_key=YOUR_API_KEY_HERE&currency=BTC&amount=500&to=CURRENCY_ADDRESS_HERE
Example Response
{
  "status": 200,
  "message": "OK",
  "rate_limit_remaining": 0.00004514,
  "currency": "BTC",
  "balance": 290000,
  "balance_bitcoin": 0.002900,
  "payout_id": 1234,
  "payout_user_hash": "SOME_HASH"
}

Use this method to get the last few payouts you did, up to 10.

Request URL(s)
  • https://api.microwallet.co/v1/payouts
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
  • currency A valid currency acronym, defaults to BTC
  • count A value between 1 and 10, defaults to 1
Return Values

This method will return status as 200 for a valid address, and 456 for an address that does not belong to an account.

  • rewards An array of payout data
Request Example
https://api.microwallet.co/v1/payouts?api_key=YOUR_API_KEY_HERE&count=2
Example Response
{
  "status": 200,
  "message": "OK",
  "rewards": [
    {
      "to": "CURRENCY_ADDRESS_HERE",
      "amount": 1,
      "date": "17-11-16 10:38:48 GMT"
    },
    {
      "to": "CURRENCY_ADDRESS_HERE",
      "amount": 1,
      "date": "17-11-16 10:38:33 GMT"
    }
  ]
}

List of all the faucets listed on our platform, grouped by currencies

Note: Data is updated every 10 minutes

Request URL(s)
  • https://api.microwallet.co/listv1/faucetlist
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
Return Values
  • list_data A JSON object containing list of the faucets. The data is listed under normal for each currencies.
Request Example
https://api.microwallet.co/listv1/faucetlist?api_key=YOUR_API_KEY_HERE
Example Response
{
    "status": 200,
    "message": "OK",
    "list_data": {
        "normal": {
            "BTC": [
                {
                    "name": "Faucet Name",
                    "url": "https://url.example.com",
                    "owner_id": 199,
                    "owner_name": "Faucet Owner",
                    "currency": "BTC",
                    "timer_in_minutes": "60",
                    "reward": "0",
                    "is_enabled": 1,
                    "creation_date": "unix timestamp",
                    "category": null,
                    "paid_today": "0.0220690",
                    "total_users_paid": 32,
                    "active_users": 32,
                    "balance": "0.1094420",
                    "health": 100
                }
            ],
            "ETH": [],
            "DOGE": [
              {
                    "name": "Faucet Name",
                    "url": "https://url.example.com",
                    "owner_id": 200,
                    "owner_name": "Faucet Owner",
                    "currency": "BTC",
                    "timer_in_minutes": "60",
                    "reward": "0",
                    "is_enabled": 1,
                    "creation_date": "unix timestamp",
                    "category": null,
                    "paid_today": "0.0220690",
                    "total_users_paid": 32,
                    "active_users": 32,
                    "balance": "0.1094420",
                    "health": 100
                }
            ],
            "LTC": [],
            "BCH": []
        }
    }
}

Need Help?

Live chat on Telegram