Mix Examples

Mix Examples

This page shows practical mix transactions for BRC-721. Mix transfers explicitly map NFT indices from ownership inputs to specific outputs. Exactly one output must be marked as the complement set.

Key Rules (Quick)

• Index ranges are end-inclusive in the CLI: 0..=0 means index 0 only.
• A single index is allowed: 3 is shorthand for 3..=3.
• The CLI converts ..= ranges to the end-exclusive format used on-chain.
• Exactly one --output must be :complement (or :rest or :*).
• To merge everything into one UTXO, use a single --output <ADDR>:complement and no explicit ranges.
• Ownership inputs must come first in the transaction; additional non-ownership inputs may follow to fund fees (the indexer ignores them).
• Input order defines index order. Within each input, token order follows the stored range order for that ownership UTXO.
• Fee rate uses the same units as Bitcoin Core's walletcreatefundedpsbt fee_rate option (see Wallet Guide).

How to Decide Index Ranges

Think of all NFTs across the inputs as a single list of indices starting at 0. Concatenate inputs in the order they appear in the transaction. The index ranges you provide map slices of that list to specific outputs.

To discover what you own and how many tokens are in each input:

• brc721 wallet assets --json (wallet-owned view)
• GET /addresses/<address>/assets (REST view)

Count the total number of NFTs in each input (sum of range lengths) to build your index plan.

Example 1: Split One NFT Out of a Multi-NFT UTXO

You have a single ownership UTXO containing multiple NFTs, and you want to send just the first NFT to a recipient and keep the rest.

brc721 tx mix \
  --outpoint <TXID:VOUT> \
  --output <RECIPIENT_ADDR>:0..=0 \
  --output <CHANGE_ADDR>:complement \
  --dust-sat 546 \
  --fee-rate <FEE_RATE>

• Index 0 goes to the recipient.
• All remaining indices go to the complement output.

Example 2: Merge Two Ownership UTXOs Into One Output

You have two ownership UTXOs and want all NFTs to land in a single address.

brc721 tx mix \
  --outpoint <TXID1:VOUT1> \
  --outpoint <TXID2:VOUT2> \
  --output <DEST_ADDR>:complement \
  --dust-sat 546 \
  --fee-rate <FEE_RATE>

• All indices go to the single complement output.
• No explicit ranges are required for this merge-all case.

Example 3: Rebalance Across Two Outputs

Send the first two NFTs to one address and the rest to another.

brc721 tx mix \
  --outpoint <TXID:VOUT> \
  --output <ADDR_A>:0..=1 \
  --output <ADDR_B>:complement \
  --dust-sat 546 \
  --fee-rate <FEE_RATE>

• Indices 0 and 1 go to ADDR_A.
• All remaining indices go to ADDR_B.

Example 4: Interleave From Two Inputs

Two ownership UTXOs, with indices 0..4 from input A and 5..9 from input B. Send indices 1..3 to one address and everything else to another.

brc721 tx mix \
  --outpoint <TXID_A:VOUT_A> \
  --outpoint <TXID_B:VOUT_B> \
  --output <ADDR_X>:1..=3 \
  --output <ADDR_Y>:complement \
  --dust-sat 546 \
  --fee-rate <FEE_RATE>

• Indices 1,2,3 go to ADDR_X.
• All remaining indices go to ADDR_Y.

Example 5: Multi-Output Mapping

Split tokens across three outputs, with a complement output for the rest.

brc721 tx mix \
  --outpoint <TXID:VOUT> \
  --output <ADDR_1>:0..=1 \
  --output <ADDR_2>:2..=4 \
  --output <ADDR_3>:complement \
  --dust-sat 546 \
  --fee-rate <FEE_RATE>

• ADDR_1 receives indices 0-1.
• ADDR_2 receives indices 2-4.
• ADDR_3 receives the complement set (everything else).

Troubleshooting

• "mix requires exactly one complement output": add or fix a --output <ADDR>:complement line.
• "outpoint not found in the BRC-721 index": the scanner has not indexed it yet, or it is not an ownership UTXO.
• "outpoint is not spendable by this wallet": the UTXO is not controlled by the current wallet.
• Fee errors: make sure the wallet has spendable BTC UTXOs to fund fees, or increase sats in the ownership UTXOs.