x402 Agent Data API

API de données en temps réel qui vend des informations aux agents IA via le protocole de paiement x402.

Les agents IA paient en USDC sur le réseau Base, par requête, sans inscription ni clé API. Chaque appel déclenche un micropaiement automatique et instantané — moins de 2 secondes du bout à l'autre.

Sommaire

1. Qu'est-ce que c'est ?
2. Architecture
3. Endpoints disponibles
4. Configuration
5. Démarrage rapide (local)
6. Déploiement sur Contabo avec Docker
7. Passer du testnet au mainnet
8. Potentiel de revenus
9. Comment un agent IA paie

Qu'est-ce que c'est ?

x402 est un protocole HTTP qui réutilise le code de statut 402 Payment Required (défini en 1991, jamais utilisé) pour permettre aux serveurs d'exiger un paiement avant de livrer une ressource.

Le flux de paiement :

1. L'agent envoie une requête GET vers /crypto/prices
2. Le serveur répond 402 avec les instructions de paiement dans le header PAYMENT-REQUIRED
3. L'agent signe un transfert USDC (sans gas — le facilitateur le règle)
4. L'agent renvoie la requête avec le header PAYMENT-SIGNATURE
5. Le facilitateur vérifie et règle le paiement on-chain (~1 seconde)
6. Le serveur répond 200 avec les données

Tout se passe automatiquement côté client via les SDK @x402/fetch ou @x402/axios.

Architecture

┌─────────────────────────────────────────────────────┐
│                   Agent IA (client)                  │
│  @x402/fetch — gère 402 automatiquement             │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP
┌──────────────────────▼──────────────────────────────┐
│             x402 Agent Data API (ce serveur)         │
│  Express.js + @x402/express middleware               │
│  Ports: 4021                                         │
└──────────┬───────────────────────────┬──────────────┘
           │                           │
   ┌───────▼───────┐          ┌────────▼────────┐
   │  Facilitateur  │          │  APIs gratuites  │
   │ x402.org /     │          │  CoinGecko,      │
   │ Coinbase CDP   │          │  DeFiLlama, HN,  │
   └───────────────┘          │  GitHub, iTunes  │
                               └─────────────────┘

Endpoints disponibles

Gratuits

Crypto / DeFi

Tech Trends

Musique / Entertainment

Configuration

Variables d'environnement

Copiez .env.example vers .env et remplissez vos valeurs :

cp .env.example .env
nano .env

Facilitateurs disponibles :

Démarrage rapide (local)

Prérequis

• Node.js 20+
• Un wallet Ethereum (MetaMask, Coinbase Wallet, etc.)
• Voir SETUP-METAMASK.md pour configurer Base et obtenir des USDC de test

Installation

# Cloner / aller dans le dossier
cd x402-agent-api

# Installer les dépendances
npm install

# Configurer l'environnement
cp .env.example .env
# Éditez .env et mettez votre adresse wallet

# Démarrer le serveur
npm start

Le serveur démarre sur http://localhost:4021.

Tester un endpoint payant

# Sans paiement — reçoit un 402 avec les instructions
curl -v http://localhost:4021/crypto/prices

# Voir la liste des endpoints gratuits
curl http://localhost:4021/

Pour faire un vrai paiement, utilisez un client x402 :

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount("0xVOTRE_CLE_PRIVEE");
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
const paidFetch = wrapFetchWithPayment(fetch, client);

const res = await paidFetch("http://localhost:4021/crypto/prices");
const data = await res.json();
console.log(data);

Déploiement sur Contabo avec Docker

1. Préparer le VPS Contabo

# Sur votre VPS Contabo (Ubuntu 22.04+)
# Mettre à jour le système
sudo apt update && sudo apt upgrade -y

# Installer Docker
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER
newgrp docker

# Installer Docker Compose
sudo apt install docker-compose-plugin -y

# Vérifier
docker --version
docker compose version

2. Transférer les fichiers

