aibtc-mcp-server

@aibtc/mcp-server

Servidor MCP nativo de Bitcoin para agentes de IA: carteras BTC/STX, rendimiento DeFi, peg sBTC, NFTs y pagos x402.

Características

• Bitcoin L1 - Consulta saldos, envía BTC, gestiona UTXOs vía mempool.space
• Cartera Propia del Agente - Los agentes tienen su propia cartera para realizar transacciones en blockchain
• Almacenamiento Seguro - Carteras cifradas con AES-256-GCM y almacenadas localmente
• Más de 350 Herramientas - Bitcoin L1 + operaciones integrales de Stacks L2
• Soporte sBTC - Operaciones nativas de Bitcoin en Stacks
• Operaciones con Tokens - Transferencias y consultas de tokens fungibles SIP-010
• Soporte NFT - Tenencias, transferencias y metadatos de NFTs SIP-009
• Trading DeFi - Intercambios en ALEX DEX y préstamos/empréstitos en Zest Protocol
• Stacking/PoX-5 - Apuesta STX con un gestor de firmantes, extiende, desapuesta, reclama recompensas sBTC
• Dominios BNS - Consultas y gestión de dominios .btc (V1 + V2)
• Pagos x402 - Manejo automático de pagos para APIs de pago

Inicio Rápido

Claude Code (Terminal)

npx @aibtc/mcp-server@latest --install

Esto configura Claude Code y crea la cartera del agente: imprime las direcciones de Stacks y Bitcoin, una contraseña generada y la frase mnemotécnica de 24 palabras una vez. Anota ambas. La frase mnemotécnica se almacena solo cifrada (AES-256-GCM) en ~/.aibtc/ en esta máquina, y la contraseña no se guarda en ningún lugar; el agente la solicita para desbloquear, y puedes cambiarla con wallet_rotate_password. Si ya existe una cartera para la red, se conserva. La cartera solo se crea cuando la instalación se ejecuta en una terminal interactiva (nunca en un pipe o registro de CI). Pasa --no-wallet para omitirlo y crear o importar una desde el agente en su lugar.

Reinicia tu terminal, envía un poco de STX a la dirección impresa y pide al agente que desbloquee la cartera y realice una llamada de inferencia de pago.

Claude Desktop (App)

npx @aibtc/mcp-server@latest --install --desktop

Esto detecta tu sistema operativo y escribe en el archivo de configuración correcto de Claude Desktop:

SO	Ruta de Configuración
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json
Windows	%APPDATA%/Claude/claude_desktop_config.json

Reinicia Claude Desktop después de instalar.

Otros Clientes MCP

Este es un servidor MCP estándar de stdio, por lo que funciona con cualquier cliente compatible con MCP. Claude Code es el objetivo --install predeterminado; selecciona otro cliente con una bandera:

npx @aibtc/mcp-server@latest --install --cursor     # Cursor
npx @aibtc/mcp-server@latest --install --windsurf   # Windsurf
npx @aibtc/mcp-server@latest --install --gemini     # Gemini CLI
npx @aibtc/mcp-server@latest --install --codex      # OpenAI Codex CLI
npx @aibtc/mcp-server@latest --install --vscode     # VS Code (writes ./.vscode/mcp.json)

Bandera	Cliente	Configuración escrita
(ninguna)	Claude Code	~/.claude.json
--desktop	Claude Desktop	claude_desktop_config.json (ver tabla de rutas arriba)
--cursor	Cursor	~/.cursor/mcp.json
--windsurf	Windsurf	~/.codeium/windsurf/mcp_config.json
--gemini	Gemini CLI	~/.gemini/settings.json
--codex	OpenAI Codex CLI	~/.codex/config.toml
--vscode	VS Code (agente Copilot)	./.vscode/mcp.json (a nivel de proyecto)

Cada instalador se fusiona con la configuración existente: no sobrescribirá otros servidores ni ajustes. Reinicia el cliente después.

OpenRouter (cualquier modelo)

