# Address Validator API — kder-ai.com

> Validation et standardisation d'adresses postales a l'appel, payees a l'usage.
> Une requete HTTP payee en x402, sans inscription ; les boutiques peuvent aussi
> s'abonner avec une cle d'API.

## Pages du site

- [Accueil](https://kder-ai.com/) : ce que fait le service, pour qui, a quel prix.
- [Tarifs](https://kder-ai.com/pricing) : essai gratuit, Starter, Pro, Enterprise, prix a l'appel en x402.
- [Guide d'integration](https://kder-ai.com/guide) : contrat JSON, codes de retour, exemples d'appel.
- [Tester une adresse](https://kder-ai.com/validate-form) : essai gratuit sans compte.
- [Creer un compte](https://kder-ai.com/signup) : cle d'API, essai gratuit sans carte bancaire.
- [Pour les agents IA](https://kder-ai.com/agents) : serveur MCP, paiement x402 a l'appel, sans compte.
- [Comparatif des prix](https://kder-ai.com/compare) : Google, Smarty, PostGrid, Geoapify et nous, prix dates et sources.
- [Espace client](https://kder-ai.com/compte) : quota, consommation, cle (connexion requise).
- [Plan du site](https://kder-ai.com/sitemap.xml) : toutes les pages publiques, dans les six langues.

Six langues : [francais](https://kder-ai.com/), [English](https://kder-ai.com/en/),
[chinois](https://kder-ai.com/zh/), [hindi](https://kder-ai.com/hi/),
[espanol](https://kder-ai.com/es/), [arabe](https://kder-ai.com/ar/).

## Appel principal

POST https://kder-ai.com/validate

    {
      "address": {
        "street": "1600 Amphitheatre Parkway",
        "city": "Mountain View",
        "state": "CA",
        "zip": "94043",
        "country": "US"
      }
    }

Reponse 200 : `result.validated`, `result.standardized` (line1, line2, city,
state, zip, country), `result.latitude`, `result.longitude`,
`result.deliverability`, `result.confidence`, `result.degraded`.

Prix : 0,02 USDC par validation en x402, sans compte. Abonnement possible :
voir « Abonnement par cle d'API ».

## Payer

Le service parle **x402 v1**. Le corps du 402 enonce l'offre exacte
(`accepts[]` : reseau `base`, jeton USDC `0x833589…2913`, montant `20000`
unites, adresse de destination, fenetre). Le client renvoie sa signature dans
l'en-tete `X-PAYMENT` : base64 d'un objet

    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "base",
      "payload": {
        "signature": "0x…",
        "authorization": { "from": "0x…", "to": "0x…", "value": "20000",
                           "validAfter": 0, "validBefore": 0, "nonce": "0x…" }
      }
    }

- Signature EIP-712 `TransferWithAuthorization` (EIP-3009) : le domaine est
  annonce dans `accepts[].extra` (`name`, `version`) pour le contrat USDC de
  Base.
- Le reglement est execute par un facilitateur avant que le service soit rendu :
  un paiement non encaisse est refuse (402).
- La reponse 200 porte `X-PAYMENT-RESPONSE` : base64 de
  `{success, transaction, network, payer}`.
- Cout : 0,02 USDC par validation, sans compte.

## Abonnement par cle d'API

Une boutique peut s'abonner au lieu de payer a l'appel : compte sur
https://kder-ai.com/signup, offres sur https://kder-ai.com/pricing, guide
d'integration sur https://kder-ai.com/guide, essai sans compte sur
https://kder-ai.com/validate-form. La cle se place dans l'en-tete `X-API-Key` de
`POST /validate`.

- Si `X-API-Key` et `X-PAYMENT` sont presents, la cle est prioritaire et rien
  n'est encaisse en USDC.
- Refus : `401` cle inconnue, `403` essai termine, `402` quota du mois consomme,
  `503` base des comptes injoignable (jamais une demande de paiement).
- L'espace client https://kder-ai.com/compte affiche la consommation et
  regenere une cle perdue.

## Reponse 402

Un 402 signifie « non paye », pas « requete invalide » : le corps JSON est un
document `PaymentRequired` conforme a x402 v1 —

    { "x402Version": 1, "error": "…", "accepts": [ { "scheme": "exact",
      "network": "base", "maxAmountRequired": "20000", "asset": "0x…",
      "payTo": "0x…", "resource": "https://kder-ai.com/validate",
      "mimeType": "application/json", "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" } } ] }

Les cles historiques (`price`, `currency`, `wallet`, `protocol`, `version`)
restent publiees pour l'outillage. Chaque 402 est journalise cote service sous
forme de metadonnees de requete (IP pseudonymisee), jamais avec l'adresse
envoyee.

## Points d'entree publies

- https://kder-ai.com/manifest : manifeste machine-lisible — schemas derives des
  modeles, exemples, cas d'usage, limites.
- https://kder-ai.com/health : etat du service et de ses dependances.
- https://kder-ai.com/metrics : compteurs du processus (format texte).
- https://kder-ai.com/metrics/revenue : revenu agrege sur 24 h / 7 j / 30 j, et
  disponibilite du registre de paiement.
- https://kder-ai.com/metrics/agents : observabilite des appelants ÔÇö requetes par
  classe (agents IA, annuaires MCP, moteurs, outils, navigateurs), agents et pages
  les plus demandes, conversion des agents IA, et la liste blanche publiee des
  agents IA reconnus. Aucune adresse en clair : les IP sont pseudonymisees
  (SHA-256 + sel). Detail : https://github.com/Kder974/address-validator/blob/main/docs/AGENTS-IA.md
- https://kder-ai.com/docs : documentation interactive.
- https://kder-ai.com/openapi.json : contrat OpenAPI.
- https://kder-ai.com/.well-known/security.txt : contact securite (RFC 9116).
- https://kder-ai.com/mcp : serveur MCP (JSON-RPC 2.0) — outil payant
  `validate_address`, decouverte gratuite (`tools/list`), paiement x402 v2 dans
  `params._meta["x402/payment"]` (un client v1 peut presenter `X-PAYMENT`).
- https://kder-ai.com/.well-known/mcp-server : carte de decouverte du serveur MCP.
- https://kder-ai.com/llms.txt : ce fichier.
- https://kder-ai.com/AGENTS.md : guide d'integration pour agents autonomes.

## Limites

- Verification : les adresses des Etats-Unis passent par SmartyStreets (USPS DPV) ;
  celles de France et d'outre-mer par la Base Adresse Nationale (BAN : score >= 0.8,
  code postal et ville confrontes) ; les autres pays ne sont pas couverts par un
  referentiel verifie, leur verification reste partielle.
- Contrat du 402 : le corps x402 v1 porte `network` a la racine, `x402Version`,
  `accepts[0].outputSchema` (schema de sortie derive de `ValidationResponse`) et
  les cles historiques `price`, `currency`, `wallet`, `protocol` (D80).
- Mode degrade honnete : si le fournisseur est injoignable, la reponse reste un
  HTTP 200 avec `degraded: true` et une confiance basse. Lire `degraded`.
- Serveur MCP : un seul outil, sans etat, sans flux SSE (`GET /mcp` repond 405)
  et sans ressources ni prompts (`resources/list` et `prompts/list` rendent des
  listes vides). L'appel de l'outil est paye : un appel sans paiement rend un
  resultat d'outil `isError` dont `structuredContent` est l'offre x402 v2, et le
  client MCP la paie dans `params._meta["x402/payment"]`.
- La voie heritagee `X-Payment-Proof` (secret partage) reste acceptee pour
  l'outillage de l'exploitant, mais un agent tiers doit payer en x402.
- Limitation de debit tenue en amont par le reverse proxy : 10 requetes par
  seconde et par IP (rafale 20), HTTP 429 au-dela.
- Le tableau de bord d'exploitation n'est pas public.