Coinwagon

🪙 Coinwagon

A fast, reliable Python package for cryptocurrency operations built with Rust. Get real-time prices, check wallet balances, and manage multiple addresses with ease.

✨ Features

• 🚀 Fast: Built with Rust for maximum performance
• 💰 Real-time Prices: Get current cryptocurrency prices in multiple fiat currencies
• 🏦 Address Balance: Check balance of individual cryptocurrency addresses
• 📊 Wallet Management: Manage and calculate total value of multiple addresses
• 🔄 Smart Caching: Built-in caching with configurable TTL (5-minute default)
• 🌐 Multiple APIs: Uses BlockCypher and Blockchair APIs with automatic fallback
• 📝 Verbose Mode: Detailed logging for debugging and monitoring
• 🔒 Error Handling: Comprehensive error handling with descriptive messages

🚀 Installation

From PyPI

pip install coinwagon

From Source

git clone https://github.com/randyungaro/coinwagon.git
cd coinwagon
pip install maturin
maturin develop

📖 Quick Start

import coinwagon

# Get Bitcoin price in USD
price = coinwagon.run_command("current-price", ["bitcoin", "usd"])
print(price)  # Output: "67234.50 USD"

# Check Bitcoin address balance
balance = coinwagon.run_command("address-balance", ["bitcoin", "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"])
print(balance)  # Output: "68.91234567 BITCOIN"

# Check wallet balance from file
result = coinwagon.run_command("wallet-balance", ["my_wallet.txt", "usd"])
print(result)
# Output:
# BITCOIN: 1.50000000 BITCOIN = 100851.75 USD
# BITCOIN: 0.25000000 BITCOIN = 16808.63 USD
# Total: 117660.38 USD

🛠️ Usage

1. Get Current Cryptocurrency Price

import coinwagon

# Basic usage
price = coinwagon.run_command("current-price", ["bitcoin", "usd"])
print(f"Bitcoin price: {price}")

# With verbose output
price = coinwagon.run_command("current-price", ["bitcoin", "usd", "--verbose"])

# Different currencies
eur_price = coinwagon.run_command("current-price", ["bitcoin", "eur"])
jpy_price = coinwagon.run_command("current-price", ["ethereum", "jpy"])

2. Check Address Balance

import coinwagon

# Check Bitcoin address
btc_address = "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
balance = coinwagon.run_command("address-balance", ["bitcoin", btc_address])
print(f"Balance: {balance}")

# With verbose output for debugging
balance = coinwagon.run_command("address-balance", ["bitcoin", btc_address, "--verbose"])

3. Wallet Balance Management

Create a wallet file (my_wallet.txt):

# My cryptocurrency addresses
bitcoin,1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
bitcoin,1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
bitcoin,3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy

Check total wallet value:

import coinwagon

# Get total wallet value in USD
result = coinwagon.run_command("wallet-balance", ["my_wallet.txt", "usd"])
print(result)

# With verbose output
result = coinwagon.run_command("wallet-balance", ["my_wallet.txt", "usd", "--verbose"])

📋 Command Reference

current-price

Get real-time cryptocurrency prices.

Usage: coinwagon.run_command("current-price", [crypto, fiat, "--verbose"])

Parameters:

• crypto: Cryptocurrency symbol (e.g., "bitcoin", "ethereum")
• fiat: Fiat currency symbol (e.g., "usd", "eur", "jpy")
• --verbose: Optional flag for detailed output

address-balance

Check balance of a specific cryptocurrency address.

Usage: coinwagon.run_command("address-balance", [crypto, address, "--verbose"])

Parameters:

• crypto: Cryptocurrency symbol (e.g., "bitcoin")
• address: Wallet address to check
• --verbose: Optional flag for detailed output

wallet-balance

Calculate total value of multiple addresses from a file.

Usage: coinwagon.run_command("wallet-balance", [wallet_file, fiat, "--verbose"])

Parameters:

• wallet_file: Path to wallet file (format: crypto,address per line)
• fiat: Fiat currency for total calculation
• --verbose: Optional flag for detailed output

📁 Wallet File Format

Create a text file with one address per line in the format crypto,address:

# Comments start with #
bitcoin,1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
bitcoin,1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
ethereum,0x742d35Cc6634C0532925a3b8D4Fddfac9e2C4cb7

# Empty lines are ignored
bitcoin,3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy

🔧 Advanced Usage

Error Handling

import coinwagon

try:
    balance = coinwagon.run_command("address-balance", ["bitcoin", "invalid_address"])
    print(balance)
except ValueError as e:
    print(f"Invalid arguments: {e}")
except RuntimeError as e:
    print(f"Runtime error: {e}")

Batch Operations

import coinwagon

addresses = [
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
    "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"
]

for addr in addresses:
    try:
        balance = coinwagon.run_command("address-balance", ["bitcoin", addr])
        print(f"{addr}: {balance}")
    except Exception as e:
        print(f"Error checking {addr}: {e}")

🔍 Supported Cryptocurrencies

• Bitcoin (bitcoin)
• Ethereum (ethereum)
• Litecoin (litecoin)
• And many more supported by CoinGecko API

For the complete list, check the CoinGecko API documentation.

⚡ Performance

• Caching: Automatic caching with 5-minute TTL reduces API calls
• Async Operations: Built on Tokio for non-blocking I/O
• Rust Performance: Core operations written in Rust for maximum speed
• Multiple APIs: Automatic fallback ensures reliability

🐛 Troubleshooting

Common Issues

1. API Rate Limits: If you encounter rate limit errors, the built-in caching will help reduce API calls.

2. Invalid Address Format: Make sure cryptocurrency addresses are in the correct format for the specific blockchain.

3. Network Issues: The package will retry failed requests and use fallback APIs when possible.

Debug Mode

Use the --verbose flag to see detailed information about API calls:

result = coinwagon.run_command("address-balance", ["bitcoin", "address", "--verbose"])

🤝 Contributing

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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

---