fluxwallet

Python wallet library and CLI for the Flux blockchain with SSP 2-of-2 multisig co-signing support.

Features

• HD wallets — BIP32/BIP44 key derivation with BIP39 mnemonic support
• Multisig — 2-of-2 (SSP) and m-of-n P2SH multisig wallets
• SSP integration — pair with SSP Key mobile app for 2FA transaction co-signing via relay
• CLI — full wallet management via fluxwallet command (typer + rich)
• MCP server — expose wallet operations to Claude Code and other MCP clients
• Encrypted storage — AES-256-GCM with Argon2id key derivation, OS keychain integration
• Fully async — async/await throughout, SQLAlchemy 2.0 with aiosqlite

Installation

pip install fluxwallet

Or with uv:

uv add fluxwallet

Requires Python 3.13+.

Quick Start

CLI

# Generate a mnemonic
fluxwallet mnemonic

# Create a new wallet
fluxwallet wallet create my_wallet

# Restore a wallet from mnemonic (prompted)
fluxwallet wallet restore my_wallet

# Check balance
fluxwallet wallet balance my_wallet

# Get receive address
fluxwallet key address my_wallet

# Send a transaction
fluxwallet tx send my_wallet t1abc... 1.5

# List all wallets
fluxwallet wallet list

Library

import asyncio
from fluxwallet.db import Db
from fluxwallet.wallet import Wallet

async def main():
    await Db.start()
    w = await Wallet.create("my_wallet", network="flux")
    key = await w.new_key()
    print(key.address)

asyncio.run(main())

SSP Multisig

Create a 2-of-2 multisig wallet paired with the SSP Key mobile app:

# Create and pair a new SSP wallet
fluxwallet ssp pair --new my_ssp

# Send (auto-detects SSP, waits for phone approval)
fluxwallet tx send my_ssp t1abc... 0.5

# Re-pair an existing wallet
fluxwallet ssp pair my_ssp

Database Encryption

Private keys are encrypted at rest with AES-256-GCM. The encryption key is derived from your password via Argon2id and stored in your OS keychain.

# Encrypt the database (first time)
fluxwallet db setup

# Check encryption status
fluxwallet db info

# Change password
fluxwallet db change-password

# Export key for headless servers
fluxwallet db setup --export-key /path/to/keyfile

# Unlock on a headless server
fluxwallet --key-file /path/to/keyfile wallet list

# Or pipe the key via stdin
cat /path/to/keyfile | fluxwallet wallet list

Auto-unlock priority: stdin > key file > OS keychain.

Platform support

CLI Reference

fluxwallet
  wallet list|create|restore|info|rename|delete|balance|scan
  key    import|address|list|new
  tx     list|utxos|update|send|sweep
  ssp    pair|info
  db     info|setup|unlock|change-password
  mnemonic

Global options:

• --key-file PATH — path to encryption key file

Examples

uv run python examples/wallet_demo.py       # Wallet creation and key generation
uv run python examples/mnemonic_demo.py      # BIP39 mnemonic generation
uv run python examples/keys_demo.py          # HD key derivation and multisig addresses
uv run python examples/multisig_demo.py      # 2-of-2 and 2-of-3 multisig wallets
uv run python examples/transaction_demo.py   # Transaction creation and signing
uv run python examples/encryption_demo.py    # Database encryption round-trip
uv run python examples/ssp_pair.py           # SSP Key pairing
uv run python examples/ssp_send.py           # SSP co-signed transaction
uv run python examples/wallet_balance.py     # Check balance and UTXOs

Development

git clone https://github.com/MorningLightMountain713/fluxwallet.git
cd fluxwallet
uv sync
uv run pytest tests/

License

MIT