# Depuis votre machine locale
rsync -avz --exclude='node_modules' --exclude='.env' \
  ./x402-agent-api/ \
  user@VOTRE_IP_CONTABO:/opt/x402-agent-api/

# Sur le VPS, configurer l'environnement
cd /opt/x402-agent-api
cp .env.example .env
nano .env   # Entrez votre WALLET_ADDRESS

3. Lancer avec Docker Compose

cd /opt/x402-agent-api

# Construire l'image et démarrer
docker compose up -d --build

# Vérifier que le conteneur tourne
docker compose ps

# Voir les logs
docker compose logs -f

4. Vérifier le déploiement

# Test de santé
curl http://localhost:4021/health

# Depuis l'extérieur (remplacer par votre IP)
curl http://VOTRE_IP_CONTABO:4021/

5. Ouvrir le port (firewall)

# UFW (Ubuntu)
sudo ufw allow 4021/tcp
sudo ufw reload

6. (Optionnel) HTTPS avec Caddy

# Installer Caddy
sudo apt install caddy -y

# Créer /etc/caddy/Caddyfile
sudo nano /etc/caddy/Caddyfile

Contenu du Caddyfile :

votre-domaine.com {
    reverse_proxy localhost:4021
}

sudo systemctl restart caddy

Commandes utiles Docker

# Arrêter le serveur
docker compose down

# Redémarrer après mise à jour du code
docker compose up -d --build

# Voir les logs en temps réel
docker compose logs -f x402-api

# Ressources utilisées
docker stats x402-agent-api

Passer du testnet au mainnet

Étapes

1. Obtenir un wallet avec de vrais USDC sur Base — voir SETUP-METAMASK.md

2. Modifier le fichier .env :

# Testnet (actuel)
WALLET_ADDRESS=0xVotrAdresse
FACILITATOR_URL=https://x402.org/facilitator
NODE_ENV=testnet

# Mainnet (production)
WALLET_ADDRESS=0xVotrAdresse
FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
NODE_ENV=production

3. Redémarrer le serveur :

# Docker
docker compose up -d --build

# Local
npm start

4. Vérifier le réseau :

curl http://localhost:4021/health
# "network": "eip155:8453" → Base mainnet ✓
# "network": "eip155:84532" → Base Sepolia (testnet)

Différences testnet vs mainnet

Potentiel de revenus

Estimation basée sur une utilisation d'agents IA actifs :

Scénario conservateur (100 requêtes/jour)

~$36/mois — couvre le VPS Contabo (~$5-8/mois) avec marge.

Scénario optimiste (1 000 requêtes/jour)

~$360/mois — revenu passif significatif si les agents IA adoptent le service.

Scénario agressif (10 000 requêtes/jour)

Les endpoints /crypto/analysis/:coin à $0.10 et /crypto/defi-yields à $0.05 sont les plus rentables. Si 10% du trafic va vers ces endpoints :

• 1 000 × $0.10 = $100/j
• ~$3 000/mois

Optimisations pour maximiser les revenus

1. Référencer le service sur x402scan.com — annuaire d'endpoints x402
2. Ajouter des endpoints premium ($0.50 - $1.00) avec des analyses plus poussées
3. Créer un SDK client pour faciliter l'intégration par les développeurs d'agents
4. Ajouter des webhooks pour notifier les agents des nouvelles données

Comment un agent IA paie

Un agent IA compatible x402 (par exemple, construit avec @x402/fetch) paie automatiquement sans aucune configuration manuelle :

// L'agent n'a besoin que de son wallet et du SDK x402
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Configuration unique
const signer = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));
const fetch = wrapFetchWithPayment(globalThis.fetch, client);

// Appels normaux — le paiement est automatique et transparent
const prices = await fetch("https://votre-api.com/crypto/prices").then(r => r.json());
const analysis = await fetch("https://votre-api.com/crypto/analysis/bitcoin").then(r => r.json());

L'agent paie ~$0.01-$0.10 par requête, reçoit les données, et continue son travail — tout en moins de 2 secondes.

Licence

MIT — Utilisez librement, en gardant la mention de l'auteur.