SQLite x402 Gateway 🔐💾

Transformez n'importe quelle base SQLite (ou PostgreSQL) en API monétisée à la requête, en une seule commande.

Basé sur le protocole ouvert x402 (paiement via le code HTTP 402 Payment Required), pensé pour l'économie naissante des agents IA.

🆚 En quoi c'est différent de ce qui existe déjà

	SDK x402 officiel (Coinbase)	SQLite x402 Gateway
Écrire les routes à la main	Oui, requis	Non — auto-détectées depuis votre base
Installation de base	~500 paquets	~70 paquets (juste Express)
Mode démo sans crypto	Non	Oui, wallet et paiements simulés
Vrai paiement testnet	À configurer soi-même	npm run generate-wallet et c'est parti
Multi-base de données	Non	SQLite (natif) + PostgreSQL (optionnel)
Multi-réseau blockchain	Oui, manuel	Configurable en un champ (x402RealMode.network)
Cache / pagination / rate limiting	Non inclus	Inclus par défaut
CLI / Docker / SDK client	Non	Les trois inclus

🎯 Démarrage rapide

npm install
npm start

⭐ Fonctionnalité phare : auto-monétisation d'une base existante

node scripts/monetize.js /chemin/vers/votre-base.db
npm start

🧩 Toutes les fonctionnalités (v2)

Cœur du protocole

• Simulation x402 complète (402 → preuve de paiement → vérification → données)
• Mode réel testnet (Base Sepolia, vrai SDK Coinbase x402-express, zéro argent réel) : npm install x402-express x402-fetch
• Multi-réseaux en mode réel : base-sepolia, base (mainnet réel ⚠️), polygon, solana selon support du facilitateur
• Schéma "upto" (paiement variable selon ressources consommées) — simulé, pour expérimenter avec cette partie avancée du protocole

Bases de données

• SQLite natif (node:sqlite, zéro dépendance) par défaut
• PostgreSQL optionnel (npm install pg, database.type: "postgres")
• Auto-détection de schéma avec description de routes enrichie à partir des noms de colonnes

Performance & robustesse

• Cache de requêtes en mémoire (TTL configurable, désactivable)
• Pagination (?page=&limit=) validée strictement (pas de valeurs négatives/absurdes)
• Rate limiting par IP (fenêtre glissante, configurable)
• En-têtes de sécurité basiques (X-Frame-Options, X-Content-Type-Options...)
• Tests automatisés (npm run test:unit, node:test natif, 14 tests)

Intégrations & observabilité

• Webhooks (Slack, Discord, ou tout endpoint HTTP) à chaque transaction
• Documentation OpenAPI 3.0 auto-générée (/openapi.json) — utile pour la découverte automatique par des agents IA
• Dashboard admin avec graphique de revenus sur 7 jours, transactions, routes populaires

Expérience développeur

• CLI (node bin/cli.js start|monetize|test|..., prête pour publication npx sqlite-x402-gateway)
• Docker / Docker Compose (docker compose up)
• SDK client (packages/client) pour consommer une gateway sans réécrire la logique 402
• Gestion sécurisée des clés : .env pour les clés privées, jamais dans config.json, jamais commité

📡 Comment fonctionne le protocole x402

1. Le client appelle une route protégée, ex. /api/products
2. Le serveur répond 402 Payment Required avec le prix et les instructions
3. Le client génère une preuve de paiement et la renvoie
4. Le serveur vérifie, exécute le SQL (avec cache et pagination), renvoie les données

⚙️ Configuration complète (config/config.json)

{
  "server": { "port": 3000, "host": "localhost" },
  "database": { "type": "sqlite", "path": "./database/data.db", "autoCreate": true, "connectionString": "" },
  "wallet": { "address": "0x...", "mode": "simulation", "realAddress": "" },
  "freeMode": false,
  "developerMode": false,
  "paymentMode": "simulation",
  "cache": { "enabled": true, "ttlMs": 5000 },
  "rateLimit": { "enabled": true, "windowMs": 60000, "maxRequests": 60 },
  "webhooks": { "enabled": false, "urls": [] },
  "x402RealMode": { "network": "base-sepolia", "facilitatorUrl": "https://x402.org/facilitator" },
  "routes": [ { "path": "/api/users", "method": "GET", "price": "0.01", "sql": "SELECT * FROM users LIMIT 20" } ]
}

🛠️ Commandes disponibles

Commande	Description
npm start	Démarre le serveur
npm run test	Simule un agent IA qui paie
npm run test:unit	Lance les 14 tests unitaires
npm run monetize -- /chemin/base.db	Auto-génère les routes depuis une base existante
npm run generate-wallet	Génère un vrai wallet testnet
npm run reset-db	Réinitialise la base de démo
node scripts/pay-as-agent.js /api/users	Paiement réel testnet, clé lue depuis .env
docker compose up	Démarre tout via Docker
node bin/cli.js help	Aide de la CLI

📂 Structure du projet

SQLite-x402-Gateway/
├── src/
│   ├── index.js, server.js, gateway.js
│   ├── payment-simulator.js, real-x402-adapter.js
│   ├── schema-introspector.js ⭐
│   ├── db-adapters/ (sqlite-adapter.js, postgres-adapter.js)
│   ├── cache.js, rate-limiter.js, webhooks.js, openapi-generator.js
│   ├── env-loader.js, config-loader.js, database-init.js, logger.js, admin.js
├── public/ (interface admin + graphique)
├── scripts/ (test-client, monetize, generate-wallet, pay-as-agent)
├── bin/cli.js
├── packages/client/ (SDK npm consommable séparément)
├── test/ (14 tests node:test)
├── config/, database/
├── Dockerfile, docker-compose.yml
├── .github/workflows/ci.yml
├── .env.example
├── LICENSE (MIT), CONTRIBUTING.md

⚠️ Limites connues (honnêteté avant tout)

• Le mode simulation est un outil pédagogique/MVP, pas une intégration blockchain de production.
• Le mode réel utilise le testnet Base Sepolia par défaut ; passer à "base" (mainnet) implique de vrais fonds.
• Le schéma "upto" n'est simulé que côté serveur ; aucune implémentation on-chain officielle disponible à ce jour dans x402-express.
• Le support PostgreSQL suppose que vos requêtes de config sont compatibles (SELECT + LIMIT/OFFSET standards).

📄 Licence

MIT — voir LICENSE

🤝 Contribuer

Voir CONTRIBUTING.md