Examples

Comprehensive examples demonstrating various use cases of the xfinance Python SDK.

Basic Compound Interest

from xfinance_sdk import XFinanceClient
from xfinance_sdk.models.request import CompoundInterestRequest
from decimal import Decimal

client = XFinanceClient(api_key="your-api-key")

# Calculate with different compounding frequencies
frequencies = {
    "Annual": 1,
    "Semi-Annual": 2,
    "Quarterly": 4,
    "Monthly": 12,
    "Daily": 365
}

for name, freq in frequencies.items():
    request = CompoundInterestRequest(
        principal=Decimal("10000"),
        annual_rate=Decimal("0.05"),
        years=10,
        compounding_frequency=freq
    )
    response = client.calculate_compound_interest(request)
    print(f"{name}: ${response.final_amount:,.2f}")

Mortgage Calculator

from xfinance_sdk.models.request import LoanCalculationRequest

def calculate_mortgage(loan_amount, interest_rate, years):
    request = LoanCalculationRequest(
        loan_amount=Decimal(str(loan_amount)),
        annual_rate=Decimal(str(interest_rate)),
        term_years=years
    )
    return client.calculate_loan_payment(request)

# 30-year fixed mortgage
response = calculate_mortgage(300000, 0.04, 30)
print(f"30-year ${300000:,.0f} at 4%: ${response.monthly_payment:,.2f}/month")

# 15-year fixed mortgage
response = calculate_mortgage(300000, 0.035, 15)
print(f"15-year ${300000:,.0f} at 3.5%: ${response.monthly_payment:,.2f}/month")

Retirement Planning

from xfinance_sdk.models.request import InvestmentReturnsRequest

def retirement_projections(initial, monthly, rate, years):
    request = InvestmentReturnsRequest(
        initial_investment=Decimal(str(initial)),
        monthly_contribution=Decimal(str(monthly)),
        expected_annual_return=Decimal(str(rate)),
        years=years
    )
    return client.calculate_investment_returns(request)

# Conservative retirement plan
response = retirement_projections(50000, 1000, 0.06, 30)
print(f"Retirement fund: ${response.final_value:,.2f}")

# Aggressive retirement plan
response = retirement_projections(50000, 2000, 0.08, 25)
print(f"Retirement fund: ${response.final_value:,.2f}")

Error Handling Example

from xfinance_sdk.exceptions import (
    BadRequestError, UnauthorizedError, ValidationError
)

try:
    # This will fail validation (negative principal)
    request = CompoundInterestRequest(
        principal=Decimal("-10000"),
        annual_rate=Decimal("0.05"),
        years=10,
        compounding_frequency=12
    )
    response = client.calculate_compound_interest(request)
except ValidationError as e:
    print(f"Validation error: {e}")
except UnauthorizedError as e:
    print(f"Authentication error: {e}")
except BadRequestError as e:
    print(f"API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Batch Processing

import asyncio
from xfinance_sdk import AsyncXFinanceClient

async def process_multiple_requests(requests):
    client = AsyncXFinanceClient(api_key="your-api-key")
    try:
        results = []
        for request in requests:
            response = await client.calculate_compound_interest(request)
            results.append(response.final_amount)
        return results
    finally:
        await client.close()

# Create multiple requests
requests = [
    CompoundInterestRequest(
        principal=Decimal("10000"),
        annual_rate=Decimal("0.05 + i * 0.01"),
        years=10,
        compounding_frequency=12
    ) for i in range(5)
]

results = asyncio.run(process_multiple_requests(requests))
for i, result in enumerate(results):
    print(f"Scenario {i+1}: ${result:,.2f}")