Metadata-Version: 2.4
Name: satoshi-api
Version: 0.3.1
Summary: Satoshi API — developer-friendly Bitcoin REST API powered by your own node
Project-URL: Homepage, https://bitcoinsapi.com
Project-URL: Documentation, https://bitcoinsapi.com/docs
Project-URL: Repository, https://github.com/Bortlesboat/bitcoin-api
Project-URL: Issues, https://github.com/Bortlesboat/bitcoin-api/issues
Author: Bortlesboat
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: api,bitcoin,blockchain,node,rest
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: bitcoinlib-rpc>=0.1.0
Requires-Dist: cachetools>=5.3
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: requests>=2.28.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: locust; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# Satoshi API

**REST API for your Bitcoin node. One `pip install`, 42 endpoints.**

[![CI](https://github.com/Bortlesboat/bitcoin-api/actions/workflows/ci.yml/badge.svg)](https://github.com/Bortlesboat/bitcoin-api/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/satoshi-api?color=orange)](https://pypi.org/project/satoshi-api/)
[![Downloads](https://img.shields.io/pypi/dm/satoshi-api)](https://pypi.org/project/satoshi-api/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Live API](https://img.shields.io/badge/live-bitcoinsapi.com-f7931a)](https://bitcoinsapi.com)

[Live Playground](https://bitcoinsapi.com/docs) &middot; [Landing Page](https://bitcoinsapi.com) &middot; [PyPI](https://pypi.org/project/satoshi-api/) &middot; [MCP Server](https://github.com/Bortlesboat/bitcoin-mcp)

</div>

---

Wraps Bitcoin Core's JSON-RPC in a clean REST interface with analyzed data, smart caching, and tiered rate limiting.

## Install & Run

```bash
pip install satoshi-api
export BITCOIN_RPC_USER=your_user BITCOIN_RPC_PASSWORD=your_password
satoshi-api
# API:  http://localhost:9332
# Docs: http://localhost:9332/docs
```

## Example

```bash
curl http://localhost:9332/api/v1/fees/recommended | jq
```

```json
{
  "data": {
    "recommendation": "Fees are low. Good time to send.",
    "estimates": { "high": 4, "medium": 2, "low": 1 }
  },
  "meta": { "timestamp": "...", "node_height": 939462, "chain": "main" }
}
```

## Core Endpoints

| Category | Endpoints | Highlights |
|----------|-----------|------------|
| **Blocks** | 8 | Latest block, by height/hash, stats, txids, header |
| **Transactions** | 7 | Decoded analysis, status, outspends, UTXO lookup, broadcast |
| **Fees** | 7 | Recommendations, landscape ("send now or wait?"), history, mempool-blocks |
| **Mempool** | 5 | Congestion score, fee buckets, recent entries |
| **Mining** | 2 | Hashrate, difficulty, next block template |
| **Network** | 4 | Peers, forks, difficulty, address validation |
| **Streams** | 2 | Real-time blocks & fees via SSE |

...and more (prices, address lookups, exchange comparison). [Full interactive docs at `/docs`](https://bitcoinsapi.com/docs).

## AI Agent Integration (MCP)

Pairs with [bitcoin-mcp](https://github.com/Bortlesboat/bitcoin-mcp) to give AI assistants direct access to your Bitcoin node via [Model Context Protocol](https://modelcontextprotocol.io/).

```json
{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "args": ["--api-url", "http://localhost:9332"]
    }
  }
}
```

## Self-Hosting

```bash
pip install satoshi-api
satoshi-api  # runs on :9332

# Expose publicly (free HTTPS + DDoS protection)
cloudflared tunnel --url http://localhost:9332
```

See [self-hosting guide](docs/self-hosting.md) for full production setup.

## Contributing

Issues and PRs welcome. Run the test suite before submitting:

```bash
pip install -e ".[dev]"
pytest
```

## License

Apache 2.0 — see [LICENSE](LICENSE).

---

<div align="center">

**[Live API](https://bitcoinsapi.com/docs)** &middot; **[Website](https://bitcoinsapi.com)** &middot; **[PyPI](https://pypi.org/project/satoshi-api/)** &middot; **[MCP Server](https://github.com/Bortlesboat/bitcoin-mcp)**

Built by a [Bitcoin Core contributor](https://github.com/Bortlesboat).

</div>
