JoinMarket Maker Bot
Earn fees by providing liquidity for CoinJoin transactions. Makers passively earn bitcoin while enhancing network privacy.
Installation
Install JoinMarket-NG with the maker component:
curl -sSL https://raw.githubusercontent.com/joinmarket-ng/joinmarket-ng/main/install.sh | bash -s -- --maker
See Installation for backend setup, Tor configuration, and manual install.
Prerequisites
- Tor is required for production maker operation.
- For Tor SOCKS/control defaults, see Tor Notes.
Quick Start
1) Create or import a wallet
jm-wallet generate --output ~/.joinmarket-ng/wallets/default.mnemonic
# or import existing mnemonic
jm-wallet import --output ~/.joinmarket-ng/wallets/default.mnemonic
Store the mnemonic offline. See Wallet guide.
2) Configure backend
Set ~/.joinmarket-ng/config.toml and choose one backend:
descriptor_wallet(recommended, own Bitcoin Core)neutrino(lightweight alternative)
Backend configuration examples are in Installation.
3) Start maker
jm-maker start --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic
The bot syncs wallet state, builds offers, and waits for takers.
4) Optional: tune fees
# Relative fee (0.2%)
jm-maker start \
--mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic \
--cj-fee-relative 0.002 \
--min-size 200000
Use exactly one fee model: --cj-fee-relative or --cj-fee-absolute.
Fidelity Bonds
Makers automatically discover bonds from the local registry at startup.
- User workflow (generate/list/recover bonds): Wallet guide
- Protocol details and cold-wallet certificate flow: Technical Privacy Notes
Migration from JoinMarket Reference
Migration is mnemonic-based:
jm-wallet import --output ~/.joinmarket-ng/wallets/default.mnemonic
jm-maker start --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic
For full bond recovery during migration, run jm-wallet recover-bonds --mnemonic-file ....
Docker Deployment
This component ships with a production-oriented docker-compose.yml.
- Setup and Tor requirements: see local compose comments and Tor Notes
- Backend tradeoffs and compatibility notes: Technical Wallet Notes
Typical run:
docker-compose up -d
docker-compose logs -f maker
Configuration Notes
Configuration merges as: config.toml < environment variables < CLI flags.
For full option lists and exact defaults, use the auto-generated command help below (jm-maker start --help).
Security and Operations
- Maker transaction signing includes strict verification before signature release.
- Directory communication goes over Tor; production should avoid clearnet fallback behavior.
- Keep mnemonic files encrypted and backed up; never share mnemonic or wallet files.
Common checks:
jm-wallet info --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic
jm-maker start --help
Command Reference
jm-maker --help
Usage: jm-maker [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy │
│ it or customize the installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ start Start the maker bot. │
│ generate-address Generate a new receive address. │
│ config-init Initialize the config file with default settings. │
╰──────────────────────────────────────────────────────────────────────────────╯
jm-maker start --help
Usage: jm-maker start [OPTIONS]
Start the maker bot.
Configuration is loaded from ~/.joinmarket-ng/config.toml (or
$JOINMARKET_DATA_DIR/config.toml),
environment variables, and CLI arguments. CLI arguments have the highest
priority.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mnemonic-file -f PATH Path to mnemonic file │
│ --prompt-bip39-passph… Prompt for BIP39 │
│ passphrase │
│ interactively │
│ --data-dir -d PATH Data directory for │
│ JoinMarket files. │
│ Defaults to │
│ ~/.joinmarket-ng │
│ [env var: │
│ JOINMARKET_DATA_DIR] │
│ --network [mainnet|testnet|sig Protocol network │
│ net|regtest] (mainnet, testnet, │
│ signet, regtest) │
│ --bitcoin-network [mainnet|testnet|sig Bitcoin network for │
│ net|regtest] address generation │
│ (defaults to │
│ --network) │
│ --backend-type TEXT Backend type: │
│ scantxoutset | │
│ descriptor_wallet | │
│ neutrino │
│ --rpc-url TEXT Bitcoin full node RPC │
│ URL │
│ [env var: │
│ BITCOIN_RPC_URL] │
│ --neutrino-url TEXT Neutrino REST API URL │
│ [env var: │
│ NEUTRINO_URL] │
│ --min-size INTEGER Minimum CoinJoin size │
│ in sats │
│ --cj-fee-relative TEXT Relative coinjoin fee │
│ (e.g., 0.001 = 0.1%) │
│ [env var: │
│ CJ_FEE_RELATIVE] │
│ --cj-fee-absolute INTEGER Absolute coinjoin fee │
│ in sats. Mutually │
│ exclusive with │
│ --cj-fee-relative. │
│ [env var: │
│ CJ_FEE_ABSOLUTE] │
│ --tx-fee-contribution INTEGER Tx fee contribution in │
│ sats │
│ --directory -D TEXT Directory servers │
│ (comma-separated │
│ host:port) │
│ [env var: │
│ DIRECTORY_SERVERS] │
│ --tor-socks-host TEXT Tor SOCKS proxy host │
│ (overrides │
│ TOR__SOCKS_HOST) │
│ --tor-socks-port INTEGER Tor SOCKS proxy port │
│ (overrides │
│ TOR__SOCKS_PORT) │
│ --tor-control-host TEXT Tor control port host │
│ (overrides │
│ TOR__CONTROL_HOST) │
│ --tor-control-port INTEGER Tor control port │
│ (overrides │
│ TOR__CONTROL_PORT) │
│ --tor-cookie-path PATH Path to Tor cookie │
│ auth file (overrides │
│ TOR__COOKIE_PATH) │
│ --disable-tor-control Disable Tor control │
│ port integration │
│ --onion-serving-host TEXT Bind address for │
│ incoming connections │
│ (overrides │
│ MAKER__ONION_SERVING_… │
│ --onion-serving-port INTEGER Port for incoming │
│ .onion connections │
│ (overrides │
│ MAKER__ONION_SERVING_… │
│ --tor-target-host TEXT Target hostname for │
│ Tor hidden service │
│ (overrides │
│ TOR__TARGET_HOST) │
│ --fidelity-bond-lockt… -L INTEGER Fidelity bond │
│ locktimes to scan for │
│ --fidelity-bond-index -I INTEGER Fidelity bond │
│ derivation index │
│ [env var: │
│ FIDELITY_BOND_INDEX] │
│ --fidelity-bond -B TEXT Specific fidelity bond │
│ to use (format: │
│ txid:vout) │
│ --no-fidelity-bond Disable fidelity bond │
│ usage. Skips registry │
│ lookup and bond proof │
│ generation even when │
│ bonds exist in the │
│ registry. │
│ --merge-algorithm -M TEXT UTXO selection │
│ strategy: default, │
│ gradual, greedy, │
│ random │
│ [env var: │
│ MERGE_ALGORITHM] │
│ --dual-offers Create both relative │
│ and absolute fee │
│ offers simultaneously. │
│ Each offer gets a │
│ unique ID (0 for │
│ relative, 1 for │
│ absolute). Use with │
│ --cj-fee-relative and │
│ --cj-fee-absolute to │
│ set fees for each. │
│ --log-level -l TEXT Log level │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
jm-maker generate-address --help
Usage: jm-maker generate-address [OPTIONS]
Generate a new receive address.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --mnemonic-file -f PATH Path to mnemonic file │
│ --prompt-bip39-passph… Prompt for BIP39 │
│ passphrase │
│ interactively │
│ --network [mainnet|testnet|sig Protocol network │
│ net|regtest] │
│ --bitcoin-network [mainnet|testnet|sig Bitcoin network for │
│ net|regtest] address generation │
│ (defaults to │
│ --network) │
│ --backend-type TEXT Backend type │
│ --log-level -l TEXT Log level │
│ --help Show this message and │
│ exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
jm-maker config-init --help
Usage: jm-maker config-init [OPTIONS]
Initialize the config file with default settings.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --data-dir -d PATH Data directory for JoinMarket files │
│ [env var: JOINMARKET_DATA_DIR] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