← Retour au Dashboard

Documentation API d'Ancrage

API REST pour ancrer et vérifier des documents sur Bitcoin Signet, et utiliser le faucet

🔐 Authentification

Toutes les requêtes vers l'API d'ancrage (sauf les endpoints publics) nécessitent une clé API dans le header X-API-Key.

X-API-Key: votre-clé-api-ici

Endpoints publics (sans authentification) :

  • GET /health - Vérification de santé (API d'ancrage)
  • GET /api/anchor/locked-utxos - Liste des UTXO verrouillés
  • GET /health - Vérification de santé (API faucet)

Endpoints nécessitant une clé API :

  • POST /api/anchor/document - Ancrer un document
  • POST /api/anchor/verify - Vérifier un hash
  • POST /api/faucet/request - Demander des sats
  • POST /api/watermark/document - Ajouter un filigrane et ancrer un document

⚠️ Important : Conservez votre clé API secrète et ne la partagez jamais publiquement.

GET /health

Vérifie l'état de santé de l'API. Cet endpoint est public et ne nécessite pas d'authentification.

Réponse (200 OK)

{
  "ok": true,
  "service": "anchor-api",
  "bitcoin": {
    "connected": true,
    "blocks": 12345
  },
  "timestamp": "2026-01-25T12:00:00.000Z"
}

Réponse (503 Service Unavailable) - Bitcoin non connecté

{
  "ok": false,
  "service": "anchor-api",
  "error": "Bitcoin RPC connection failed",
  "timestamp": "2026-01-25T12:00:00.000Z"
}
POST /api/anchor/document

Ancre un document sur la blockchain Bitcoin Signet en créant une transaction qui inclut le hash du document dans un OP_RETURN.

Paramètres (Body JSON)

Paramètre Type Requis Description
hash string Oui Hash SHA256 du document en hexadécimal (64 caractères)
documentUid string Non Identifiant optionnel du document (pour le logging)

Exemple de requête

curl -X POST https://certificator.4nkweb.com/api/anchor/document \
  -H "Content-Type: application/json" \
  -H "X-API-Key: votre-clé-api" \
  -d '{
    "hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "documentUid": "doc-12345"
  }'

Réponse (200 OK)

{
  "txid": "abc123def456...",
  "status": "pending",
  "confirmations": 0,
  "block_height": null
}

Codes de statut possibles

  • 200 Succès - Transaction créée et envoyée au mempool
  • 400 Requête invalide - Hash manquant ou format incorrect
  • 401 Non autorisé - Clé API manquante ou invalide
  • 402 Solde insuffisant - Pas assez de fonds pour créer la transaction
  • 503 Service indisponible - Erreur "too-long-mempool-chain" (trop d'ancêtres non confirmés)
  • 500 Erreur serveur - Erreur interne lors de la création de la transaction

Exemple d'erreur (402 Payment Required)

{
  "error": "Insufficient Balance",
  "message": "Insufficient balance to create anchor transaction"
}

Exemple d'erreur (503 Service Unavailable) - Too Long Mempool Chain

{
  "error": "Service Unavailable",
  "message": "too-long-mempool-chain, too many unconfirmed ancestors [limit: 25]"
}

Cette erreur se produit lorsque l'API tente d'utiliser un UTXO non confirmé qui a trop d'ancêtres non confirmés dans le mempool. Bitcoin Core limite la chaîne d'ancêtres à 25 transactions pour éviter les attaques par spam.

Solution : L'API utilise maintenant uniquement des UTXOs confirmés (au moins 1 confirmation) pour éviter cette erreur. Attendez qu'un bloc soit miné pour que les UTXOs soient confirmés.

ℹ️ Gestion des UTXOs

  • L'API utilise uniquement des UTXOs confirmés (au moins 1 confirmation) pour éviter les erreurs "too-long-mempool-chain"
  • Les UTXOs non confirmés sont automatiquement exclus de la sélection
  • Chaque transaction d'ancrage provisionne automatiquement 7 UTXOs de 2500 sats pour les ancrages futurs
  • Les UTXOs provisionnés deviendront utilisables après confirmation dans un bloc
POST /api/anchor/verify

Vérifie si un hash est ancré sur la blockchain Bitcoin Signet. Recherche dans les transactions OP_RETURN pour trouver le hash.

Paramètres (Body JSON)

Paramètre Type Requis Description
hash string Oui Hash SHA256 à vérifier (64 caractères hex)
txid string Non ID de transaction optionnel pour accélérer la recherche

Exemple de requête

curl -X POST https://certificator.4nkweb.com/api/anchor/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: votre-clé-api" \
  -d '{
    "hash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "txid": "abc123def456..."
  }'

