| name | nunchuk-coin-control |
| description | Inspect and manage a wallet's coins (UTXOs) - list and filter coins, lock and unlock them, and organize them with tags and collections including automatic rules (add untagged coins, add by tag, auto-lock). Use when the user wants to label, organize, protect, or audit individual coins, or set up automatic coin classification. |
Nunchuk Coin Control
If auth or network setup is the blocker, use nunchuk-setup.
To spend specific coins, spend from a tag or collection, or set change-coin tags, use nunchuk-wallet-transactions (tx create --coin / --from-tag / --from-collection / --change-tags).
List Coins
List a wallet's coins with status, amount, received date-time, lock state, tags, and collections:
nunchuk coin list --wallet <wallet-id>
Filter the listing:
nunchuk coin list --wallet <wallet-id> --status CONFIRMED
nunchuk coin list --wallet <wallet-id> --tag kyc
nunchuk coin list --wallet <wallet-id> --untagged
nunchuk coin list --wallet <wallet-id> --collection "Exchange A"
nunchuk coin list --wallet <wallet-id> --locked
nunchuk coin list --wallet <wallet-id> --unlocked
--status takes one of:
CONFIRMED — unspent and confirmed on-chainINCOMING_PENDING_CONFIRMATION — received but not yet confirmedOUTGOING_PENDING_SIGNATURES — reserved as an input of a pending transaction that still needs signaturesOUTGOING_PENDING_BROADCAST — reserved as an input of a fully signed transaction awaiting broadcast
Each coin's outpoint (txid:vout) is what --coin options take everywhere (coin lock, coin tag add, tx create --coin, ...).
Lock and Unlock
A locked coin is never picked by automatic coin selection or --send-all sweeps. Explicitly selecting it with tx create --coin still spends it — the lock guards against accidental use, not deliberate use.
nunchuk coin lock --wallet <wallet-id> --coin <txid>:<vout>
nunchuk coin unlock --wallet <wallet-id> --coin <txid>:<vout>
--coin is repeatable to lock or unlock several coins at once.
Tags
Tags are reusable labels for classifying coins (for example kyc, exchange-a, payroll). Names are case-sensitive, contain no whitespace, and a leading # is accepted and stripped.
nunchuk coin tag create kyc --wallet <wallet-id>
nunchuk coin tag list --wallet <wallet-id>
nunchuk coin tag add kyc --wallet <wallet-id> --coin <txid>:<vout> --coin <txid>:<vout>
nunchuk coin tag remove kyc --wallet <wallet-id> --coin <txid>:<vout>
nunchuk coin tag rename kyc --wallet <wallet-id> --name kyc-verified
nunchuk coin tag delete kyc --wallet <wallet-id>
Show a tag's member coins with live amounts and the spendable total:
nunchuk coin tag get kyc --wallet <wallet-id>
Collections
Collections are named groups of coins with optional auto-membership rules. Names are case-sensitive, unique per wallet, and may contain spaces (quote them).
nunchuk coin collection create "Exchange A" --wallet <wallet-id>
nunchuk coin collection list --wallet <wallet-id>
nunchuk coin collection get "Exchange A" --wallet <wallet-id>
nunchuk coin collection add "Exchange A" --wallet <wallet-id> --coin <txid>:<vout>
nunchuk coin collection remove "Exchange A" --wallet <wallet-id> --coin <txid>:<vout>
nunchuk coin collection delete "Exchange A" --wallet <wallet-id>
Rule flags on create (and update):
--add-untagged — new coins arriving without tags join automatically (--no-add-untagged to turn off on update)--add-tag <tag> — coins join when they receive one of these tags (repeatable; --clear-add-tags to reset on update)--auto-lock — coins are locked the moment they join (--no-auto-lock to turn off on update)--apply-to-existing — one-shot: run the rules over currently known coins now
Quarantine posture — lock every unclassified inbound coin until reviewed:
nunchuk coin collection create quarantine --wallet <wallet-id> --add-untagged --auto-lock
Auto-collect coins as they get tagged:
nunchuk coin collection create verified --wallet <wallet-id> --add-tag kyc --apply-to-existing
Update rules later (members are kept):
nunchuk coin collection update quarantine --wallet <wallet-id> --no-auto-lock
nunchuk coin collection update verified --wallet <wallet-id> --add-tag cold
Change-Coin Tags
When a transaction produces change from tagged inputs, the change coin inherits the inputs' tags by default. Override at creation with tx create --change-tags <subset|none> (see nunchuk-wallet-transactions). The choice is applied automatically when the change coin is next seen — even if the transaction was broadcast by the mobile app or backend, not the CLI.
Common requests
User asks: which coins do I have, and which are locked or tagged:
nunchuk coin list --wallet <wallet-id>
User asks: protect a coin from being spent:
nunchuk coin lock --wallet <wallet-id> --coin <txid>:<vout>
User asks: tag my exchange coins:
nunchuk coin tag create exchange-a --wallet <wallet-id>
nunchuk coin tag add exchange-a --wallet <wallet-id> --coin <txid>:<vout> --coin <txid>:<vout>
User asks: how much do my KYC coins add up to:
nunchuk coin tag get kyc --wallet <wallet-id>
User asks: lock every new coin until I review it:
nunchuk coin collection create quarantine --wallet <wallet-id> --add-untagged --auto-lock
Defaults
- Coin-control data (locks, tags, collections) is stored locally and encrypted, per machine — it does not sync with the Nunchuk mobile app or server.
- Collection rules are evaluated lazily when the CLI next sees the wallet's coins (
coin list, tx create, tx draft, tx broadcast) — there is no background process.
coin tag get / coin collection get join local membership with the live unspent set: spent members are marked [spent] and the Total: line sums spendable members only.- Use
--json when the user needs exact machine-readable output.
Gotchas
- A lock only guards automatic selection —
tx create --coin spends a locked coin.
- Collection membership applies on arrival and is never re-evaluated or auto-removed: removing a tag keeps the coin in collections it already joined, and deleting a collection keeps its coins' lock state.
- Auto-lock fires once, on join — unlocking a member coin afterwards sticks.
- A change coin that inherits tags does not join
--add-untagged collections (it is not untagged when the rules run).
- Tag and collection names are case-sensitive (
KYC ≠ kyc); a lookup miss suggests near-matches.
--untagged cannot be combined with --tag.- Deleting a tag removes it from every coin, collection rule, and pending change-tag intent.
