Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mempool/mempool/llms.txt

Use this file to discover all available pages before exploring further.

​
Get Difficulty Adjustment

Retrieve information about the current difficulty adjustment period, including estimated retarget date and difficulty change. 
curl "https://mempool.space/api/v1/difficulty-adjustment"
​
progressPercent
number
Progress through the current difficulty epoch as a percentage (0-100)
​
difficultyChange
number
Estimated difficulty change percentage at the next retarget. Positive values indicate an increase, negative values indicate a decrease. Range: -75 to 300.
​
estimatedRetargetDate
number
Estimated Unix timestamp (in milliseconds) of the next difficulty retarget
​
remainingBlocks
number
Number of blocks remaining until the next difficulty adjustment
​
remainingTime
number
Estimated time remaining until the next retarget in milliseconds
​
previousRetarget
number
Difficulty change percentage from the previous retarget. Range: -75 to 300.
​
previousTime
number
Unix timestamp (in milliseconds) of the previous difficulty retarget
​
nextRetargetHeight
number
Block height at which the next difficulty adjustment will occur
​
timeAvg
number
Average time between blocks in the current epoch in milliseconds
​
adjustedTimeAvg
number
Adjusted average block time considering the hashrate implied over the last 504 blocks, in milliseconds
​
timeOffset
number
Time offset for testnet networks. On testnet, difficulty resets to 1 after 20 minutes of no blocks. This field shows the time since the last block (capped at 20 minutes) in milliseconds. Always 0 on mainnet.
​
expectedBlocks
number
Expected number of blocks that should have been mined in the elapsed time based on the 10-minute target

​
Response Example

{
  "progressPercent": 45.2,
  "difficultyChange": 3.14,
  "estimatedRetargetDate": 1709567890000,
  "remainingBlocks": 1104,
  "remainingTime": 6624000000,
  "previousRetarget": -1.26,
  "previousTime": 1708355234000,
  "nextRetargetHeight": 840672,
  "timeAvg": 595000,
  "adjustedTimeAvg": 598000,
  "timeOffset": 0,
  "expectedBlocks": 920.5
}

​
Understanding Difficulty Adjustment

Bitcoin’s difficulty adjusts every 2016 blocks (approximately every 2 weeks) to maintain an average block time of 10 minutes. The adjustment is calculated based on how long it actually took to mine the previous 2016 blocks compared to the target time.
  • If blocks were mined faster than 10 minutes on average, difficulty increases (positive difficultyChange)
  • If blocks were mined slower than 10 minutes on average, difficulty decreases (negative difficultyChange)
  • Maximum increase: +300% (4x difficulty)
  • Maximum decrease: -75% (1/4 difficulty)

​
Use Cases

  • Mining Profitability: Estimate future mining difficulty to calculate expected returns
  • Network Monitoring: Track Bitcoin network hashrate changes through difficulty adjustments
  • Fee Estimation: Difficulty increases often correlate with increased network activity
  • Educational Tools: Display real-time information about Bitcoin’s self-adjusting security mechanism

​
Notes

The adjustedTimeAvg provides a more accurate estimate for the first 504 blocks of an epoch by using a sliding window over the last 504 blocks that includes data from the previous epoch.
On testnet networks, the difficulty can reset to 1 if no block is found for 20 minutes. The timeOffset field indicates when this rule might apply. This does not occur on mainnet.

Build docs developers (and LLMs) love

Get started for freeTalk to us