Skip to content

A faucet for cosmos-sdk apps that uses the app binary only

Notifications You must be signed in to change notification settings

tendermint/faucet

Repository files navigation

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"}]}