Metadata-Version: 2.4
Name: satoshidata
Version: 0.1.0
Summary: Bitcoin wallet intelligence API client — identify any address, 21 sats per query
Author-email: satoshidata <dev@satoshidata.ai>
License-Expression: MIT
Project-URL: Homepage, https://satoshidata.ai
Project-URL: Documentation, https://satoshidata.ai/openapi.json
Project-URL: Repository, https://github.com/wrbtc/satoshidata-examples
Project-URL: MCP, https://satoshidata.ai/mcp/
Keywords: bitcoin,wallet,intelligence,blockchain,mcp,l402,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# satoshidata

Bitcoin wallet intelligence API client. Identify any Bitcoin address from 30M+ labeled wallets.

## Install

```bash
pip install satoshidata
```

## Quick start

```python
from satoshidata import SatoshiDataClient

sd = SatoshiDataClient()

# Free: check any address
result = sd.trust_safety("bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h")
print(result["assessment"]["headline"])  # "Verified Binance (exchange)"

# Free: current BTC price
price = sd.price()
print(f"BTC: ${price['price_usd']:,.0f}")

# Free: network overview
network = sd.network_summary()
print(network["hashrate_eh"])

# Free: transaction status
tx = sd.tx_status("a1075db55d416d3ca199f55b6084e2115b9345e16c5cf302fc80e9d5fbf5d48d")
print(tx["state"])  # "confirmed"
```

## Premium (21 sats per call)

```python
sd = SatoshiDataClient(api_key="your-api-key")

# Full wallet intelligence
summary = sd.summary("bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h")
print(summary["likely_entity"])  # "Binance"

# Batch lookup (up to 100 addresses)
batch = sd.batch_trust_safety([
    "bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h",
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
])
print(len(batch["results"]))

# Payment verification
verified = sd.tx_verify(
    txid="c2d6e69901e1af159fe4a3e774d9b0a511141f82f970e2db1f726031dc482f36",
    address="bc1qhjkadr66r22edl96vuvetyuvpp44mdn8wqvhm5",
    min_amount_sats=410,
    min_confirmations=1,
)
```

## All methods

### Free (no API key)
| Method | Description |
|--------|-------------|
| `api_health()` | Basic service health |
| `wallets_index()` | Wallet route index |
| `trust_safety(address)` | Wallet trust-safety teaser |
| `price()` | BTC market snapshot |
| `onchain()` | On-chain regime data |
| `fees()` | Fee-rate recommendations |
| `mempool()` | Mempool state |
| `network_summary()` | Combined network snapshot |
| `tx_status(txid)` | Transaction status |
| `timestamp_status(hash)` | Timestamp lookup |
| `timestamp_quote()` | Timestamp preflight quote |
| `timestamp_verify(hash, proof)` | Proof verification |
| `capabilities()` | List all capabilities |
| `billing_catalog()` | Public billing catalog |
| `feedback(type, ...)` | Submit label corrections |

### Premium (21 sats / API key)
| Method | Description |
|--------|-------------|
| `summary(address)` | Full wallet intelligence |
| `detail(address)` | Label evidence breakdown |
| `contributors(address)` | Label contributors |
| `batch_trust_safety(addresses)` | Batch trust-safety |
| `batch_summary(addresses)` | Batch summaries |
| `tx_lookup(txid)` | Full transaction details |
| `tx_verify(txid, address, amount)` | Payment verification |
| `timestamp_submit(hash)` | Bitcoin timestamping |
| `timestamp_proof(hash)` | Download proof |
| `create_checkout(plan_id, payment_method_id)` | Create bridge checkout |
| `checkout_status(checkout_id)` | Poll checkout status |
| `refresh_checkout(checkout_id)` | Refresh a pending checkout |
| `redeem_test_code(code)` | Redeem a bridge test code |

## MCP

satoshidata.ai is also available as an MCP server:

```json
{
  "mcpServers": {
    "satoshidata": {
      "url": "https://satoshidata.ai/mcp/"
    }
  }
}
```

## Example flows

### Wallet trust-safety

```python
from satoshidata import SatoshiDataClient

client = SatoshiDataClient()
result = client.trust_safety("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa")
print(result["assessment"]["headline"])
```

### Network summary

```python
from satoshidata import SatoshiDataClient

client = SatoshiDataClient()
summary = client.network_summary()
print(summary["fastest_fee_sat_vb"], summary["hashrate_eh"])
```

### Batch address scoring

```python
from satoshidata import SatoshiDataClient

client = SatoshiDataClient(api_key="your-api-key")
batch = client.batch_trust_safety([
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "1N52wHoVR79PMDishab2XmRHsbekCdGquK",
])
for row in batch["results"]:
    print(row.get("address"), row.get("assessment", {}).get("headline"))
```

## Links

- API: https://satoshidata.ai
- Docs: https://satoshidata.ai/openapi.json
- MCP: https://satoshidata.ai/mcp/
- Smithery: https://smithery.ai/servers/satoshidata/wallet-intelligence
