fx-sdk 0.1.0

A Pythonic SDK for the f(x) Protocol

f(x) Protocol Python SDK

Creator: Christopher Stampar (@cstampar)
Date: December 20, 2025

A Pythonic, production-grade SDK for interacting with the f(x) Protocol. This client abstracts Web3.py boilerplate and provides human-readable interfaces for both V1 and V2 products.

✨ Key Features

• Modular Design: Clean separation of read and write operations.
• Precision First: Uses Python Decimal for all human-readable amounts.
• Full Protocol Coverage: Supports fxUSD, fETH, rUSD, veFXN, Gauges, and all x tokens (xETH, xCVX, xWBTC, xeETH, xezETH, xstETH, xfrxETH).
• Infrastructure-Aware: Direct integration with the Pool Manager, Treasury, and Multi-Path Converter.
• V1 & V2 Support: Robust support for both legacy and current protocol versions.

🚀 Quick Start

Read-Only Mode (No Private Key Required)

from fx_sdk.client import ProtocolClient

# Initialize in read-only mode
client = ProtocolClient(
    rpc_url="https://mainnet.infura.io/v3/YOUR_API_KEY"
)

# Read balance
fxusd_balance = client.get_fxusd_balance()
print(f"fxUSD Balance: {fxusd_balance}")

# Fetch protocol NAV
nav = client.get_treasury_nav()
print(f"Base NAV: {nav['base_nav']}")

Write Mode (Secure Authentication Options)

The SDK supports multiple secure methods for wallet authentication. Never hardcode private keys in your scripts!

Option 1: Environment Variable (Recommended for Production)

# Set in your shell or deployment environment
export FX_PROTOCOL_PRIVATE_KEY="0x..."

from fx_sdk.client import ProtocolClient

client = ProtocolClient(
    rpc_url="https://mainnet.infura.io/v3/YOUR_API_KEY"
    # Private key automatically loaded from FX_PROTOCOL_PRIVATE_KEY
)

Option 2: .env File (Recommended for Local Development)

Create a .env file in your project root:

FX_PROTOCOL_PRIVATE_KEY=0x...

from fx_sdk.client import ProtocolClient

client = ProtocolClient(
    rpc_url="https://mainnet.infura.io/v3/YOUR_API_KEY"
    # Private key automatically loaded from .env file
)

Important: Add .env to your .gitignore to prevent committing secrets!

Option 3: Google Colab Secrets

from fx_sdk.client import ProtocolClient

# Store your private key in Colab secrets: 'fx_protocol_private_key'
client = ProtocolClient(
    rpc_url="https://mainnet.infura.io/v3/YOUR_API_KEY"
    # Private key automatically loaded from Colab secrets
)

Option 4: Browser Wallet (MetaMask, etc.)

from fx_sdk.client import ProtocolClient

client = ProtocolClient(
    rpc_url="https://mainnet.infura.io/v3/YOUR_API_KEY",
    use_browser_wallet=True  # Connects to MetaMask or other browser extension
)

# Transactions will prompt user approval in browser
tx_hash = client.mint_f_token(market_address="0x...", base_in=1.0)

Option 5: Explicit Private Key (Not Recommended)

# ⚠️ Only use for testing! Never commit this to version control.
client = ProtocolClient(
    rpc_url="https://mainnet.infura.io/v3/YOUR_API_KEY",
    private_key="0x..."  # Explicit parameter (lowest priority)
)

Authentication Priority Order

The SDK checks for credentials in this order:

1. Explicit private_key parameter
2. FX_PROTOCOL_PRIVATE_KEY environment variable
3. .env file (FX_PROTOCOL_PRIVATE_KEY)
4. Google Colab secret (fx_protocol_private_key)
5. Browser wallet (if use_browser_wallet=True)

📂 Project Structure

• fx_sdk/: Core SDK logic.
  • client.py: The main ProtocolClient.
  • constants.py: Contract addresses and system configurations.
  • utils.py: Unit conversion and formatting utilities.
  • exceptions.py: Custom exception classes.
• abis/: JSON ABI files for all supported contracts.
• features.md: Detailed list of SDK capabilities.

🛠 Project Status & Progress

The SDK is currently in a feature-complete state for initial release.

Done:

• Scaffolding & Core Architecture
• Data Normalization (Wei <-> Decimal)
• Contract Registry (V1 & V2)
• Governance & veFXN support
• Gauge & Reward claiming
• V2 Pool Manager (Operate, Liquidate, Rebalance)
• V1 Treasury & Market support
• Multi-Path Converter & stETH Gateway
• Rebalance Pool (Stability Pool) support
• Integrated ABIs for all core components

🔒 Security Best Practices

1. Never commit private keys to version control. Always use .gitignore to exclude .env files.
2. Use environment variables in production deployments (AWS, Heroku, etc.).
3. Use .env files for local development, but never commit them.
4. Use Colab secrets when working in Google Colab notebooks.
5. Use browser wallets for interactive applications where users control their own keys.
6. Read-only mode is available for analytics and monitoring without any credentials.

📝 Documentation

For a full list of features and supported products, see features.md.

⚖️ License

MIT