JoinMarket Taker Client
Mix your bitcoin for privacy via CoinJoin. Takers initiate transactions and pay small fees to makers.
Installation
Install JoinMarket-NG with the taker component:
curl -sSL https://raw.githubusercontent.com/joinmarket-ng/joinmarket-ng/main/install.sh | bash -s -- --taker
See Installation for backend setup, Tor configuration, and manual install.
Quick Start
1) Create a wallet
jm-wallet generate --output ~/.joinmarket-ng/wallets/default.mnemonic
Store the mnemonic offline. See Wallet guide.
2) Fund and inspect
jm-wallet info --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic --backend neutrino
3) Run a CoinJoin
jm-taker coinjoin \
--mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic \
--amount 1000000
Default destination is INTERNAL (next mixdepth), which is the standard privacy-preserving path.
Common Use Cases
# Mix to next mixdepth (INTERNAL)
jm-taker coinjoin --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic --amount 500000
# Mix and send to external destination
jm-taker coinjoin --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic \
--amount 500000 --destination bc1qexampleaddress...
# Sweep one mixdepth
jm-taker coinjoin --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic \
--amount 0 --mixdepth 2
# Pick the inputs by hand (interactive TUI)
jm-taker coinjoin --mnemonic-file ~/.joinmarket-ng/wallets/default.mnemonic \
--amount 500000 --select-utxos
Increase counterparties (for larger anonymity sets) with --counterparties.
With --select-utxos the selector shows every UTXO in the wallet grouped by
mixdepth. A CoinJoin spends from a single mixdepth, so the first UTXO you
toggle pins the source mixdepth (deselect everything to unpin); pass
--mixdepth to pin it up front. The INTERNAL destination then targets the
mixdepth after the derived one.
Tumbler
For multi-step automated mixing, run jm-taker tumble <schedule.json>.
- Schedule format and operational guidance are in
taker/README.md. - Privacy model and protocol-level behavior are in Technical Privacy Notes.
Configuration Notes
Configuration merges as: config.toml < environment variables < CLI flags.
Backend setup and defaults: Installation.
taker.tx_fee_factor controls additive fee randomization, not a direct multiplier. A value
of 0.2 picks a session fee rate between the base rate and base_rate * 1.2; 0 disables
randomization.
For all option details, use auto-generated command help below (jm-taker coinjoin --help, jm-taker tumble --help).
Ignored makers
The taker keeps a persisted list of makers that previously misbehaved (rejected
PoDLE commitments, returned an invalid signature, etc.) at
<data-dir>/ignored_makers.txt. This list is treated as a soft preference:
the maker selector tries to avoid these nicks, but if the resulting eligible
pool is too small to fill the requested counterparty count the selector tops
the pick up from the ignored list rather than failing the whole CoinJoin. Use
jm-taker clear-ignored-makers to reset the list.
In contrast, makers that explicitly reject the current CoinJoin attempt (e.g. a fresh blacklist response in this fill phase) are hard-excluded from that attempt only — they will be retried in future runs unless they also end up on the persisted ignored list.
Docker Deployment
This component ships with docker-compose.yml for containerized operation.
Typical flow:
docker-compose up -d bitcoind tor
docker-compose run --rm taker jm-taker coinjoin --amount 1000000
docker-compose logs -f taker
Takers only require Tor SOCKS; no Tor control port is needed.
Command Reference
jm-taker --help
Usage: jm-taker [OPTIONS] COMMAND [ARGS]...
JoinMarket Taker - Execute CoinJoin transactions
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy │
│ it or customize the installation. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ clear-ignored-makers Clear the list of ignored makers. │
│ coinjoin Execute a single CoinJoin transaction. │
│ config-init Initialize the config file with default settings. │
│ tumble Run a tumbler schedule of CoinJoins. │
╰──────────────────────────────────────────────────────────────────────────────╯
jm-taker clear-ignored-makers --help
Usage: jm-taker clear-ignored-makers [OPTIONS]
Clear the list of ignored makers.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config-file PATH Config file path (decoupled from data dir). │
│ Defaults to <data-dir>/config.toml │
│ [env var: JOINMARKET_CONFIG_FILE] │
│ --data-dir -d PATH Data directory for JoinMarket files │
│ [env var: JOINMARKET_DATA_DIR] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
jm-taker coinjoin --help
Usage: jm-taker coinjoin [OPTIONS]
Execute a single CoinJoin transaction.
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 ────────────────────────────────────────────────────────────────────╮
│ * --amount -a INTEGER Amount in sats │
│ (0 for sweep) │
│ [required] │
│ --backend -b TEXT Backend type: │
│ descriptor_wall… │
│ | neutrino │
│ --bitcoin-netw… [mainnet|testne Bitcoin network │
│ t|signet|regtes for addresses │
│ t] (defaults to │
│ --network) │
│ --block-target INTEGER Target blocks │
│ for fee │
│ estimation │
│ (1-1008). Cannot │
│ be used with │
│ neutrino. │
│ --bond-exponent FLOAT Exponent for │
│ fidelity bond │
│ value │
│ calculation │
│ [env var: │
│ BOND_VALUE_EXPO… │
│ --bondless-all… FLOAT Fraction of time │
│ to choose makers │
│ randomly │
│ (0.0-1.0) │
│ [env var: │
│ BONDLESS_MAKERS… │
│ --bondless-zer… --no-bondless-… For bondless │
│ spots, require │
│ zero absolute │
│ fee │
│ [env var: │
│ BONDLESS_REQUIR… │
│ --config-file PATH Config file path │
│ (decoupled from │
│ data dir). │
│ Defaults to │
│ <data-dir>/conf… │
│ [env var: │
│ JOINMARKET_CONF… │
│ --counterparti… -n INTEGER Number of makers │
│ --data-dir PATH Data directory │
│ (default: │
│ ~/.joinmarket-ng │
│ or │
│ $JOINMARKET_DAT… │
│ [env var: │
│ JOINMARKET_DATA… │
│ --destination -d TEXT Destination │
│ address (or │
│ 'INTERNAL' for │
│ next mixdepth) │
│ [default: │
│ INTERNAL] │
│ --directory -D TEXT Directory │
│ servers │
│ (comma-separate… │
│ [env var: │
│ DIRECTORY_SERVE… │
│ --fee-rate FLOAT Manual fee rate │
│ in sat/vB. │
│ Mutually │
│ exclusive with │
│ --block-target. │
│ --help Show this │
│ message and │
│ exit. │
│ --log-level -l TEXT Log level │
│ --max-abs-fee INTEGER Max absolute fee │
│ in sats │
│ --max-rel-fee TEXT Max relative fee │
│ (0.001=0.1%) │
│ --mixdepth -m INTEGER Source mixdepth │
│ (default 0; with │
│ --select-utxos, │
│ derived from the │
│ selection unless │
│ set explicitly) │
│ --mnemonic-file -f PATH Path to mnemonic │
│ file │
│ --network [mainnet|testne Protocol network │
│ t|signet|regtes for handshakes │
│ t] │
│ --neutrino-url TEXT Neutrino REST │
│ API URL │
│ [env var: │
│ NEUTRINO_URL] │
│ --prompt-bip39… Prompt for BIP39 │
│ passphrase │
│ interactively │
│ --rpc-url TEXT Bitcoin full │
│ node RPC URL │
│ [env var: │
│ BITCOIN_RPC_URL] │
│ --select-utxos -s Interactively │
│ select UTXOs │
│ (fzf-like TUI) │
│ --tor-socks-ho… TEXT Tor SOCKS proxy │
│ host (overrides │
│ TOR__SOCKS_HOST) │
│ --tor-socks-po… INTEGER Tor SOCKS proxy │
│ port (overrides │
│ TOR__SOCKS_PORT) │
│ --yes -y Skip │
│ confirmation │
│ prompt │
╰──────────────────────────────────────────────────────────────────────────────╯
jm-taker config-init --help
Usage: jm-taker config-init [OPTIONS]
Initialize the config file with default settings.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config-file PATH Config file path (decoupled from data dir). │
│ Defaults to <data-dir>/config.toml │
│ [env var: JOINMARKET_CONFIG_FILE] │
│ --data-dir -d PATH Data directory for JoinMarket files │
│ [env var: JOINMARKET_DATA_DIR] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
jm-taker tumble --help
Usage: jm-taker tumble [OPTIONS] SCHEDULE_FILE
Run a tumbler schedule of CoinJoins.
Configuration is loaded from ~/.joinmarket-ng/config.toml, environment
variables,
and CLI arguments. CLI arguments have the highest priority.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * schedule_file PATH Path to schedule JSON file [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --backend -b TEXT Backend type: │
│ descriptor_wallet | │
│ neutrino │
│ --config-file PATH Config file path │
│ (decoupled from data │
│ dir). Defaults to │
│ <data-dir>/config.toml │
│ [env var: │
│ JOINMARKET_CONFIG_FIL… │
│ --data-dir PATH Data directory │
│ (default: │
│ ~/.joinmarket-ng or │
│ $JOINMARKET_DATA_DIR) │
│ [env var: │
│ JOINMARKET_DATA_DIR] │
│ --directory -D TEXT Directory servers │
│ (comma-separated) │
│ [env var: │
│ DIRECTORY_SERVERS] │
│ --help Show this message and │
│ exit. │
│ --log-level -l TEXT Log level │
│ --mnemonic-file -f PATH Path to mnemonic file │
│ --network [mainnet|testnet|sig Bitcoin network │
│ net|regtest] │
│ --neutrino-url TEXT Neutrino REST API URL │
│ [env var: │
│ NEUTRINO_URL] │
│ --prompt-bip39-passph… Prompt for BIP39 │
│ passphrase │
│ interactively │
│ --rpc-url TEXT Bitcoin full node RPC │
│ URL │
│ [env var: │
│ BITCOIN_RPC_URL] │
│ --tor-socks-host TEXT Tor SOCKS proxy host │
│ (overrides │
│ TOR__SOCKS_HOST) │
│ --tor-socks-port INTEGER Tor SOCKS proxy port │
│ (overrides │
│ TOR__SOCKS_PORT) │
╰──────────────────────────────────────────────────────────────────────────────╯