Nunchuk Coin Control

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-chain
• INCOMING_PENDING_CONFIRMATION — received but not yet confirmed
• OUTGOING_PENDING_SIGNATURES — reserved as an input of a pending transaction that still needs signatures
• OUTGOING_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.