API Docs FHMW v1

API Documentation

On this page you will find all the necessary information and explanations of the API to easily integrate with a new or existing faucet or website compatible with FaucetHub’s v1 API.

Migration

Move an existing FaucetHub compatible faucet/website to our service

The API is designed to be compatible with faucets coming from FaucetBOX.com and FaucetHub.io. You will find the PHP library in the project root called microwallet.php providing the Microwallet() class, and compatible classes FaucetHub() and FaucetBox(). Please note that to use your own Microwallet script you must call setBaseURL() to correctly set your Microwallet script’s URL to https://microwallet.faucethub.io/api/v1/.

API Methods

All methods and usage explained

Using the API is easy, as every request you make is a HTTP POST request with a set of parameters such as one of your API keys 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.

Check your wallet’s balance

Use this method to get your configured wallt’s balance in any supported currency.

Request URL(s)

• https://microwallet.faucethub.io/api/v1/balance
• https://microwallet.faucethub.io/api/v1/getbalance

Parameters

• api_key Your API key
• currency A valid currency acronym

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

https://microwallet.faucethub.io/api/v1/balance?api_key=YOUR_API_KEY_HERE¤cy=DOGE

Example Response

{
"status": 200,
"message": "OK",
"currency": "DOGE",
"balance": 1000000000000,
"balance_bitcoin": 10000
}
        

List of supported wallets

Use this method to get a list of all the currencies you have configured and their status.

Request URL(s)

• https://microwallet.faucethub.io/api/v1/currencies

Parameters

• api_key Your API key

Return Values

• currencies An array of currency acronyms (e.g. BTC)
• currencies_names A full array including the acronym, name and wallet/payout status (enabled true or false)

https://microwallet.faucethub.io/api/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
}
]
}
        

Check address is valid

Before sending a payout check if the given crypto-currency address is valid for paying.

Request URL(s)

• https://microwallet.faucethub.io/api/v1/checkaddress

Parameters

• api_key Your API key
• address The coin address you checking.
• currency Currency of the address.

Return Values

This method will return status as 200 for a valid address.

• payout_user_hash A unique hash corresponding to the individual address-currency combination.

https://microwallet.faucethub.io/api/v1/checkaddress?api_key=YOUR_API_KEY_HERE&address=CURRENCY_ADDRESS_HERE

Example Response

{
"status": 200,
"message": "OK",
"payout_user_hash": "SOME_HASH"
}
        

Send to address

Use this method to send coins to an address, the main method of the API. This creates a pending payout ready to be processed on the next withdraw cycle.

Request URL(s)

• https://microwallet.faucethub.io/api/v1/send

Parameters

• api_key Your API key
• to The coin address
• amount The amount to send in satoshi (e.g. 100, 500)
• currency A valid currency acronym
• referral Set this value to true, 1, or simply leave it blank. Use it to indicate that this payout is a referral earning

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.

https://microwallet.faucethub.io/api/v1/send?api_key=YOUR_API_KEY_HERE¤cy=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"
}
        

Recent payouts/rewards

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

Request URL(s)

• https://microwallet.faucethub.io/api/v1/payouts

Parameters

• api_key Your API key
• currency A valid currency acronym
• count A value no lower than 1

Return Values

• rewards An array of payout data

https://microwallet.faucethub.io/api/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"
}
]
}
        

Error Code List

Troubleshoot your API implementation

Having a problem with integrating the API? Received an error code and need to know what it means? Check the list below for all errors and what they mean with help and suggestions.

Insufficient Funds

{"status":402,"message":"This site has insufficient funds to send the payout."}

The return message should be self-explanatory. Your balance is not high enough to make the payout which was requested. You will need to top-up your wallet’s balance.

Invalid API Method

{"status":404,"message":"API Error: Invalid API method."}

The API method you sent was not valid. Please check the API Methods section above this one for a list of valid methods and their usage.

Invalid API Key

{"status":403,"message":"API Error: Invalid API key."}

The API you provided for the request does not match up to any in your system, and is therefore invalid.

Invalid Currency

{"status":410,"message":"API Error: Provided currency is not valid."}

The currency you provided in the request is not on your list of configured currencies.

Invalid Coin Address

{"status":412,"message":"API Error: Coin address invalid."}

You will see this error only when sending a payout, if the provided address does not appear to be a valid one. This is up to your users to use a proper coin address for the currency in question.

Missing Parameters

{"status":414,"message":"API Error: Parameters missing.","missing_params":["api_key","currency"]}

You are missing one or more required parameters for the method you are using. Check the API Methods section above to make sure you are sending all the required parameters. We provide an array of missing param keys in the missing_params attribute in the response.

API Disabled

{"status":452,"message":"API access disabled by site owner.","missing_params":["api_key","currency"]}

If you set the API status for your faucet to disabled (status from ON to OFF) you will get this message for every request which is made. Switch it back on to resolve the error.

Unsupported Method

{"status":411,"message":"API Error: Unsupported request method.","missing_params":["api_key","currency"]}

If you try to send anything other than a HTTP POST request you will get this error.

Access Denied

{"status":401,"message":"API Error: Access denied.","missing_params":["api_key","currency"]}

If you have enabled the Access Control List on your API Key, all unauthorised IP addresses will receive this error when they attempt to make a request. If you get this error unexpectedly, double check the IP address of your server is correctly authorised in your ACL.

Maintenance

{"status":501,"message":"Maintenance mode, please try again later: This site is under maintenance.","missing_params":["api_key","currency"]}

This errors means that maintenance mode has been enabled. While in maintenance mode you will not be able to make any API requests.

Application error

{"status":999,"message":"Application error, please try again later.","missing_params":["api_key","currency"]}

This message means that something on our end caused the request to fail. If you keep getting this error, please contact support for further assistance.