Los clientes anteriores son hosts MCP: se conectan a este servidor por ti. Para manejar las herramientas con un modelo de OpenRouter en su lugar, el servidor incluye un puente integrado: se inicia a sí mismo en modo servidor, expone las herramientas al modelo como herramientas de función y ejecuta el bucle de llamada de herramientas. Este es el patrón del lado del cliente del libro de recetas MCP de OpenRouter, empaquetado en el binario.

export OPENROUTER_API_KEY=sk-or-...
npx @aibtc/mcp-server@latest bridge "what's the STX balance of SP3...?"

Banderas de seguridad (este servidor mueve fondos reales, por lo que el puente no agrega nada extra por defecto y te permite restringirlo):

Bandera	Efecto
--read-only	Expone solo herramientas de solo lectura (sin transferencias/intercambios/despliegues/etc.)
--allow a,b	Forzar permitir nombres de herramientas específicos (agregados al conjunto)
--block a,b	Forzar eliminar nombres de herramientas específicos (prevalece sobre --allow)
--max-spend-ustx <n> / --max-spend-sats <n>	Limita el gasto mediante el riel de límite de gasto del servidor (aplicado antes de firmar)
--list-tools	Imprime el conjunto de herramientas expuesto y sale (no se necesita clave API)
--model <id>	Modelo de OpenRouter (predeterminado anthropic/claude-3.5-haiku)
--network <net>	mainnet o testnet (predeterminado mainnet)
--max-turns <n>	Límite del bucle de llamada de herramientas (predeterminado 10)

# Preview what a read-only session would expose, no key needed:
npx @aibtc/mcp-server@latest bridge --read-only --list-tools

# Read-only chat, plus one explicitly allowed write tool:
npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."

Antes de que se ejecute cualquier bucle de agente (y en --list-tools), el puente imprime un recibo de seguridad compacto en stderr: red, modo de solo lectura, recuentos de herramientas expuestas/escritura/bloqueadas, el límite de gasto de la sesión y el número de endpoints x402 conocidos, para que los límites de ejecución configurados sean visibles de antemano. Solo informa límites; nunca reclama ningún valor movido.

La lista de permitidos se vuelve a aplicar en el momento de la ejecución, por lo que un modelo nunca puede llamar a una herramienta fuera del conjunto expuesto. Cualquier marco de agente compatible con MCP (@openrouter/agent, OpenAI Agents SDK, Claude Agent SDK) también puede apuntar directamente a este servidor: el puente es para manejarlo a través de la API cruda de OpenRouter sin adoptar un marco.

Modo Testnet

Agrega --testnet a cualquier comando de instalación:

npx @aibtc/mcp-server@latest --install --testnet            # Claude Code, testnet
npx @aibtc/mcp-server@latest --install --cursor --testnet   # Cursor, testnet

¿Por qué npx? Usar npx @aibtc/mcp-server@latest garantiza que siempre obtengas la versión más reciente automáticamente. Las instalaciones globales (npm install -g) no se actualizan automáticamente.

Perfiles de Herramientas

Cada definición de herramienta se carga en el contexto del modelo, por lo que --install escribe AIBTC_TOOLS=core: un núcleo reducido de 24 herramientas: cartera (incluyendo wallet_rotate_password; wallet_export está en el grupo wallet para que la frase mnemotécnica no esté a una llamada de distancia), saldos, transferencias STX/BTC/sBTC, x402 (list_x402_endpoints, probe_x402_endpoint, execute_x402_endpoint) y ganancias (earning_opportunities, bounty_list/get/submit, identity_register).

Agrega grupos con AIBTC_TOOLS=core,defi,ordinals en el env del servidor (el núcleo siempre está incluido), o carga todo con AIBTC_TOOLS=all / --profile full. Si AIBTC_TOOLS no está configurado en absoluto, se carga cada herramienta, por lo que las configuraciones escritas por versiones anteriores conservan todas sus herramientas:

npx @aibtc/mcp-server@latest --install --profile full   # writes AIBTC_TOOLS=all

