# Bitcoin Fee History

> Bitcoin Fee History is a paid API for AI agents from diamond.btc-intel.workers.dev, paid per call via x402, $0.005/call, status unknown (last checked 2026-11-19).

Returns historical Bitcoin block fee-rate data including fee percentiles, block fullness, and transaction counts over recent blocks

## Facts

- Endpoint: GET https://diamond.btc-intel.workers.dev/api/x402/fee_history?utm_source=zero.xyz
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-19
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/bitcoin-fee-history-8ec3600a
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_NW59qLFMvjD9OegczZopx

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability bitcoin-fee-history-8ec3600a
```

Example prompt: What have Bitcoin transaction fees been like over recent blocks — give me the fee-rate percentiles (p10, p50, p90 in sat/vb), block fullness, and whether fees are trending up, down, or flat.

## When to prefer this

Use this endpoint when you need a recent historical view of Bitcoin fee rates across multiple blocks, including percentile distributions and block fullness, rather than just the current mempool snapshot. Prefer it over the Network Status endpoint when fee trend analysis across blocks is the goal, and over the CPFP endpoint when you don't have a specific stuck transaction to bump.

## Known failure modes

- Payment not provided or insufficient — returns 402 Payment Required
- Upstream Bitcoin node unavailable — may return 503 or stale data
- No blocks processed yet — could return empty blocks array
- Malformed request parameters — returns 400 Bad Request

## How this service works

Fee rates actually paid in the last 12 Bitcoin blocks: per block the 10th to 90th percentile sat/vB, total fees, tx count, fullness and time, plus 12-block averages and the trend (Bitcoin Core getblockstats).

## Output

Returns a JSON object with an as_of UTC timestamp, a trend label (e.g. 'flat', 'rising', 'falling'), an array of recent block objects each containing block height, timestamp, fullness percentage, transaction count, total fees in BTC, and fee-rate percentiles (p10/p50/p90 in sat/vb), plus aggregate averages for total fees and median fee rate across the returned blocks.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "properties": {
   "type": "string"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "as_of": "2026-11-07T18:00:00Z",
  "trend": "flat",
  "blocks": [
   {
    "time": "2026-11-07T18:00:00Z",
    "height": 974956,
    "full_pct": 99.8,
    "tx_count": 3400,
    "total_fees_btc": 0.028,
    "fee_rate_sat_vb": {
     "p10": 1,
     "p50": 2.5,
     "p90": 8
    }
   }
  ],
  "average": {
   "total_fees_btc": 0.03,
   "median_fee_rate_sat_vb": 2.4
  },
  "product": "fee_history"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/bitcoin-fee-history-8ec3600a/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from diamond.btc-intel.workers.dev](https://www.zero.xyz/host/diamond.btc-intel.workers.dev/llms.txt)