Réponse (200 OK) - Hash trouvé

{
  "found": true,
  "txid": "abc123def456...",
  "block_height": 12345,
  "confirmations": 100,
  "timestamp": "2026-01-25T10:00:00.000Z"
}

Réponse (200 OK) - Hash non trouvé

{
  "found": false,
  "txid": null,
  "block_height": null,
  "confirmations": null,
  "timestamp": null
}

Codes de statut possibles

  • 200 Succès - Vérification effectuée
  • 400 Requête invalide - Hash manquant ou format incorrect
  • 401 Non autorisé - Clé API manquante ou invalide
  • 500 Erreur serveur - Erreur interne lors de la vérification
GET /api/anchor/locked-utxos

Retourne la liste des UTXO actuellement verrouillés par le mutex de l'API. Cet endpoint est public et ne nécessite pas d'authentification.

Exemple de requête

curl -X GET https://certificator.4nkweb.com/api/anchor/locked-utxos

Réponse (200 OK)

{
  "locked": [
    {
      "txid": "abc123def456...",
      "vout": 0
    },
    {
      "txid": "def456abc123...",
      "vout": 1
    }
  ],
  "count": 2
}
POST /api/faucet/request

Demande des sats (testnet coins) via le faucet. Distribue 50 000 sats (0.0005 BTC) par défaut sur une adresse Bitcoin Signet valide. Nécessite une clé API valide dans le header x-api-key.

Paramètres (Body JSON)

Paramètre Type Requis Description
address string Oui Adresse Bitcoin Signet valide (commence par tb1, bcrt1, 2 ou 3)

Exemple de requête

curl -X POST https://certificator.4nkweb.com/api/faucet/request \
  -H "Content-Type: application/json" \
  -H "x-api-key: votre-clé-api" \
  -d '{
    "address": "tb1qwe0nv3s0ewedd63w20r8kwnv22uw8dp2tnj3qc"
  }'

Réponse (200 OK)

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

Codes de statut possibles

  • 200 Succès - Transaction créée et envoyée au mempool
  • 400 Requête invalide - Adresse manquante ou format incorrect
  • 401 Non autorisé - Clé API manquante ou invalide
  • 503 Service indisponible - Solde insuffisant dans le wallet du faucet
  • 500 Erreur serveur - Erreur interne lors de la création de la transaction

Exemple d'erreur (401 Unauthorized)

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Exemple d'erreur (503 Service Unavailable)

{
  "error": "Insufficient Balance",
  "message": "Insufficient balance to send coins"
}

ℹ️ Notes importantes

  • Le montant par défaut est de 50 000 sats (0.0005 BTC)
  • L'adresse doit être une adresse Bitcoin Signet valide
  • La transaction est envoyée au mempool immédiatement
  • Le statut "pending" signifie que la transaction est dans le mempool mais pas encore confirmée
  • Les confirmations augmentent à mesure que les blocs sont minés
POST /api/watermark/document

Ajoute un filigrane à un document, le convertit en PDF, et l'ancre sur la blockchain Bitcoin Signet. Les fichiers sont automatiquement scannés avec ClamAV avant traitement.

Paramètres (Body JSON)

