Skip to content
🚰 The Ocean Faucet Server allows requesting Ether for a particular Ocean network.
JavaScript Shell Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
scripts more cleanup, less verbose dev server Apr 11, 2019
src keep doc.insert logic intact Jul 19, 2019
.babelrc report coverage as part of test Apr 11, 2019
.editorconfig setup linting tools Feb 13, 2019
.eslintrc move sll the things, kick out views Apr 10, 2019
.prettierignore move tests Apr 11, 2019
.prettierrc move sll the things, kick out views Apr 10, 2019
Dockerfile more cleanup, less verbose dev server Apr 11, 2019
LICENSE Initial commit Nov 26, 2018 allow disabling of time span check Jul 18, 2019
docker-compose.yml more cleanup, less verbose dev server Apr 11, 2019
package-lock.json Release 0.2.6 Jul 19, 2019


Faucet Server

🚰 The Ocean Faucet Server allows users to request Ether for a particular Ethereum network. A UI for it is deployed under

Build Status Docker Cloud Build Status code style: prettier js oceanprotocol

Table of Contents


Get Started

Before starting to develop, you need to run a local Ocean network using Barge:

git clone
cd barge
./ --latest --no-secret-store --no-aquarius --no-brizo --no-pleuston --local-spree-node --force-pull

Then, start the Faucet server in a live-reloading watch mode:

docker-compose up -d mongo
npm install
npm start


POST /faucet

To request Ether, a user can send an HTTP POST request to http://localhost:3001/faucet with an HTTP request body like:

    "address": "<string>", //required
    "agent": "<string>",   //optional, Possible values - server, twitter, telegram, gitter

An example HTTP POST request using wget:

wget --header="Content-Type: application/json" \
--post-data '{"address": "0x7E187af69973a66e049a15E763c97CB726765f87", "agent": "twitter"}' \

Sample Response Body:

  "success": true,
  "message": "Successfully added 3 ETH to your account.",
  "txHash": "0xb86e762b870055deee924aeb33c08c162abdb6a71faa8531dbba84e985402b64"

An error response looks like this:

  "success": false,
  "message": "Crypto is hard."


Shows information about the software version, which will be returned as HTML by default to be more human-friendly when accessed from a browser.

To get a json response instead, set the Accept header to application/json:

wget --header="Accept: application/json" \

Sample Response Body:

{ "software": "faucet", "version": "0.2.2" }

UI Example

For an example on how to implement a UI, have a look at the React component in commons:


You can configure the server in the file src/config.js or by exporting values into your environment.

The amount of Ether is determined by the values of the configuration settings server.faucetEth.

To connect remotely to Ocean's Nile network instead of a local running network, modify the server.faucetNode setting like so:

server: {
  faucetNode: ''

The timespan check can be disabled by setting faucetTimeSpan to 0:

server: {
  faucetTimeSpan: 0

For the Twitter server to work, you need to configure all the values under twitter in src/config.js.


Before running the tests, configure your test environment variables if needed and make sure MongoDB service is running:

cp tests/.env.test.example tests/.env.test
docker-compose up -d mongo

Then start the unit tests:

npm test

To get a test coverage report:

npm run coverage

Production build

To create a production build of the Faucet server, execute:

npm run build

This will create the build output into ./dist. You can then run and serve from this build output with:

npm run serve


You can deploy the Faucet server using docker-compose. The Docker image will do a production build of the server and run it:

docker-compose up


Running any release task does the following:

  • bumps the project version
  • creates a Git tag
  • updates file with commit messages
  • commits and pushes everything
  • creates a GitHub release with commit messages as description

You can execute the script using {major|minor|patch} as first argument to bump the version accordingly:

  • To bump a patch version: npm run release
  • To bump a minor version: npm run release minor
  • To bump a major version: npm run release major

By creating the Git tag with these tasks, Travis will trigger a new Kubernetes deployment automatically aftr a successful tag build.

For the GitHub releases steps a GitHub personal access token, exported as GITHUB_TOKEN is required. Setup


See the page titled "Ways to Contribute" in the Ocean Protocol documentation.


Copyright 2018 Ocean Protocol Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
You can’t perform that action at this time.