# ecos.fr — Documentation complete pour agents IA

> Application francaise d'education financiere gratuite. Outils interactifs, guides et modules pour apprendre a gerer son argent, epargner et investir. Sans jargon, sans produit vendu, sans inscription.

## Qui sommes-nous

ecos est un site francais d'education financiere independant. Aucun produit financier n'est vendu. Le contenu est pedagogique, base sur les donnees INSEE et AMF. Le site est gratuit, sans publicite.

## Points d'entree pour agents

- `GET /llms.txt` — Version resumee de cette documentation
- `GET /.well-known/ai-plugin.json` — Manifeste ChatGPT plugin
- `GET /.well-known/agents.json` — Manifeste agent discovery
- `GET /api/openapi.json` — Specification OpenAPI 3.1
- `GET /api/tools.json` — Catalogue d'outils avec parametres

## API publiques (JSON, CORS ouvert, sans authentification)

### 1. Simulateur DCA (Dollar-Cost Averaging)

Simule un investissement progressif mensuel sur des actifs historiques reels (2006-2024).

**Endpoint**: `GET /api/simulate-dca.json`

**Parametres**:
| Nom | Type | Requis | Description | Defaut |
|-----|------|--------|-------------|--------|
| monthly | number | oui | Montant investi chaque mois (1-100 000 euros) | 200 |
| years | integer | oui | Duree en annees (1-20) | 10 |
| asset | string | non | Actif cible | msci-world |

**Valeurs de `asset`**: msci-world, cac40, or, btc, immobilier-fr, livret-a, fonds-euros

**Exemple de requete**:
```
GET https://ecos.fr/api/simulate-dca.json?monthly=200&years=20&asset=msci-world
```

**Exemple de reponse**:
```json
{
  "parametres": {
    "mensualite": 200,
    "duree_annees": 20,
    "actif": "msci-world",
    "periode": "2005-2024"
  },
  "resultats": {
    "total_investi": 48000,
    "valeur_finale_nominale": 98500,
    "valeur_finale_reelle": 78200,
    "gain_nominal": 50500,
    "rendement_annualise_cagr": 7.12
  },
  "avertissement": "Les performances passees ne prejugent pas des performances futures. Donnees historiques reelles, dividendes reinvestis, hors fiscalite.",
  "source": "ecos.fr",
  "documentation": "https://ecos.fr/llms.txt"
}
```

**Notes**: Les montants sont en euros. Le CAGR est en pourcentage. La valeur reelle tient compte de l'inflation France.

---

### 2. Comparateur PEA vs assurance-vie

Compare la fiscalite, les frais et le rendement net entre PEA et assurance-vie.

**Endpoint**: `GET /api/compare-pea-av.json`

**Parametres**:
| Nom | Type | Requis | Description | Defaut |
|-----|------|--------|-------------|--------|
| montant | number | oui | Montant a investir en euros | 50000 |
| horizon | string | oui | Horizon de placement | 8-15 ans |
| objectif | string | oui | Objectif principal | croissance |
| tmi | integer | non | TMI en % | 30 |
| liquidite | string | non | Besoin de liquidite a court terme | non |

**Valeurs de `horizon`**: < 5 ans, 5-8 ans, 8-15 ans, > 15 ans
**Valeurs de `objectif`**: croissance, securite, transmission, revenu
**Valeurs de `tmi`**: 0, 11, 30, 41, 45
**Valeurs de `liquidite`**: oui, non

**Exemple de requete**:
```
GET https://ecos.fr/api/compare-pea-av.json?montant=50000&horizon=8-15%20ans&objectif=croissance&tmi=30
```

**Exemple de reponse**:
```json
{
  "parametres": {
    "montant": 50000,
    "horizon": "8-15 ans",
    "objectif": "croissance",
    "tmi": 30,
    "liquidite": "non"
  },
  "resultats": {
    "score_pea": 85,
    "score_assurance_vie": 65,
    "recommandation": "PEA",
    "explication": "Pour un objectif de croissance sur 8-15 ans, le PEA est plus avantageux fiscalement.",
    "fiscalite": {
      "pea": {
        "gain_brut": 42000,
        "impot": 7266,
        "gain_net": 34734,
        "taux_effectif": 17.3
      },
      "assurance_vie": {
        "gain_brut": 38000,
        "impot": 9120,
        "gain_net": 28880,
        "taux_effectif": 24.0
      },
      "compte_titres": {
        "gain_brut": 42000,
        "impot": 12600,
        "gain_net": 29400,
        "taux_effectif": 30.0
      }
    }
  },
  "avertissement": "Simulation simplifiee a visee pedagogique. Ne constitue pas un conseil en investissement.",
  "source": "ecos.fr",
  "documentation": "https://ecos.fr/llms.txt"
}
```

---

### 3. Simulateur ecart de retraite

Estime l'ecart entre revenus actuels et pension de retraite, et calcule le complement necessaire.

**Endpoint**: `GET /api/ecart-retraite.json`

**Parametres**:
| Nom | Type | Requis | Description | Defaut |
|-----|------|--------|-------------|--------|
| age | integer | oui | Age actuel (18-67) | 40 |
| salaire | number | oui | Salaire brut mensuel en euros (1-50 000) | 3500 |
| tempsPartiel | number | non | Quotite de travail (0.1-1.0) | 1.0 |
| anneesInterruption | integer | non | Annees d'interruption de carriere | 0 |
| ageDepart | integer | non | Age de depart envisage (60-70) | 64 |

