Metadata-Version: 2.4
Name: satoshi-api
Version: 0.3.2
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: prometheus-client>=0.20.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: requests>=2.28.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: all
Requires-Dist: posthog>=3.0.0; extra == 'all'
Requires-Dist: resend>=2.0.0; extra == 'all'
Requires-Dist: stripe>=7.0.0; extra == 'all'
Requires-Dist: upstash-redis>=1.0.0; extra == 'all'
Provides-Extra: analytics
Requires-Dist: posthog>=3.0.0; extra == 'analytics'
Provides-Extra: billing
Requires-Dist: stripe>=7.0.0; extra == 'billing'
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'
Provides-Extra: email
Requires-Dist: resend>=2.0.0; extra == 'email'
Provides-Extra: indexer
Requires-Dist: asyncpg>=0.29.0; extra == 'indexer'
Requires-Dist: pyzmq>=25.0.0; extra == 'indexer'
Provides-Extra: redis
Requires-Dist: upstash-redis>=1.0.0; extra == 'redis'
Description-Content-Type: text/markdown

<div align="center">

# Satoshi API

**REST API for your Bitcoin node. One `pip install`, 73 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. Optional integrations: email notifications (Resend), persistent rate limiting (Upstash Redis), and privacy-first analytics (PostHog) -- all disabled by default.

## 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).

## For AI Agents

**[bitcoin-mcp](https://github.com/Bortlesboat/bitcoin-mcp)** — the first Bitcoin MCP server on the official Anthropic MCP Registry — gives AI assistants direct access to your Bitcoin node via [Model Context Protocol](https://modelcontextprotocol.io/). 35 tools, 6 prompts, 7 resources.

```bash
# Install and point at your Satoshi API instance
pip install bitcoin-mcp
SATOSHI_API_URL=https://bitcoinsapi.com bitcoin-mcp
```

Or connect to a local node directly:

```json
{
  "mcpServers": {
    "bitcoin": { "command": "bitcoin-mcp" }
  }
}
```

## 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>
