🌊 Liquid Testnet Faucet

A comprehensive Liquid Network testnet faucet and explorer with asset issuance capabilities, powered by LWK (Liquid Wallet Kit)

🚀 Features • ⚙️ Installation • 🔧 Configuration • 🏃‍♂️ Usage • 📡 API • 🔗 Links

</div>

✨ Features

🎯 Multi-Asset Faucet (LWK-Powered)

💰 LBTC Faucet - Get Liquid Bitcoin testnet coins via LWK
🧪 Test Asset Faucet - Receive custom test assets using LWK
⚡ AMP Asset Faucet - Access AMP tokens
🛡️ Rate Limiting - Built-in protection against abuse
🔧 LWK Integration - All transactions powered by Liquid Wallet Kit

🔍 Block Explorer

📊 Real-time Stats - Blockchain height, mempool size, disk usage
🧱 Block Explorer - Browse blocks with transaction details
💾 Mempool Viewer - Monitor pending transactions
🔗 Transaction Details - Full transaction information

🏭 Asset Issuance (LWK-Native)

🎨 Custom Assets - Create your own Liquid assets using LWK
🔐 Reissuance Tokens - Control asset supply with LWK
📝 Contract Support - Define asset metadata and properties
🌐 Domain Verification - Link assets to domains
✅ Pre-configured Domain - Use liquidtestnet.com as a valid domain for any test token
⚡ LWK Transaction Builder - Native LWK transaction construction

🛠️ Utilities

📤 Transaction Broadcasting - Submit raw transactions
✅ Mempool Testing - Validate transactions before broadcast
📋 OP_RETURN Support - Store data on-chain

⚙️ Installation

Prerequisites

Python 3.8 or higher
Liquid Elements node (testnet)
LWK (Liquid Wallet Kit) - Core dependency for all Liquid operations

Quick Start

# 1. Clone the repository
git clone https://github.com/your-username/liquidtestnet.com.git
cd liquidtestnet.com

# 2. Create virtual environment
python3 -m venv venv3
source venv3/bin/activate  # On Windows: venv3\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure the application (see Configuration section)
cp liquid.conf.example liquid.conf
# Edit liquid.conf with your settings

# 5. Run the application
python faucet.py

Dependencies

LWK (Liquid Wallet Kit) - ⭐ Core engine for all Liquid operations
Flask - Web framework
Flask-Limiter - Rate limiting
WallyCore - Bitcoin/Liquid cryptographic library
Bitcoin RPC - Elements node communication

🔧 Configuration

Create a liquid.conf file with the following structure:

[GENERAL]
liquid_instance: LIQUID

[LIQUID]
host:
port:
username:
password:
wallet:
passphrase:

[AMP]
url:
username:
password:
token:
assetuuid:

[GDK]
mnemonic:
subaccount:
address:
amp0_user:
amp0_password:
amp0_assetid:

[LWK]
mnemonic:
address:
assetid:

Configuration Sections

| Section | Description | Required | Purpose | |---------|-------------|----------|---------| | GENERAL | Basic application settings | ✅ | Defines which Liquid instance to use | | LIQUID | Elements node RPC configuration | ✅ | Connection to Liquid testnet node | | AMP | Asset Management Protocol settings | ✅ | For AMP token distribution | | GDK | Green Development Kit (AMP0) settings | ✅ | For AMP0 wallet integration | | LWK | Liquid Wallet Kit configuration | ✅ | Core LWK wallet and asset settings |

🔧 Configuration Details

All Sections Are Required

GENERAL Section:

liquid_instance: Must match one of the configured sections (e.g., "LIQUID")

LIQUID Section:

host: Elements node hostname
port: Elements node RPC port (typically 7041 for testnet)
username: RPC username
password: RPC password
wallet: Wallet name (can be empty for default wallet)
passphrase: Wallet passphrase (can be empty if no passphrase)

AMP Section (for AMP token support):

url: AMP server URL
username: AMP server username
password: AMP server password
token: AMP authentication token
assetuuid: AMP asset UUID

GDK Section (for AMP0 integration):

mnemonic: AMP0 mnemonic phrase
subaccount: AMP0 subaccount identifier
address: AMP0 wallet address
amp0_user: AMP0 username
amp0_password: AMP0 password
amp0_assetid: AMP0 asset ID

LWK Section:

mnemonic: 24-word mnemonic phrase for LWK wallet
address: LWK wallet address
assetid: Asset ID for test token distribution

🎯 Simplified Token Issuance

For easy test token creation, you can use liquidtestnet.com as a pre-validated domain:

# Example: Create a test token using liquidtestnet.com domain
curl "http://localhost:8123/api/issuer?command=asset&asset_amount=1000&asset_address=tlq1q...&token_amount=100&token_address=tlq1q...&pubkey=02...&name=MyTestToken&ticker=MTT&precision=8&domain=liquidtestnet.com"

LWK Benefits:

⚡ Native Liquid Support - Built specifically for Liquid Network
🔐 Secure Transaction Building - LWK handles all cryptographic operations
🎯 Simplified API - No need to understand low-level Liquid protocols
✅ Pre-validated Domain - Eliminates domain verification setup for test tokens

This makes development and testing much faster with LWK's streamlined approach!

🏃‍♂️ Usage

Starting the Server

# Activate virtual environment
source venv3/bin/activate

# Start the faucet server
python faucet.py

The server will start on http://0.0.0.0:8123

Web Interface

| Endpoint | Description | |----------|-------------| | / | Home page with blockchain stats | | /faucet | Multi-asset faucet interface | | /explorer | Block explorer | | /mempool | Mempool transaction viewer | | /issuer | Asset issuance interface | | /utils | Transaction utilities | | /about | About page |

📡 API

Faucet Endpoints

Get Faucet Status

GET /api/faucet?address=your_address&action=lbtc

Parameters:

address - Liquid address to receive funds
action - Asset type (lbtc, test, amp)

Response:

{
  "result": "Sent 100000 LBTC to address tlq1q...",
  "balance": 5000000,
  "balance_test": 1000000,
  "balance_amp": 100
}

Asset Issuance

GET /api/issuer?command=asset&asset_amount=1000&asset_address=tlq1q...&token_amount=100&token_address=tlq1q...&pubkey=02...&name=MyAsset&ticker=MA&precision=8&domain=liquidtestnet.com

💡 Pro Tip: You can use liquidtestnet.com as the domain for any test token issuance. This domain is pre-configured and validated, making it easy to create test assets with LWK without needing to set up your own domain verification.

Explorer Endpoints

Blockchain Stats

GET /api/stats

Block Information

GET /api/block?height=12345

Transaction Details

GET /api/transaction?txid=abc123...

Mempool

GET /api/mempool

🔗 Links

🌐 Live Site: liquidtestnet.com
📚 Liquid Network: liquid.net
🛠️ Elements Project: github.com/ElementsProject/elements
💼 LWK Documentation: github.com/Blockstream/lwk - Core technology powering this faucet

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This is a testnet faucet for development and testing purposes only. The assets distributed have no real value and should not be used for production applications.

Made with ❤️ for the Liquid Network community using LWK (Liquid Wallet Kit)

🔝 Back to Top