Grupo	Herramientas
wallet	Extras de gestión de cartera, almacén de credenciales cifrado
stacks	Transacciones de Stacks, contratos, tokens, NFTs, consultas de cadena, herramientas de nonce
sbtc	Depósito/retiro sBTC, Styx BTC→sBTC
bitcoin	UTXOs de Bitcoin L1, vigilancia de mempool
lightning	Cartera Lightning (Spark) y pagos L402
stacking	Stacking PoX, stacking dual, StackSpot
defi	ALEX, Zest, Bitflow, Jingswap, cazador/panel de rendimiento, análisis Tenero
pillar	Cartera inteligente Pillar
ordinals	Inscripciones, runas, PSBT, mercado/P2P de ordinals, multisig taproot
bns	Nombres BNS
identity	Identidad y reputación ERC-8004, firma de mensajes
social	Nostr, bandeja de entrada AIBTC
earn	Tablón de recompensas (crear, aceptar, pagar, mis vistas)
legion	AIBTC News Legion
markets	Mercado de predicción de Stacks, At Stake
dev	Andamiaje, OpenRouter, ajustes, mercado de inferencia, arXiv

Las instrucciones del servidor enumeran los grupos que están desactivados, para que el agente pueda indicarte cuál habilitar. El bridge de OpenRouter comienza con el conjunto completo y lo reduce con sus propias banderas --read-only/--allow/--block.

Configuración Manual

Si prefieres configurar manualmente, agrega lo siguiente al archivo de configuración de tu cliente. La bandera -y evita que npx solicite confirmación.

Claude Code / Claude Desktop / Cursor / Windsurf / Gemini CLI — JSON mcpServers:

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": {
        "NETWORK": "mainnet"
      }
    }
  }
}

VS Code (.vscode/mcp.json) — usa una clave servers y una entrada tipada:

{
  "servers": {
    "aibtc": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": { "NETWORK": "mainnet" }
    }
  }
}

OpenAI Codex CLI (~/.codex/config.toml) — TOML, no JSON:

[mcp_servers.aibtc]
command = "npx"
args = ["-y", "@aibtc/mcp-server@latest"]

[mcp_servers.aibtc.env]
NETWORK = "mainnet"

Zed (settings.json) — usa una clave context_servers:

{
  "context_servers": {
    "aibtc": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": { "NETWORK": "mainnet" }
    }
  }
}

Cline / Roo Code (extensión de VS Code) — agrega el mismo bloque JSON mcpServers de arriba a través del panel de configuración MCP de la extensión (la ruta exacta de cline_mcp_settings.json varía según el SO y la compilación de VS Code).

Cualquier otro cliente MCP también funciona: apúntalo a npx -y @aibtc/mcp-server@latest a través de stdio con NETWORK en el entorno.

Dándole una Cartera a Claude

--install crea una cartera para ti (ver Inicio Rápido). Si instalaste con --no-wallet, configuraste el cliente manualmente o quieres otra cartera, el agente puede crear o importar una:

Conversación de Ejemplo

You: What's your wallet address?

Claude: I don't have a wallet yet. Would you like to assign me one?
        I can either create a fresh wallet or you can import an existing one.

You: Create a new wallet called "agent-wallet"

Claude: What password should I use to protect the wallet?

You: use "secure123password"

Claude: I now have a wallet! My address is ST1ABC...XYZ

        IMPORTANT: Please save this recovery phrase securely:
        "word1 word2 word3 ... word24"

        This phrase will NOT be shown again. It's the only way to recover
        the wallet if the password is forgotten.

You: Send 10 STX to ST2DEF...

Claude: Done! I've sent 10 STX to ST2DEF...
        Transaction: 0x123...

Estados de la Cartera

Estado	Lo que Dice Claude	Qué Hacer
Sin cartera	"No tengo una cartera todavía"	Usa wallet_create o wallet_import
Bloqueada	"Mi cartera está bloqueada"	Usa wallet_unlock con la contraseña
Lista	"Mi dirección es ST..."	Claude puede realizar transacciones

Gestión de Sesión

