NestEgg - Brazilian Investment Index Comparison Tool

A FastAPI application that helps you compare different Brazilian investment indexes, considering taxes and investment periods.

Features

Compare returns between different investment types:
- Poupança (tax-free savings account)
- SELIC Treasury Bonds (with optional spread: SELIC+X%)
- CDB (Certificado de Depósito Bancário)
  - Fixed-rate CDB (Prefixado)
  - CDI-based CDB (X% of CDI)
  - IPCA-based CDB (IPCA+X%)
- LCI (Letra de Crédito Imobiliário, tax-free)
  - Fixed-rate LCI (Prefixado)
  - CDI-based LCI (X% of CDI)
  - IPCA-based LCI (IPCA+X%)
- LCA (Letra de Crédito do Agronegócio, tax-free)
  - Fixed-rate LCA (Prefixado)
  - CDI-based LCA (X% of CDI)
  - IPCA-based LCA (IPCA+X%)
- IPCA (Inflation-indexed investments with optional spread: IPCA+X%)
- CDI (Certificado de Depósito Interbancário with optional percentage: X% of CDI)
- Bitcoin (BTC) with real market prices from CryptoCompare API
Automatic tax calculation based on investment type and period
Historical data from Brazilian Central Bank API
Future projections based on historical volatility and trends
Dynamic IPCA data retrieval with multi-level fallback strategies
Bitcoin price data from CryptoCompare API
User-friendly interface with Today buttons for date selection
Convenient form reset with New Query button
Robust error handling and logging
Easy-to-use REST API

Installation

Make sure you have Python 3.9+ installed

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone this repository
Install dependencies:
```
uv pip install -e .
```

Building the UI

The NestEgg UI is built with TypeScript and requires Node.js to compile the TypeScript code to JavaScript.

Make sure you have Node.js installed (version 16+)
Build the TypeScript files:
```
cd nestegg/static
./build.sh
```

Usage

Start the server:

uvicorn nestegg.main:app --reload --port 8001

Access the UI by navigating to http://localhost:8001 in your browser
Or access the API documentation at http://localhost:8001/docs to use the interactive API

Make a POST request to /api/v1/calculate with a JSON body like:

{
  "investment_type": "cdb",
  "amount": 10000.0,
  "start_date": "2024-03-01",
  "end_date": "2024-12-31",
  "cdb_rate": 12.5
}

Or compare multiple investments at once with:

curl -X GET "http://localhost:8001/api/v1/compare?amount=10000&period=1&cdb_rate=14.5&lci_rate=12.0&lca_rate=11.5&ipca_spread=5.5&selic_spread=2.0&cdi_percentage=109.0"

API Documentation

The API provides the following endpoints:

GET /api/v1/investment-types

List all supported investment types with their descriptions.

Response:

[
  {
    "id": "poupanca",
    "name": "Poupanca",
    "description": "Poupança - Tax-free savings account with yield based on SELIC rate"
  },
  {
    "id": "selic",
    "name": "Selic",
    "description": "SELIC Treasury Bonds - Government bonds yielding 100% of SELIC rate"
  }
]

POST /api/v1/calculate

Calculate investment returns for a single Brazilian investment type.

Request parameters:

investment_type: Type of investment (cdb, poupanca, selic, lci, lca, ipca, cdi, btc, lci_cdi, lca_cdi, lci_ipca, lca_ipca, cdb_ipca)
amount: Initial investment amount
start_date: Start date (format: YYYY-MM-DD)
end_date: End date (format: YYYY-MM-DD)
cdb_rate: CDB rate as percentage (required for CDB investments)
lci_rate: LCI rate as percentage (required for fixed-rate LCI investments)
lca_rate: LCA rate as percentage (required for fixed-rate LCA investments)
ipca_spread: IPCA spread in percentage points (optional, default: 0, required for IPCA, LCI_IPCA, LCA_IPCA, CDB_IPCA)
selic_spread: SELIC spread in percentage points (optional, default: 0)
cdi_percentage: CDI percentage (optional, default: 100.0, required for CDI, LCI_CDI, LCA_CDI)

Response:

