cryptils 0.1.0a4

A simple python utility library for representing cryptocurrency amounts

cryptils

An utility library for representing cryptocurrency amounts in Python.

---

Installation

pip install cryptils

Quick Start

from cryptils import BTC, ETH, USDC, USDT

# Create amounts with exact decimal precision
btc = BTC("1.5")
print(btc)  # 1.50000000 BTC

eth = ETH("2.0")
print(eth)  # 2.000000000000000000 ETH

# Arithmetic with other amounts
result = BTC("0.5") + BTC("0.25")
print(result)  # 0.75000000 BTC

# Arithmetic with built-in types (int, float, Decimal)
from decimal import Decimal

btc = BTC("1.0")
print(btc + 0.5)  # 1.50000000 BTC (added float)
print(btc + 2)  # 3.00000000 BTC (added int)
print(btc + Decimal("0.5"))  # 1.50000000 BTC (added Decimal)
print(2 * btc)  # 2.00000000 BTC (int * BTC)
print(10 - BTC("2.5"))  # 7.50000000 BTC (int - BTC)

# Different currencies maintain their own precision
usdc = USDC("100")
print(usdc)  # 100.000000 USDC

# Access the raw Decimal value
print(btc.to_decimal())  # Decimal('1.50000000')

# Get the formatted string explicitly
print(btc.to_string())  # 1.50000000 BTC

Features

• Uses decimal.Decimal internally to avoid floating-point errors.
• Consistent precision handling per currency (e.g., 8 decimals for BTC, 6 for USDC).
• Simple, explicit API designed for financial precision.

Pydantic Support

CryptoAmount subclasses work as Pydantic v2 field types:

from pydantic import BaseModel
from cryptils import BTC, ETH, USDC

class WalletBalance(BaseModel):
    btc: BTC
    eth: ETH
    usdc: USDC

wallet = WalletBalance(btc="1.5", eth=2, usdc=100.0)
print(wallet.model_dump_json())
# {"btc":"1.50000000","eth":"2.000000000000000000","usdc":"100.000000"}

Requires Pydantic v2 (pip install pydantic).

Development

This project uses uv for environment management, ruff for linting and formatting, and tox for testing across Python versions.

# Setup environment
uv sync

# Run tests
uv run pytest

# Run tests across all supported Python versions
uv run tox

# Format and lint
uv run ruff check --fix .
uv run ruff format .

# Install pre-commit hooks
uv run pre-commit install

# Run pre-commit on all files
uv run pre-commit run --all-files

License

This project is licensed under the terms of the MIT license.