• Por defecto, la cartera se bloquea automáticamente después de 15 minutos
• Puedes cambiar esto con wallet_set_timeout (establécelo en 0 para deshabilitar)
• Usa wallet_lock para bloquear la cartera manualmente
• Usa wallet_unlock cuando necesites que Claude vuelva a transaccionar

Almacenamiento de la Cartera

Las carteras de Claude se almacenan localmente en tu máquina:

~/.aibtc/
├── wallets.json       # Wallet index (names, addresses - no secrets)
├── config.json        # Active wallet, settings
└── wallets/
    └── [wallet-id]/
        └── keystore.json  # Encrypted mnemonic (AES-256-GCM + Scrypt)

Seguridad:

• Cifrado AES-256-GCM con derivación de clave Scrypt
• Se requiere contraseña para desbloquear
• Las frases mnemotécnicas nunca se almacenan en texto plano
• Los permisos de archivo se establecen solo para el propietario (0600)

Soporte de Bitcoin L1

Cada cartera deriva automáticamente tanto una dirección de Stacks como una dirección de Bitcoin de la misma frase mnemotécnica usando los estándares BIP39/BIP32.

Rutas de Derivación (BIP84):

• Mainnet: m/84'/0'/0'/0/0 (tipo de moneda Bitcoin 0)
• Testnet: m/84'/1'/0'/0/0 (tipo de moneda Bitcoin testnet 1)

Formato de Dirección:

• Mainnet: bc1q... (SegWit nativo P2WPKH)
• Testnet: tb1q... (SegWit nativo P2WPKH)

Capacidades:

• Soporte completo de transacciones Bitcoin L1 (enviar BTC)
• Consultas de saldo y UTXO a través de la API de mempool.space
• Estimación de tarifas (rápida/media/lenta)
• Transacciones P2WPKH (SegWit nativo) para tarifas óptimas

Ejemplo:

You: Create a wallet called "my-wallet"
Claude: I've created a wallet with:
        Stacks address: ST1ABC...
        Bitcoin address: bc1q...

You: Send 50000 sats to bc1q...
Claude: Done! Transaction broadcast: abc123...

Ambas direcciones se derivan de la misma frase de recuperación, lo que facilita la gestión de activos tanto de la Capa 1 (Bitcoin) como de la Capa 2 (Stacks).

Herramientas Disponibles (más de 350 en total)

Gestión de Cartera

Herramienta	Descripción
wallet_create	Crear una nueva cartera para Claude
wallet_import	Importar una cartera existente para Claude
wallet_unlock	Desbloquear la cartera de Claude
wallet_lock	Bloquear la cartera de Claude
wallet_list	Listar las carteras disponibles de Claude
wallet_switch	Cambiar a una cartera diferente de Claude
wallet_delete	Eliminar una cartera
wallet_export	Exportar la frase mnemotécnica de la cartera
wallet_status	Verificar si la cartera de Claude está lista (incluye direcciones de Stacks y Bitcoin)
wallet_set_timeout	Establecer cuánto tiempo permanece desbloqueada la cartera

Bitcoin L1

Herramienta	Descripción
get_btc_balance	Obtener saldo de BTC (total, confirmado, no confirmado)
get_btc_fees	Obtener estimaciones de tarifas (rápida, media, lenta)
get_btc_utxos	Listar UTXOs para una dirección
transfer_btc	Enviar BTC a un destinatario
get_cardinal_utxos	UTXOs seguros para gastar (sin inscripciones)
get_ordinal_utxos	UTXOs que contienen inscripciones

Vigilancia de Mempool (Bitcoin)

Herramienta	Descripción
get_btc_mempool_info	Obtener estadísticas actuales del mempool de Bitcoin (recuento de transacciones, vsize, tarifas, histograma de tarifas)
get_btc_transaction_status	Obtener estado de confirmación y detalles de una transacción de Bitcoin por txid
get_btc_address_txs	Obtener historial reciente de transacciones para una dirección de Bitcoin (últimas 25 transacciones)

Inscripciones de Bitcoin

