faucet

A faucet that uses cosmos-sdk executable binaries only.

The main purpose of this faucet is to avoid using RPC or API endpoints, and use the CLI binary instead, more specifically, the commands:

$ {app}d tx bank send

and:

$ {app}d query txs

Since the faucet only uses the CLI binary, it is compatible with practically any blockchain built with cosmos-sdk even if different types of keys are used (such as in ethermint for example).

Installation

Using cURL

$ curl https://get.starport.network/faucet! | bash

Use docker image

Use docker image ghcr.io/tendermint/faucet. You can use it in a Kubernetes pod with shareProcessNamespace or mount the chain binary using docker:

$ docker run -it -v ~/go/bin/gaiad:/usr/local/bin/gaiad ghcr.io/tendermint/faucet

From Source

You can build the faucet with:

$ make build

The executable binary will be avaialable in the ./build/ directory. To install it to $GOPATH/bin, use instead:

$ make install

Usage

Configuration

You can configure the faucet either using command line flags or environment variables. The following table shows the available configuration options and respective defaults:

flag	env	description	default
port	PORT	tcp port where faucet will be listening for requests	8000
account-name	ACCOUNT_NAME	name of the account to be used by the faucet	faucet
mnemonic	MNEMONIC	mnemonic for restoring an account
keyring-password	KEYRING_PASSWORD	password for accessing keyring
cli-name	DENOMS	denomination of the coins sent by default (comma separated)	uatom
credit-amount	CREDIT_AMOUNT	amount to credit in each request	10000000
max-credit	MAX_CREDIT	maximum credit per account	100000000
sdk-version	SDK_VERSION	version of sdk (launchpad or stargate)	stargate
node	NODE	address of tendermint RPC endpoint for this chain
keyring-backend	KEYRING_BACKEND	keyring backend to be used
legacy-send	LEGACY_SEND	whether to use legacy send command	false
coin-type	COIN_TYPE	registered coin type number for HD derivation (BIP-0044)	118
home	HOME	replaces the default home used by the chain

gaia example

This faucet options default to work with gaia. So you can start the faucet with just:

$ faucet --keyring-password 12345678
INFO[0000] listening on :8000

or, with environment variables:

$ export KEYRING_PASSWORD=12345678
$ faucet
INFO[0000] listening on :8000

ethermint example

Start the faucet with:

$ faucet --cli-name ethermintcli --denoms ueth --keyring-password 12345678 --sdk-version launchpad
INFO[0000] listening on :8000

or, with environment variables:

$ export CLI_NAME=ethermintcli
$ export SDK_VERSION=launchpad
$ export DENOMS=ueth
$ export KEYRING_PASSWORD=12345678
$ faucet
INFO[0000] listening on :8000

wasmd example

Start the faucet with:

$ faucet --cli-name wasmcli --denoms ucosm --keyring-password 12345678
INFO[0000] listening on :8000

or, with environment variables:

$ export CLI_NAME=wasmcli
$ export DENOMS=ucosm
$ export KEYRING_PASSWORD=12345678
$ faucet
INFO[0000] listening on :8000

Request tokens

You can request tokens by sending a POST request to the faucet, with a key address in a JSON:

$ curl -X POST -d '{"address": "cosmos1kd63kkhtswlh5vcx5nd26fjmr9av74yd4sf8ve"}' http://localhost:8000
{"transfers":[{"coin":"10000000uatom","status":"ok"}]}

For requesting specific coins, use:

$ curl -X POST -d '{"address": "cosmos1kd63kkhtswlh5vcx5nd26fjmr9av74yd4sf8ve", "coins": ["10uatom", "20ueth"]}' http://localhost:8000
{"transfers":[{"coin":"10uatom","status":"ok"}, {"coin":"20ueth","status":"ok"}]}