anchorage_layer_simple/api-faucet/README.md

API Faucet Bitcoin Signet

Auteur : Équipe 4NK Date : 2026-01-23 Version : 1.0.0

Description

API REST pour distribuer des sats (50000 sats = 0.0005 BTC) sur la blockchain Bitcoin Signet. Cette API permet aux utilisateurs de recevoir des fonds de test pour développer et tester des applications Bitcoin.

Caractéristiques

• Port : 3021
• Format : JSON REST API
• Bitcoin : Connexion RPC au nœud Bitcoin Signet (port 38332)
• Montant par défaut : 50 000 sats (0.0005 BTC)

Installation

Prérequis

• Node.js >= 18.0.0
• Accès au nœud Bitcoin Signet (RPC sur port 38332)
• Wallet Bitcoin avec des fonds pour distribuer

Installation des Dépendances

cd api-faucet
npm install

Configuration

1. Copier le fichier d'exemple :

cp .env.example .env

2. Éditer .env :

# Bitcoin RPC Configuration
BITCOIN_RPC_HOST=localhost
BITCOIN_RPC_PORT=38332
BITCOIN_RPC_USER=bitcoin
BITCOIN_RPC_PASSWORD=bitcoin
BITCOIN_RPC_TIMEOUT=30000

# API Configuration
FAUCET_API_PORT=3021
FAUCET_API_HOST=0.0.0.0

# Faucet Configuration
FAUCET_AMOUNT=0.0005  # Montant en BTC (50000 sats par défaut)

# Logging
LOG_LEVEL=info
NODE_ENV=production

Important :

• BITCOIN_RPC_HOST : Si l'API est dans un conteneur Docker, utiliser l'IP du conteneur Bitcoin ou host.docker.internal
• FAUCET_AMOUNT : Montant à distribuer en BTC (par défaut 0.0005 = 50000 sats)

Démarrage

Mode Développement

npm run dev

Mode Production

npm start

Avec PM2 (recommandé pour production)

# Installer PM2 globalement
sudo npm install -g pm2

# Démarrer l'API avec PM2
pm2 start src/server.js --name faucet-api

# Sauvegarder la configuration PM2
pm2 save

# Configurer PM2 pour démarrer au boot
pm2 startup
# Suivre les instructions affichées

Endpoints

GET /health

Vérifie l'état de l'API et de la connexion Bitcoin.

Authentification : Non requise

Réponse :

{
  "status": "ok",
  "service": "bitcoin-signet-faucet-api",
  "version": "1.0.0",
  "bitcoin": {
    "connected": true,
    "chain": "signet",
    "blocks": 1234,
    "networkactive": true,
    "connections": 5,
    "wallet_balance": 10.5
  },
  "timestamp": "2026-01-23T12:00:00.000Z"
}

POST /api/faucet/request

Demande des sats via le faucet.

Authentification : Non requise

Body :

{
  "address": "tb1qwe0nv3s0ewedd63w20r8kwnv22uw8dp2tnj3qc"
}

Réponse (succès) :

{
  "success": true,
  "txid": "a1b2c3d4e5f6789012345678901234567890123456789012345678901234567890",
  "address": "tb1qwe0nv3s0ewedd63w20r8kwnv22uw8dp2tnj3qc",
  "amount": 0.0005,
  "amount_sats": 50000,
  "status": "pending",
  "confirmations": 0,
  "block_height": null
}

Réponse (erreur) :

{
  "error": "Bad Request",
  "message": "Invalid Bitcoin address format"
}

Exemples d'Utilisation

Avec curl

# Vérifier l'état de l'API
curl http://localhost:3021/health

# Demander des sats
curl -X POST http://localhost:3021/api/faucet/request \
  -H "Content-Type: application/json" \
  -d '{
    "address": "tb1qwe0nv3s0ewedd63w20r8kwnv22uw8dp2tnj3qc"
  }'

Avec JavaScript (fetch)

const response = await fetch('http://localhost:3021/api/faucet/request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    address: 'tb1qwe0nv3s0ewedd63w20r8kwnv22uw8dp2tnj3qc',
  }),
});

const result = await response.json();
console.log(result);

Configuration Nginx (sur proxy 192.168.1.100)

Ajouter dans la configuration nginx du proxy :

# API Faucet
server {
    listen 443 ssl http2;
    server_name faucet.signet.4nkweb.com;

    ssl_certificate /etc/letsencrypt/live/faucet.signet.4nkweb.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/faucet.signet.4nkweb.com/privkey.pem;

    location / {
        proxy_pass http://192.168.1.103:3021;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Note : Remplacer 192.168.1.103 par l'IP du serveur où l'API est déployée.

Architecture

Client
  ↓ HTTPS
Nginx (proxy 192.168.1.100:443)
  ↓ HTTP
API Faucet (port 3021)
  ↓ RPC
Bitcoin Signet Node (port 38332)

Sécurité

Rate Limiting (Recommandé)

Pour éviter les abus, il est recommandé d'implémenter un rate limiting. Exemple avec express-rate-limit :

npm install express-rate-limit

import rateLimit from 'express-rate-limit';

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 1, // 1 requête par adresse IP toutes les 15 minutes
  message: 'Too many requests from this IP, please try again later.',
});

app.use('/api/faucet/request', limiter);

Validation des Adresses

L'API valide automatiquement les adresses Bitcoin avant d'envoyer les fonds. Seules les adresses valides sont acceptées.

Gestion des Erreurs

• 400 Bad Request : Adresse invalide
• 503 Service Unavailable : Solde insuffisant
• 500 Internal Server Error : Erreur serveur

Dépannage

L'API ne démarre pas

• Vérifier que le port 3021 n'est pas utilisé : netstat -tlnp | grep 3021
• Vérifier les logs : pm2 logs faucet-api
• Vérifier la configuration dans .env

Erreur "Insufficient balance"

• Vérifier le solde du wallet : bitcoin-cli getbalance
• Miner des blocs pour obtenir des fonds
• Vérifier que le wallet est déverrouillé

Erreur "Invalid Bitcoin address"

• Vérifier que l'adresse est une adresse Signet valide (commence par tb1, bcrt1, 2, ou 3)
• Vérifier le format de l'adresse (25-62 caractères)

Transaction non envoyée

• Vérifier les logs de l'API pour les erreurs RPC
• Vérifier que le nœud Bitcoin est accessible
• Vérifier que le wallet est déverrouillé et a des fonds

Structure des Fichiers

api-faucet/
├── package.json
├── README.md
├── .env.example
└── src/
    ├── server.js          # Serveur Express
    ├── bitcoin-rpc.js     # Client Bitcoin RPC
    ├── logger.js          # Logger
    └── routes/
        ├── faucet.js      # Routes du faucet
        └── health.js      # Routes de santé

Licence

MIT