Metadata-Version: 2.4
Name: satoshiapi-mcp
Version: 1.0.0
Summary: MCP server for SatoshiAPI — Bitcoin intelligence via Lightning micropayments
Project-URL: Homepage, https://api.satoshiapi.io
Project-URL: Repository, https://github.com/SatoshiAPI/satoshi-btc-api
Author-email: Satoshi <satoshi@agentmail.to>
License-Expression: MIT
Keywords: ai-agents,bitcoin,l402,lightning,mcp,micropayments
Requires-Python: >=3.9
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# SatoshiAPI MCP Server ⚡

Model Context Protocol server for [SatoshiAPI](https://api.satoshiapi.io) — Bitcoin intelligence data powered by Lightning micropayments.

Gives any MCP-compatible AI agent (Claude, GPT, Gemini) access to real-time Bitcoin data: price, mempool fees, block height, sentiment, and DCA signals.

## Install

```bash
pip install mcp pymacaroons
```

## Quick Start

### Claude Desktop

Add to `~/.config/claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "satoshiapi": {
      "command": "python3",
      "args": ["/path/to/satoshiapi_mcp.py"]
    }
  }
}
```

### With auto-payment (connect your LND node)

```json
{
  "mcpServers": {
    "satoshiapi": {
      "command": "python3",
      "args": ["/path/to/satoshiapi_mcp.py"],
      "env": {
        "SATOSHIAPI_LND_REST": "https://127.0.0.1:8079",
        "SATOSHIAPI_LND_MACAROON": "/path/to/invoice.macaroon",
        "SATOSHIAPI_LND_CERT": "/path/to/tls.cert"
      }
    }
  }
}
```

With LND configured, the agent pays invoices automatically. Without it, the agent receives the Lightning invoice and instructions for manual payment.

## Available Tools

| Tool | Description | Cost |
|------|-------------|------|
| `get_btc_price` | BTC/USD price + 24h change | 10 sats |
| `get_mempool_fees` | Fee estimates (sat/vB) | 10 sats |
| `get_block_height` | Block height + hashrate | 10 sats |
| `get_sentiment` | Fear & Greed index | 25 sats |
| `get_dca_signal` | DCA signal with reasoning | 50 sats |
| `get_api_status` | Service status | Free |
| `pay_and_request` | Complete manual L402 payment | — |

## How It Works

1. Agent calls a tool (e.g., `get_btc_price`)
2. MCP server hits `api.satoshiapi.io/price`
3. API returns HTTP 402 with Lightning invoice + macaroon
4. If LND is configured → auto-pays and returns data
5. If no LND → returns invoice for manual payment
6. Agent uses the data in its response

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `SATOSHIAPI_URL` | API base URL (default: `https://api.satoshiapi.io`) | No |
| `SATOSHIAPI_LND_REST` | LND REST endpoint (e.g., `https://127.0.0.1:8079`) | For auto-pay |
| `SATOSHIAPI_LND_MACAROON` | Path to LND invoice macaroon | For auto-pay |
| `SATOSHIAPI_LND_CERT` | Path to LND TLS certificate | For auto-pay |

## License

MIT — [SatoshiAPI](https://github.com/SatoshiAPI/satoshi-btc-api)