Paramètre Type Requis Description
apiKey string Oui Clé API pour l'authentification (peut aussi être dans le header X-API-Key)
fileData string Conditionnel Fichier encodé en base64 (requis si textContent n'est pas fourni)
fileName string Non Nom du fichier (requis si fileData est fourni)
mimeType string Non Type MIME du fichier (requis si fileData est fourni)
textContent string Conditionnel Contenu texte à convertir en PDF (requis si fileData n'est pas fourni)
watermarkOptions object Oui Options de filigrane (voir détails ci-dessous)

Structure de watermarkOptions

Paramètre Type Description
enabled boolean Doit être true
text string Texte libre du filigrane (optionnel)
signature string Signature cryptographique (optionnel)
depositor string Nom du dépositaire (optionnel)
dateUTC boolean Ajouter la date UTC dans le filigrane
dateLocal boolean Ajouter la date locale dans le filigrane
blockNumber boolean Ajouter le numéro de bloc dans le filigrane
blockHash boolean Ajouter le hash du bloc dans le filigrane
documentHash boolean Ajouter le hash du document d'origine dans le filigrane

Exemple de requête

curl -X POST https://watermark.certificator.4nkweb.com/api/watermark/document \
  -H "Content-Type: application/json" \
  -H "X-API-Key: votre-clé-api" \
  -d '{
    "apiKey": "votre-clé-api",
    "fileData": "base64_encoded_file_data",
    "fileName": "document.pdf",
    "mimeType": "application/pdf",
    "watermarkOptions": {
      "enabled": true,
      "text": "Document confidentiel",
      "depositor": "John Doe",
      "dateUTC": true,
      "dateLocal": true,
      "blockNumber": true,
      "documentHash": true
    }
  }'

Réponse (200 OK)

{
  "success": true,
  "antivirusScan": {
    "scanned": true,
    "clean": true,
    "infected": false,
    "viruses": [],
    "error": null
  },
  "original": {
    "txid": "abc123def456...",
    "status": "pending",
    "confirmations": 0,
    "hash": "a1b2c3d4e5f6...",
    "file": {
      "name": "document.pdf",
      "extension": "pdf",
      "data": "base64_encoded_pdf"
    }
  },
  "watermarked": {
    "txid": "def456abc123...",
    "status": "pending",
    "confirmations": 0,
    "hash": "b2c3d4e5f6a1...",
    "file": {
      "name": "document.pdf",
      "extension": "pdf",
      "data": "base64_encoded_pdf"
    }
  },
  "certificate": {
    "name": "certificat-document.pdf",
    "extension": "pdf",
    "data": "base64_encoded_pdf"
  },
  "merged": {
    "name": "document-avec-certificat.pdf",
    "extension": "pdf",
    "data": "base64_encoded_pdf"
  }
}

Codes de statut possibles

  • 200 Succès - Document filigrané et ancré
  • 400 Requête invalide - Fichier infecté, paramètres manquants ou incorrects
  • 401 Non autorisé - Clé API manquante ou invalide
  • 500 Erreur serveur - Erreur interne lors du traitement

Exemple d'erreur (400 Bad Request) - Fichier infecté

{
  "error": "Bad Request",
  "message": "File contains viruses",
  "viruses": ["Trojan.Example"],
  "antivirusScan": {
    "scanned": true,
    "clean": false,
    "infected": true,
    "viruses": ["Trojan.Example"],
    "error": null
  }
}

ℹ️ Notes importantes

  • Tous les fichiers sont automatiquement scannés avec ClamAV avant traitement
  • Les fichiers infectés sont rejetés avec une erreur 400
  • Si ClamAV est indisponible, le traitement continue en mode dégradé (antivirusScan.scanned = false)
  • Le résultat inclut 4 fichiers PDF : original, filigrané, certificat, et fusionné (filigrané + certificat)
  • Les fichiers sont retournés en base64 dans le champ data
  • Les TXID sont des liens cliquables vers mempool.4nkweb.com dans les résultats
POST /api/scan/buffer

Scanne un buffer de données (base64) pour détecter les virus avec ClamAV. Cette API est utilisée en interne par l'API filigrane.

Base URL : https://antivir.certificator.4nkweb.com

Paramètres (Body JSON)

Paramètre Type Requis Description
data string Oui Données encodées en base64 à scanner
filename string Non Nom du fichier (pour le logging)

Exemple de requête

curl -X POST https://antivir.certificator.4nkweb.com/api/scan/buffer \
  -H "Content-Type: application/json" \
  -d '{
    "data": "base64_encoded_data",
    "filename": "document.pdf"
  }'

Réponse (200 OK) - Fichier propre

{
  "clean": true,
  "infected": false,
  "viruses": [],
  "filename": "document.pdf",
  "size": 12345
}

Réponse (200 OK) - Fichier infecté

{
  "clean": false,
  "infected": true,
  "viruses": ["Trojan.Example"],
  "filename": "document.pdf",
  "size": 12345
}

Codes de statut possibles

  • 200 Succès - Scan effectué (fichier propre ou infecté)
  • 400 Requête invalide - Données manquantes ou format incorrect
  • 503 Service indisponible - ClamAV non disponible
  • 500 Erreur serveur - Erreur interne lors du scan

ℹ️ Notes importantes

  • Cette API est principalement utilisée en interne par l'API filigrane
  • Le port fixe est 3023
  • Si ClamAV est indisponible, l'API retourne une erreur 503
  • Les fichiers sont scannés en mémoire (pas de fichiers temporaires sur disque)
GET /api/utxo/list

Obtient la liste complète des UTXOs du wallet, catégorisés par type (bloc rewards, ancrages, changes, frais).

