satoshi-api 0.1.0__tar.gz

satoshi_api-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# Bitcoin Core RPC connection
+BITCOIN_RPC_HOST=127.0.0.1
+BITCOIN_RPC_PORT=8332
+# For testnet: BITCOIN_RPC_PORT=18332
+# For signet:  BITCOIN_RPC_PORT=38332
+# For regtest: BITCOIN_RPC_PORT=18443
+BITCOIN_RPC_USER=
+BITCOIN_RPC_PASSWORD=
+# Optional: path to Bitcoin Core data directory (for cookie auth)
+BITCOIN_DATADIR=
+
+# API settings
+API_PORT=9332
+API_HOST=0.0.0.0
+API_DB_PATH=data/bitcoin_api.db
+
+# CORS origins (comma-separated). Use * only for local/dev.
+# Default: http://localhost:3000,http://localhost:9332
+CORS_ORIGINS=http://localhost:3000,http://localhost:9332
+
+# Rate limits (requests per minute)
+RATE_LIMIT_ANONYMOUS=30
+RATE_LIMIT_FREE=100
+RATE_LIMIT_PRO=500
+RATE_LIMIT_ENTERPRISE=2000

satoshi_api-0.1.0/.env.production.example

@@ -0,0 +1,10 @@
+# Production environment for Satoshi API
+# Copy to .env.production and fill in values
+
+BITCOIN_RPC_HOST=host.docker.internal
+BITCOIN_RPC_PORT=8332
+BITCOIN_RPC_USER=satoshiapi
+BITCOIN_RPC_PASSWORD=
+CORS_ORIGINS=https://api.yourdomain.dev
+API_HOST=0.0.0.0
+API_PORT=9332

satoshi_api-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install git+https://github.com/Bortlesboat/bitcoinlib-rpc.git
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Run tests with coverage
+        run: pytest -v --cov=bitcoin_api --cov-report=term-missing --cov-fail-under=70
+
+      - name: Docker build (smoke test)
+        if: matrix.python-version == '3.12'
+        continue-on-error: true
+        run: docker build -t bitcoin-api-test .