Herramienta	Descripción
get_taproot_address	Obtener la dirección Taproot (P2TR) de la cartera
estimate_inscription_fee	Calcular el costo de la inscripción
inscribe	Crear transacción de compromiso de inscripción
inscribe_reveal	Completar transacción de revelación de inscripción
get_inscription	Obtener contenido de inscripción de la transacción de revelación
get_inscriptions_by_address	Listar inscripciones propiedad de una dirección

Comercio de PSBT y Ordinals

Herramienta	Descripción
psbt_create_ordinal_buy	Construir un PSBT del lado del comprador para la compra de ordinals
psbt_sign	Firmar entradas de PSBT seleccionadas con las claves de la billetera activa
psbt_decode	Decodificar entradas/salidas/estado de firmas del PSBT
psbt_broadcast	Finalizar y transmitir un PSBT completamente firmado

Firma de Mensajes

Herramienta	Descripción
sip018_sign	Firmar datos estructurados de Clarity (SIP-018)
sip018_verify	Verificar firma SIP-018
sip018_hash	Calcular hash SIP-018 sin firmar
stacks_sign_message	Firmar texto plano (compatible con SIWS)
stacks_verify_message	Verificar firma de mensaje de Stacks
btc_sign_message	Firmar con clave de Bitcoin (BIP-137)
btc_verify_message	Verificar firma BIP-137

Billetera y Saldo

Herramienta	Descripción
get_wallet_info	Obtener direcciones de billetera de Claude (Stacks + Bitcoin) y estado
get_stx_balance	Obtener saldo de STX para cualquier dirección
get_stx_fees	Obtener estimaciones de tarifas de STX (baja, media, alta)

Transferencias de STX

Herramienta	Descripción
transfer_stx	Enviar STX a un destinatario
broadcast_transaction	Transmitir una transacción pre-firmada

Operaciones con sBTC

Herramienta	Descripción
sbtc_get_balance	Obtener saldo de sBTC
sbtc_transfer	Enviar sBTC
sbtc_initiate_withdrawal	Iniciar salida de sBTC hacia BTC L1
sbtc_withdraw	Alias para iniciar retiro
sbtc_withdrawal_status	Verificar estado de solicitud de retiro
sbtc_get_deposit_info	Obtener instrucciones de depósito de BTC
sbtc_deposit	Construir, firmar y transmitir depósito BTC→sBTC
sbtc_deposit_status	Verificar estado del depósito mediante API de Emily
sbtc_get_peg_info	Obtener ratio de anclaje y TVL

Operaciones con Tokens (SIP-010)

Herramienta	Descripción
get_token_balance	Obtener saldo de cualquier token SIP-010
transfer_token	Enviar cualquier token SIP-010
get_token_info	Obtener metadatos del token
list_user_tokens	Listar tokens propiedad de una dirección
get_token_holders	Obtener principales tenedores de un token

Operaciones con NFTs (SIP-009)

Herramienta	Descripción
get_nft_holdings	Listar NFTs propiedad de una dirección
get_nft_metadata	Obtener metadatos del NFT
transfer_nft	Enviar un NFT
get_nft_owner	Obtener propietario del NFT
get_collection_info	Obtener detalles de la colección NFT
get_nft_history	Obtener historial de transferencias del NFT

Stacking / PoX

Herramienta	Descripción
get_pox_info	Ciclo PoX-5 actual, altura de quema, fase de preparación
get_stacking_status	Monto bloqueado, gestor de firmante, altura de desbloqueo
list_stacking_signers	Gestores de firmante en el conjunto de firmantes del próximo ciclo
stack_stx	Bloquear STX con un gestor de firmante
extend_stacking	Extender, aumentar, cambiar firmante o pago (actualización de participación)
unstake_stx	Detener antes de tiempo; desbloquea el próximo ciclo
get_stacking_rewards	Recompensas de sBTC no reclamadas para un ciclo
claim_stacking_rewards	Reclamar recompensas de un ciclo mediante el gestor de firmante

Dominios BNS (V1 + V2)

