rustywallet-checker

A fast, reliable Rust library for checking cryptocurrency wallet balances. Supports Bitcoin and Ethereum with automatic fallback between multiple API providers.

Features

• Bitcoin Balance Checking: Support for all address types (Legacy, SegWit, Taproot)
• Ethereum Balance Checking: Native ETH balance queries
• Async/Await Support: Built with Tokio for high-performance async operations
• Multiple API Providers: Automatic fallback between providers for reliability
• Rate Limit Handling: Built-in retry logic and rate limit detection
• Comprehensive Error Handling: Detailed error types for different failure scenarios
• Zero-Copy Parsing: Efficient JSON parsing with minimal allocations
• Type Safety: Strong typing for addresses and balance amounts

Installation

Add this to your Cargo.toml:

[dependencies]
rustywallet-checker = "0.1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Quick Start

use rustywallet_checker::{check_btc_balance, check_eth_balance};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check Bitcoin balance
    let btc_balance = check_btc_balance("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa").await?;
    println!("BTC Balance: {} satoshis", btc_balance.balance);
    
    // Check Ethereum balance
    let eth_balance = check_eth_balance("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045").await?;
    println!("ETH Balance: {} ETH", eth_balance.balance_eth);
    
    Ok(())
}

Bitcoin Balance Checking

Supported Address Types

• Legacy (P2PKH): Addresses starting with 1
• SegWit (P2WPKH): Addresses starting with bc1q
• Taproot (P2TR): Addresses starting with bc1p

Example

use rustywallet_checker::{check_btc_balance, BtcBalance};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let balance: BtcBalance = check_btc_balance("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa").await?;
    
    println!("Confirmed balance: {} satoshis", balance.balance);
    println!("Unconfirmed balance: {} satoshis", balance.unconfirmed);
    println!("Total received: {} satoshis", balance.total_received);
    println!("Transaction count: {}", balance.tx_count);
    
    Ok(())
}

API Providers

• Primary: blockstream.info API
• Fallback: blockchain.info API

Ethereum Balance Checking

Example

use rustywallet_checker::{check_eth_balance, EthBalance};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let balance: EthBalance = check_eth_balance("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045").await?;
    
    println!("Balance in wei: {}", balance.balance_wei);
    println!("Balance in ETH: {}", balance.balance_eth);
    
    Ok(())
}

API Providers

Multiple public Ethereum RPC endpoints with automatic failover:

• Cloudflare ETH Gateway
• Ankr Public RPC
• Public Node RPC

Async Usage

All functions are async and return Futures. Use with any async runtime:

use rustywallet_checker::check_btc_balance;
use tokio;

// With Tokio
#[tokio::main]
async fn main() {
    let balance = check_btc_balance("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa").await.unwrap();
    println!("Balance: {}", balance.balance);
}

// With async-std
use async_std::task;

fn main() {
    task::block_on(async {
        let balance = check_btc_balance("1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa").await.unwrap();
        println!("Balance: {}", balance.balance);
    });
}

Error Handling

The library provides comprehensive error handling with the CheckerError enum:

use rustywallet_checker::{check_btc_balance, CheckerError};

match check_btc_balance("invalid-address").await {
    Ok(balance) => {
        println!("Balance: {} satoshis", balance.balance);
    }
    Err(CheckerError::InvalidAddress(addr)) => {
        eprintln!("Invalid address format: {}", addr);
    }
    Err(CheckerError::RateLimited) => {
        eprintln!("Rate limited by API provider, try again later");
    }
    Err(CheckerError::NetworkError(e)) => {
        eprintln!("Network error: {}", e);
    }
    Err(CheckerError::ApiError(msg)) => {
        eprintln!("API error: {}", msg);
    }
    Err(CheckerError::ParseError(e)) => {
        eprintln!("Failed to parse response: {}", e);
    }
}

Error Types

• InvalidAddress: The provided address format is invalid
• RateLimited: API rate limit exceeded
• NetworkError: Network connectivity issues
• ApiError: API provider returned an error
• ParseError: Failed to parse API response

API Reference

Functions

check_btc_balance(address: &str) -> Result<BtcBalance, CheckerError>

Checks the balance of a Bitcoin address.

Parameters:

• address: Bitcoin address string (Legacy, SegWit, or Taproot)

Returns:

• Ok(BtcBalance): Balance information
• Err(CheckerError): Error details

check_eth_balance(address: &str) -> Result<EthBalance, CheckerError>

Checks the balance of an Ethereum address.

Parameters:

• address: Ethereum address string (0x prefixed)

Returns:

• Ok(EthBalance): Balance information
• Err(CheckerError): Error details

Types

BtcBalance

pub struct BtcBalance {
    pub balance: u64,        // Confirmed balance in satoshis
    pub unconfirmed: u64,    // Unconfirmed balance in satoshis
    pub total_received: u64, // Total received in satoshis
    pub tx_count: u32,       // Number of transactions
}

EthBalance

pub struct EthBalance {
    pub balance_wei: String, // Balance in wei (as string to handle large numbers)
    pub balance_eth: f64,    // Balance in ETH (converted from wei)
}

CheckerError

pub enum CheckerError {
    InvalidAddress(String),
    RateLimited,
    NetworkError(String),
    ApiError(String),
    ParseError(String),
}

License

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