faucet.coinbin.org

try now at faucet.coinbin.org

features

• supports signet, maybe works for testnet too
• rich admin interface and many configurations options, many optional
• set withdraw limits
• optionally combine queued payouts into bounded multi-output on-chain transactions
• auto-consolidations jobs
• prometheus metrics

client IP behind a reverse proxy

The faucet reads the client address from the header selected by -client-ip-header (or FAUCET_CLIENT_IP_HEADER). By default it is empty, so the direct TCP peer address is used and all client-IP headers are ignored.

When running behind Cloudflare, select its corresponding field:

-client-ip-header="CF-Connecting-IP"

Most selected headers must contain exactly one valid IPv4 or IPv6 address; missing, malformed, duplicated, and comma-separated values fall back to the direct peer address. When X-Forwarded-For is selected, its first comma-separated address is used, matching the standard client-first proxy chain format.

Only enable a client-IP header when the reverse proxy overwrites it and the origin cannot be reached directly. Otherwise a client can spoof the address used by the payout limits and admin IP allowlist.

payout fee rate

Automatic faucet payouts use 0.11 sat/vB by default. Set a different rate with -payout-fee-rate-sats-per-vb, or with the FAUCET_PAYOUT_FEE_RATE_SATS_PER_VB environment variable. The command-line flag takes precedence over the environment variable. Set the value to 0 to omit fee_rate and let the Bitcoin Core wallet select its default rate.

-payout-fee-rate-sats-per-vb=0.25

To use Augur's 3-block, 95% probability estimate for payouts, admin sends, and consolidation transactions, enable -use-augur-fees. The fee JSON is fetched immediately and every five minutes. Startup waits for the first fetch to succeed and does not start the service if it fails. The last successful rate is cached for later refresh failures. Rates are rounded up to Bitcoin Core's 0.001 sat/vB precision.

-use-augur-fees \
-augur-fees-url=https://fees.signet.coinbin.org/fees.json

The equivalent environment variables are FAUCET_USE_AUGUR_FEES and FAUCET_AUGUR_FEES_URL. Command-line flags take precedence. The faucet_augur_fee_last_success_timestamp_seconds metric reports the Unix timestamp of the last successful fee fetch, or 0 before one succeeds. The faucet_augur_fee_rate_sats_per_vbyte gauge is exposed after the first successful fetch and reports the last successfully loaded rate.

quick run with docker

# website on  :7766
# metrics on  :9844


docker run  \
    -d --name faucet \
    --restart=always \
    -v /data/signet/faucet/data:/data  \
    -p 7766:7766 \
    -p 9844:9844  \
    lnliz/faucet.coinbin.org:latest   \
    -bitcoin-rpc-host <<rpc-host>> \
    -bitcoin-rpc-user <<rpc-user>> \
    -bitcoin-rpc-password <<rpc-pass>> \
    -admin-path=/admin  \
    -admin-2fa-secret="..." \
    -admin-password admin-password \
    -admin-ip=123.123.123.123 \
    -admin-cookie-secret="..."   \
    -turnstile-site-key="0x4AAAAAA..." \
    -turnstile-secret="0x4AAAAAA..." \
    -data-dir /data \
    -batch-payouts=true \
    -batch-interval=10s \
    -payout-fee-rate-sats-per-vb=0.25 \
    -max-batch-size=50 \
    -consolidation-amount-threshold=2.1 \
    -consolidation-min-utxos=10 \
    -consolidation-max-utxos=35 \
    -auto-consolidation-interval=9m \
    -max-withdrawals-per-ip-24h=4 \
    -metrics-addr=0.0.0.0:9844 \
    -listen 0.0.0.0:7766

-batch-payouts is disabled by default. In the default individual mode, each logical payout is its own on-chain transaction and a processing pass handles at most 50 payouts. Enable -batch-payouts=true to combine queued payouts into multi-output transactions. -batch-interval controls both processors; -max-batch-size applies only when batching is enabled, must be between 1 and 50, and defaults to 50.

The SQLite schema is upgraded automatically at startup. Batching adds two batch-ownership columns plus signed_raw_tx, payout_digest, and prepared_digest to transactions, and adds a payout_batches table. No separate SQL migration is required. Existing normal pending, broadcast, and failed rows are preserved. A legacy row left in processing cannot be retried safely because the old schema did not retain its signed transaction, so startup moves it to broadcast_unknown for manual wallet reconciliation. A legacy broadcast_unknown row without signed bytes is never automatically retried and blocks wallet-writing startup until it is manually reconciled. An interrupted claim made by this version is distinguishable by its ownership token and is safely returned to pending only when it has no prepared or broadcast evidence.

An active prepared batch created by an earlier batching build without the full payout-manifest and prepared-transaction integrity binding is also upgraded conservatively: its signed bytes and txid are retained, its children become broadcast_unknown, and the active slot remains blocked for manual reconciliation. The upgraded binary will not infer missing integrity evidence from mutable rows or automatically broadcast that transaction.

This release must not be deployed as a rolling upgrade. Stop every old faucet process before starting the upgraded binary. Never run old and new processors against the same SQLite database or Bitcoin Core wallet: the legacy processor can race a new atomic batch claim and pay the same request separately. Do not roll back to an older processor while an active batch or recoverable individual transaction exists because it cannot recover the stored signed transaction. Extra columns and tables are schema-compatible with old GORM models, but that does not make rollback operationally safe.

After all processes have stopped cleanly, make a backup before upgrading. WAL mode is enabled, so do not copy only a live faucet.db; either stop all database users first or use SQLite's online backup command/API so committed WAL contents are included. Start one upgraded instance and verify migration and any broadcast_unknown reconciliation before serving traffic. Use only one wallet-writing application instance. Payouts, manual sends, and UTXO consolidation are serialized inside a process, and manual sends/consolidation are refused while durable payout recovery is unfinished. These protections do not cover another process or direct Bitcoin Core wallet writes.

Both payout modes store the fully signed transaction, deterministic txid, and an exact logical-payout manifest before the first broadcast attempt. Before it is stored, the final signed transaction is decoded and its ordered destination amounts and OP_RETURN are verified, allowing only the change output reported by Bitcoin Core. Recovery re-validates persisted signed bytes, then rebroadcasts only that exact transaction instead of constructing a replacement. An unresolved recovery is a FIFO wallet barrier: later payouts, manual sends, and consolidation cannot consume its inputs.

Mode changes require a full process restart. Enabling batching is refused while an individual signed transaction needs recovery. Disabling batching is refused while any batch is preparing, ready, or has an unknown broadcast result. Start again in the previous mode to finish automatic recovery first. Malformed or older prepared state that cannot be proven against its payout manifest fails startup and requires manual wallet/database reconciliation.

Manual admin sends and consolidation are not stored in the payout recovery journal. If either reports an ambiguous broadcast outcome, the running process places all local wallet writers on a safety hold. Reconcile the reported txid in Bitcoin Core, then deliberately restart the service; do not restart or retry before reconciliation. The hold is process-local, so it does not protect against another process, a direct Bitcoin Core wallet write, or an unreconciled restart.