Herramienta	Descripción
lookup_bns_name	Resolver dominio .btc a dirección
reverse_bns_lookup	Obtener dominio .btc para una dirección
get_bns_info	Obtener detalles del dominio
check_bns_availability	Verificar si el dominio está disponible
get_bns_price	Obtener precio de registro
list_user_domains	Listar dominios propiedad
preorder_bns_name	Preordenar un dominio .btc (paso 1 de 2)
register_bns_name	Registrar un dominio .btc (paso 2 de 2)

Contratos Inteligentes

Herramienta	Descripción
call_contract	Llamar a una función de contrato inteligente
deploy_contract	Desplegar un contrato inteligente de Clarity
get_transaction_status	Verificar estado de transacción
call_read_only_function	Llamar a función de solo lectura

DeFi - ALEX DEX (Mainnet)

Utiliza el alex-sdk oficial para operaciones de intercambio. Admite símbolos de tokens simples como "STX", "ALEX".

Herramienta	Descripción
alex_list_pools	Descubrir todos los pools de trading disponibles
alex_get_swap_quote	Obtener salida esperada para un intercambio de tokens
alex_swap	Ejecutar un intercambio de tokens (el SDK maneja el enrutamiento)
alex_get_pool_info	Obtener reservas del pool de liquidez

DeFi - Protocolo Zest (Mainnet)

Admite 10 activos: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC

Herramienta	Descripción
zest_list_assets	Listar todos los activos de préstamo admitidos
zest_get_position	Obtener posición de suministro/préstamo del usuario
zest_supply	Suministrar activos para ganar intereses
zest_withdraw	Retirar activos suministrados
zest_borrow	Pedir prestado contra garantía
zest_repay	Reembolsar activos prestados

DeFi - Bitflow DEX (Mainnet)

Agregador de DEX que enruta operaciones a través de múltiples fuentes de liquidez.

Unidades: Las herramientas de Bitflow usan por defecto unidades humanas (amountUnit: "human"). Pase "2" para intercambiar 2 STX, no "2000000". Establezca amountUnit: "base" solo cuando trabaje con enteros on-chain sin procesar. Consulte la guía Unidades y Decimales para detalles y errores comunes.

Herramienta	Descripción
bitflow_get_ticker	Obtener datos de mercado (no se necesita clave API)
bitflow_get_quote	Obtener cotización de intercambio
bitflow_swap	Ejecutar intercambio de tokens

Pillar Smart Wallet

Billetera inteligente de sBTC con integración del Protocolo Zest y autenticación por passkey.

Herramienta	Descripción
pillar_connect	Conectar a la billetera Pillar
pillar_send	Enviar sBTC a nombres BNS o direcciones
pillar_boost	Crear posición apalancada de sBTC
pillar_position	Ver billetera y posición en Zest

Para agentes autónomos, use herramientas pillar_direct_* (no se necesita navegador).

Consultas de Blockchain

Herramienta	Descripción
get_account_info	Obtener nonce de cuenta, saldo
get_account_transactions	Listar historial de transacciones
get_block_info	Obtener detalles del bloque
get_mempool_info	Obtener transacciones pendientes
get_contract_info	Obtener ABI y fuente del contrato
get_contract_events	Obtener historial de eventos del contrato
get_network_status	Obtener estado de salud de la red

Yield Hunter (Autónomo)

Herramienta	Descripción
yield_hunter_start	Iniciar depósitos autónomos sBTC→Zest
yield_hunter_stop	Detener la caza de rendimiento
yield_hunter_status	Verificar estado del cazador de rendimiento
yield_hunter_configure	Ajustar umbral, reserva, intervalo

Endpoints de API x402

Herramienta	Descripción
list_x402_endpoints	Descubrir endpoints x402
execute_x402_endpoint	Ejecutar endpoint x402 con pago automático
scaffold_x402_endpoint	Generar proyecto de Cloudflare Worker para x402
scaffold_x402_ai_endpoint	Generar API de IA x402 con OpenRouter

Ejemplos de Uso

Gestión de billetera:

"¿Cuál es tu dirección de billetera?" "Crea una billetera para ti" "Desbloquea tu billetera" "Mantén tu billetera desbloqueada por 1 hora"

