← 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

⚠️ 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
  • 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"
}
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

ℹ️ 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 URL

L'API est accessible à l'adresse :

https://certificator.4nkweb.com

⚠️ 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