web3-oracle 0.3.0

A package to retrieve token prices by timestamp

Web3 Oracle

A Python package for retrieving token prices by timestamp, datetime, or Ethereum block number.

Features

• Get token prices by timestamp or datetime
• Get token prices by Ethereum block number
• Fast ETH price lookup by block number using direct mapping
• Fast BTC price lookup by Ethereum block number
• Reference prices for altcoins and less common tokens
• Unified token price lookup with automatic source selection
• Command-line interface

Installation

pip install web3-oracle

Testing

To test the complete package functionality:

# Run complete test suite
python run_tests.py
# OR
make test

# Quick tests only (faster)
python run_tests.py --quick
# OR 
make test-quick

The test suite verifies:

• ✅ ETH/BTC price lookup by timestamp
• ✅ ETH/BTC price lookup by block number (with different rounding logic)
• ✅ Altcoin reference prices
• ✅ CLI functionality
• ✅ Performance benchmarks

Usage

Basic Usage

from web3_oracle import Oracle
from datetime import datetime

# Initialize the oracle
oracle = Oracle()

# Get price by timestamp
eth_price = oracle.get_price("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", 1620518400)

# Get price by datetime
dt = datetime(2022, 1, 15, 12, 0, 0)
btc_price = oracle.get_price_by_datetime("0x2260fac5e5542a773aa44fbcfedf7c193bc2c599", dt)

# Get reference price for less common tokens
uni_price = oracle.get_reference_price("0x1f9840a85d5af5bf1d1762f925bdaddc4201f984")

# Get Ethereum price by block number (WETH/WBTC only)
eth_block_price = oracle.get_price_by_block("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", 15000000)

# Fast ETH price lookup by block (rounded to nearest 10,000)
fast_eth_price = oracle.fast_price(14350000)  # Will use price at block 14350000

# Fast BTC price lookup by block (rounded to nearest 10,000)
fast_btc_price = oracle.fast_btc_price(18039284)  # Will use price at block 18039284

# Unified token price lookup (automatically chooses optimal source) - RECOMMENDED
token_price = oracle.get_token_price(
    token_address="0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",  # UNI token
    block_number=15000000  # Optional
)

Command Line Interface

# Get price by timestamp
web3-oracle get_price 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 1620518400

# Get price by date and time
web3-oracle get_price_by_date 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 "2021-05-08" "12:00:00"

# Get reference price for a token
web3-oracle get_reference_price 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984

# Get price by block number (WETH/WBTC only)
web3-oracle get_price_by_block 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 15000000

# Fast ETH price lookup
web3-oracle fast_price 14350000

# Fast BTC price lookup
web3-oracle fast_btc_price 18039284

# Unified token price lookup (automatically selects best source)
web3-oracle get_token_price 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 --block 15000000
web3-oracle get_token_price 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984

# List all available tokens
web3-oracle list_tokens

Data Sources

The package uses several data sources:

• ethereum_prices.csv: Historical ETH prices by timestamp
• bitcoin_prices.csv: Historical BTC prices by timestamp
• stable_prices.csv: Historical stablecoin prices by timestamp
• altcoins_prices.csv: Reference prices for altcoins and less common tokens
• eth_block_prices.csv: Direct mapping of Ethereum block numbers to ETH prices
• btc_block_prices.csv: Direct mapping of Ethereum block numbers to BTC prices

Tools

The package includes tools for indexing Ethereum blocks and creating price mappings:

# Generate ETH block to price direct mapping
python -m web3_oracle.tools.index_eth_blocks

# Generate BTC price mapping for Ethereum blocks
python -m web3_oracle.tools.index_btc_blocks

Priority Order for Token Prices

The unified get_token_price method uses the following priority order:

1. For WETH with block number: Direct block price mapping (fastest)
2. For WBTC with block number: Direct block price mapping (fast)
3. For any token with reference price: Reference price from altcoins data
4. For any token with block number: Not supported (use timestamp or reference price)
5. For any token with timestamp: Regular timestamp lookup