{
  "markdown": "# DPE-X402\n\n**API française sur les diagnostics de performance énergétique (DPE), monétisée en USDC via le protocole x402 pour les agents IA autonomes.**\n\n[![Live](https://img.shields.io/badge/status-live-brightgreen)](https://dpe.bdatax.com)\n[![Network](https://img.shields.io/badge/network-base--mainnet-blue)](https://basescan.org)\n[![x402](https://img.shields.io/badge/x402-enabled-A05A2C)](https://x402.org)\n[![Version](https://img.shields.io/badge/version-0.7.2-informational)](./CHANGELOG.md)\n\n> 🌐 **URL de production** : https://dpe.bdatax.com\n> 📄 **Découverte automatique** : https://dpe.bdatax.com/.well-known/x402.json\n\n---\n\n## Ce que fait cette API\n\nInterrogation intelligente de la base publique [ADEME](https://data.ademe.fr) sur les DPE (Diagnostics de Performance Énergétique) en France, avec :\n\n- **7 modes de recherche** : adresse libre, code postal, GPS, numéro DPE, identifiant BAN, etc.\n- **Géocodage automatique** via l'API [BAN](https://adresse.data.gouv.fr) (avec sélection stricte pour éviter les faux positifs)\n- **Enrichissement DVF** *(v0.7.0)* : chaque résultat est complété par une estimation de valeur marchande basée sur les transactions immobilières réelles publiées par la DGFiP (prix médian €/m², estimation totale, nombre de comparables, date de la dernière transaction du quartier)\n- **Enrichissement Géorisques** *(v0.7.1)* : chaque résultat est enrichi de la synthèse des risques naturels et technologiques de la commune (inondation, séisme, radon, retrait-gonflement argile, mouvement de terrain, ICPE, canalisations matières dangereuses, pollution des sols…), servie par l'API officielle Géorisques (BRGM + Ministère Transition écologique)\n- **Enrichissement INSEE FILOSOFI** *(v0.7.2)* : chaque résultat inclut les indicateurs socio-économiques de la commune — médiane du niveau de vie, taux de pauvreté, déciles D1/D9, rapport interdécile (indicateur d'inégalité), part des actifs et des retraités — issus du dispositif Fichier Localisé Social et Fiscal 2021 de l'INSEE\n- **Scoring intelligent** de la pertinence de chaque résultat\n- **Déduplication et classement multi-critères** (score, surface, date)\n- **3 formats d'export** : JSON (défaut), CSV, XLSX\n- **Paiement à la requête** via le protocole x402 (HTTP 402) sur **Base mainnet** — **~0,001 USDC par appel**\n\nConçu pour être utilisé par des **agents IA autonomes** qui payent en crypto sans intervention humaine (Machine Economy), mais aussi utilisable directement par un humain avec `curl` ou un navigateur.\n\n---\n\n## Quick start\n\n### 1. Voir ce que l'API expose (gratuit)\n\n```bash\ncurl https://dpe.bdatax.com/\n```\n\n### 2. Interroger l'API sans payer (renvoie 402)\n\n```bash\ncurl -i \"https://dpe.bdatax.com/dpe?cp=75001\"\n```\n\nRéponse :\n\n```\nHTTP/1.1 402 Payment Required\n{\n  \"x402Version\": 1,\n  \"accepts\": [{\n    \"scheme\": \"exact\",\n    \"network\": \"base\",\n    \"asset\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\n    \"maxAmountRequired\": \"1000\",\n    \"payTo\": \"0xc0a484b32798dEefcA38Ced6c6Aa780660c752A4\"\n  }]\n}\n```\n\n### 3. Payer et récupérer les DPE (avec un client x402)\n\nVoir [`test-client.js`](./test-client.js) pour un exemple complet en Node.js utilisant [`x402-fetch`](https://www.npmjs.com/package/x402-fetch) et [`viem`](https://viem.sh).\n\n---\n\n## Endpoints disponibles\n\n| Endpoint | Prix | Description |\n|---|---|---|\n| `GET /` | Gratuit | Page d'accueil, liste des endpoints |\n| `GET /.well-known/x402.json` | Gratuit | Fichier de découverte pour crawlers x402 |\n| `GET /dpe?cp=75001` | 0,001 USDC | Recherche par code postal |\n| `GET /dpe?adresse=203 rue Saint-Honoré 75001 Paris` | 0,001 USDC | Recherche par adresse libre |\n| `GET /dpe?voie=Saint-Honoré&cp=75001` | 0,001 USDC | Recherche par nom de rue |\n| `GET /dpe?numero=203&voie=Saint-Honoré&cp=75001` | 0,001 USDC | Recherche par numéro + rue + CP |\n| `GET /dpe?numeroDPE=2175E0465600P` | 0,001 USDC | Recherche par identifiant DPE |\n| `GET /dpe?lat=48.864968&lon=2.331665` | 0,001 USDC | Recherche par coordonnées GPS |\n| `GET /dpe?cp=75001&format=csv` | 0,001 USDC | Export CSV (compatible Excel FR) |\n| `GET /dpe?cp=75001&format=xlsx` | 0,001 USDC | Export Excel natif |\n\nChaque appel `/dpe` renvoie un JSON structuré avec `meilleurResultat`, `resultats` (tableau classé), `dpeLePlusRecent`, et des métadonnées de recherche.\n\n---\n\n## Enrichissement DVF *(nouveau en v0.7.0)*\n\nChaque DPE renvoyé est automatiquement enrichi (sans surcoût) avec des données de marché immobilier issues de la base publique **DVF** (Demandes de Valeurs Foncières, DGFiP) :\n\n```json\n{\n  \"adresse\": \"14 rue Vauvilliers 75001 Paris\",\n  \"etiquetteDPE\": \"F\",\n  \"surfaceM2\": 22.9,\n  \"coutAnnuelTotal\": 1168,\n  \"dvf\": {\n    \"prixMedianM2\": 12400,\n    \"prixEstimeTotal\": 283960,\n    \"nbTransactionsComparables\": 8,\n    \"derniereTransaction\": \"2025-11-14\",\n    \"rayonMetres\": 200,\n    \"ecartSurfacePct\": 30\n  }\n}\n```\n\n**Méthode** : pour chaque DPE géolocalisé, on cherche dans un rayon de 200 m les transactions immobilières récentes (2024-2025), du même type (appartement / maison), avec une surface comparable (±30 %). On calcule ensuite la médiane des prix au m² et on l'applique à la surface du DPE.\n\n`dvf` vaut `null` si l'échantillon est trop faible (moins de 3 transactions comparables) ou si le département n'est pas encore indexé — le champ apparaît toujours pour que les consommateurs de l'API puissent tester sa présence de façon uniforme.\n\n**Couverture** : France entière (métropole + DROM), transactions publiées jusqu'à la dernière mise à jour semestrielle DGFiP.\n\n**Mise à jour de l'index DVF** : deux fois par an (avril et octobre), en lançant localement `node build-dvf-index.js` après avoir téléchargé le nouveau fichier `full.csv.gz` depuis [data.gouv.fr](https://www.data.gouv.fr/fr/datasets/demandes-de-valeurs-foncieres-geolocalisees/), puis en pushant `data/dvf/`.\n\n---\n\n## Enrichissement Géorisques *(nouveau en v0.7.1)*\n\nChaque DPE renvoyé est aussi enrichi (sans surcoût pour l'utilisateur) avec une synthèse des risques naturels et technologiques qui pèsent sur sa commune, via l'API officielle **Géorisques** maintenue par le BRGM et le Ministère de la Transition écologique :\n\n```json\n{\n  \"adresse\": \"203 Rue Saint-Honoré 75001 Paris\",\n  \"etiquetteDPE\": \"F\",\n  \"codeInsee\": \"75101\",\n  \"georisques\": {\n    \"commune\": \"PARIS 1ER ARRONDISSEMENT\",\n    \"codeInsee\": \"75101\",\n    \"risquesNaturels\": {\n      \"inondation\": \"existant\",\n      \"seisme\": \"faible\",\n      \"retraitGonflementArgile\": \"important\",\n      \"radon\": \"faible\",\n      \"mouvementTerrain\": \"existant\",\n      \"remonteeNappe\": \"existant\"\n    },\n    \"risquesTechnologiques\": {\n      \"icpe\": \"concerne\",\n      \"canalisationsMatieresDangereuses\": \"concerne\",\n      \"pollutionSols\": \"concerne\"\n    },\n    \"nbRisquesPresents\": 9,\n    \"sourceUrl\": \"https://www.georisques.gouv.fr/mes-risques/...\"\n  }\n}\n```\n\n**Méthode** : le code INSEE de la commune est dérivé du champ `identifiantBAN` du DPE, puis on interroge l'endpoint `/api/v1/resultats_rapport_risque` de Géorisques. La réponse est mise en cache 24 h en RAM par code INSEE — même 1000 DPE dans une même commune ne génèrent qu'**un seul appel API par jour**.\n\n`georisques` vaut `null` si le codeInsee n'a pas pu être dérivé (DPE sans identifiantBAN), si l'API Géorisques répond en erreur, ou si le timeout de 5 s est dépassé. Comportement gracieux : les autres champs de la réponse (DPE + DVF) restent servis normalement.\n\n**Cas d'usage typique** : assureurs (calcul de prime), banques (analyse de risque de crédit immobilier), plateformes de tokenisation immobilière (due diligence automatisée), agents IA immobiliers autonomes.\n\n---\n\n## Utilisation avec un client Node.js\n\nInstallation :\n\n```bash\nnpm install x402-fetch viem\n```\n\nUtilisation :\n\n```javascript\nimport { wrapFetchWithPayment } from \"x402-fetch\";\nimport { privateKeyToAccount } from \"viem/accounts\";\n\nconst account = privateKeyToAccount(process.env.PRIVATE_KEY);\nconst fetchWithPayment = wrapFetchWithPayment(fetch, account, BigInt(10_000));\n\nconst response = await fetchWithPayment(\n  \"https://dpe.bdatax.com/dpe?cp=75001\"\n);\nconst data = await response.json();\nconsole.log(data.meilleurResultat);\n```\n\nUn exemple complet et commenté est disponible dans [`test-client.js`](./test-client.js).\n\nPour tester, il faut :\n1. Un wallet EVM avec quelques centimes d'USDC sur **Base mainnet** (bridge depuis Arbitrum, Ethereum, ou achat direct sur Coinbase)\n2. Créer un fichier `client.env` avec `PRIVATE_KEY=...` (jamais commit !)\n3. Lancer : `node --env-file=client.env test-client.js`\n\n---\n\n## Architecture\n\nPipeline en 12 étapes pour chaque requête `/dpe` :\n\n1. Middleware x402 (paiement)\n2. Extraction des critères de recherche\n3. Analyse automatique de l'adresse (regex)\n4. Géocodage inverse BAN (GPS → adresse)\n5. Géocodage direct BAN (adresse → GPS, avec validation stricte CP/ville)\n6. Requêtes ADEME parallélisées (Promise.all)\n7. Scoring de chaque DPE (barème calibré)\n8. Déduplication et classement multi-critères\n9. **Enrichissement DVF** — pour chaque résultat, lookup local des transactions immobilières comparables (cache LRU en mémoire)\n10. **Enrichissement Géorisques** — appel API `/resultats_rapport_risque` par code INSEE (cache RAM 24 h)\n11. **Enrichissement INSEE FILOSOFI** — lookup local des revenus/pauvreté/déciles par code INSEE (cache LRU)\n12. Sortie au format demandé (JSON/CSV/XLSX)\n\nTemps de réponse typique : **< 800 ms** (l'appel Géorisques ajoute ~200-400 ms au premier appel par commune, ensuite servi depuis le cache ; DVF et INSEE sont locaux donc quelques ms).\n\n---\n\n## Roadmap\n\n- **v0.7.0** ✅ Enrichissement DVF (transactions immobilières, prix médian €/m²)\n- **v0.7.1** ✅ Enrichissement Géorisques (inondation, sismique, radon, pollutions, ICPE, argile…)\n- **v0.7.2** ✅ Enrichissement INSEE FILOSOFI (revenu médian, taux de pauvreté, déciles)\n- **v0.8.x** : Scores propriétaires (rénovation, confort d'été, attractivité globale)\n- **v0.9.x** : Endpoint `/dpe/enrichi` à tarif différencié (~0,02 USDC)\n- **v1.0** : Consolidation, SLA public, dashboards partenaires\n\n---\n\n## Attribution\n\n- Données DPE : [ADEME](https://data.ademe.fr) — Open Data\n- Données de valeurs foncières (DVF) : [DGFiP / Etalab](https://www.data.gouv.fr/fr/datasets/demandes-de-valeurs-foncieres-geolocalisees/) — Open Data\n- Risques naturels et technologiques : [Géorisques](https://www.georisques.gouv.fr) — BRGM et Ministère de la Transition écologique\n- Revenus et pauvreté par commune : [INSEE FILOSOFI 2021](https://www.insee.fr/fr/statistiques/7756729) — Licence Ouverte\n- Géocodage : [Base Adresse Nationale](https://adresse.data.gouv.fr) — Open Data\n- Protocole de paiement : [x402](https://x402.org) — standard HTTP 402 poussé par Coinbase\n\n---\n\n## Stack\n\n- **Runtime** : Node.js + [Express 5](https://expressjs.com)\n- **Paiement** : [x402-express](https://www.npmjs.com/package/x402-express) sur [Base](https://base.org)\n- **Export Excel** : [SheetJS](https://sheetjs.com)\n- **Hébergement** : [Render.com](https://render.com) (Frankfurt)\n- **DNS** : [Cloudflare](https://cloudflare.com)\n\n---\n\n## Marque\n\n[**BData X**](https://bdatax.com) — Portfolio d'APIs françaises monétisées x402 sur données publiques.\n\n---\n\n## Licence\n\nCe projet est distribué sous **Business Source License 1.1** (BSL) — voir [`LICENSE`](./LICENSE).\n\n**En résumé** :\n\n- ✅ Tu peux **étudier, forker, modifier** le code librement\n- ✅ Tu peux l'utiliser pour tes projets **personnels ou internes**\n- ✅ Tu peux **contribuer** via des pull requests\n- ❌ Tu ne peux **PAS** en faire une **SaaS commercial concurrent** de dpe.bdatax.com\n\nLe **27 août 2030**, cette licence bascule automatiquement en **Apache 2.0** (totalement libre).\n\nPour un usage commercial concurrent avant cette date, contact via le repo.\n",
  "bytes": 11739,
  "sha": "d5e93a22607eb2736cfcc1abe821955944efa69cd9b0c0133d0d0fa24578d741",
  "repo_slug": "bdatax-x/dpe-x402",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_benliberte_immo_11fa7399/readme"
}