{
  "investment_type": "cdb",
  "initial_amount": 10000.0,
  "final_amount": 11000.0,
  "gross_profit": 1200.0,
  "net_profit": 1000.0,
  "tax_amount": 200.0,
  "effective_rate": 10.0,
  "start_date": "2024-03-01",
  "end_date": "2024-12-31",
  "rate": 12.5,
  "tax_info": {
    "tax_rate_percentage": 17.5,
    "tax_amount": 200.0,
    "is_tax_free": false,
    "tax_period_days": 305,
    "tax_period_description": "181 to 360 days (20% tax)"
  }
}

GET /api/v1/compare

Compare returns between different investment types and provide recommendations.

Request parameters:

amount: Initial investment amount
period: Investment period in years (optional if start_date and end_date are provided)
start_date: Start date (format: YYYY-MM-DD, optional if period is provided)
end_date: End date (format: YYYY-MM-DD, optional if period is provided)
cdb_rate: CDB rate as percentage (optional)
lci_rate: LCI rate as percentage (optional)
lca_rate: LCA rate as percentage (optional)
ipca_spread: IPCA spread in percentage points (optional)
selic_spread: SELIC spread in percentage points (optional)
cdi_percentage: CDI percentage (optional)
lci_cdi_percentage: LCI CDI percentage (optional)
lca_cdi_percentage: LCA CDI percentage (optional)
lci_ipca_spread: LCI IPCA spread (optional)
lca_ipca_spread: LCA IPCA spread (optional)
cdb_ipca_spread: CDB IPCA spread (optional)
include_poupanca: Whether to include Poupança in comparison (optional, default: false)
include_btc: Whether to include Bitcoin in comparison (optional, default: false)

The comparison will include investment types based on the parameters provided:

CDB Prefixado will be included when cdb_rate is provided
LCI Prefixado will be included when lci_rate is provided
LCA Prefixado will be included when lca_rate is provided
Tesouro IPCA+ will be included when ipca_spread is provided
Tesouro SELIC will be included when selic_spread is provided
CDB CDI will be included when cdi_percentage is provided
LCI CDI will be included when lci_cdi_percentage is provided
LCA CDI will be included when lca_cdi_percentage is provided
LCI IPCA+ will be included when lci_ipca_spread is provided
LCA IPCA+ will be included when lca_ipca_spread is provided
CDB IPCA will be included when cdb_ipca_spread is provided
Poupança will be included when include_poupanca=true
Bitcoin will be included when include_btc=true

Response:

[
  {
    "type": "LCI 95.00% CDI",
    "rate": 11.40,
    "effective_rate": 5.62,
    "gross_profit": 561.85,
    "net_profit": 561.85,
    "tax_amount": 0.0,
    "final_amount": 10561.85,
    "tax_free": true,
    "recommendation": "Best option among compared investments"
  },
  {
    "type": "LCA 90.00% CDI",
    "rate": 10.80,
    "effective_rate": 5.31,
    "gross_profit": 531.45,
    "net_profit": 531.45,
    "tax_amount": 0.0,
    "final_amount": 10531.45,
    "tax_free": true,
    "recommendation": "0.31% lower than LCI 95.00% CDI"
  },
  {
    "type": "CDB Prefixado 14.50%",
    "rate": 14.50,
    "effective_rate": 5.30,
    "gross_profit": 725.00,
    "net_profit": 530.47,
    "tax_amount": 194.53,
    "final_amount": 10530.47,
    "tax_free": false,
    "recommendation": "0.32% lower than LCI 95.00% CDI"
  },
  {
    "type": "CDB 109.00% CDI",
    "rate": 13.08,
    "effective_rate": 4.84,
    "gross_profit": 654.00,
    "net_profit": 484.59,
    "tax_amount": 169.41,
    "final_amount": 10484.59,
    "tax_free": false,
    "recommendation": "0.78% lower than LCI 95.00% CDI"
  },
  {
    "type": "Tesouro SELIC+2.00%",
    "rate": 14.00,
    "effective_rate": 4.82,
    "gross_profit": 700.00,
    "net_profit": 482.30,
    "tax_amount": 217.70,
    "final_amount": 10482.30,
    "tax_free": false,
    "recommendation": "0.80% lower than LCI 95.00% CDI"
  }
]

A sorted list of investment comparisons, with the best performing investments first
Includes tax calculations and effective rates for each investment type
Provides a recommendation highlighting the best option
Clearly marks calculations for historical data vs. projected future returns

