# Satoshi API Bitcoin Fee Intelligence

Use this skill when a user or agent needs Bitcoin fee timing, mempool pressure, transaction cost estimates, or a send-now-or-wait decision.

## Discovery

- Homepage: https://bitcoinsapi.com
- Agent commerce packet: https://bitcoinsapi.com/.well-known/agent-commerce.json
- Agents registry: https://bitcoinsapi.com/agents.json
- x402 discovery: https://bitcoinsapi.com/.well-known/x402
- x402 JSON alias: https://bitcoinsapi.com/.well-known/x402.json
- x402 capability discovery: https://bitcoinsapi.com/x402/discovery
- Paid OpenAPI: https://bitcoinsapi.com/openapi.json
- Full OpenAPI: https://bitcoinsapi.com/api/openapi.json
- MCP discovery: https://bitcoinsapi.com/.well-known/mcp.json
- MCP tools: https://bitcoinsapi.com/.well-known/mcp/tools.json
- A2A agent card: https://bitcoinsapi.com/.well-known/agent-card.json
- LLM guide: https://bitcoinsapi.com/llms.txt

## First Value

Start free. Call:

```http
GET https://bitcoinsapi.com/api/v1/fees/recommended
```

Use the response to answer whether the user should send Bitcoin now or wait, what fee target to use, and why.

## Premium x402 Path

Use x402 only when the user or buyer agent has approved pay-per-call access.

1. Discover pricing:

```http
GET https://bitcoinsapi.com/.well-known/x402
```

2. Make a tiny proof call:

```http
GET https://bitcoinsapi.com/api/v1/fees/now
```

3. For one premium answer, call:

```http
GET https://bitcoinsapi.com/api/v1/x402/satoshi-bitcoin-fee/fees/briefing
```

This costs $0.05 and returns the same premium briefing as `/api/v1/fees/briefing`.

## MCP Setup

Install:

```bash
pip install bitcoin-mcp
```

Claude Code:

```bash
claude mcp add bitcoin -- bitcoin-mcp
```

The MCP server exposes 49 Bitcoin tools and falls back to the hosted Satoshi API when no local Bitcoin node is configured.

## Guardrails

- Do not claim on-chain savings were realized unless the user provides transaction evidence.
- Treat displayed savings as potential savings from timing guidance.
- Use free endpoints before paid x402 calls when the task can be answered for free.
- Do not mutate paid-call parameters between an x402 challenge and paid retry.
- Prefer canonical `/api/v1` paths for generated clients.