Metadata-Version: 2.4
Name: readwhitepaper
Version: 0.1.0
Summary: Python client for ReadWhitepaper — blockchain whitepaper database with 30 whitepapers, 163 glossary terms, and 15-language translations
Project-URL: Homepage, https://readwhitepaper.com
Project-URL: Documentation, https://readwhitepaper.com/developers/
Project-URL: Repository, https://github.com/dobestan/readwhitepaper-python
Project-URL: API, https://readwhitepaper.com/api/
Author-email: dobestan <dobestan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bitcoin,blockchain,crypto,cryptocurrency,defi,ethereum,readwhitepaper,web3,whitepaper
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# readwhitepaper

[![PyPI](https://img.shields.io/pypi/v/readwhitepaper)](https://pypi.org/project/readwhitepaper/)
[![Python](https://img.shields.io/pypi/pyversions/readwhitepaper)](https://pypi.org/project/readwhitepaper/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/readwhitepaper/)

Python client for the [ReadWhitepaper](https://readwhitepaper.com) API — a blockchain whitepaper database hosting 30 cryptocurrency whitepapers with section-level content, 163 glossary terms, full-text search, and 3,458 translations across 15 languages. Pure Python, zero dependencies, fully typed.

ReadWhitepaper provides structured, machine-readable access to the foundational documents of the cryptocurrency ecosystem. Every whitepaper is broken into individually addressable sections, translated into 15 languages, and cross-referenced with a comprehensive blockchain glossary.

> **Explore the whitepapers at [readwhitepaper.com](https://readwhitepaper.com)** — [Bitcoin Whitepaper](https://readwhitepaper.com/bitcoin/), [Ethereum Whitepaper](https://readwhitepaper.com/ethereum/), [API Docs](https://readwhitepaper.com/developers/)

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You'll Find on ReadWhitepaper](#what-youll-find-on-readwhitepaper)
  - [Cryptocurrency Whitepapers](#cryptocurrency-whitepapers)
  - [Section-Level Content](#section-level-content)
  - [Blockchain Glossary](#blockchain-glossary)
  - [Multilingual Translations](#multilingual-translations)
  - [Full-Text Search](#full-text-search)
  - [Relationship Graph](#relationship-graph)
- [API Endpoints](#api-endpoints)
- [API Client](#api-client)
  - [Whitepapers](#whitepapers)
  - [Glossary](#glossary)
  - [Search](#search)
  - [Stats and Languages](#stats-and-languages)
  - [Graph](#graph)
- [Learn More About Blockchain Whitepapers](#learn-more-about-blockchain-whitepapers)
- [Also Available](#also-available)
- [License](#license)

## Install

```bash
pip install readwhitepaper
```

## Quick Start

```python
from readwhitepaper import ReadWhitepaperClient

# Initialize the client — no API key needed
client = ReadWhitepaperClient()

# List all 30 cryptocurrency whitepapers
whitepapers = client.list_whitepapers()
for wp in whitepapers.results:
    print(f"{wp.crypto.ticker} — {wp.authors[0]} ({wp.year})")
    # BTC — Satoshi Nakamoto (2008)
    # ETH — Vitalik Buterin (2013)

# Read Bitcoin's whitepaper section by section
bitcoin = client.get_whitepaper("bitcoin")
for section in bitcoin.sections:
    print(f"§{section.section_number}: {section.heading_text}")
    # §Abstract: Abstract
    # §1: Introduction
    # §2: Transactions
```

## What You'll Find on ReadWhitepaper

### Cryptocurrency Whitepapers

ReadWhitepaper hosts the foundational documents of 30 major cryptocurrencies, ranked by market capitalization. A cryptocurrency whitepaper is the primary technical document published by a blockchain project's creators, describing the protocol's design, consensus mechanism, economic model, and intended use cases. The tradition began with Satoshi Nakamoto's 2008 Bitcoin whitepaper, which introduced the concept of decentralized peer-to-peer electronic cash.

| Rank | Ticker | Author(s) | Year | Sections |
|------|--------|-----------|------|----------|
| 1 | BTC | Satoshi Nakamoto | 2008 | 14 |
| 2 | ETH | Vitalik Buterin | 2013 | 23 |
| 3 | USDT | J.R. Willett | 2016 | 10 |
| 4 | XRP | David Schwartz, Noah Youngs, Arthur Britto | 2014 | 11 |
| 5 | SOL | Anatoly Yakovenko | 2017 | 12 |
| 6 | USDC | Circle | 2018 | 10 |
| 7 | BNB | Binance | 2017 | 6 |
| 8 | DOGE | Billy Markus, Jackson Palmer | 2013 | 9 |
| 9 | ADA | Charles Hoskinson, IOHK | 2017 | 6 |
| 10 | TRX | Justin Sun | 2017 | 9 |

```python
# Get whitepaper metadata for any cryptocurrency
eth = client.get_whitepaper("ethereum")
print(f"Authors: {', '.join(eth.authors)}")   # Vitalik Buterin
print(f"Year: {eth.year}")                     # 2013
print(f"Sections: {eth.total_sections}")       # 23
print(f"Source: {eth.source_url}")             # https://ethereum.org/...
```

### Section-Level Content

Every whitepaper is decomposed into individually addressable sections with full text content. This enables granular analysis, citation, and cross-referencing across documents.

```python
# Read individual sections of any whitepaper
sections = client.get_sections("bitcoin")
abstract = sections[0]
print(abstract.content[:120])
# "A purely peer-to-peer version of electronic cash would allow online payments
#  to be sent directly from one party to another..."

# Get the table of contents for quick navigation
toc = client.get_toc("ethereum")
for entry in toc[:5]:
    print(f"  {entry.section_number}. {entry.heading}")
    # Abstract. Abstract
    # 1. Introduction and Existing Concepts
    # 2. Bitcoin As A State Transition System
```

### Blockchain Glossary

163 blockchain terms organized across 12 categories (consensus, transactions, networking, mining, wallets, DeFi, stablecoins, governance, smart contracts, layer-2, privacy, and cryptography). Each term includes a precise definition and cross-references to whitepaper sections where the concept appears.

| Category | Terms | Example Terms |
|----------|-------|---------------|
| consensus | 22 | Proof of Work, Proof of Stake, BFT, Finality |
| transactions | 18 | UTXO, Gas, Nonce, Mempool |
| networking | 16 | Block, Blockchain, Node, Gossip Protocol |
| mining | 12 | Hash Rate, ASIC, Block Reward, Difficulty |
| wallets | 10 | Address, HD Wallet, Seed Phrase |
| defi | 14 | AMM, Liquidity Pool, Flash Loan, Yield Farming |

```python
# Browse the blockchain glossary
glossary = client.list_glossary(limit=5)
for term in glossary.results:
    print(f"{term.term} [{term.category}] — appears {term.occurrence_count}x")
    # Blockchain [networking] — appears 53x
    # Block [networking] — appears 47x

# Look up a specific term
pos = client.get_glossary_term("proof-of-stake")
print(pos.definition)
print(f"Aliases: {pos.aliases}")
```

### Multilingual Translations

All 30 whitepapers are translated into 15 languages with section-level granularity, totaling 3,458 individual translations. This makes the technical knowledge accessible to developers and researchers worldwide.

| Language | Code | Direction | Whitepapers |
|----------|------|-----------|-------------|
| English | en | LTR | 30 |
| Korean | ko | LTR | 30 |
| Japanese | ja | LTR | 30 |
| Chinese (Simplified) | zh-hans | LTR | 30 |
| Spanish | es | LTR | 30 |
| Arabic | ar | RTL | 30 |
| Hindi | hi | LTR | 30 |
| French | fr | LTR | 30 |
| Russian | ru | LTR | 30 |
| German | de | LTR | 30 |

```python
# Read Bitcoin's whitepaper in Korean
bitcoin_ko = client.get_whitepaper("bitcoin", language="ko")
for s in bitcoin_ko.sections[:2]:
    print(f"§{s.section_number}: {s.heading_text}")

# Check translation coverage for any whitepaper
coverage = client.get_coverage("ethereum")
for lang in coverage.languages[:3]:
    print(f"  {lang.language}: {lang.completion_percent}% ({lang.translated_sections}/{lang.total_sections})")
    # en: 100.0% (23/23)
    # ko: 100.0% (23/23)
```

### Full-Text Search

Search across all whitepaper content with highlighted snippets and deep links to specific sections.

```python
# Search across all whitepapers for a concept
results = client.search("proof of work")
for r in results[:3]:
    print(f"{r.slug} §{r.heading}: ...{r.snippet}...")

# Search within a specific whitepaper
btc_results = client.search("double-spending", slug="bitcoin")
```

### Relationship Graph

Explore connections between whitepapers through a knowledge graph that maps how blockchain projects reference and build upon each other.

```python
# Get the full relationship graph
graph = client.get_graph()
print(f"Nodes: {len(graph.nodes)}, Edges: {len(graph.edges)}")

for node in graph.nodes[:3]:
    print(f"{node.ticker} ({node.year}) — {node.type}")
```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/whitepapers/` | List all 30 whitepapers |
| GET | `/api/whitepapers/{slug}/` | Whitepaper detail with sections |
| GET | `/api/whitepapers/{slug}/sections/` | Sections only |
| GET | `/api/whitepapers/{slug}/toc/` | Table of contents |
| GET | `/api/whitepapers/{slug}/coverage/` | Translation coverage |
| GET | `/api/glossary/` | List 163 glossary terms |
| GET | `/api/glossary/{slug}/` | Glossary term detail |
| GET | `/api/search/?q=` | Full-text search |
| GET | `/api/stats/` | Platform statistics |
| GET | `/api/languages/` | Supported languages |
| GET | `/api/graph/` | Relationship graph |

### Example

```bash
curl -s "https://readwhitepaper.com/api/whitepapers/bitcoin/"
```

```json
{
  "crypto": {
    "ticker": "BTC",
    "slug": "bitcoin",
    "website_url": "https://bitcoin.org",
    "brand_color": "#F7931A",
    "market_cap_rank": 1
  },
  "authors": ["Satoshi Nakamoto"],
  "year": 2008,
  "source_url": "https://bitcoin.org/bitcoin.pdf",
  "total_sections": 14,
  "available_languages": ["ar", "de", "en", "es", "fr", "hi", "id", "ja", "ko", "pt", "ru", "th", "tr", "vi", "zh-hans"]
}
```

Full API documentation at [readwhitepaper.com/developers/](https://readwhitepaper.com/developers/).

## API Client

### Whitepapers

```python
from readwhitepaper import ReadWhitepaperClient

client = ReadWhitepaperClient()

# List with pagination
page1 = client.list_whitepapers(limit=10, page=1)
page2 = client.list_whitepapers(limit=10, page=2)

# Full detail with sections
solana = client.get_whitepaper("solana")
print(f"{solana.crypto.ticker}: {solana.total_sections} sections")

# Sections and TOC
sections = client.get_sections("cardano")
toc = client.get_toc("cardano", language="ja")

# Translation coverage
cov = client.get_coverage("polkadot")
```

### Glossary

```python
# Browse all terms with pagination
terms = client.list_glossary(limit=20)

# Get a specific term with translations
term = client.get_glossary_term("smart-contract", language="ko")
print(term.translated_term)
print(term.translated_definition)
```

### Search

```python
# Global search across all whitepapers
results = client.search("zero knowledge")

# Scoped search within a single whitepaper
results = client.search("sharding", slug="ethereum")
```

### Stats and Languages

```python
stats = client.get_stats()
print(f"Whitepapers: {stats.whitepapers}")      # 30
print(f"Sections: {stats.sections}")              # 247
print(f"Translations: {stats.translations}")      # 3,458
print(f"Languages: {len(stats.supported_languages)}")  # 15

languages = client.get_languages()
for lang in languages:
    print(f"{lang.code}: {lang.name} ({lang.native_name})")
```

### Graph

```python
graph = client.get_graph()
for edge in graph.edges[:5]:
    print(f"{edge.source} --{edge.type}--> {edge.target}")
```

## Learn More About Blockchain Whitepapers

- **Read**: [Bitcoin Whitepaper](https://readwhitepaper.com/bitcoin/) . [Ethereum Whitepaper](https://readwhitepaper.com/ethereum/) . [All Whitepapers](https://readwhitepaper.com/)
- **Explore**: [Blockchain Glossary](https://readwhitepaper.com/glossary/) . [Whitepaper Graph](https://readwhitepaper.com/graph/)
- **API**: [REST API Docs](https://readwhitepaper.com/developers/)

## Also Available

| Platform | Package | Install |
|----------|---------|---------|
| **npm** | [readwhitepaper](https://www.npmjs.com/package/readwhitepaper) | `npm install readwhitepaper` |
| **Go** | [readwhitepaper-go](https://github.com/dobestan/readwhitepaper-go) | `go get github.com/dobestan/readwhitepaper-go` |
| **Rust** | [readwhitepaper](https://crates.io/crates/readwhitepaper) | `cargo add readwhitepaper` |
| **Ruby** | [readwhitepaper](https://rubygems.org/gems/readwhitepaper) | `gem install readwhitepaper` |

## License

MIT
