Skip to content

API Documentation Integrate your faucet/website with our API

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

The following information is intended for Developers

Migration Move an existing faucet/website to our service

Our API is designed to be compatible with faucets coming from FaucetBOX.com. For owners who already have a faucet setup for use with another microwallet provider we offer an easy migration guide to get you moved over to our platform as fast as possible.

Migrate Now Download PHP Library

API Methods 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.


Check your balance

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

Request URL(s)
  • https://faucethub.io/api/v1/balance
  • https://faucethub.io/api/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://faucethub.io/api/v1/balance?api_key=YOUR_API_KEY_HERE&currency=DOGE
Example Response
{
  "status": 200,
  "message": "OK",
  "currency": "DOGE",
  "balance": 1000000000000,
  "balance_bitcoin": 10000
}
                

List of supported currencies

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

Request URL(s)
  • https://faucethub.io/api/v1/currencies
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
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)
Request Example
https://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 belongs to an account

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://faucethub.io/api/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.

Request Example
https://faucethub.io/api/v1/checkaddress?api_key=YOUR_API_KEY_HERE&address=CURRENCY_ADDRESS_HERE
Example Response
{
  "status": 200,
  "message": "OK"
}
                

Send to address

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

Request URL(s)
  • https://faucethub.io/api/v1/send
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
  • to The coin address you are sending to, which must be valid. An error will be returned if it's not valid. Emails/usernames are not supported at this time, but may be supported in the future.
  • 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://faucethub.io/api/v1/send?api_key=YOUR_API_KEY_HERE&amount=500&to=CURRENCY_ADDRESS_HERE¤cy=BTC
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, up to 10.

Request URL(s)
  • https://faucethub.io/api/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
  • rewards An array of payout data
Request Example
https://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"
    }
  ]
}
                

Top Faucets List

Premium

This Premium-only method is used to get the raw data of the Top Faucets List used for our list. When using this API we encourage you to store the data returned via a scheduled task/cron job rather than continully calling the method. The data is updated every 15 minutes.

Request URL(s)
  • https://faucethub.io/api/listv1/faucetlist
Parameters
  • api_key Your API key from your faucet in the Manager's Faucet List page
Return Values
  • list_data A large JSON object of faucets and their data split into premium, normal and inactive. Each one is then split by currency.
Request Example
https://faucethub.io/api/listv1/faucetlist?api_key=YOUR_API_KEY_HERE
Example Response
{
  "status": 200,
  "message": "OK",
 "list_data": {
    "premium": {
      "BTC": [
        {
          "name": "KickassTraffic",
          "url": "https://www.kickasstraffic.com",
          "owner_id": "123",
          "owner_name": "kickasstraffic",
          "currency": "BTC",
          "timer_in_minutes": "1440",
          "reward": "3000",
          "is_enabled": "1",
          "creation_date": "1480028524",
          "category": "1,4",
          "paid_today": 0.00226897,
          "paid_week": 0.00688604,
          "paid_total": 0.13068441,
          "active_users": 109,
          "estimated_2_week_payout": 0.01032906,
          "balance": 0.01855018,
          "health": 100
		},
		*/ etc. */
	]}
}
                

Error Code List Troubleshoot your API implementation

Having a problem with integrating our 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 faucet 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 account balance from the Faucet Manager wallet or FREE Top-up section.


Invalid API Method

{"status":404,"message":"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":"Invalid API key."}

The API you provided for the request does not match up to any faucet in our system, and is therefore invalid. Please get your API key from your faucet/website in the Faucet List page in Faucet Manager.


Invalid Currency

{"status":410,"message":"Not a valid currency."}

The currency you provided in the request is not on our list of supported currencies. At this time our supported currency acronyms are ["BTC","LTC","DOGE","BLK","DASH","PPC","XPM"]


Invalid Coin Address

{"status":412,"message":"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":"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.


Too many requests

{"status":441,"message":"Too many requests, please try again later."}

If you send too many API requests in a given time frame your API key will be blocked from making further requests for a short time.

The following limits are in place for all users:

  • 120 requests per 1 mins
  • 1000 requests per 10 mins
  • 4000 requests per 1 hours

If you are exceeding these limits more often, then please contact support and we can arrange for a small increase.


Send limit reached

{"status":450,"message":"The send limit set by the faucet owner has been reached, please try again later."}

You will get this message if you are trying to send a payout which will exceed the Rate Limits set in your faucet/website's settings. If you did not enable the Rate Limit, you should not get this message at any point.


API Disabled

{"status":452,"message":"API access disabled by faucet owner."}

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":"Unsupported request method."}

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


Access Denied

{"status":401,"message":"Access denied."}

If you have enabled the Access Control List on your account, 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.


Coin address no user

{"status":456,"message":"Coin address does not belong to an account on FaucetHub.io, please make an account and link your address and try again."}

If a user attempts to claim or get a payout at an address which is not tied to a user, they will get this message. It's important to show users this message so they know how to proceed next and that they need to make an account here on FaucetHub.io and link their currency address before they can claim on your faucet/website.


Maintenance

{"status":501,"message":"Maintenance mode, please try again later."}

This errors means that our system is currently in maintenance mode. 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."}

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.