satoshi_api-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,34 @@
+name: Deploy Landing Page
+
+on:
+  push:
+    branches: [main, master]
+    paths: ["docs/website/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/configure-pages@v4
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/website
+
+      - id: deployment
+        uses: actions/deploy-pages@v4

satoshi_api-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

satoshi_api-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.env
+*.db
+data/
+.venv/
+tasks/

satoshi_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## [0.2.1] - 2026-03-06
+
+### Added
+- `GET /tx/{txid}/hex` — raw transaction hex string
+- `GET /tx/{txid}/outspends` — spending status of each output (spent/unspent via UTXO set)
+- `GET /blocks/{hash}/header` — block header as hex string
+- `GET /fees/mempool-blocks` — projected next blocks from mempool, grouped by fee rate
+- `GET /prices` — BTC price in 6 currencies from CoinGecko (60s cache)
+- `GET /network/validate-address/{address}` — validate a Bitcoin address
+- 9 new unit tests + 6 new e2e tests (80 unit + 21 e2e total)
+
+### Changed
+- RPC whitelist: added `getblockheader`, `validateaddress` (now 19 commands)
+- Total endpoints: 27 → 33
+
+## [0.2.0] - 2026-03-06
+
+### Added
+- `GET /mempool/txids` — all transaction IDs in the mempool
+- `GET /mempool/recent` — most recent mempool entries sorted by time (configurable count, max 100)
+- `GET /blocks/tip/height` — chain tip height
+- `GET /blocks/tip/hash` — chain tip block hash
+- `GET /blocks/{hash}/txids` — transaction IDs in a block
+- `GET /blocks/{hash}/txs` — full transactions in a block (paginated, default 25, max 100)
+- `GET /tx/{txid}/status` — transaction confirmation status
+- `GET /network/difficulty` — difficulty epoch progress, blocks remaining, estimated retarget date
+- Competitive analysis document (vs mempool.space — 161 endpoints mapped)
+- 12 new unit tests + 6 new e2e tests (71 unit + 15 e2e total)
+
+### Changed
+- RPC whitelist: added `getrawmempool` (now 17 commands)
+- Total endpoints: 19 → 27
+
+## [0.1.0] - 2026-03-05
+
+### Added
+- REST API with 19 endpoints across 7 categories (blocks, transactions, fees, mempool, mining, network, status)
+- Tiered API key authentication (anonymous, free, pro, enterprise)
+- Sliding-window rate limiting (per-minute in-memory + daily DB-backed)
+- TTL caching with reorg-safe depth awareness
+- Input validation (txid format, block height range, fee target bounds)
+- Structured error responses with request IDs
+- Docker support with health checks
+- 59 unit tests + 9 e2e tests with full endpoint coverage
+- Security hardening: POST auth requirements, node fingerprint redaction, access logging, body size limits
+- Production deployment support: Cloudflare Tunnel config, docker-compose.prod, self-hosting docs
+- Bitcoin Core RPC whitelist configuration example

satoshi_api-0.1.0/CLAUDE.md

@@ -0,0 +1,61 @@
+# Satoshi API -- Project Instructions
+
+## Scope of Work (MANDATORY)
+
+**`docs/SCOPE_OF_WORK.md` is the canonical project document. It MUST be updated with every change.**
+
+After any code change, documentation update, or architectural decision:
+1. Update the relevant section(s) in `docs/SCOPE_OF_WORK.md`
+2. If adding/removing endpoints: update Section 3 (API Surface)
+3. If adding/removing files: update Section 6 (Deliverables)
+4. If fixing bugs or addressing review findings: update Section 5.2 (Critical Issues Fixed)
+5. If changing security controls: update Section 4 (Security Model)
+6. If test count changes: update Section 6.1 (sprint table totals)
+7. If adding known limitations: update Section 5.3
+8. If deployment steps change: update Section 7
+
+The SOW is the single source of truth for what this project is, what it does, and what state it's in. Treat it like a living design doc, not a one-time artifact.
+
+## Architecture
+
+- **Stack:** FastAPI + bitcoinlib-rpc + SQLite (WAL mode)
+- **Entry point:** `src/bitcoin_api/main.py`
+- **Config:** Pydantic Settings from env vars (`config.py`), RPC password is `SecretStr`
+- **Auth:** API key via `X-API-Key` header, tier-based (anonymous/free/pro/lightning/enterprise)
+- **L402:** Lightning micropayments via HTTP 402 + macaroon challenge (disabled by default)
+- **Rate limiting:** Sliding window (in-memory) + daily (DB-backed)
+- **Caching:** Per-cache locks, reorg-safe depth awareness, bounded LRU for hash mappings
+
+## Testing
+
+- Run tests: `python -m pytest tests/test_api.py tests/test_l402.py -q`
+- E2E (requires running API): `python -m pytest tests/test_e2e.py -m e2e`
+- Load test: `locust -f tests/locustfile.py --host http://localhost:9332`
+- Security check: `SATOSHI_API_KEY=<key> bash scripts/security_check.sh`
+- `authed_client` fixture for POST endpoint tests (requires API key in DB)
+- `client` fixture is anonymous -- use for GET tests and auth rejection tests
+
+## Conventions
+
+- Response envelope: `{ data, meta }` on success, `{ error }` on failure
+- All errors include `request_id` for tracing
+- POST endpoints require `free` tier or above (403 for anonymous)
+- Node version info redacted for anonymous users on `/network`
+- Secrets: never log, never commit. RPC password uses `SecretStr`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `docs/SCOPE_OF_WORK.md` | Living project document (KEEP UPDATED) |
+| `src/bitcoin_api/main.py` | App, middleware, exception handlers |
+| `src/bitcoin_api/config.py` | Settings from env vars |
+| `src/bitcoin_api/auth.py` | API key auth |
+| `src/bitcoin_api/rate_limit.py` | Rate limiting |
+| `src/bitcoin_api/cache.py` | TTL + LRU caching |
+| `src/bitcoin_api/lightning.py` | Lightning client (Alby Hub + mock) |
+| `src/bitcoin_api/l402.py` | L402 macaroon minting/verification |
+| `src/bitcoin_api/pricing.py` | Endpoint pricing map (sats) |
+| `tests/test_api.py` | Unit tests (80) |
+| `tests/test_l402.py` | L402 tests (32) |
+| `tests/test_e2e.py` | E2E tests (21) |

satoshi_api-0.1.0/Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml .
+COPY src/ src/
+
+RUN apt-get update && apt-get install -y --no-install-recommends git && \
+    pip install --no-cache-dir git+https://github.com/Bortlesboat/bitcoinlib-rpc.git && \
+    pip install --no-cache-dir . && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY scripts/ scripts/
+
+RUN mkdir -p /app/data && \
+    adduser --disabled-password --no-create-home apiuser && \
+    chown -R apiuser:apiuser /app/data
+
+USER apiuser
+
+EXPOSE 9332
+
+HEALTHCHECK --interval=30s --timeout=5s \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:9332/healthz')" || exit 1
+
+CMD ["python", "-m", "bitcoin_api.main"]

satoshi_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Barnes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

satoshi_api-0.1.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: satoshi-api
+Version: 0.1.0
+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: MIT
+License-File: LICENSE
+Keywords: api,bitcoin,blockchain,node,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: MIT 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: 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'
+Provides-Extra: l402
+Requires-Dist: httpx>=0.27.0; extra == 'l402'
+Description-Content-Type: text/markdown
+
+# Satoshi API
+
+[![CI](https://github.com/Bortlesboat/bitcoin-api/actions/workflows/ci.yml/badge.svg)](https://github.com/Bortlesboat/bitcoin-api/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+The thinnest REST layer over your Bitcoin node. One `pip install`, instant API.
+
+Powered by [bitcoinlib-rpc](https://github.com/Bortlesboat/bitcoinlib-rpc) for analyzed data (fees, mempool congestion, block stats) rather than raw RPC dumps. Part of the AI agent pipeline: **bitcoinlib-rpc** -> **satoshi-api** -> [bitcoin-mcp](https://github.com/Bortlesboat/bitcoin-mcp).
+
+## Prerequisites
+
+- **Bitcoin Core** running with `server=1` in `bitcoin.conf` (RPC enabled)
+- Python 3.10+
+
+**Node configuration notes:**
+- Transaction lookups (`/tx/{txid}`, `/tx/{txid}/raw`) for confirmed transactions require `txindex=1`
+- Block template (`/mining/nextblock`) requires at least one connected peer on mainnet
+- Block stats (`/blocks/{height}/stats`) is unavailable for pruned blocks below the prune height
+
+## Quick Start
+
+```bash
+pip install bitcoin-api  # or: pip install -e . for local dev
+
+# Point at your node
+export BITCOIN_RPC_USER=your_user
+export BITCOIN_RPC_PASSWORD=your_password
+# For testnet: export BITCOIN_RPC_PORT=18332
+# For signet:  export BITCOIN_RPC_PORT=38332
+
+# Run
+bitcoin-api  # or: satoshi-api
+# -> http://localhost:9332/docs
+```
+
+### Docker
+
+```bash
+# Create .env with your node credentials
+echo "BITCOIN_RPC_USER=your_user" > .env
+echo "BITCOIN_RPC_PASSWORD=your_password" >> .env
+
+docker compose up -d
+```
+
+## Endpoints
+
+All endpoints are under `/api/v1/`. Interactive docs at `/docs`.
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /health` | Node ping (no auth required) |
+| `GET /status` | Sync progress, peers, disk usage |
+| `GET /network` | Version, connections, relay fee |
+| `GET /network/forks` | Chain tips / fork detection |
+| `GET /network/difficulty` | Difficulty epoch progress, retarget estimate |
+| `GET /blocks/latest` | Latest block analysis |
+| `GET /blocks/tip/height` | Chain tip height |
+| `GET /blocks/tip/hash` | Chain tip block hash |
+| `GET /blocks/{height_or_hash}` | Block by height or hash |
+| `GET /blocks/{height}/stats` | Raw block statistics |
+| `GET /blocks/{hash}/txids` | Transaction IDs in a block |
+| `GET /blocks/{hash}/txs` | Full transactions in a block (paginated) |
+| `GET /blocks/{hash}/header` | Block header hex string |
+| `GET /tx/{txid}` | Transaction analysis (fees, SegWit, Taproot, inscriptions) |
+| `GET /tx/{txid}/raw` | Raw decoded transaction |
+| `GET /tx/{txid}/status` | Confirmation status |
+| `GET /tx/{txid}/hex` | Raw transaction hex string |
+| `GET /tx/{txid}/outspends` | Spending status of each output |
+| `GET /utxo/{txid}/{vout}` | UTXO lookup |
+| `GET /mempool` | Mempool analysis (fee buckets, congestion) |
+| `GET /mempool/info` | Raw mempool stats |
+| `GET /mempool/tx/{txid}` | Mempool entry for a transaction |
+| `GET /mempool/txids` | All transaction IDs in the mempool |
+| `GET /mempool/recent` | Most recent mempool entries |
+| `GET /fees` | Fee estimates (1, 3, 6, 25, 144 blocks) |
+| `GET /fees/recommended` | Human-readable fee recommendation |
+| `GET /fees/{target}` | Fee estimate for specific block target |
+| `GET /fees/mempool-blocks` | Projected next blocks from mempool by fee rate |
+| `GET /mining` | Hashrate, difficulty, retarget estimate |
+| `GET /mining/nextblock` | Block template analysis |
+| `GET /network/validate-address/{addr}` | Validate a Bitcoin address |
+| `GET /prices` | BTC price in USD, EUR, GBP, JPY, CAD, AUD |
+| `POST /decode` | Decode raw transaction hex |
+| `POST /broadcast` | Broadcast signed transaction |
+
+## Examples
+
+```bash
+# Health check
+curl http://localhost:9332/api/v1/health
+
+# Fee recommendation
+curl http://localhost:9332/api/v1/fees/recommended
+
+# Analyze a transaction
+curl http://localhost:9332/api/v1/tx/a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d
+
+# Latest block
+curl http://localhost:9332/api/v1/blocks/latest
+
+# With API key (higher rate limits)
+curl -H "X-API-Key: your_key_here" http://localhost:9332/api/v1/mempool
+```
+
+## API Keys
+
+Anonymous access works out of the box. For higher rate limits, create a key:
+
+```bash
+python scripts/create_api_key.py --tier free --label "my-app"
+python scripts/create_api_key.py --tier pro --label "production"
+```
+
+Pass the key via `X-API-Key` header. Query parameter `?api_key=` is deprecated (sunset: 2026-09-01).
+
+## Rate Limits
+
+| Tier | Req/min | Req/day |
+|------|---------|---------|
+| Anonymous | 30 | 1,000 |
+| Free (API key) | 100 | 10,000 |
+| Pro | 500 | 100,000 |
+| Enterprise | 2,000 | Unlimited |
+
+Rate limit info in response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-RateLimit-Daily-Limit`, `X-RateLimit-Daily-Remaining`.
+
+Every response includes `X-Request-ID` (UUID) and `X-Auth-Tier` headers.
+
+## Response Format
+
+Standard envelope on all endpoints:
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "timestamp": "2026-03-05T12:00:00+00:00",
+    "request_id": "550e8400-e29b-41d4-a716-446655440000",
+    "node_height": 880000,
+    "chain": "main"
+  }
+}
+```
+
+Errors:
+
+```json
+{
+  "error": {
+    "status": 404,
+    "title": "Not Found",
+    "detail": "Transaction not found",
+    "request_id": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+
+## Input Validation
+
+- Transaction IDs and block hashes must be exactly 64 hex characters
+- Invalid formats return 422 immediately (no wasted RPC calls)
+- Invalid API keys return 401 (not silent downgrade to anonymous)
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT