The UTXO Model

Almost every confusing thing about building on Bitcoin dissolves once the UTXO model clicks, which is why it is the first concept to learn. Unlike a chain that keeps a running balance per account and mutates it on each transfer, Bitcoin holds no balances at all: value lives as discrete, indivisible coins called unspent transaction outputs (UTXOs), each locked to a script and each either fully spent or fully unspent. There is no address-to-balance row to read and no nonce to track — a transaction simply consumes some existing UTXOs and creates new ones in their place. After this guide you will understand what a UTXO is and how it is identified, why an address balance is something you compute rather than fetch, how to read a live output with gettxout against https://bitcoin.therpc.io/YOUR_API_KEY, and how coin selection and change work when you spend.

Core Concepts

• A UTXO is one unspent output of a past transaction, carrying a BTC amount and a locking script. It is identified by a pair: the txid of the transaction that created it and the vout index of that output within it — for example txid:0 and txid:1 are two distinct coins.
• There are no account balances. A wallet's balance is not stored anywhere; it is the sum of every UTXO whose locking script pays an address the wallet controls. To value an address you gather its UTXOs and add them up.
• A transaction consumes and creates. Each input names a UTXO to spend, and once spent that UTXO is gone forever; each output mints a fresh UTXO. Value is conserved input by input, with the leftover paid as the fee.
• The UTXO set is the current state of spendable coins. gettxout reads from this in-memory set, not from historical transaction data, so it answers "is this output still spendable right now?" directly and quickly.
• There is no nonce. Bitcoin needs no per-account counter to order spends, because an input explicitly references the exact output it spends. Double-spending is prevented by the rule that each UTXO can be consumed only once, not by a sequence number.

Reading an Unspent Output

1{
2  "jsonrpc": "1.0",
3  "id": "therpc",
4  "method": "gettxout",
5  "params": [
6    "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
7    0,
8    true
9  ]
10}

Working with UTXOs

• gettxout returns a live output's details: value denominated in BTC, the scriptPubKey with its type and address, and a confirmations count, plus coinbase and the best-block context. It answers only for outputs still in the UTXO set.
• A null result is normal, not an error. When gettxout returns null the output is either already spent or never existed — that is exactly how you confirm a coin has been consumed. Do not treat null as a failure to handle; treat it as the "spent or unknown" answer.
• To inspect a spent output, use getrawtransaction. Because spent outputs leave the UTXO set, gettxout can no longer see them. Fetch the creating transaction by txid and read its vout[n] to recover the value and script of an output that has since been spent.
• Mind the units across methods. gettxout reports value in whole BTC, while statistics methods like getblockstats report amounts in satoshis (1 BTC = 100,000,000 sat). Convert deliberately and keep internal accounting in integer satoshis to avoid floating-point drift.

Best Practices

• Value an address by summing its UTXOs. There is no balance endpoint to call; the correct figure is the total of every unspent output locked to the address. Maintain your own UTXO index per address and add the amounts rather than expecting a single balance number.
• Plan coin selection and change. A transaction usually cannot match the exact amount with the coins on hand, so you pick a set of UTXOs that covers the amount plus fee and send the remainder back to yourself as a change output. Smarter selection (fewer, larger inputs) shrinks the transaction and so the fee.
• Avoid dust. A tiny output can cost more in future fees to spend than it holds, making it uneconomical to ever move. Outputs below the network's dust threshold also fall under the relay fee floor and will be rejected, so size change and payment outputs above that limit.
• Use include_mempool for in-flight spends. Pass it to gettxout so the answer accounts for outputs already spent by unconfirmed mempool transactions. This prevents you from selecting a coin that is still "unspent" on chain but already committed in a pending transaction, which would create a double-spend.

See also

• gettxout - Read a single unspent output from the UTXO set
• getrawtransaction - Inspect inputs and outputs of any transaction
• Reading Raw Transactions - Decoding transaction structure