Metadata-Version: 2.1
Name: CryptoExplorer
Version: 1.0.0
Summary: Simplified cryptocurrency and blockchain data extraction
Author: Archie Marques
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tqdm>=4.65.0
Requires-Dist: klib>=1.1.1
Requires-Dist: ccxt>=4.0.86
Requires-Dist: pandas>=2.0.3
Requires-Dist: pyarrow>=12.0.0
Requires-Dist: numpy>=1.23.5
Requires-Dist: moralis==0.1.49
Requires-Dist: pytest

## Overview

The CryptoExplorer repository offers a unified interface to query blockchain data, monitor trading activities, retrieve exchange price histories, and access Bitcoin network health metrics. Explore and extend the modules to suit your specific use-case.

It enables you to:

- Retrieve swap transaction data from the blockchain.
- Extract and convert OHLCV price data via exchanges.
- Fetch comprehensive Bitcoin on-chain metrics.

## Glossary

- **swap**: An action performed by a user when executing a trade on a DEX Exchange.
- **txid**: Transaction ID.

## API Classes & Usage

### AccountAPI

This high-level API handler chains multiple providers to retrieve swap transaction data from the blockchain.

Methods:

- __get_wallet_swaps(wallet: str, coin_name: bool = False)__  
   Extracts all swap transactions for a wallet.  
   _Note_: setting the `coin_name` param to `True` will include the names of the tokens involved.
- __get_buys(wallet_address: str, asset_name: str = "WBTC")__  
   Retrieves buy transactions from the swap data for the specified asset.
- __get_sells(wallet_address: str, asset_name: str = "WBTC")__  
   Retrieves sell transactions from the swap data for the specified asset.

Example:

```py
from crypto_explorer import AccountAPI

api = AccountAPI(api_key="YOUR_MORALIS_API_KEY", verbose=True)
wallet = "0xYourWalletAddress"

# Retrieve all swap transactions with coin names
swaps = api.get_wallet_swaps(wallet, coin_name=True)

# Retrieve buy transactions for asset "WBTC"
buys = api.get_buys(wallet, asset_name="WBTC")

# Retrieve sell transactions for asset "WBTC"
sells = api.get_sells(wallet, asset_name="WBTC")

```

### BlockscoutAPI

Provides methods to access swap data from the Blockscout API.

Methods:

- __get_transactions(txid: str, coin_name: bool = False)__  
   Extracts swap transaction data for a specific txid.
- __get_account_transactions(wallet: str, coin_names: bool = False)__  
   Retrieves all swap transactions for a wallet.

_Note_: setting the `coin_name` param to `True` will include the names of the tokens involved.

Example:

```py
from crypto_explorer import BlockscoutAPI

blockscout = BlockscoutAPI(verbose=True)
txid = "0xTransactionIDExample"

# Get swap transaction details for a specific txid
transaction = blockscout.get_transactions(txid, coin_name=True)

# Get all swap transactions for a wallet
wallet_tx = blockscout.get_account_transactions("0xYourWalletAddress", coin_names=True)

```

### MoralisAPI

Extracts swap transactions and historical token balance data using the Moralis API.

Methods:

- __get_account_swaps(wallet: str, coin_name: bool = False, add_summary: bool = False)__  
   Retrieves all swap transactions (swaps) for a wallet.  
   _Note_: setting the `coin_name` param to `True` will include the names of the tokens involved.  
   _Note 2_: setting the `add_summary` param to `True` will includes transaction summaries.
- __get_wallet_token_balances_history(wallet_address: str, token_address: str, kwargs)__  
   Retrieves a walletâ€™s historical token balances to track portfolio changes.

Example:

```py
from crypto_explorer import MoralisAPI

moralis = MoralisAPI(verbose=True, api_key="YOUR_MORALIS_API_KEY")
wallet = "0xYourWalletAddress"

# Get swap transactions with coin names and summary
swaps = moralis.get_account_swaps(wallet, coin_name=True, add_summary=True)

# Get historical token balances (portfolio history)
history = moralis.get_wallet_token_balances_history(wallet, token_address="0xTokenAddress")

```

### CcxtAPI

Retrieves OHLCV (price) market data from exchanges via the CCXT library.

Methods:

- __get_all_klines(until: int | None = None)__  
   Extracts OHLCV price data for the configured symbol and timeframe.
- __to_OHLCV()__  
   Converts the fetched OHLCV data into a pandas DataFrame.  
   _Note_: Call get_all_klines before to_OHLCV to avoid a ValueError.

Example:

```py
import ccxt
from crypto_explorer import CcxtAPI

# Create a CCXT API instance for BTCUSDT on Binance
ccxt_api = CcxtAPI("BTCUSDT", "2h", ccxt.binance(), verbose="Text")

# Fetch OHLCV price data
ccxt_api.get_all_klines()

# Convert fetched data to a DataFrame
ohlcv_df = ccxt_api.to_OHLCV().data_frame
print(ohlcv_df)

```

### QuickNodeAPI

Extracts Bitcoin on-chain information using QuickNode endpoints.

Methods:

- __get_blockchain_info()__  
   Extracts general on-chain Bitcoin information such as network type, block height, sync progress, and protocol upgrade status.
- __get_block_stats(block_height: int)__  
   Extracts detailed Bitcoin block statistics including transaction fees, size metrics, UTXO changes, SegWit data, and economic figures (in satoshis).

Example:

```py
from crypto_explorer import QuickNodeAPI

# List your QuickNode API URLs
api_keys = ["https://your.quicknode.endpoint"]

quicknode = QuickNodeAPI(api_keys, default_api_key_idx=0)

# Retrieve general Bitcoin blockchain information
info = quicknode.get_blockchain_info()
print(info)

# Retrieve statistics for a specific Bitcoin block
block_stats = quicknode.get_block_stats(680000)
print(block_stats)

```

## Repository Structure

- **api/**:

   - `account_api.py`: Manages API handlers and chaining via the `AccountAPI`.
   - `blockscout_api.py`: Contains the `BlockscoutAPI` for accessing blockchain swap data.
   - `ccxt_api.py`: Provides the `CcxtAPI` to extract market data (OHLCV) from exchanges.
   - `moralis_api.py`: Implements the `MoralisAPI` for querying swap transactions and wallet token balances.
   - `quicknode_api.py`: Contains the `QuickNodeAPI` for Bitcoin on-chain information.
   - **tests/**: Unit tests for modules in the `api/` directory.

- __custom_exceptions/__: Custom exception classes.
- **utils/**: Utility functions and classes (e.g., time conversions, logging, kline utilities).
- **tests/**: General unit tests for repository functionality.

## Tests

Unit tests are provided in the tests/ directories within each module.

To run the tests, execute:

```sh
python -m pytest

```

## Setup & Installation

1. Clone the repository:

```bash
git clone https://github.com/m-marqx/CryptoExplorer.git
cd CryptoExplorer 

```

2. Set up a virtual environment:

```bash
python -m venv venv
source venv/bin/activate  # For Windows: venv\Scripts\activate

```

3. Install dependencies:

```sh
pip install -r requirements.txt

```

*Note*: Ensure you are using Python 3.11 or a compatible version.

## Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
