Skip to main content

​
Mining RPC Methods

Mining RPCs provide functionality for generating blocks, estimating network hashrate, and interacting with mining pool software.
Most mining RPCs are primarily used for testing on regtest/testnet or by mining pool operators. Solo mining on mainnet is generally not profitable.

​
Network Hashrate

​
getnetworkhashps

Returns the estimated network hashes per second based on recent blocks. 
# Get network hashrate over last 120 blocks
bitcoin-cli getnetworkhashps

# Get hashrate over last 2016 blocks (difficulty period)
bitcoin-cli getnetworkhashps 2016

# Get hashrate at specific height
bitcoin-cli getnetworkhashps 120 700000
​
result
number
Estimated network hashes per second

​
getmininginfo

Returns mining-related information. 
bitcoin-cli getmininginfo
​
blocks
number
Current block height
​
currentblockweight
number
Weight of the last block
​
currentblocktx
number
Number of transactions in last block
​
difficulty
number
Current difficulty
​
networkhashps
number
Estimated network hashes per second
​
pooledtx
number
Number of transactions in mempool
​
chain
string
Network name (main, test, signet, regtest)
​
warnings
string
Any network warnings

​
Block Generation (Regtest/Testnet)

​
generatetoaddress

Mines blocks to a specified address. Only works on regtest. 
# Generate 10 blocks to address
bitcoin-cli -regtest generatetoaddress 10 "bcrt1q..."
​
result
array
Array of block hashes generated
This RPC only works on regtest network. For mainnet/testnet, use external mining software.

​
generatetodescriptor

Mines blocks to a specified descriptor. Only works on regtest. 
# Generate 11 blocks to descriptor
bitcoin-cli -regtest generatetodescriptor 11 "wpkh([d34db33f/84h/0h/0h]xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL/0/*)#3wqxq7ju"
​
result
array
Array of block hashes generated

​
generate

Deprecated. Replaced by the -generate CLI option. 
# Use this instead:
bitcoind -regtest -generate

​
Mining Pool Operations

​
getblocktemplate

Returns data needed to construct a block to mine. 
# Get block template
bitcoin-cli getblocktemplate '{"rules": ["segwit"]}'
​
version
number
Block version
​
previousblockhash
string
Hash of previous block
​
transactions
array
Array of transaction objects with:
  • data: Serialized transaction (hex)
  • txid: Transaction ID
  • hash: Transaction witness hash
  • depends: Transaction dependencies (1-based indices)
  • fee: Transaction fee in satoshis
  • sigops: Legacy signature operations count
  • weight: Transaction weight
​
coinbaseaux
object
Data for coinbase transaction
​
coinbasevalue
number
Maximum value for coinbase (subsidy + fees)
​
target
string
Hash target (hex)
​
mintime
number
Minimum timestamp for block
​
curtime
number
Current timestamp
​
bits
string
Compressed difficulty target
​
height
number
Height of next block
​
default_witness_commitment
string
Witness commitment for coinbase (if SegWit enabled)
This RPC requires the node to be configured for mining (e.g., with -miner configuration) and have at least one peer connection.

​
submitblock

Submits a new block to the network. 
bitcoin-cli submitblock "0400000000000000000000..."
​
result
string | null
  • null: Block was accepted
  • Error string: Block was rejected with reason
Possible rejection reasons:
  • duplicate: Block already exists
  • duplicate-invalid: Block previously marked invalid
  • inconclusive: Node not sure if block is valid
  • rejected: Block violated consensus rules
  • high-hash: Block doesn’t meet proof-of-work requirement

​
submitheader

Submits a block header (without transactions) to check validity. 
bitcoin-cli submitheader "00000020890fbf6..."
Useful for testing block header validity without constructing full block.

​
Priority and Fee Estimation

​
prioritisetransaction

Modifies transaction priority for block inclusion. 
# Increase transaction priority by 10,000 satoshis
bitcoin-cli prioritisetransaction "txid" 0 10000

# Decrease priority
bitcoin-cli prioritisetransaction "txid" 0 -10000
​
result
boolean
Returns true if successful
This affects the transaction’s priority in this node’s mempool and block template generation. It does not affect other nodes.

​
Block Assembly

​
getblockhash

Returns the hash of a block at given height. 
bitcoin-cli getblockhash 0
​
result
string
Block hash at specified height

​
Mining Configuration

For mining operations, configure your bitcoin.conf: 
# Enable mining
server=1

# Set minimum relay fee (optional)
minrelaytxfee=0.00001

# For regtest mining
regtest=1
[regtest]
rpcuser=your_username
rpcpassword=your_password

​
Mining Pool Integration

Typical mining pool workflow:
  1. Get block template 
    bitcoin-cli getblocktemplate '{"rules": ["segwit"]}'
  2. Construct coinbase transaction with pool’s address and witness commitment
  3. Build merkle root from transactions
  4. Create block header with nonce field
  5. Mine block by incrementing nonce until valid proof-of-work found
  6. Submit block 
    bitcoin-cli submitblock "block_hex_data"

​
Testing Block Generation

For testing on regtest: 
# Start regtest node
bitcoind -regtest -daemon

# Create a wallet
bitcoin-cli -regtest createwallet "test"

# Generate address
ADDR=$(bitcoin-cli -regtest getnewaddress)

# Mine 101 blocks (100 + 1 to make first coinbase spendable)
bitcoin-cli -regtest generatetoaddress 101 "$ADDR"

# Check balance
bitcoin-cli -regtest getbalance

​
Difficulty Information

Understanding difficulty values:
  • Difficulty: Multiple of minimum difficulty (1.0 = minimum)
  • Target: Maximum hash value for valid block (lower = harder)
  • Bits: Compact representation of target
  • Chainwork: Cumulative proof-of-work in chain (hex)
Difficulty adjusts every 2016 blocks (~2 weeks) to maintain 10-minute block time.