Ce week-end, j'ai créé un serveur MCP pour un portefeuille Bitcoin : des outils que les agents d'IA peuvent appeler via le Model Context Protocol. Le [repo](https://github.com/markmhendrickson/mcp-server-bitcoin) expose 93 outils sur les couches 1 et 2. Un mnémonique pilote les deux.

J'étais auparavant directeur général de [Leather](https://leather.io), un portefeuille crypto qui prend également en charge Bitcoin et Stacks. Chez Leather, j'ai constaté que les portefeuilles d'auto-garde destinés aux humains s'adressaient principalement aux personnes désireuses d'absorber l'attention et la complexité (par exemple les dégens et les développeurs). Cela signifiait l'hygiène clé, la connaissance des frais, les flux de confirmation et le reste. La charge cognitive a limité le véritable marché adressable.

Les portefeuilles agents changent cela. Lorsque l'interface principale est constituée d'agents qui raisonnent et exécutent dans le cadre de la politique, l'utilisateur approuve uniquement ce qui compte. Les frictions diminuent et le nombre de personnes capables de pratiquement détenir leurs propres clés augmente.

Les deux mêmes chaînes. Surface différente.

## Ce que le serveur expose (L1 et L2 sur une seule surface)

Le serveur est un processus MCP unique. Les clients envoient des noms d'outils et des arguments JSON via stdio et récupèrent des résultats structurés. Les actions destructrices (envois, signature et diffusion, déploiement) prennent en charge `dry_run` et ne sont pas diffusées par défaut. Le serveur ne renvoie jamais de clés ou de mnémoniques.

### Couche 1 (Bitcoin)

**Bitcoin de base :**

- Dérivation d'adresses pour P2PKH, P2SH-P2WPKH, P2WPKH et P2TR avec clés et chemins publics.
- Comptes avec soldes par type d'adresse ([mempool.space](https://mempool.space) pour les données UTXO) ; solde du portefeuille et prix BTC (USD, EUR).
- Envois mono et multi-destinataires (montant en BTC ou EUR) ; aperçu du transfert avec estimation des frais avant envoi.
- Sweep (envoi max) et consolidation UTXO.
- Signature, décodage et signature de lots PSBT ; signature et vérification du message (héritage ECDSA et BIP-322).
- Niveaux de frais de mempool.space et estimation des frais par nombre d'entrées/sorties et type d'adresse.
- Liste UTXO avec filtres (type d'adresse, valeur minimale, confirmé uniquement) et détails par UTXO.

**Ordinaux et inscriptions :**

- Liste des inscriptions avec pagination ; détails de l'inscription (genèse, type de contenu, ordinal sat, rareté, emplacement).
- Envoyer des inscriptions (UTXO complet ou divisé afin que seule la plage sat de l'inscription aille au destinataire).
- Extraire les ordinaux des UTXO mixtes ; récupérer BTC à partir de l'adresse des ordinaux (balayage des UTXO sans inscription) ; récupérer les ordinaux qui ont atterri sur l'adresse de paiement vers l'adresse de la racine pivotante.
- Créez des inscriptions uniques ou par lots avec des estimations des frais de validation/révélation.

**Gestion des transactions et du portefeuille :**

- Historique des transactions pour BTC et Stacks ; statut pour une seule transmission.
- Accélérer le BTC en attente via RBF ; annuler le BTC en attente (envoi RBF à soi-même).
- Configuration du réseau et points de terminaison de l'API ; changer de réseau principal/réseau de test ; ajouter un réseau personnalisé.
- Répertoriez tous les noms et descriptions d'outils pris en charge.

**Ledger (application Bitcoin) :**

- Obtenez les adresses BTC à partir d'un appareil [Ledger](https://www.ledger.com) connecté.
- Signez PSBT avec l'application Ledger Bitcoin.

### Couche 2 (piles)

Le même mnémonique dérive les clés Stacks (chemin `m/44'/5757'/0'/0/0`). [Hiro](https://hiro.so) API Stacks pour les données en chaîne et la diffusion.

**Piles :**

- Adresses et clés publiques ; comptes avec solde STX, montants verrouillés, occasionnels.
- Solde comprenant des jetons fongibles et non fongibles.
- Transfert STX (micro-STX) avec mémo en option ; aperçu du transfert avec frais et vérification du solde.
- Transferts SIP-10 fongibles et SIP-9 NFT via des appels contractuels.
- Clarté : appel de fonction publique, déploiement de contrat, appel en lecture seule.
- Signer les Stacks tx sérialisés (SIP-30), signer le message, signer les données structurées SIP-018 ; estimation des frais et des frais.
- Mise à jour du profil en chaîne ([schema.org/Person](https://schema.org/Person)) pour les noms BNS.
- Requêtes de transactions avec filtres (type, plage de blocs, non ancrées) et par contrat.
- Mempool : liste des transactions en attente, statistiques du mempool, transactions abandonnées.
- Explorateur de blocs : blocs récents, bloc par hauteur ou hachage, Empile les blocs pour un bloc Bitcoin donné.
- Événements de contrat : événements pour un contrat, ou événements d'actif pour une adresse.
- Métadonnées des jetons : métadonnées et détenteurs SIP-10 et SIP-9.
- Informations sur le réseau et santé/état.

**Swaps, DeFi et pont :**

- Paires et protocoles pris en charge ([ALEX](https://alexlab.co/), [Bitflow](https://www.bitflow.finance), [Velar](https://www.velar.co)).
- Devis d'échange (rendement estimé, tarif, frais) pour les trois ; exécuter le swap via ALEX DEX. Bitflow et Velar prennent en charge les cotations et la découverte de paires ; vous pouvez ajouter l'exécution via des SDK de protocole (par exemple, le SDK Velar renvoie les paramètres d'appel de contrat).
- Échangez l'historique de l'activité en chaîne.
- Solde sBTC et informations de dépôt/retrait relais.
- Empilement : statut actuel du PoX, informations sur le cycle (blocs restants, pourcentage terminé, temps restant estimé, taux de participation), lancer l'empilement en solo, révoquer la délégation.

**BNS et données de marché :**

- [BNS](https://docs.stacks.co/docs/stacks-blockchain/bns) recherche (nom à adresse), noms appartenant à l'adresse, enregistrement du nom BNS.
- Prix multi-actifs (par exemple [CoinGecko](https://www.coingecko.com)) ; historique des prix pour la cartographie.
- Résumé du portefeuille (BTC + STX en USD) ; tous les actifs et objets de collection (inscriptions, Stacks NFT).

**Ledger (application Stacks) :**

- Obtenez les adresses Stacks de Ledger.
- Signez la transaction Stacks avec l'application Ledger Stacks.

## Sécurité et conception

⚠️ Ce serveur MCP est expérimental et n'est pas sécurisé pour des fonds significatifs. Utilisez-le uniquement avec des portefeuilles que vous êtes prêt à perdre. Personne n’a testé ou audité le code. Je le traite comme un artefact de recherche pour explorer les surfaces de portefeuille natives des agents.

Les opérations destructrices sont par défaut « dry_run : true ». Des outils de prévisualisation et d’estimation existent pour chaque chemin d’envoi. Les clés restent hors du contrôle de version et hors des réponses de l'outil. Le script d'exécution charge « .env » à partir de la racine du dépôt.

**Variables clés du portefeuille (garder secrètes, ne jamais s'engager) :**

- **`BTC_PRIVATE_KEY`** — Clé privée Bitcoin codée en WIF ; si défini, a priorité sur le mnémonique.
- **`BTC_MNEMONIC`** — Phrase de départ BIP-39 ; le serveur l'utilise pour dériver les clés Bitcoin et Stacks (même mnémonique, chemin `m/44'/5757'/0'/0/0` pour Stacks).
- **`BTC_MNEMONIC_PASSPHRASE`** — Phrase secrète BIP-39 facultative à utiliser avec `BTC_MNEMONIC`.

**Sécurité et limites (env ou .env) :**

- **`BTC_NETWORK`** — `mainnet` ou `testnet` (par défaut `testnet`).
- **`BTC_MAINNET_ENABLED`** — Définissez ceci pour autoriser les envois sur le réseau principal (indicateur de sécurité).
- **`BTC_DRY_RUN`** — Lorsqu'elles sont définies (par défaut), les opérations destructrices (envois, signature et diffusion, déploiement) ne sont pas diffusées ; définissez-le sur « false » pour autoriser des transactions réelles.
- **`BTC_MAX_SEND_BTC`** — Plafond facultatif sur le montant d'envoi en BTC ; le serveur rejette les demandes supérieures.
- **`BTC_MAX_FEE_SATS`** — Plafond facultatif des frais en satoshis par transaction.
- **`STX_ACCOUNT_INDEX`** — Index du compte de dérivation des piles (par défaut `0`).
- La configuration détermine autrement le niveau de frais (taux fixe ou niveau mempool.space : heure, demi-heure, le plus rapide).

## Comment cela s'adapte à ma pile d'agents

J'exécute des agents sur une architecture à trois couches. Les couches sont clairement séparées afin que la mémoire, le raisonnement et l'action restent au bon endroit.

**Couche de vérité :** Il s'agit du substrat de mémoire. Il contient des données typées et structurées : fonds, flux, transactions, contacts, tâches, etc. Dans ma configuration, le magasin canonique est [Neotoma](/posts/truth-layer-agent-memory). Il utilise le sourcing d'événements et les réducteurs, avec une résolution complète de provenance et d'entité. Les agents l'ont lu. Ils n’écrivent jamais directement la vérité. Toutes les mises à jour transitent par les événements de domaine produits par la couche d'exécution.

**Couche stratégique :** C'est là que résident les objectifs, les contraintes et les tactiques. Les documents stratégiques, les playbooks tactiques et les manuels d’opérations se trouvent ici. Les agents utilisent cette couche pour raisonner : ils lisent l’état du monde, évaluent les priorités et les risques, et produisent des décisions et des commandes. La stratégie est une pure cognition. Aucun effet secondaire. État entré, décisions retirées.

**Couche d'exécution :** C'est là que les actions externes se produisent. Il prend des commandes de la couche stratégique et exécute des effets secondaires via des adaptateurs : courrier électronique, calendrier, DNS et, dans ce cas, le portefeuille MCP Bitcoin et Stacks. Le serveur de portefeuille est un adaptateur d’exécution parmi tant d’autres. Cela ne modifie jamais la couche de vérité. Il fait la chose (envoyer, signer, échanger) et le reste de la pile enregistre ce qui s'est passé via les événements de domaine. Commandes entrantes, événements sortants.

Je définis et maintiens la stratégie. Les agents lisent à partir de la couche de vérité et appellent les outils MCP pour les exécuter. Je n'utilise pas d'interface utilisateur cryptographique par pointer-cliquer pour les opérations de routine. J'interviens uniquement pour approuver les actions qui dépassent mes limites prédéfinies.

À court terme, mes cas d'utilisation sont ponctuels : payer des services, rééquilibrer des portefeuilles via des invites manuelles. À plus long terme, je souhaite que ces flux soient automatisés. Les agents surveilleraient, raisonneraient et exécuteraient dans le cadre de la politique. Je verrais des explications et approuverais en cas de besoin.

## Comment j'aborde la construction

Je suis d'abord en train de nourrir le serveur dans mes propres flux de travail. Je teste chaque surface (envois, PSBT, ordinaux, transferts de Stacks, swaps) progressivement avec de petites quantités et des essais à sec.

Je l'ai connecté à la même pile où j'utilise déjà [couches de vérité et de stratégie](/posts/agentic-search-and-the-truth-layer#where-ive-hit-limits). Les agents peuvent combiner les actions du portefeuille avec le calendrier, les e-mails et les données. Les utilisateurs externes ne sont pas encore concernés.

Mon objectif est de valider la forme d'une surface de portefeuille agent et de rendre mes propres opérations Bitcoin et Stacks pilotées par un agent plutôt que manuelles.

Pour l'exécuter : clonez [mcp-server-bitcoin](https://github.com/markmhendrickson/mcp-server-bitcoin) (ou ajoutez-le en tant que sous-module dans `mcp/btc_wallet/`), ajoutez le serveur à votre configuration MCP (utilisez le chemin de script `run_btc_wallet_mcp.sh`) et utilisez un portefeuille de test avec exécution à sec.