Verificar saldos:

"¿Cuánto STX tienes?" "¿Cuál es tu saldo de sBTC?"

Transferir tokens:

"Envía 2 STX a ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" "Transfiere 0.001 sBTC a muneeb.btc"

NFTs:

"¿Qué NFTs posees?" "Envía este NFT a alice.btc"

Dominios BNS:

"¿Qué dirección es satoshi.btc?" "¿Está disponible myname.btc?"

Comercio DeFi (mainnet):

"¿Qué pools están disponibles en ALEX?" "Intercambia 0.1 STX por ALEX" "Obtén una cotización de 100 STX a ALEX" "¿Qué activos puedo prestar en Zest?" "Suministra 100 stSTX a Zest" "Pide prestado 50 aeUSDC de Zest" "Verifica mi posición en Zest"

Endpoints x402:

"Obtén pools de liquidez en tendencia" "Cuéntame un chiste de papás"

Tokens Admitidos

Los tokens conocidos pueden referenciarse por símbolo:

• sBTC - Bitcoin nativo en Stacks
• USDCx - USD Coin en Stacks
• ALEX - Token de gobernanza de ALEX
• wSTX - STX envuelto

Tokens de ALEX DEX: STX, ALEX, y cualquier token de alex_list_pools

Activos del Protocolo Zest: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC

O use cualquier token SIP-010 por ID de contrato: SP2X...::token-name

Configuración

Variable de Entorno	Descripción	Predeterminado
NETWORK	mainnet o testnet	mainnet
AIBTC_TOOLS	core, core,<group,...>, o all (ver Perfiles de Herramientas). --install escribe core	todas las herramientas cuando no se establece
CLIENT_MNEMONIC	(Opcional) Mnemónico preconfigurado	-
HIRO_API_KEY	(Opcional) Clave API de Hiro para límites de tasa más altos	-
SPEND_LIMIT_ENABLED	Establezca false para deshabilitar el límite de gasto de la billetera	true
SPEND_LIMIT_DAILY_USTX / SPEND_LIMIT_SESSION_USTX	Tope de gasto de STX por día / por desbloqueo (micro-STX)	50000000 (50 STX)
SPEND_LIMIT_DAILY_SATS / SPEND_LIMIT_SESSION_SATS	Tope de gasto de BTC por día / por desbloqueo (sats)	50000
AIBTC_ALLOW_BLIND_SIGN	Permitir que schnorr_sign_digest firme resúmenes sin procesar (un sighash firmado gasta fuera del límite de gasto)	desactivado

Nota sobre NETWORK: El comando --install escribe NETWORK=mainnet por defecto (pase --testnet para usar testnet). Si omite NETWORK de su configuración por completo, el respaldo en tiempo de ejecución también es mainnet.

Nota sobre límites de gasto: Un riel de seguridad activado por defecto mide cada gasto de STX, sBTC y BTC (transferencias, llamadas a contratos, transacciones patrocinadas, pagos automáticos x402/L402, transmisiones de Bitcoin, psbt_sign) contra un tope acumulativo por sesión y por día, de modo que una sola instrucción incorrecta o un endpoint malicioso no pueda vaciar la billetera. Un gasto que supere el tope se bloquea antes de firmarse o transmitirse, y se le indica al agente que le pregunte a usted. Aumente los topes mediante las variables de entorno anteriores, o deshabilítelos con SPEND_LIMIT_ENABLED=false. El límite se ejecuta dentro del servidor: no contiene un agente con acceso de shell a su máquina, así que mantenga las herramientas de gasto fuera de la lista de aprobación automática de su cliente. Ver SECURITY.md.

Nota: CLIENT_MNEMONIC es opcional. El enfoque recomendado es permitir que Claude cree su propia billetera. HIRO_API_KEY es opcional pero recomendado para producción — sin él, puede alcanzar los límites de tasa públicos de Hiro (respuestas 429). Obtenga una clave en platform.hiro.so.

Arquitectura

