Metadata-Version: 2.4
Name: cryptologo
Version: 0.1.0
Summary: Python client for crypto-logo.com — 413 cryptocurrency logos in SVG, PNG, WebP, ICO
Project-URL: Homepage, https://crypto-logo.com
Project-URL: Documentation, https://crypto-logo.com/api/docs/
Project-URL: Repository, https://github.com/dobestan/cryptologo-python
Project-URL: API Reference, https://crypto-logo.com/api/docs/
Author-email: dobestan <dobestan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,bitcoin,branding,crypto,cryptocurrency,ethereum,icon,logo,png,svg
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 :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# cryptologo

[![PyPI](https://img.shields.io/pypi/v/cryptologo)](https://pypi.org/project/cryptologo/)
[![Python](https://img.shields.io/pypi/pyversions/cryptologo)](https://pypi.org/project/cryptologo/)
[![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/cryptologo/)

Python client for [crypto-logo.com](https://crypto-logo.com) — the cryptocurrency logo database with 413 coins in SVG, PNG, WebP, JPEG, and ICO formats. Zero dependencies (stdlib `urllib` only).

Every logo is available as a scalable SVG vector and pre-generated raster derivatives in 13 standard sizes (16px to 2000px). Logos are served from Cloudflare R2 CDN with immutable cache headers for production-grade performance. The dataset is extracted from [crypto-logo.com](https://crypto-logo.com), which tracks logo assets for Bitcoin, Ethereum, Solana, and 410+ other cryptocurrencies ranked by market cap.

> **Try the interactive logo browser at [crypto-logo.com](https://crypto-logo.com)** — [Bitcoin logo](https://crypto-logo.com/bitcoin-btc/), [Ethereum logo](https://crypto-logo.com/ethereum-eth/), [API docs](https://crypto-logo.com/api/docs/)

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [List All Coins](#list-all-coins)
  - [Download Logos](#download-logos)
  - [Generate CDN URLs](#generate-cdn-urls)
  - [Fetch Logo Variants and History](#fetch-logo-variants-and-history)
- [Cryptocurrency Logo Standards](#cryptocurrency-logo-standards)
  - [SVG vs PNG — When to Use Which](#svg-vs-png--when-to-use-which)
  - [Standard Sizes for Crypto Logos](#standard-sizes-for-crypto-logos)
  - [Brand Color Consistency](#brand-color-consistency)
- [API Reference](#api-reference)
- [API Endpoints](#api-endpoints)
- [Learn More About Cryptocurrency Logos](#learn-more-about-cryptocurrency-logos)
- [Also Available](#also-available)
- [License](#license)

## Install

```bash
pip install cryptologo
```

## Quick Start

```python
from cryptologo import CryptoLogo

client = CryptoLogo()

# List all 413 coins sorted by market cap
coins = client.list_coins()
for coin in coins[:5]:
    print(f"{coin.name} ({coin.ticker}) — rank #{coin.market_cap_rank}")
# Bitcoin (BTC) — rank #1
# Ethereum (ETH) — rank #2
# Tether (USDT) — rank #3

# Download Bitcoin logo as SVG
client.download_logo("bitcoin-btc", "svg")
# Saved: bitcoin-btc.svg

# Download Ethereum logo as 512x512 PNG
client.download_logo("ethereum-eth", "png", width=512)
# Saved: ethereum-eth-512x512.png
```

## What You Can Do

### List All Coins

The `list_coins()` method returns all 413 active coins with metadata including name, ticker, slug, format availability (PNG/SVG), localized search terms in 14 languages, and CoinGecko market cap ranking.

| Field | Type | Description |
|-------|------|-------------|
| `name` | str | Display name (e.g., "Bitcoin") |
| `ticker` | str | Trading symbol (e.g., "BTC") |
| `slug` | str | URL identifier (e.g., "bitcoin-btc") |
| `has_png` | bool | PNG logo available |
| `has_svg` | bool | SVG vector available |
| `search_terms` | list | Names in Korean, Japanese, Chinese, etc. |
| `market_cap_rank` | int/None | CoinGecko ranking |

```python
from cryptologo import CryptoLogo

client = CryptoLogo()
coins = client.list_coins()

# Filter coins that have SVG logos
svg_coins = [c for c in coins if c.has_svg]
print(f"{len(svg_coins)} coins have SVG logos")  # 413 coins have SVG logos

# Find a specific coin by ticker
btc = next((c for c in coins if c.ticker == "BTC"), None)
if btc:
    print(f"{btc.name}: slug={btc.slug}, rank=#{btc.market_cap_rank}")
```

### Download Logos

Fetch logo image data as bytes or save directly to a file. SVG logos require no size parameter. Raster formats (PNG, WebP, JPEG, ICO) require a width.

```python
from cryptologo import CryptoLogo

client = CryptoLogo()

# Get raw SVG bytes — scalable vector, ideal for web
svg_bytes = client.get_logo("bitcoin-btc", "svg")

# Get PNG at specific size — pre-generated, not resized on-the-fly
png_bytes = client.get_logo("solana-sol", "png", width=256)

# Download to file with auto-generated filename
path = client.download_logo("bitcoin-btc", "svg")
print(path)  # bitcoin-btc.svg

# Download to specific path
path = client.download_logo("ethereum-eth", "png", "logos/eth.png", width=128)

# ICO format for favicons (sizes: 16, 32, 48, 64, 128, 256)
client.download_logo("bitcoin-btc", "ico", width=32)

# OG image with white background (1200x630 for social sharing)
client.download_logo("bitcoin-btc", "png", width=1200, height=630, bg="FFFFFF")
```

### Generate CDN URLs

Build URLs for direct embedding in HTML, Markdown, or documentation. The CDN serves pre-generated derivatives from Cloudflare R2 with `Cache-Control: immutable` — no Django server overhead.

```python
from cryptologo import CryptoLogo

client = CryptoLogo()

# CDN URL for fast image display (recommended for <img> tags)
url = client.get_cdn_url("bitcoin-btc", "webp", 128)
# https://cdn.crypto-logo.com/logos/bitcoin-btc/128x128/transparent.webp

# CDN URL for SVG vector
url = client.get_cdn_url("ethereum-eth", "svg")
# https://cdn.crypto-logo.com/logos/ethereum-eth/vector.svg

# API URL (for downloads with Content-Disposition header)
url = client.get_logo_url("bitcoin-btc", "png", width=512, height=512)
# https://crypto-logo.com/api/logo/bitcoin-btc.png?w=512&h=512
```

### Fetch Logo Variants and History

Some coins have alternate logo designs (full wordmark, diamond shape, animated) and historical versions showing brand evolution.

```python
from cryptologo import CryptoLogo

client = CryptoLogo()

# Get a logo variant (alternate design)
full_logo = client.get_asset("versions/bitcoin-btc-full.svg")

# Get a historical logo version
old_logo = client.get_asset("history/bitcoin-btc-2009.png")
```

## Cryptocurrency Logo Standards

### SVG vs PNG — When to Use Which

Cryptocurrency projects publish official logos in SVG (vector) and PNG (raster). Choosing the right format depends on the use case.

| Use Case | Recommended Format | Reason |
|----------|--------------------|--------|
| Website/app UI | SVG | Scales to any resolution, small file size (~2-15KB) |
| Exchange listing | PNG 512x512 | Standard requirement for CoinGecko, CoinMarketCap |
| Mobile app icon | PNG 128x128 or 256x256 | iOS/Android require raster at specific sizes |
| Favicon | ICO 32x32 or SVG | ICO for legacy browsers, SVG for modern |
| Social media / OG image | PNG 1200x630 | Open Graph standard with solid background |
| Print / merch | SVG | Infinite scalability without quality loss |
| Documentation | SVG or PNG 64-128px | SVG preferred, PNG for Markdown compatibility |
| Email signature | PNG 48-64px | Most email clients don't render SVG |

### Standard Sizes for Crypto Logos

The industry has converged on standard sizes. CryptoLogo pre-generates all 13 standard sizes for each coin.

| Size | Common Use |
|------|-----------|
| 16x16 | Favicon, inline text icons |
| 32x32 | Favicon, small UI elements |
| 48x48 | Tab icons, small badges |
| 64x64 | List items, table cells |
| 96x96 | Grid thumbnails |
| 128x128 | Card previews, mobile |
| 200x200 | Profile images |
| 256x256 | Medium detail views |
| 400x400 | Large cards |
| 512x512 | Exchange listing standard |
| 1024x1024 | High-DPI displays |
| 2000x2000 | Maximum quality raster |
| 1200x630 | OG image (social sharing) |

### Brand Color Consistency

Each cryptocurrency has an official brand color (e.g., Bitcoin's #F7931A orange, Ethereum's #627EEA purple). CryptoLogo stores the `brand_color` for each coin, enabling consistent color theming in portfolio apps, dashboards, and data visualizations.

Notable brand colors:
- **Bitcoin**: #F7931A (orange) — designed by Satoshi-era contributor
- **Ethereum**: #627EEA (purple) — from the Ethereum Foundation brand kit
- **Solana**: #9945FF (violet) — gradient-based identity system
- **Cardano**: #0033AD (blue) — academic/formal positioning
- **Dogecoin**: #C2A633 (gold) — matches the Shiba Inu meme aesthetic

## API Reference

| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `list_coins()` | — | `list[Coin]` | All 413 coins with metadata |
| `get_logo(slug, fmt, ...)` | slug, fmt, width, height, bg | `bytes` | Logo image bytes |
| `get_logo_url(slug, fmt, ...)` | slug, fmt, width, height, bg | `str` | API URL for logo |
| `get_cdn_url(slug, fmt, width)` | slug, fmt, width, cdn_domain | `str` | CDN URL for embedding |
| `download_logo(slug, fmt, dest, ...)` | slug, fmt, dest, width, height, bg | `Path` | Save logo to file |
| `get_asset(file_path)` | file_path | `bytes` | Variant/history asset |

## API Endpoints

The crypto-logo.com REST API is free, requires no authentication, and supports CORS.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/logo/{slug}.{fmt}` | Logo image (png, svg, webp, jpeg, ico) |
| GET | `/api/coins.json` | All coins metadata (JSON array) |
| GET | `/api/asset/{path}` | Variant and history files |
| GET | `/api/docs/` | Interactive API documentation |
| GET | `/api/schema/` | OpenAPI 3.0 schema |

### Example

```bash
# List all coins
curl -s "https://crypto-logo.com/api/coins.json" | python3 -m json.tool | head -20

# Download Bitcoin SVG
curl -O "https://crypto-logo.com/api/logo/bitcoin-btc.svg"

# Download Ethereum PNG 256x256
curl -O "https://crypto-logo.com/api/logo/ethereum-eth.png?w=256&h=256"

# Get OG image with white background
curl -O "https://crypto-logo.com/api/logo/bitcoin-btc.png?w=1200&h=630&bg=FFFFFF"
```

```json
[
  {
    "name": "Bitcoin",
    "ticker": "BTC",
    "slug": "bitcoin-btc",
    "has_png": true,
    "has_svg": true,
    "search_terms": ["\ube44\ud2b8\ucf54\uc778", "\u30d3\u30c3\u30c8\u30b3\u30a4\u30f3"],
    "market_cap_rank": 1
  }
]
```

Full API documentation at [crypto-logo.com/api/docs/](https://crypto-logo.com/api/docs/).

## Learn More About Cryptocurrency Logos

- **Browse**: [All Coins](https://crypto-logo.com/) · [Categories](https://crypto-logo.com/categories/) · [Formats](https://crypto-logo.com/formats/)
- **API**: [API Docs](https://crypto-logo.com/api/docs/) · [OpenAPI Schema](https://crypto-logo.com/api/schema/)

## Also Available

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

## License

MIT
