ByteForge Crypto Commons

A Python library providing common models and utilities for cryptocurrency projects. This library serves as a foundation for building cryptocurrency-related applications by providing standardized data models and types.

Features

• Standardized Data Models: Well-defined Python dataclasses for representing cryptocurrency data
• Type Safety: Full type hints and documentation for all models
• Comprehensive Market Data: Support for various market metrics and statistics
• Flexible Design: Optional fields for extended data while maintaining core required fields

Installation

pip install byteforge-crypto-commons

Usage

Token State

The TokenState class represents the complete state of a cryptocurrency token at a specific moment in time:

from crypto_commons.types.token_state import TokenState
from crypto_commons.types.quote import Quote
import datetime

# Dates/times are stored as unix-timestamp ints (seconds since the epoch)
now_ts = int(datetime.datetime.now().timestamp())

# Create a quote for USD
quote = Quote(
    base_currency="USD",
    price=50000.0,
    volume_24h=1000000000.0,
    percent_change_1h=1.5,
    percent_change_24h=5.0,
    percent_change_7d=10.0,
    percent_change_30d=20.0,
    market_cap=1000000000000.0,
    last_updated=now_ts
)

# Create a token state
token_state = TokenState(
    id=1,
    name="Bitcoin",
    symbol="BTC",
    timestamp=now_ts,
    quote_map={"USD": quote}
)

Quote

The Quote class represents market data for a cryptocurrency in a specific currency:

from crypto_commons.types.quote import Quote
import datetime

quote = Quote(
    base_currency="USD",
    price=50000.0,
    volume_24h=1000000000.0,
    percent_change_1h=1.5,
    percent_change_24h=5.0,
    percent_change_7d=10.0,
    percent_change_30d=20.0,
    market_cap=1000000000000.0,
    last_updated=int(datetime.datetime.now().timestamp())  # unix timestamp
)

TokenInfo

The TokenInfo class represents basic information about a cryptocurrency token:

from crypto_commons.types.token_info import TokenInfo
import datetime

token_info = TokenInfo(
    id=1,
    rank=1,
    name="Bitcoin",
    symbol="BTC",
    slug="bitcoin",
    status=1,
    is_active=1,
    first_historical_data=int(datetime.datetime(2010, 7, 17).timestamp()),  # unix timestamp
    last_historical_data=int(datetime.datetime.now().timestamp()),  # unix timestamp
    platform=None
)

Data Models

TokenState

Represents the complete state of a cryptocurrency token, including:

• Basic information (id, name, symbol)
• Market data through Quote objects
• Supply metrics (circulating, total, max supply)
• Status indicators (is_active, is_fiat)
• Additional metadata (tags, platform, creation date)

Supply fields (max_supply, circulating_supply, total_supply, and self_reported_circulating_supply) accept fractional or whole token quantities, or None when unknown. They are annotated as Optional[float], which also accepts integers in Python's numeric typing rules. Values retain their original runtime type and value; the model does not coerce, round, or truncate them.

TokenInfo

Represents basic information about a cryptocurrency token, including:

• Core identifiers (id, name, symbol, slug)
• Market rank and status
• Historical data availability
• Platform information (for tokens on other blockchains)
• Active status indicator

Quote

Represents market data for a cryptocurrency in a specific currency, including:

• Price and volume data
• Market capitalization
• Percentage changes over various time periods
• Supply metrics
• Additional market statistics

CryptocurrencyInfo

Rich token metadata (the heavier payload from a cryptocurrency info endpoint), complementing the lightweight TokenInfo. Includes description, logo, tags, date_added / date_launched (unix timestamps), and two nested models:

• CryptocurrencyPlatform — the on-chain platform a token is deployed on (chain identifiers plus the token's contract address); None for native L1s
• CryptocurrencyUrls — categorized URL bundle (website, explorer, source code, social, etc.)

Since version 0.7, contract_addresses lists per-chain deployments as CryptocurrencyPlatform objects. It defaults to an independent empty list on each instance. The existing platform field and positional constructor arguments retain their meaning.

For CMC's contract_address[] payload, SDK parsers should map entry.platform.coin.id/name/symbol/slug to each platform's identity fields and entry.contract_address to token_address. Thus name uses the native coin's name, not entry.platform.name, and id is a CMC ID, not an EVM chain ID. The models store this data; SDKs are responsible for populating it. Consumers should select the desired chain explicitly rather than relying on list order or assuming the single platform represents their desired chain.

Requirements

• Python 3.8 or higher
• No third-party dependencies (stdlib only)

License

This project is licensed under the O'Saasy License - see the LICENSE file for details (https://osaasy.dev/).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

• Jason Byteforge

Project Links

• GitHub Repository
• Issue Tracker