friendbot

Friendbot Service for the Stellar Test Network

Stellar's native asset faucet.

Friendbot helps users of the Stellar testnet by exposing a REST endpoint that creates & funds new accounts and contract addresses.

[!WARNING]

Merges of pull requests to the main branch deploy to testnet immediately.

[!TIP]

Friendbot for Testnet is hosted at https://friendbot.stellar.org.
Friendbot for Futurenet is hosted at https://friendbot-futurenet.stellar.org.
Friendbot in Quickstart is available at http://localhost:8000/friendbot.

API Usage

Friendbot exposes a simple REST API with a single endpoint that accepts both GET and POST requests.

Endpoint

GET|POST /

Parameters

Examples

Using cURL

GET request:

curl http://localhost:8004/?addr=GDJIN6W6PLTPKLLM57UW65ZH4BITUXUMYQHIMAZFYXF45PZVAWDBI77Z

POST request:

curl -X POST "http://localhost:8004/" \
  -d "addr=GDJIN6W6PLTPKLLM57UW65ZH4BITUXUMYQHIMAZFYXF45PZVAWDBI77Z"

Funding a contract address (requires fund_contract_addresses and rpc_url configured):

curl http://localhost:8004/?addr=CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC

Using JavaScript

// GET request
const response = await fetch('http://localhost:8004/?addr=GDJIN6W6PLTPKLLM57UW65ZH4BITUXUMYQHIMAZFYXF45PZVAWDBI77Z');
const transaction = await response.json();

// POST request
const response = await fetch('http://localhost:8004/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'addr=GDJIN6W6PLTPKLLM57UW65ZH4BITUXUMYQHIMAZFYXF45PZVAWDBI77Z'
});
const transaction = await response.json();

Response

On success, the API returns a 200 OK.

Note the contents of the response may change depending on the underlying systems in use to submit and process the transaction and should generally not be relied upon.

Error Responses

The API returns appropriate HTTP status codes and error details:

• 400 Bad Request: Invalid account address or account already funded
• 404 Not Found: Account does not exist (for certain operations)
• 500 Internal Server Error: Server-side error

Running Friendbot

Docker

Run Friendbot using the pre-built Docker image:

docker run \
  --platform linux/amd64 \
  -v $PWD/friendbot.cfg:/friendbot.cfg \
  -p 8004:8004 \
  stellar/friendbot:<FULL-GIT-SHA>

See below for how to configure the friendbot.cfg file that needs to be mounted.

The service will be available at http://localhost:8004.

🔗 View on Docker Hub

Source

1. Build:

   go build -o friendbot .
   

2. Configure a friendbot.cfg file.

3. Run:

   ./friendbot --conf=friendbot.cfg
   

Command Line Options

Configuration

The service uses TOML configuration files. Configuration can be provided in a single file, or split into separate config and secret files.

Single File Configuration

All settings including secrets can be in one file:

./friendbot --conf=friendbot.cfg

Separate Config and Secret Files

For environments where you want to store secrets separately:

./friendbot --conf=config.cfg --secret=secrets.cfg

The --secret file can contain secrets:

# secrets.cfg
friendbot_secret = "S..."

The --conf file contains everything else:

# config.cfg
port = 8004
network_passphrase = "Test SDF Network ; September 2015"
horizon_url = "https://horizon-testnet.stellar.org"
starting_balance = "10000.00"

[!NOTE] For backwards compatibility, friendbot_secret can still be included in the --conf file. If both files contain friendbot_secret, the value from --secret takes precedence.

Configuration Settings

[!NOTE] You must configure either horizon_url or rpc_url, but not both. Friendbot can interact with the Stellar network through either Horizon (the traditional REST API) or RPC (the newer JSON-RPC API).

[!NOTE] The fund_contract_addresses option requires rpc_url to be configured. Contract address funding is not supported when using horizon_url.

Secret Settings

Settings available in the --secret file:

Development

See CONTRIBUTING.md.

Checking Build

go build ./...

Running Tests

go test ./...