A minimal faucet API for Ethereum and ERC20 tokens.
You have developed a nice dApp. And you want people to try it. But people don't want to bother getting test ether. You know there exists http://faucet.ropsten.be:3001, but it's public and supports only Ropsten. Also, you know you could deploy your own https://github.com/sponnet/locals-faucetserver, but it requires you to set up a Firebase account, and you're too lazy (aren't we all <3).
So you deploy this super micro nano faucet in no time, add some test ether and / or your ERC20 tokens to it, and start rolling! Now, your users can start testing your dApp seamlessly.
So, the intended use case is providing some test ether and / or your ERC20 token to your dApp users automatically. It's not intended for wide audience use. Ideally, your Front End would generate a new wallet for the user, then make an HTTP request to your faucet and get a small amount (0.01 ETH or whatevs) so the user can call methods on your smart contract and pay for gas.
Also, ideally, you'd create another layer on top of this faucet that provides authentication, rate limiting or other niceties. Imagine having a publicly available "faucet gateway" that makes sure that the faucet drips only once every minute, and this faucet service behind it, being only accessible by the gateway.
- Self hosted Ethereum + ERC20 faucet
- Supports whichever Ethereum test network, over Http or Web Sockets
- You don't need a local GETH node, Infura is fine
- Supports any ERC20 token
- No fuss deployment - you only need NodeJS
- Super simple configuration
- Exposed as an API, no Front End
- No queuing - sends ether right away
- Doesn't allow abuse - it only allows you to get one dose until it runs out
- Clone the repo
- Edit the configuration
- Send some ether to the wallet specified in config
- If you turn on the ERC20 module, send some of your tokens to the wallet specified in config
npm start
(starts the server locally)
- The easiest way is to use an automated NodeJS deployment solution like Now or Heroku
- If you're deploying to a VPS, you'll need to configure your server to pass requests to the Node app (reverse proxy)
Now.sh is a service allowing you to host a few of your node apps for free. It's really cool because it gives you a unique url as a subdomain on now.sh
, and you have automatic SSL through them, which is really helpful when developing small apps and just wanting to show them off quickly.
You can deploy this repo to Now by running:
now -p --dotenv
The -p
flag tell Now to deploy your app as public - this is the limit for free accounts.
The --dotenv
option is really important because it tells Now to start your node app with your .env
config.
To tell the faucet how to work, do this:
cp .env.example .env
vim .env
Then just change the parameters in the .env
file.
Paste your private key here. This wallet will be used to drip ETH.
Important you must remove the 0x
from the start of the key.
Defines how much Ether you'll give per request.
Url of the Ethereum node you'll be connecting to. Here are some examples:
https://ropsten.infura.io
- Infura Ropsten over HTTPwss://ropsten.infura.io
- Infura Ropsten over WebSockethttps://rinkeby.infura.io
- Infura Rinkeby over HTTPhttps://kovan.infura.io
- Infura Kovan over HTTPhttp://178.33.23.12
- Your GETH node running on a VPS over HTTPws://178.33.23.12
- Your GETH node running on a VPS over WebSocket
If set, prints a few debug messages to the console whenever someone requests some ETH.
If set, your faucet will drip ETH. If not, no API routes for ETH will be created.
If set, your faucet will drip your configured ERC20 token. If not, no API routes for your token will be created.
Address of your ERC20 token smart contract. Make sure that it's on the same testnet used by ETH_NODE_URL
.
Paste your private key here. This wallet will be used to drip your ERC20 token. Remember to send some ether to it too, it will be needed to transaction fees!
Important you must remove the 0x
from the start of the key.
JSON ABI of your ERC20 contract. You'll see that we included the default ERC20 ABI, so you most likely don't need to edit this. If you are using a different token standard like ERC777, than add your token's ABI here.
Enter the name of your token here, e.g. 'REW'
.
Defines how much of your ERC20 token you'll give per request.
The faucet exposes an API allowing CORS.
Returns:
balance
- Remaining balance in the faucet ETH walletaddress
- Public address of the faucet ETH walletcurrency
- Currency that we're referring to. In this case it's always ETH.
Allows you to request Ether to be sent to the address
.
The request will be open until the transaction is mined, so don't be alarmed if it takes 30 sec - 1 min to finish. When calling it from front end, make sure to either do it in background and notify the user once it's complete, or to display some cat gifs while loading.
Parameters:
address
- Address that will receive Ether
Returns:
transactionHash
- You can use it to find the transaction on EtherscanremainingBalance
- Faucet's remaining balance in ETHamount
- Amount sent to the address
Possible errors:
- Throws an error if there is not enough ether in the faucet to complete the request
- Throws an error if you try to get ether for an address multiple times, while the first request wasn't yet mined
Returns:
balance
- Remaining balance in the faucet ETH walletaddress
- Public address of the faucet ETH walletcurrency
- Currency that we're referring to. Taken fromERC20_NAME
config parameter.
Allows you to request your ERC20 token to be sent to the address
.
The request will be open until the transaction is mined, so don't be alarmed if it takes 30 sec - 1 min to finish. When calling it from front end, make sure to either do it in background and notify the user once it's complete, or to display some cat gifs while loading.
Parameters:
address
- Address that will receive Ether
Returns:
remainingBalance
- Faucet's remaining balance in ERC20amount
- Amount sent to the address
Possible errors:
- Throws an error if there is not enough ERC20 tokens in the faucet to complete the request
- Throws an error if you try to get tokens for an address multiple times, while the first request wasn't yet mined
The faucet generates and signs raw transactions, then sending them to the blockchain. This means the you don't have to have your own GETH node with accounts unlocked, which is nice.
MIT