# Satoshi API - Bitcoin Fee Market Research

> Satoshi API - Bitcoin Fee Market Research is a paid API for AI agents from bitcoinsapi.com, paid per call via x402, $0.05/call, status unknown (last checked 2026-09-14).

Answers natural-language questions about the Bitcoin fee market, returning live fee recommendations, mempool context, and cost estimates to help decide when to send transactions.

## Facts

- Endpoint: POST https://bitcoinsapi.com/api/v1/research/bitcoin-fee-market
- Price: $0.05/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/satoshi-api-bitcoin-fee-market-research-92ee3beb
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_N0sC57BMP3a3-CS4aYFoa

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 satoshi-api-bitcoin-fee-market-research-92ee3beb -d '<json body>'
```

Example prompt: Should I send this Bitcoin transaction now or wait? Check the current fee market and look 6 hours ahead to tell me if fees are likely to drop.

## When to prefer this

Use this endpoint when an agent or app needs to decide whether to send a Bitcoin transaction based on current and near-future fee conditions. It is preferred over raw mempool APIs because it returns opinionated, agent-ready recommendations in natural language alongside structured data, rather than requiring the caller to interpret raw fee histograms. Best suited for autonomous agents that need to gate or time Bitcoin transactions without human intervention.

## Known failure modes

- Invalid or missing 'question' field returns a validation error
- horizon_hours out of supported range may return empty forecast data
- Mempool data source unavailability may result in stale or partial market context
- Malformed JSON body returns HTTP 400
- Payment not included or insufficient USDC balance returns HTTP 402

## How this service works

Know when to send Bitcoin and when to wait. Satoshi API gives apps and AI agents live fee recommendations, mempool context, and cost estimates. Free, open source.

## Output

Returns a JSON object with a natural-language 'answer' (e.g. 'Delay non-urgent transactions if you can'), a 'briefing' summarizing the Bitcoin fee market, a 'market' object with structured mempool and fee data, the original 'question' echoed back, 'citations' listing the underlying data endpoints used, and an 'agent_action' object with a recommended next step for the calling agent.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "question": {
   "type": "string"
  },
  "horizon_hours": {
   "type": "integer"
  },
  "include_history": {
   "type": "boolean"
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "schema": {
  "type": "object",
  "required": [
   "briefing",
   "answer",
   "citations"
  ],
  "properties": {
   "answer": {
    "type": "string"
   },
   "market": {
    "type": "object"
   },
   "briefing": {
    "type": "string"
   },
   "question": {
    "type": "string"
   },
   "citations": {
    "type": "array"
   },
   "agent_action": {
    "type": "object"
   }
  }
 },
 "example": {
  "answer": "Delay non-urgent transactions if you can.",
  "briefing": "Bitcoin fee market research",
  "citations": [
   {
    "endpoint": "/api/v1/fees/landscape"
   }
  ],
  "x402_price_usd": "$0.05"
 },
 "mimeType": "application/json"
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/satoshi-api-bitcoin-fee-market-research-92ee3beb/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from bitcoinsapi.com](https://www.zero.xyz/host/bitcoinsapi.com/llms.txt)