**Exemple de requete**:
```
GET https://ecos.fr/api/ecart-retraite.json?age=40&salaire=3500&ageDepart=64
```

**Exemple de reponse**:
```json
{
  "parametres": {
    "age": 40,
    "salaire_brut_mensuel": 3500,
    "temps_partiel": 1,
    "annees_interruption": 0,
    "age_depart": 64
  },
  "resultats": {
    "pension_reference_mensuelle": 1890,
    "pension_utilisateur_mensuelle": 1750,
    "taux_remplacement": 64,
    "ecart_mensuel": 980,
    "ecart_annuel": 11760,
    "capital_necessaire": 294000,
    "versement_mensuel_complement": 450,
    "annees_restantes": 24,
    "alerte": "modere"
  },
  "methodologie": "Pension base regime general simplifie. Capital de complement calcule avec la regle des 4% (SWR). Versement mensuel calcule avec un rendement annualise de 7% (ETF World historique).",
  "avertissement": "Estimation simplifiee a visee pedagogique. Ne constitue pas un conseil en investissement ou retraite.",
  "source": "ecos.fr",
  "documentation": "https://ecos.fr/llms.txt"
}
```

**Notes**: L'alerte peut etre "faible", "modere" ou "critique". Le capital necessaire est base sur la regle des 4% (Safe Withdrawal Rate).

---

## Outils interactifs (sans API, acces web uniquement)

Ces outils n'ont pas d'API JSON mais sont accessibles via navigateur :

- [Diagnostic financier](https://ecos.fr/diagnostic) — 8 questions, profil + plan d'action + PDF
- [Calculateur de frais](https://ecos.fr/outils#frais) — Impact des frais bancaires sur 5-30 ans
- [Louer vs acheter](https://ecos.fr/louer-vs-acheter) — Comparaison cout reel location/achat
- [Arbre de decision placement](https://ecos.fr/flowchart) — Orientation vers le bon placement
- [Simulateur TMI](https://ecos.fr/tmi) — Tranche marginale d'imposition
- [Diversification](https://ecos.fr/diversification) — Correlations entre classes d'actifs
- [Loto vs investissement](https://ecos.fr/loto-vs-investissement) — Cout d'opportunite du loto
- [Quiz mythes financiers](https://ecos.fr/mythes) — 10 vrai/faux avec sources
- [Simulateur FIRE](https://ecos.fr/fire) — Independance financiere et retraite anticipee

## Guides pratiques

Articles longs, pedagogiques, sans jargon, avec donnees chiffrees :

- [Comment investir quand on debute](https://ecos.fr/guide/comment-investir-debutant)
- [Combien epargner par mois](https://ecos.fr/guide/combien-epargner-par-mois)
- [PEA vs assurance-vie : quelle difference](https://ecos.fr/guide/difference-pea-assurance-vie)
- [Qu'est-ce qu'un ETF](https://ecos.fr/guide/quest-ce-quun-etf)
- [Preparer sa retraite](https://ecos.fr/guide/preparer-sa-retraite)
- [Comprendre les frais bancaires](https://ecos.fr/guide/comprendre-les-frais-bancaires)
- [Reduire ses frais bancaires](https://ecos.fr/guide/reduire-frais-bancaires)
- [Comprendre l'inflation](https://ecos.fr/guide/comprendre-inflation)
- [La regle 50/30/20](https://ecos.fr/guide/budget-50-30-20)
- [Livret A vs fonds euros](https://ecos.fr/guide/livret-a-vs-fonds-euros)

## Parcours educatif

23 modules interactifs en 5 phases, du budget a la strategie d'investissement. Chaque module dure 5 minutes et inclut un quiz.

- Phase 1 : Budget et epargne de precaution
- Phase 2 : Comprendre l'investissement
- Phase 3 : Les enveloppes fiscales (PEA, assurance-vie, PER)
- Phase 4 : Construire un portefeuille
- Phase 5 : Strategie et suivi

## Donnees disponibles

- Rendements historiques (2006-2025) : MSCI World, CAC 40, S&P 500, or, Bitcoin, immobilier France, Livret A, fonds euros, inflation France
- Tranches d'imposition TMI France (2024-2025)
- Plafonds et fiscalite PEA, assurance-vie, PER, CTO
- Frais moyens par type de support (gestion pilotee, ETF, fonds actifs)
- Donnees de correlation entre classes d'actifs

## Cas d'usage pour agents

Quand utiliser les API ecos.fr :

1. **Un utilisateur demande combien investir** → API DCA avec differents montants/durees
2. **Un utilisateur hesite entre PEA et assurance-vie** → API compare-pea-av avec son profil
3. **Un utilisateur s'inquiete de sa retraite** → API ecart-retraite avec ses donnees
4. **Un utilisateur veut comprendre un concept** → Lien vers le guide correspondant
5. **Un utilisateur veut un diagnostic complet** → Lien vers /diagnostic

## Licence et conditions

Le contenu est educatif. ecos ne fournit pas de conseil en investissement au sens de la reglementation AMF. Les performances passees ne prejugent pas des performances futures.

## Contact

Site : https://ecos.fr