You ←→ Claude ←→ aibtc-mcp-server
                        ↓
              Claude's Wallet (~/.aibtc/)
                        ↓
              ┌─────────┴─────────┐
              ↓                   ↓
        Hiro Stacks API    x402 Endpoints
              ↓                   ↓
        Stacks Blockchain  Paid API Services

Notas de Seguridad

• La billetera de Claude se almacena cifrada en SU máquina
• La contraseña nunca se almacena - solo el almacén de claves cifrado
• Los mnemónicos se muestran solo una vez al crear
• Bloqueo automático después de 15 minutos (configurable)
• Las transacciones se firman localmente antes de transmitirse
• Límite de gasto (activado por defecto): los gastos salientes están limitados por sesión y por día para que una sola instrucción incorrecta no pueda vaciar la billetera — ver Configuración
• Hook de pre-commit de escaneo de secretos: los contribuyentes obtienen un hook (instalado automáticamente mediante npm install) que bloquea la confirmación de una frase semilla o clave privada
• Para mainnet: Fondee con montos pequeños primero

Ver SECURITY.md para el modelo completo de protección de claves de billetera y pasos de recuperación ante fugas de claves.

Avanzado: Mnemónico Preconfigurado

Para configuraciones automatizadas donde Claude necesita acceso inmediato a la billetera, agregue la variable de entorno CLIENT_MNEMONIC a su configuración del servidor MCP (en ~/.claude.json para Claude Code, o claude_desktop_config.json para Claude Desktop):

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["@aibtc/mcp-server@latest"],
      "env": {
        "CLIENT_MNEMONIC": "your twenty four word mnemonic phrase",
        "NETWORK": "testnet"
      }
    }
  }
}

Esto omite el flujo de creación de billetera: Claude tiene acceso inmediato para realizar transacciones.

Habilidad del Agente

Este paquete incluye una habilidad compatible con Agent Skills que enseña a cualquier LLM cómo usar las capacidades de la billetera de Bitcoin de manera efectiva.

¿Qué es?

La habilidad aibtc-bitcoin-wallet proporciona:

• Flujos de trabajo estructurados para operaciones de Bitcoin L1 (saldo, envío, tarifas)
• Guías de referencia para billeteras inteligentes Pillar y DeFi de Stacks L2
• Instrucciones agnósticas al LLM que funcionan con Claude Code, Cursor, Codex y más de 20 otras herramientas

Uso de la Habilidad

La habilidad se incluye automáticamente cuando instalas el servidor MCP. Encuéntrala en:

• Local: node_modules/@aibtc/mcp-server/skill/SKILL.md
• ClawHub: clawhub.ai/skills - busca aibtc-bitcoin-wallet

Estructura de la habilidad

skill/
├── SKILL.md                        # Bitcoin L1 core workflows
└── references/
    ├── at-stake.md                 # El Salvador prediction market & side legions
    ├── genesis-lifecycle.md        # Agent registration & check-in
    ├── inscription-workflow.md     # Bitcoin inscription guide
    ├── pillar-wallet.md            # Pillar smart wallet guide
    ├── stacks-defi.md              # Stacks L2 / DeFi operations
    ├── troubleshooting.md          # Common issues and solutions
    └── x402-inbox.md               # x402 inbox messaging

Desarrollo

git clone https://github.com/aibtcdev/aibtc-mcp-server.git
cd aibtc-mcp-server
npm install
npm run build
npm run dev       # Run with tsx (development)

Lanzamientos

Este repositorio utiliza Release Please para lanzamientos automatizados:

1. Fusiona PRs con commits convencionales (feat:, fix:, etc.)
2. Release Please crea un PR de lanzamiento con el registro de cambios
3. Fusiona el PR de lanzamiento para publicar

Secretos del repositorio (Mantenedores)

Secreto	Descripción
NPM_TOKEN	Token de publicación npm para el ámbito @aibtc
CLAWHUB_API_TOKEN	Token de API de ClawHub para la publicación de habilidades

Para obtener un token de API de ClawHub, visita clawhub.ai y crea una cuenta.

Licencia

MIT