<!--
{
  "availability" : [

  ],
  "documentType" : "symbol",
  "framework" : "Bitcoin",
  "identifier" : "/documentation/Bitcoin",
  "metadataVersion" : "0.1.0",
  "role" : "Framework",
  "symbol" : {
    "kind" : "Framework",
    "modules" : [
      "Bitcoin"
    ],
    "preciseIdentifier" : "Bitcoin"
  },
  "title" : "Bitcoin"
}
-->

# Bitcoin

Embed a Bitcoin Core daemon in your Swift application with a type-safe RPC client and fluent configuration builder.

## Overview

The Bitcoin module embeds [Bitcoin Core](https://github.com/bitcoin/bitcoin) in a Swift application and exposes its JSON-RPC interface as typed Swift APIs.

- Start and stop an in-process `bitcoind` with ``doc://Bitcoin/documentation/Bitcoin/Daemon`` on a dedicated background thread; `start(with:)` returns immediately and `waitUntilStopped()` joins on shutdown
- Send typed JSON-RPC commands via ``doc://Bitcoin/documentation/Bitcoin/RPCClient`` over an in-process C bridge for non-wallet calls and HTTP for wallet calls or remote nodes
- Build Bitcoin Core configurations with the fluent ``doc://Bitcoin/documentation/Bitcoin/BitcoinConfig`` builder
- Catch network-specific option misuse at compile time via phantom-typed networks

The module pairs with [`BitcoinKernel`](https://github.com/21-DOT-DEV/swift-bitcoinkernel) in the [21.dev](https://github.com/21-DOT-DEV) Swift Bitcoin ecosystem. `BitcoinKernel` wraps `libbitcoinkernel` for consensus validation without a full node. Use `Bitcoin` for a full node with mempool, wallet, and P2P. Use `BitcoinKernel` for validation primitives only.

```swift
import Bitcoin

// Configure a regtest node
let auth = RPCAuth(username: "user", salt: "abc", passwordHMAC: "def")
let config = BitcoinConfig.regtest().rpcAuth(auth).server()

// Start the embedded daemon
try Daemon.start(with: config)

// Create an RPC client
let client = RPCClient(
    url: URL(string: "http://127.0.0.1:18443")!,
    username: "user",
    password: "pass"
)

// Query the blockchain
let info = try await client.getBlockchainInfo()
print("Chain: \(info.chain), Height: \(info.blocks)")
```

## Topics

### Essentials

[Getting Started with Bitcoin (Embedded Daemon)](/documentation/Bitcoin/GettingStarted)

Boot an embedded `bitcoind` inside your Swift binary, connect a typed async/await [`RPCClient`](/documentation/Bitcoin/RPCClient) over an in-process bridge, and verify the round-trip with [`getBlockchainInfo()`](/documentation/Bitcoin/RPCClient/getBlockchainInfo()) on regtest. No separate Bitcoin Core install required.

[`Bitcoin`](/documentation/Bitcoin/Bitcoin)

Top-level namespace for the Bitcoin module.

### Daemon Lifecycle

[`Daemon`](/documentation/Bitcoin/Daemon)

Controls the lifecycle of an embedded Bitcoin Core daemon process.

### RPC Client

[`RPCClient`](/documentation/Bitcoin/RPCClient)

A client for interacting with the Bitcoin JSON-RPC API.

[`RPCClientError`](/documentation/Bitcoin/RPCClientError)

Client-side RPC errors.

[`JSONRPCService`](/documentation/Bitcoin/JSONRPCService)

A service for sending JSON-RPC requests to a Bitcoin node over HTTP.

### Transport Layer

[`RPCTransport`](/documentation/Bitcoin/RPCTransport)

Abstracts the raw data transport for JSON-RPC calls.

[`WalletCapableTransport`](/documentation/Bitcoin/WalletCapableTransport)

Transports that support wallet path scoping.

[`HTTPTransport`](/documentation/Bitcoin/HTTPTransport)

Sends JSON-RPC requests over HTTP to a Bitcoin node.

[`DirectTransport`](/documentation/Bitcoin/DirectTransport)

Sends JSON-RPC requests directly to the in-process Bitcoin Core dispatch
table via `bitcoin_rpc()`, bypassing HTTP entirely.

### JSON-RPC Protocol

[`JSONRPCRequest`](/documentation/Bitcoin/JSONRPCRequest)

Represents a JSON-RPC request to be sent to the Bitcoin node.

[`JSONRPCResponse`](/documentation/Bitcoin/JSONRPCResponse)

A generic JSON-RPC response envelope.

### Configuration

[`BitcoinConfig`](/documentation/Bitcoin/BitcoinConfig)

A type-safe, fluent builder for Bitcoin Core CLI arguments.

[`BitcoinNetwork`](/documentation/Bitcoin/BitcoinNetwork)

Compile-time marker for a Bitcoin network.

[`Mainnet`](/documentation/Bitcoin/Mainnet)

Bitcoin mainnet (production).

[`Testnet`](/documentation/Bitcoin/Testnet)

Bitcoin testnet3.

[`Testnet4`](/documentation/Bitcoin/Testnet4)

Bitcoin testnet4.

[`Regtest`](/documentation/Bitcoin/Regtest)

Bitcoin regtest (regression test network).

[`Signet`](/documentation/Bitcoin/Signet)

Bitcoin signet.

### Configuration Value Types

[`IPAddress`](/documentation/Bitcoin/IPAddress)

A validated IP address (v4, v6, or CIDR range) for use in Bitcoin Core config.

[`RPCAuth`](/documentation/Bitcoin/RPCAuth)

A Bitcoin Core `rpcauth` credential in the form `user:salt$hmac`.

[`PruneMode`](/documentation/Bitcoin/PruneMode)

Controls Bitcoin Core’s block storage pruning behaviour.

[`BlockFilterMode`](/documentation/Bitcoin/BlockFilterMode)

Controls whether Bitcoin Core builds compact block filters.

[`FeeRate`](/documentation/Bitcoin/FeeRate)

A fee rate expressed in BTC per kilovbyte (BTC/kvB).

[`NetworkType`](/documentation/Bitcoin/NetworkType)

The network transport layer used to filter peer connections.

[`AddressType`](/documentation/Bitcoin/AddressType)

The output script type used for receiving and change addresses.

[`ZMQEndpoint`](/documentation/Bitcoin/ZMQEndpoint)

A ZeroMQ publish endpoint address passed to Bitcoin Core ZMQ options.

[`DebugCategory`](/documentation/Bitcoin/DebugCategory)

A logging category for the Bitcoin Core `-debug=` flag.

### Configuration Validation

[`ConfigError`](/documentation/Bitcoin/ConfigError)

A fatal conflict in a `BitcoinConfig` that prevents the daemon from
starting correctly.

[`ConfigWarning`](/documentation/Bitcoin/ConfigWarning)

A non-fatal issue in a `BitcoinConfig` that may indicate misconfiguration.

### Response Models — Blockchain

[`Block`](/documentation/Bitcoin/Block)

Represents a block in the Bitcoin blockchain.

[`BlockHeader`](/documentation/Bitcoin/BlockHeader)

Block header data from `getblockheader` (verbose=true).

[`BlockWithTransactions`](/documentation/Bitcoin/BlockWithTransactions)

Represents a block with full transaction details in the Bitcoin blockchain.

[`BlockWithPrevouts`](/documentation/Bitcoin/BlockWithPrevouts)

A block with full transaction details and prevout info (verbosity 3, v28+).

[`BlockStats`](/documentation/Bitcoin/BlockStats)

Per-block statistics from `getblockstats`.

[`BlockFilter`](/documentation/Bitcoin/BlockFilter)

Compact block filter data from `getblockfilter`.

[`BlockchainInfo`](/documentation/Bitcoin/BlockchainInfo)

Represents information about the current state of the blockchain.

[`ChainTip`](/documentation/Bitcoin/ChainTip)

A chain tip from `getchaintips`.

[`ChainTxStats`](/documentation/Bitcoin/ChainTxStats)

Chain transaction statistics from `getchaintxstats`.

[`DeploymentInfo`](/documentation/Bitcoin/DeploymentInfo)

Deployment information from `getdeploymentinfo` (v24+).

[`TxOut`](/documentation/Bitcoin/TxOut)

Unspent transaction output from `gettxout`.

[`TxOutSetInfo`](/documentation/Bitcoin/TxOutSetInfo)

UTXO set statistics from `gettxoutsetinfo`.

[`TxSpendingPrevout`](/documentation/Bitcoin/TxSpendingPrevout)

Result item from `gettxspendingprevout` (v24+).

### Response Models — Transactions

[`Transaction`](/documentation/Bitcoin/Transaction)

Represents a Bitcoin transaction as returned in verbose block/transaction RPCs.

[`DecodedTransaction`](/documentation/Bitcoin/DecodedTransaction)

Decoded transaction from `decoderawtransaction`.

[`RawTransaction`](/documentation/Bitcoin/RawTransaction)

Verbose transaction from `getrawtransaction` (verbose=true).

[`Vin`](/documentation/Bitcoin/Vin)

A transaction input.

[`Vout`](/documentation/Bitcoin/Vout)

A transaction output.

[`ScriptSig`](/documentation/Bitcoin/ScriptSig)

The scriptSig of a transaction input.

[`ScriptPubKey`](/documentation/Bitcoin/ScriptPubKey)

The scriptPubKey of a transaction output.

[`SignedTransaction`](/documentation/Bitcoin/SignedTransaction)

Result of `signrawtransactionwithkey`.

[`DecodedScript`](/documentation/Bitcoin/DecodedScript)

Result of `decodescript`.

### Response Models — PSBT

[`DecodedPSBT`](/documentation/Bitcoin/DecodedPSBT)

Decoded PSBT from `decodepsbt`.

[`PSBTAnalysis`](/documentation/Bitcoin/PSBTAnalysis)

Result of `analyzepsbt`.

[`FinalizedPSBT`](/documentation/Bitcoin/FinalizedPSBT)

Result of `finalizepsbt`.

### Response Models — Mempool

[`MempoolInfo`](/documentation/Bitcoin/MempoolInfo)

Active state of the transaction memory pool from `getmempoolinfo`.

[`MempoolEntry`](/documentation/Bitcoin/MempoolEntry)

A single mempool transaction entry from `getmempoolentry` or verbose mempool RPCs.

[`MempoolFees`](/documentation/Bitcoin/MempoolFees)

Fee breakdown for a mempool entry. All amounts in BTC.

[`MempoolAcceptResult`](/documentation/Bitcoin/MempoolAcceptResult)

Result of `testmempoolaccept` for a single transaction.

### Response Models — Network

[`PeerInfo`](/documentation/Bitcoin/PeerInfo)

Per-peer information from `getpeerinfo`.

[`NetworkInfo`](/documentation/Bitcoin/NetworkInfo)

Network information from `getnetworkinfo`.

[`AddedNodeInfo`](/documentation/Bitcoin/AddedNodeInfo)

Information about a manually added node from `getaddednodeinfo`.

[`NodeAddress`](/documentation/Bitcoin/NodeAddress)

Known node address from `getnodeaddresses`.

[`BannedInfo`](/documentation/Bitcoin/BannedInfo)

Banned peer entry from `listbanned`.

[`NetTotals`](/documentation/Bitcoin/NetTotals)

Network traffic totals from `getnettotals`.

[`ZMQNotification`](/documentation/Bitcoin/ZMQNotification)

ZMQ notification endpoint from `getzmqnotifications` (v17+).

### Response Models — Mining

[`MiningInfo`](/documentation/Bitcoin/MiningInfo)

Mining-related information from `getmininginfo`.

[`BlockTemplate`](/documentation/Bitcoin/BlockTemplate)

Block template data from `getblocktemplate` (BIP 22/23/9/145).

[`GeneratedBlock`](/documentation/Bitcoin/GeneratedBlock)

Result of `generateblock` — a block mined from specified transactions.

### Response Models — Wallet

[`WalletInfo`](/documentation/Bitcoin/WalletInfo)

Wallet state information from `getwalletinfo`.

[`WalletTransaction`](/documentation/Bitcoin/WalletTransaction)

Transaction details from wallet context via `gettransaction`.

[`WalletBalances`](/documentation/Bitcoin/WalletBalances)

Balance information from `getbalances`.

[`UnspentOutput`](/documentation/Bitcoin/UnspentOutput)

An unspent transaction output from `listunspent`.

[`ListSinceBlockResult`](/documentation/Bitcoin/ListSinceBlockResult)

Result of `listsinceblock`.

[`CreateWalletResult`](/documentation/Bitcoin/CreateWalletResult)

Result of `createwallet` or `loadwallet`.

[`BumpFeeResult`](/documentation/Bitcoin/BumpFeeResult)

Result of `bumpfee`.

[`SendResult`](/documentation/Bitcoin/SendResult)

Result of the `send` or `sendall` wallet RPC.

[`FundRawTransactionResult`](/documentation/Bitcoin/FundRawTransactionResult)

Result of `fundrawtransaction`.

[`RescanResult`](/documentation/Bitcoin/RescanResult)

Result of `rescanblockchain`.

### Response Models — Utility

[`AddressValidation`](/documentation/Bitcoin/AddressValidation)

Result of `validateaddress`.

[`DescriptorInfo`](/documentation/Bitcoin/DescriptorInfo)

Result of `getdescriptorinfo`.

[`MultisigResult`](/documentation/Bitcoin/MultisigResult)

Result of `createmultisig`.

[`SmartFeeEstimate`](/documentation/Bitcoin/SmartFeeEstimate)

Result of `estimatesmartfee`.

[`IndexInfo`](/documentation/Bitcoin/IndexInfo)

Per-index status from `getindexinfo`.

[`MemoryInfo`](/documentation/Bitcoin/MemoryInfo)

Memory usage information from `getmemoryinfo` (mode “stats”).

[`RPCInfo`](/documentation/Bitcoin/RPCInfo)

Details of the RPC server from `getrpcinfo`.

### Response Models — Shared Types

[`BTCAmount`](/documentation/Bitcoin/BTCAmount)

Single Bitcoin amount type. Stores satoshis, decodes/encodes BTC decimal.

[`UnixTimestamp`](/documentation/Bitcoin/UnixTimestamp)

Unix epoch seconds. Decodes/encodes as `Int64`.

[`RPCParam`](/documentation/Bitcoin/RPCParam)

A parameter value for a JSON-RPC request.

[`RPCError`](/documentation/Bitcoin/RPCError)

A server-originated JSON-RPC error from Bitcoin Core.

[`LastProcessedBlock`](/documentation/Bitcoin/LastProcessedBlock)

The last block processed by the wallet, included in many wallet RPC responses.

[`PrevTxOut`](/documentation/Bitcoin/PrevTxOut)

Previous transaction output description for `signrawtransactionwithkey`.

### Response Models — Scanning

[`ScanTxOutResult`](/documentation/Bitcoin/ScanTxOutResult)

Result from `scantxoutset` (action=start).

[`ScanTxOutProgress`](/documentation/Bitcoin/ScanTxOutProgress)

Progress of a running `scantxoutset` (action=status).