Example curl Commands

Here are some example curl commands for using the API:

Calculate a single CDB investment

curl -X POST "http://localhost:8001/api/v1/calculate?investment_type=cdb&amount=10000&start_date=2024-01-01&end_date=2024-12-31&cdb_rate=14.5"

Compare multiple investments with custom parameters (using period)

curl -X GET "http://localhost:8001/api/v1/compare?amount=10000&period=1&cdb_rate=14.5&lci_rate=12.0&lca_rate=11.5&ipca_spread=5.5&selic_spread=2.0&cdi_percentage=109.0"

Compare multiple investments with custom parameters (using dates)

curl -X GET "http://localhost:8001/api/v1/compare?amount=10000&start_date=2024-01-01&end_date=2024-12-31&cdb_rate=14.5&lci_rate=12.0&lca_rate=11.5&ipca_spread=5.5&selic_spread=2.0&cdi_percentage=109.0"

Compare investments with different LCI/LCA variants

curl -X GET "http://localhost:8001/api/v1/compare?amount=10000&period=1&cdb_rate=14.5&lci_rate=12.0&lca_rate=11.5&ipca_spread=5.5&selic_spread=2.0&cdi_percentage=109.0&lci_cdi_percentage=95.0&lca_cdi_percentage=90.0&lci_ipca_spread=4.5&lca_ipca_spread=4.0"

Compare investments with CDB IPCA and other specific types

curl -X GET "http://localhost:8001/api/v1/compare?amount=10000&period=1&lci_rate=13.5&lci_cdi_percentage=94.0&cdb_ipca_spread=5.5&include_poupanca=true&include_btc=true"

Compare investments with future dates (projections)

curl -X GET "http://localhost:8001/api/v1/compare?amount=10000&start_date=2025-01-01&end_date=2025-12-31&cdb_rate=14.5&lci_rate=12.0&lca_rate=11.5&ipca_spread=5.5&selic_spread=2.0&cdi_percentage=109.0"

Data Sources

The application uses the following data sources:

Brazilian Central Bank API (BCB)
- SELIC rate (BCB series code 11)
- CDI rate (BCB series code 12)
- IPCA (inflation) rate (BCB series code 433)
- Poupança rate (BCB series code 25)
CryptoCompare API
- Current and historical Bitcoin prices in BRL
- Future Bitcoin price projections based on historical volatility

For future dates, the application uses sophisticated projections based on historical data patterns and volatility. These projections are clearly marked in the results. For IPCA, the system employs a multi-level dynamic fallback strategy using recent historical data.

UI Features

The web interface provides several user-friendly features:

Today Buttons: Next to date inputs, allowing you to quickly set a date to today
New Query Button: Resets all selections and results to start fresh
Responsive Design: Works well on desktop and mobile devices
Dynamic Investment Selection: Only selected investment types are included in comparisons
Interactive Results: Clear visualization of investment performance

Changelog

See CHANGELOG.md for a detailed history of changes.

License

See LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github		.github
nestegg		nestegg
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.lock		requirements.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

NestEgg - Brazilian Investment Index Comparison Tool

Features

Installation

Building the UI

Usage

API Documentation

GET /api/v1/investment-types

POST /api/v1/calculate

GET /api/v1/compare

Example curl Commands

Calculate a single CDB investment

Compare multiple investments with custom parameters (using period)

Compare multiple investments with custom parameters (using dates)

Compare investments with different LCI/LCA variants

Compare investments with CDB IPCA and other specific types

Compare investments with future dates (projections)

Data Sources

UI Features

Changelog

License

About

Releases

Packages

Languages

License

kiraum/nestegg

Folders and files

Latest commit

History

Repository files navigation

NestEgg - Brazilian Investment Index Comparison Tool

Features

Installation

Building the UI

Usage

API Documentation

GET /api/v1/investment-types

POST /api/v1/calculate

GET /api/v1/compare

Example curl Commands

Calculate a single CDB investment

Compare multiple investments with custom parameters (using period)

Compare multiple investments with custom parameters (using dates)

Compare investments with different LCI/LCA variants

Compare investments with CDB IPCA and other specific types

Compare investments with future dates (projections)

Data Sources

UI Features

Changelog

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages