API Documentation

Introduction


At this page, you'll find technical details and guidelines to integrate our REST API within your application or faucet.

If you are a webmaster or a non-developer, then this page is probably not meant for you. Instead, you can click here and download our free faucet script to launch your own faucet with our API in no time.

Appropriate Usage of API


In order to keep the service running from everyone seamlessly, we request you to NOT to hammer our servers with spammy, unintended API calls. We've written a bit about avoiding these excessive unintended API usage from your account.

For example, when you're calling the send function, we automatically return your balance after sending the transaction, so obviously, it would not make sense to send another request for getbalance method. Please avoid sending requests for the information you already have.

Also, we recommend that you cache the data such as balance, user hash and other information. It would be wise to reload this information every 5 minutes or so using cron jobs or daemons. Do not call our API for every public page.

API Methods

Using our API is very easy and straightforward. All you need is to send a HTTP POST request to our end-points with the required parameters such as api_key and currency and the response is returned in JSON. Each request contains a status and message which tells about the status of your request - 200 for a successful request.

Get balance of the faucet (getbalance, balance):


Request URL(s)
  • https://faucetpay.io/api/v1/balance
  • https://faucetpay.io/api/v1/getbalance
Parameters
  • api_key A valid API Key from the website
  • currency Defaults to "BTC", can be explicitly set
Return Values
  • currency The currency you set while making the request
  • balance Your balance in satoshis (108)
  • balance_bitcoin Your balance is regular way
Request Response 

{
    "status": 200,
    "message": "OK",
    "currency": "BTC",
    "balance": "100000000",
    "balance_bitcoin": "1"
}


Get list of currencies supported (currencies):


Request URL
  • https://faucetpay.io/api/v1/currencies
Parameters
  • api_key A valid API Key from the website
Return Values
  • currencies A JSON array with abbreviation of currencies
  • currencies_names A JSON array with names and abbreviations.
Request Response 

{
    "status": 200,
    "message": "OK",
    "currencies": [
        "BTC",
        "ETH"
    ],
    "currencies_names": [
        {
            "name": "Bitcoin",
            "acronym": "BTC"
        },
        {
            "name": "Ethereum",
            "acronym": "ETH"
        }
    ]
}


Check address if it belongs to someone (checkaddress):


Request URL
  • https://faucetpay.io/api/v1/checkaddress
Parameters
  • api_key A valid API Key from the website
  • address Address you'd like to check
  • currency Defaults to "BTC", can be explicitly set
Return Values
  • payout_user_hash Contains the hash of user to whom the address belongs. Use it to identify the user.
Request Response 

{
    "status": 200,
    "message": "OK",
    "payout_user_hash": "b8446e7a814d677f5e381f2e05206bf0cee6d063"
}
{
    "status": 456,
    "message": "The address does not belong to any user."
}


Send payment (send):


Request URL
  • https://faucetpay.io/api/v1/send
Parameters
  • api_key A valid API Key from the website
  • amount Amount that you want to send in satoshis (10^8). For example: 50
  • to The address or email which you wanna pay amount to
  • currency Defaults to "BTC", can be explicitly set
  • referral Indicate if this is a normal or referral payment. Set to true for a referral payment.
  • ip_address Provide an IP address if you would like to use our anti-fraud system.
Return Values
  • rate_limit_remaining You will get this value which indicates how much can still be paid out with the set rate limit. Ignore if you haven't set any rate limit.
  • currency The currency in which you paid up.
  • balance The balance remaining after you paid up (in satoshis).
  • balance_bitcoin The balance remaining after you paid up (in coin value).
  • payout_id A unique identifier for this transaction.
  • payout_user_hash Contains the hash of user to whom the address belongs. Use it to identify the user.
Request Response 

{
    "status": 200,
    "message": "OK",
    "rate_limit_remaining": 9.99780024,
    "currency": "BTC",
    "balance": "8673047351",
    "balance_bitcoin": "86.73047351",
    "payout_id": 109,
    "payout_user_hash": "c448e31098a8dfb48248f7e2374e77674bb90925"
}


Recent payouts (payouts):


Request URL
  • https://faucetpay.io/api/v1/payouts
Parameters
  • api_key A valid API Key from the website
  • currency Defaults to "BTC", can be explicitly set
  • count Number of transactions you want to fetch, a value between 0 and 100.
Return Values
  • rewards This is an array of payouts.
Request Response 

{
    "status": 200,
    "message": "OK",
    "rewards": [
        {
            "to": "ADDRESS",
            "amount": 10451,
            "date": "14-06-18 03:11:59 GMT"
        },
        {
            "to": "ADDRESS",
            "amount": 151,
            "date": "10-06-18 03:11:59 GMT"
        }
    ]
}


Faucet List:


Request URL
  • https://faucetpay.io/api/listv1/faucetlist
Parameters
  • api_key A valid API Key from the website
Return Values
  • list_data A JSON object containing list of the faucets. The data is listed under normal for each currencies.
Request Response 

{
    "status": 200,
    "message": "OK",
    "list_data": {
        "normal": {
            "BTC": [
                {
                    "id": 1,
                    "name": "Rushbitcoin.com",
                    "url": "https:\/\/rushbitcoin.com",
                    "owner_id": "734",
                    "owner_name": "anteruzic1",
                    "currency": "BTC",
                    "timer_in_minutes": "60",
                    "reward": "0",
                    "is_enabled": "0",
                    "creation_date": "0",
                    "category": null,
                    "paid_today": "0.000000",
                    "total_users_paid": "0",
                    "active_users": "0",
                    "balance": "0.00000000",
                    "health": "0"
                }
            ],
            "ETH": [
                {
                    "id": 2,
                    "name": "MBZ Community",
                    "url": "https:\/\/xcoin.mybook.biz",
                    "owner_id": "1036",
                    "owner_name": "Misael29",
                    "currency": "ETH",
                    "timer_in_minutes": "60",
                    "reward": "84",
                    "is_enabled": "1",
                    "creation_date": "0",
                    "category": null,
                    "paid_today": "0.062315",
                    "total_users_paid": "104",
                    "active_users": "103",
                    "balance": "0.02714408",
                    "health": "100"
                }
            ]
        }
    }
}

Error Codes


Code Message
200 Success.
401 Access denied, you are not using a whitelisted API.
402 You don't have sufficient funds for this transaction.
403 Invalid API Key used. Please login to your account and use a valid API Key.
404 Invalid API method accessed.
405 You are sending an invalid amount of payment to the user.
410 Invalid currency provided.
450 The send limit set by the faucet owner has been reached, please try again later.
456 The address does not belong to any user.
457 The user has been blacklisted (by you) from the faucet API system. Related with Report and Blacklist tool.