xfinance Python SDK
===================

Official Python SDK for X-Finance API - Comprehensive financial calculations for Python applications.

.. toctree::
   :maxdepth: 2
   :caption: Documentation
   :hidden:

   installation
   quickstart
   api-reference
   examples
   authentication
   error-handling
   configuration

.. toctree::
   :maxdepth: 1
   :caption: Development
   :hidden:

   contributing
   changelog

Overview
--------

The **xfinance Python SDK** provides a comprehensive interface to the X-Finance API, 
offering robust financial calculation capabilities including compound interest, 
loan payments, investment returns, and more.

Key Features:

- **Compound Interest Calculations**: Flexible compounding with custom frequencies
- **Loan Payment Calculations**: Mortgage and loan amortization support
- **Investment Returns**: Future value projections with regular contributions
- **Async Support**: Non-blocking asynchronous operations
- **Type Safety**: Full Pydantic validation with type hints
- **Error Handling**: Comprehensive exception hierarchy
- **Authentication**: API key and JWT token support

Quick Installation
------------------

.. code-block:: bash

   pip install xfinance-python-sdk

Basic Usage
-----------

.. code-block:: python

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

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

   # Calculate compound interest
   request = CompoundInterestRequest(
       principal=Decimal("10000"),
       annual_rate=Decimal("0.05"),
       years=10,
       compounding_frequency=12
   )

   response = client.calculate_compound_interest(request)
   print(f"Final amount: ${response.final_amount:,.2f}")

Getting Help
------------

- `GitHub Repository <https://github.com/martourez21/xfinance-python-sdk>`_
- `Issue Tracker <https://github.com/martourez21/xfinance-python-sdk/issues>`_
- `PyPI Package <https://pypi.org/project/xfinance-python-sdk/>`_

License
-------

MIT License - See LICENSE file for details.