Metadata-Version: 2.1
Name: pyrfx
Version: 0.1.2
Summary: A comprehensive Python SDK for interacting with RFX contracts and data.
Home-page: https://rfx.exchange
License: MIT
Keywords: SDK,RFX,blockchain,Python,DeFi,DEX,Exchange
Author: Lukas
Author-email: lukas@relative.fi
Maintainer: Lukas
Maintainer-email: lukas@relative.fi
Requires-Python: >=3.10,<4
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: eth-abi (>=5.1.0,<6.0.0)
Requires-Dist: hexbytes (>=1.2.1,<2.0.0)
Requires-Dist: numpy (>=2.1.2,<3.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: ratelimit (>=2.2.1,<3.0.0)
Requires-Dist: tenacity (>=9.0.0,<10.0.0)
Requires-Dist: web3 (>=7.3.0,<8.0.0)
Project-URL: Documentation, https://rfx.exchange
Project-URL: Repository, https://github.com/relative-finance/sdk_v2
Description-Content-Type: text/markdown

[![Tests](https://github.com/relative-finance/sdk_v2/actions/workflows/test.yml/badge.svg)](https://github.com/relative-finance/sdk_v2/actions/workflows/test.yml) [![Deploy](https://github.com/relative-finance/sdk_v2/actions/workflows/deploy.yml/badge.svg?branch=main)](https://github.com/relative-finance/sdk_v2/actions/workflows/deploy.yml)

# RFX Python SDK

A Python-based SDK developed for interacting with RFX Exchange, offering tools and scripts for executing various operations, including trading and liquidity management.

## Table of Contents
- [Usage](#usage)
- [Local Installation](#local-installation)
- [Running Tests](#running-tests)

## Usage
The SDK can be installed via pip:
```sh
pip install pyrfx
```

## Local Installation
The supported Python versions: >= 3.10 <4

To set up the SDK locally, follow these steps:
```sh
mkdir dist/
cd ./dist
poetry build
cd ..
poetry install --with dev
```

## Running Tests
To execute tests:
```sh
poetry run pytest
```


## GET Classes

### AvailableLiquidity Class

The `AvailableLiquidity` class, inheriting from `Data`, is used to calculate and log available liquidity for long and short positions across multiple markets.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, an optional flag (`use_local_datastore`) to specify local datastore usage, and a logging level (`log_level`).
- **Logging**: Uses a logger to provide detailed information on the liquidity computation process.
- **Data Processing**: Implements `_get_data_processing()` to process available liquidity for each market using Web3 contract calls and price data from Oracle.
- **Precision Calculation**: Uses `_get_precision_factors()` to calculate precision factors for long, short, and oracle prices.
- **Token Price Fetching**: The `_get_token_price()` method fetches the recent token prices with error handling.
- **Liquidity Calculation**: The `_log_liquidity()` method calculates and logs the available liquidity for long and short positions, providing insight into the market state.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
available_liquidity: dict = AvailableLiquidity(config=config).get_data()
```

### BorrowAPR Class

The `BorrowAPR` class, inheriting from `Data`, is used to retrieve and calculate the Borrow Annual Percentage Rate (APR) for long and short positions across multiple blockchain markets.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`).
- **Logging**: Uses a logger to provide detailed information during APR data computation.
- **Data Processing**: Implements `_get_data_processing()` to generate and calculate long and short borrow APR for each market, utilizing parallel data processing for efficiency.
- **Threaded Processing**: The class uses `execute_threading()` to handle data retrieval concurrently, improving performance for large datasets.
- **APR Calculation**: The `_process_threaded_output()` method calculates and logs borrow APR values for long and short positions based on the threaded data.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
borrow_apr: dict = BorrowAPR(config=config).get_data()
```

### ClaimableFees Class

The `ClaimableFees` class, inheriting from `Data`, retrieves and calculates the total claimable fees (both long and short) across blockchain markets.

#### Key Features
- **Initialization**: Takes a `ConfigManager` object to handle chain configurations, and a logging level (`log_level`).
- **Logging**: Uses a logger to log detailed information during the fee calculation process.
- **Data Processing**: Implements `_get_data_processing()` to compute the total claimable fees for each market in USD.
- **Threaded Processing**: Uses `execute_threading()` to retrieve data in parallel for long and short claimable fees, boosting performance.
- **Oracle Price Fetching**: Fetches prices via the `OraclePrices` class for accurate USD valuation of fees.
- **Claimable Fee Calculation**: The `_calculate_total_fees()` method computes the total fees and logs the result, converting raw outputs into USD values.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
claimable_fees: dict = ClaimableFees(config=config).get_data()
```

### ContractBalance Class

The `ContractBalance` class, inheriting from `Data`, retrieves the USD balance of contracts in liquidity pools across multiple blockchain markets. It integrates smoothly into the SDK and supports blockchain data retrieval for pool liquidity analysis.

#### Key Features
- **Initialization**: Takes a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`).
- **Logging**: Uses a logger to log information about the pool balances during the data fetching and computation processes.
- **Oracle Price Integration**: Fetches oracle prices via the `OraclePrices` class for calculating the USD equivalent of token balances.
- **Pool Balance Calculation**: Implements `get_pool_balances()` to query token balances from available markets and compute the total value in liquidity pools.
- **Saving Data**: Optionally saves the pool balance data to a JSON file if the `ConfigManager` has `save_to_json` enabled.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
contract_balances: dict = ContractBalance(config=config).get_pool_balances()
```

### Data Base Class

The `Data` class serves as an abstract base class for retrieving and processing blockchain market data. It provides a foundation for handling token prices, managing market information, and saving data in various formats.

#### Key Features
- **Initialization**: Takes a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`). Supports optional use of a local datastore and filtering of swap markets.
- **Logging**: Uses a logger to provide detailed logs during data processing.
- **Market Information Handling**: Includes methods to retrieve long and short token addresses for each market, as well as filtering out swap markets.
- **Data Saving**: Supports saving data in both JSON (`_save_to_json()`) and CSV (`_save_to_csv()`) formats, allowing for easy data export.
- **Oracle Prices Integration**: Fetches prices from `OraclePrices` to facilitate calculations.
- **PnL Calculation**: Includes a method (`_get_pnl()`) to retrieve the Profit and Loss (PnL) and Open Interest with PnL for a market.
- **Market Information Retrieval**: `_get_oracle_prices()` and `_get_token_addresses()` are used for gathering token price information from the reader contract and managing the data associated with markets.
- **Abstract Data Processing**: Defines an abstract `_get_data_processing()` method, intended to be implemented by subclasses for specific data processing logic.

#### Example Usage
As this is an abstract base class, you would use it by extending it in a subclass. Here is a simple example of how to do that:

### EstimateSwapOutput Class

The `EstimateSwapOutput` class is used to estimate the swap output between two tokens on a blockchain network. It utilizes market data, available liquidity, and oracle price information to provide an estimate of the output token amount and price impact.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a dictionary of markets. The logging level (`log_level`) can also be specified.
- **Logging**: Uses a logger to provide detailed information about the token swap process.
- **Swap Output Estimation**: Implements `get_swap_output()` to estimate the amount of output tokens for a given input token and amount, including resolving token addresses and calculating price impacts.
- **Swap Route Determination**: Utilizes `SwapRouter` to determine the optimal swap route based on the available markets.
- **Market Price Integration**: Fetches recent prices using the `OraclePrices` class to accurately calculate the swap output in USD.
- **Support for Multiple Tokens**: Can handle multiple tokens and dynamically resolves token addresses if not provided.

#### Example Usage
```python
# Initialize parameters
parameters: dict[str, str | float] = {
    "start_token_symbol": "WETH",
    "out_token_symbol": "USDC",
    "token_amount": 0.4,
}
config: ConfigManager = ConfigManager(...)
available_markets: dict[ChecksumAddress, dict[str, Any]] = Markets(config=config).get_available_markets()
eso: EstimateSwapOutput = EstimateSwapOutput(config=config, markets=available_markets)
swap_output: dict[str, float] = eso.get_swap_output(
    start_token_symbol=parameters["start_token_symbol"],
    out_token_symbol=parameters["out_token_symbol"],
    token_amount=parameters["token_amount"],
)
```

### FundingFee Class

The `FundingFee` class is responsible for calculating funding fees for long and short positions in RFX blockchain markets. It can retrieve data from a local datastore or directly from an API, perform multithreaded calculations, and log results.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations, an optional flag (`use_local_datastore`) for data retrieval, and a logging level (`log_level`).
- **Data Loading**: Loads open interest data either from a local JSON file or from an API (`_load_open_interest_data()`).
- **Data Processing**: The `_get_data_processing()` method retrieves relevant market data, processes it in a multithreaded manner, and calculates funding APR.
- **Market Information Handling**: Gathers token addresses and oracle prices for each market (`_process_market_key()`).
- **Funding Fee Calculation**: Uses the `_process_threaded_output()` method to calculate funding fees for long and short positions based on oracle prices and interest values.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
funding_fee: dict = FundingFee(config=config).get_data()
```

### Markets Class

The `Markets` class is responsible for retrieving and managing blockchain market data, including token addresses and metadata for different markets. It provides methods for accessing market-specific information and integrates seamlessly with the overall SDK.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations, and a logging level (`log_level`).
- **Market Data Retrieval**: Retrieves and processes raw market data using a reader contract, organizing it into a structured dictionary (`_process_markets()`).
- **Token Address Access**: Provides methods to access long, short, and index token addresses for each market (`get_long_token_address()`, `get_short_token_address()`, `get_index_token_address()`).
- **Market Metadata**: Retrieves additional market-specific metadata, such as the market symbol, decimal factors, and whether a market is synthetic.
- **Market Filtering**: Filters out markets that are not in the signed prices API to ensure only live, valid markets are processed.
- **Swap Market Handling**: Handles both standard and swap markets, with logic to generate appropriate market symbols and metadata.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
available_markets: dict = Markets(config=config).get_available_markets()
```

### OpenInterest Class

The `OpenInterest` class retrieves and processes open interest data for long and short positions across RFX blockchain markets. It uses oracle price data and multi-threaded calculations to provide efficient and accurate data analysis.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations and a logging level (`log_level`).
- **Open Interest Calculation**: Uses the `_get_data_processing()` method to calculate open interest by fetching market data and using multi-threaded execution for efficiency.
- **Oracle Price Integration**: Retrieves oracle prices using the `OraclePrices` class to determine market pricing information.
- **Multi-threading Execution**: The `_execute_multithreading()` method is used to process multiple calculations concurrently, improving performance.
- **Precision Handling**: Determines precision factors for synthetic and non-synthetic markets (`_get_precision_factor()`) to accurately calculate open interest values.
- **Logging Results**: Logs the final calculated values for long and short open interest, providing a clear summary of the market data.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
open_interest: dict = OpenInterest(config=config).get_data()
```

### OpenPositions Class

The `OpenPositions` class is responsible for retrieving and processing open positions for a given blockchain address. It fetches open positions from a reader contract and processes them into a structured format, including detailed metrics like leverage and profit percentage.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, an optional address for querying, and a logging level (`log_level`).
- **Open Position Retrieval**: Uses the `get_open_positions()` method to fetch and process all open positions for the given address.
- **Market Data Integration**: Integrates with available market data to provide context and symbols for each open position.
- **Leverage and Price Calculation**: Calculates key metrics for each open position, including entry price, leverage, mark price, and profit percentage (`_calculate_position_metrics()`).
- **Oracle Price Integration**: Uses the `OraclePrices` class to retrieve recent oracle prices for calculating the mark price of a position.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
open_positions: dict = OpenPositions(config=config).get_open_positions()
```

### OraclePrices Class

The `OraclePrices` class is responsible for fetching and processing the latest signed token prices from the RFX API for various blockchain networks. It integrates with the `ConfigManager` to configure the relevant API endpoint based on the blockchain network.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for blockchain configurations and a logging level (`log_level`).
- **Price Retrieval**: Uses the `get_recent_prices()` method to make a GET request to the RFX Oracle API and retrieve signed token prices.
- **Request Handling**: Implements error handling for request failures (`_make_query()`) and validates the response format (`_process_output()`).
- **Logging**: Logs the progress of requests and the processing of token prices.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
prices: dict = OraclePrices(config=config).get_recent_prices()
```

### PoolTVL Class

The `PoolTVL` class retrieves and calculates the Total Value Locked (TVL) in USD across all pools for a given blockchain. It uses data from oracle prices and a data store contract to determine the value of tokens in each pool.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations and a logging level (`log_level`). Also initializes oracle price data and data store contract.
- **TVL Calculation**: The `get_pool_balances()` method calculates the TVL for each pool by querying token balances and calculating their equivalent USD values.
- **Oracle Price Integration**: Uses the `OraclePrices` class to fetch the most recent prices of tokens, which are then used to calculate USD values.
- **Data Store Contract Integration**: Uses a Web3 contract to query the current token balances for both long and short positions in each pool.
- **Logging and Data Saving**: Logs detailed TVL information for each market and saves the TVL data to JSON and/or CSV formats, if configured to do so.

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
pool_tvl_data: dict = PoolTVL(config=config).get_pool_balances()
```

### RPPrices Class

The `RPPrices` class is responsible for calculating Reward Pool (RP) prices for various market actions, such as withdrawal, deposit, and trading, in the blockchain ecosystem. It extends the `Data` class to use common market and token retrieval functionalities and processes market prices using contract queries.

#### Key Features
- **Initialization**: Accepts a `ConfigManager` object for chain-specific configurations, a logging level (`log_level`), and initializes a reader contract to interact with the blockchain.
- **Market Actions**: Provides methods to calculate RP prices for different actions:
  - `get_price_withdraw()`: Fetches RP prices for withdrawing from a liquidity pool.
  - `get_price_deposit()`: Fetches RP prices for depositing into a liquidity pool.
  - `get_price_traders()`: Fetches RP prices for traders.
- **Multithreading**: Implements threading for price calculations to improve performance when querying multiple markets concurrently.
- **Market Data Preparation**: Uses `_prepare_market_data()` to gather the relevant market addresses and token information needed for price queries.
- **Data Processing**: Uses `_process_output()` to convert the raw outputs into a more structured and human-readable format.
- **Data Saving**: Saves the processed RP prices to JSON or CSV formats if configured (`_save_output()`).

#### Example Usage
```python
config: ConfigManager = ConfigManager(...)
rp_prices: dict = RPPrices(config=config).get_price_traders()
```

## Order Classes




## Utils

