Buda Portfolio API (Python + FastAPI)

Valúa un portafolio de criptomonedas en CLP / COP / PEN usando precios en tiempo real desde Buda.com.
La API consulta los endpoints públicos de Buda:

• /markets → lista de pares disponibles
• /markets/{market}/ticker → último precio (last_price)

Docs oficiales de Buda:

• EN
• ES

---

Requerimientos

• Python 3.12+
• Docker & Docker Compose (opcional, para despliegue)
• Dependencias listadas en requirements.txt

---

Ejecución local

Usando Python directamente

git clone https://github.com/<TU-USUARIO>/Buda-2025.git
cd Buda-2025

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

uvicorn src.app.main:app --reload --port 3000

Accede a la documentación interactiva:

Swagger UI → http://localhost:3000/docs

OpenAPI JSON → http://localhost:3000/openapi.json

---

Usando Docker Compose

docker compose up --build -d

Esto levantará el servicio en el puerto 3000.
Swagger estará disponible en http://localhost:3000/docs. Si quieres ver la previsualización tipo Flutter con Streamlit, también se publica en http://localhost:8501.

Para detenerlo:

docker compose down

---

Endpoint principal

POST /portfolio/value

Guarda cada valuación (timestamp, fiat, total) en data/history.json para poder renderizar gráficas sin base de datos.

Input (JSON):

{
  "portfolio": {
    "BTC": 0.5,
    "ETH": 2.0,
    "USDT": 1000
  },
  "fiat_currency": "CLP"
}

Output (ejemplo):

{
  "fiat_currency": "CLP",
  "total_value": 123456789.0,
  "breakdown": {
    "BTC": {
      "qty": 0.5,
      "unit_price": 100000000.0,
      "route": ["btc-clp"],
      "value": 50000000.0
    },
    "ETH": {
      "qty": 2.0,
      "unit_price": 25000000.0,
      "route": ["eth-btc","btc-clp"],
      "value": 50000000.0
    }
  },
  "unpriced_assets": ["USDT"]
}

---

Endpoint de gráficas (para Flutter)

GET /portfolio/charts?fiat_currency=CLP

Devuelve PNGs en base64 ya prerenderados y la serie cruda:

{
  "fiat_currency": "CLP",
  "history_chart_png_base64": "<...>",
  "monthly_chart_png_base64": "<...>",
  "series": [
    {"timestamp": "2025-01-01T00:00:00Z", "total_value": 123456789.0},
    {"timestamp": "2025-02-01T00:00:00Z", "total_value": 111000000.0}
  ]
}

Notas:

• Los PNG usan backend headless (Matplotlib Agg); no requiere GUI.
• El archivo data/history.json debe ser escribible en el entorno de despliegue.
• Si no hay datos para la fiat solicitada, responde 404.

---

Endpoint de gráfica por activo

GET /portfolio/asset-chart?asset=BTC&fiat_currency=CLP

Devuelve el precio unitario del activo a lo largo del tiempo (PNG base64 + serie cruda):

{
  "fiat_currency": "CLP",
  "asset": "BTC",
  "asset_chart_png_base64": "<...>",
  "series": [
    {"timestamp": "2025-01-01T00:00:00Z", "unit_price": 100000000.0, "qty": 0.5, "value": 50000000.0}
  ]
}

---

Lógica de rutas

• Directa → Si existe el par ASSET-FIAT.
• Puente → Si no existe directo, prueba vía:
  • ASSET-BTC → BTC-FIAT
  • ASSET-USDC → USDC-FIAT

Si no existe ruta, el activo pasa a unpriced_assets.

---

Tests

Los tests automatizados están en la carpeta test/.
Para ejecutarlos:

docker compose run --rm \
  -e PYTHONPATH="/app:/app/src" \
  -v "$PWD/src:/app/src:ro" \
  -v "$PWD/test:/app/tests:ro" \
  api pytest -q

---

Supuestos documentados

• Solo soporta monedas fiat: CLP, COP, PEN.
• Se usan precios de Buda en tiempo real (last_price).
• Se persiste solo el total de cada valuación para gráficas en data/history.json (sin detalles del portafolio).
• Solo activos con ruta directa o vía puente (BTC/USDC) son valorizados.

---

Extras incluidos

• Documentación OpenAPI generada automáticamente por FastAPI.
• Despliegue vía Dockerfile en Render (zero-config).
• Tests unitarios y de integración con pytest y responses.

---

Autor

Proyecto desarrollado por Matías Dávila (2025)