Base URL : https://dashboard.certificator.4nkweb.com

Exemple de requête

curl -X GET https://dashboard.certificator.4nkweb.com/api/utxo/list

Réponse (200 OK)

{
  "blocRewards": [...],
  "anchors": [...],
  "changes": [...],
  "fees": [...],
  "counts": {
    "blocRewards": 10,
    "anchors": 150,
    "changes": 25,
    "fees": 5,
    "total": 190,
    "availableForAnchor": 180,
    "confirmedAvailableForAnchor": 175
  }
}

ℹ️ Notes importantes

  • Seuls les UTXOs avec au moins 1 confirmation sont retournés (pour éviter les erreurs "too-long-mempool-chain")
  • availableForAnchor : Nombre d'UTXOs disponibles pour l'ancrage (> 2000 sats, non dépensés, non verrouillés)
  • confirmedAvailableForAnchor : Nombre d'UTXOs confirmés disponibles pour l'ancrage
  • Les UTXOs sont triés par montant décroissant par défaut
GET /api/utxo/small-info

Obtient les informations sur les UTXOs de moins de 2500 sats disponibles pour consolidation (nombre et montant total).

Base URL : https://dashboard.certificator.4nkweb.com

Exemple de requête

curl -X GET https://dashboard.certificator.4nkweb.com/api/utxo/small-info

Réponse (200 OK)

{
  "count": 45,
  "totalAmount": 0.0001125,
  "totalSats": 11250
}

ℹ️ Notes importantes

  • Seuls les UTXOs confirmés (< 2500 sats, non dépensés, non verrouillés) sont comptés
  • count : Nombre d'UTXOs disponibles pour consolidation
  • totalAmount : Montant total en BTC
  • totalSats : Montant total en satoshis
POST /api/utxo/consolidate

Consolide tous les UTXOs de moins de 2500 sats en un seul gros UTXO. Cette opération optimise le wallet en réduisant le nombre de petits UTXOs.

Base URL : https://dashboard.certificator.4nkweb.com

Exemple de requête

curl -X POST https://dashboard.certificator.4nkweb.com/api/utxo/consolidate

Réponse (200 OK) - Succès

{
  "success": true,
  "txid": "a1b2c3d4e5f6...",
  "inputCount": 45,
  "totalInputAmount": 0.0001125,
  "changeAmount": 0.0001025,
  "estimatedFee": 0.00001
}

Réponse (500) - Erreur

{
  "success": false,
  "error": "No small UTXOs available for consolidation"
}

Codes de statut possibles

  • 200 Succès - Consolidation effectuée
  • 500 Erreur - Aucun UTXO disponible ou erreur lors de la consolidation

ℹ️ Notes importantes

  • Seuls les UTXOs confirmés de moins de 2500 sats sont consolidés
  • Les UTXOs verrouillés ou déjà dépensés sont exclus
  • La transaction est envoyée au mempool immédiatement
  • Le montant consolidé est retourné comme change (moins les frais estimés)
  • Cette opération optimise le wallet en réduisant le nombre de petits UTXOs

ℹ️ Informations Complémentaires

Format du Hash

Le hash doit être un hash SHA256 en format hexadécimal, exactement 64 caractères.

Exemple valide: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
Longueur: 64 caractères
Format: hexadécimal (0-9, a-f, A-F)

Format de la Transaction

Les transactions d'ancrage incluent :

  • Un output OP_RETURN contenant "ANCHOR:" suivi du hash
  • Un output d'ancrage de 2500 sats
  • 7 outputs de provisionnement de 2500 sats chacun
  • Un output de change (si nécessaire)

Base URLs

Les APIs sont accessibles aux adresses suivantes :

API d'Ancrage : https://certificator.4nkweb.com
API Filigrane : https://watermark.certificator.4nkweb.com
API ClamAV : https://antivir.certificator.4nkweb.com

Ports fixes

Tous les ports sont fixes et ne peuvent pas être modifiés :

  • API d'Ancrage : Port 3010
  • API Faucet : Port 3021
  • API Filigrane : Port 3022
  • API ClamAV : Port 3023
  • Dashboard : Port 3020

⚠️ Notes importantes

  • Les transactions sont envoyées au mempool immédiatement
  • Le statut "pending" signifie que la transaction est dans le mempool mais pas encore confirmée
  • Les confirmations augmentent à mesure que les blocs sont minés
  • En cas d'erreur 402 (Solde insuffisant), vous devez approvisionner le wallet de l'API