aibtc-mcp-server

Servidor MCP nativo do Bitcoin para agentes de IA: carteiras BTC/STX, rendimento DeFi, peg sBTC, NFTs e pagamentos x402.

GitHub

Experimente este MCPPatrocinado

Documentação

@aibtc/mcp-server

Servidor MCP nativo de Bitcoin para agentes de IA: carteiras BTC/STX, rendimento DeFi, peg sBTC, NFTs e pagamentos x402.

Recursos

Bitcoin L1 - Verifique saldos, envie BTC, gerencie UTXOs via mempool.space
Carteira Própria do Agente - Agentes têm sua própria carteira para realizar transações na blockchain
Armazenamento Seguro - Carteiras criptografadas com AES-256-GCM e armazenadas localmente
Mais de 350 Ferramentas - Bitcoin L1 + operações abrangentes de Stacks L2
Suporte a sBTC - Operações nativas de Bitcoin em Stacks
Operações com Tokens - Transferências e consultas de tokens fungíveis SIP-010
Suporte a NFT - Posse, transferências e metadados de NFTs SIP-009
Negociação DeFi - Swaps ALEX DEX e empréstimos/empréstimos Zest Protocol
Stacking/PoX-5 - Faça stake de STX com um gerenciador de signatários, estenda, retire o stake, reivindique recompensas sBTC
Domínios BNS - Consultas e gerenciamento de domínios .btc (V1 + V2)
Pagamentos x402 - Tratamento automático de pagamentos para APIs pagas

Início Rápido

Claude Code (Terminal)

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

Isso configura o Claude Code e cria a carteira do agente: imprime os endereços Stacks e Bitcoin, uma senha gerada e a mnemônica de 24 palavras uma vez. Anote ambos. A mnemônica é armazenada apenas criptografada (AES-256-GCM) em ~/.aibtc/ nesta máquina, e a senha não é salva em nenhum lugar; o agente a solicita para desbloquear, e você pode alterá-la com wallet_rotate_password. Se uma carteira para a rede já existir, ela é mantida. A carteira só é criada quando a instalação é executada em um terminal interativo (nunca em um pipe ou log de CI). Passe --no-wallet para pular e criar ou importar uma a partir do agente.

Reinicie seu terminal, envie um pouco de STX para o endereço impresso e peça ao agente para desbloquear a carteira e fazer uma chamada de inferência paga.

Claude Desktop (App)

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

Isso detecta seu sistema operacional e grava no arquivo de configuração correto do Claude Desktop:

SO	Caminho de Configuração
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`
Windows	`%APPDATA%/Claude/claude_desktop_config.json`

Reinicie o Claude Desktop após a instalação.

Outros Clientes MCP

Este é um servidor MCP stdio padrão, portanto funciona com qualquer cliente compatível com MCP. O Claude Code é o alvo padrão do --install; selecione outro cliente com uma flag:

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)

Flag	Cliente	Configuração gravada
(nenhuma)	Claude Code	`~/.claude.json`
`--desktop`	Claude Desktop	`claude_desktop_config.json` (veja a tabela de caminhos acima)
`--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` (escopo do projeto)

Cada instalador faz merge na configuração existente — não sobrescreve outros servidores ou configurações. Reinicie o cliente após a instalação.

OpenRouter (qualquer modelo)

Os clientes acima são hosts MCP — eles se conectam a este servidor para você. Para acionar as ferramentas com um modelo OpenRouter em vez disso, o servidor inclui uma ponte integrada: ele se inicia em modo servidor, expõe as ferramentas ao modelo como ferramentas de função e executa o loop de chamada de ferramentas. Este é o padrão do lado do cliente do cookbook MCP do OpenRouter, empacotado no binário.

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

Flags de segurança (este servidor movimenta fundos reais, então a ponte não adiciona nada extra por padrão e permite que você a restrinja):

Flag	Efeito
`--read-only`	Expõe apenas ferramentas somente leitura (sem transferência/swap/deploy/etc.)
`--allow a,b`	Força a permissão de nomes específicos de ferramentas (adicionados ao conjunto)
`--block a,b`	Força a remoção de nomes específicos de ferramentas (tem precedência sobre `--allow`)
`--max-spend-ustx <n>` / `--max-spend-sats <n>`	Limita gastos via o trilho de limite de gastos do servidor (aplicado antes da assinatura)
`--list-tools`	Imprime o conjunto de ferramentas exposto e sai (nenhuma chave de API necessária)
`--model <id>`	Modelo OpenRouter (padrão `anthropic/claude-3.5-haiku`)
`--network <net>`	`mainnet` ou `testnet` (padrão `mainnet`)
`--max-turns <n>`	Limite do loop de chamada de ferramentas (padrão 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 qualquer loop de agente ser executado (e em --list-tools), a ponte imprime um recibo de segurança compacto em stderr — rede, modo somente leitura, contagens de ferramentas expostas/gravação/bloqueadas, o limite de gastos da sessão e o número de endpoints x402 conhecidos — para que os limites de execução configurados fiquem visíveis antecipadamente. Ele relata apenas limites; nunca afirma qualquer valor movimentado.

A lista de permissões é reaplicada no momento da execução, então um modelo nunca pode chamar uma ferramenta fora do conjunto exposto. Qualquer framework de agente compatível com MCP (@openrouter/agent, OpenAI Agents SDK, Claude Agent SDK) também pode apontar diretamente para este servidor — a ponte serve para acioná-lo através da API bruta do OpenRouter sem adotar um framework.

Modo Testnet

Adicione --testnet a qualquer comando de instalação:

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

Por que npx? Usar npx @aibtc/mcp-server@latest garante que você sempre obtenha a versão mais recente automaticamente. Instalações globais (npm install -g) não são atualizadas automaticamente.

Perfis de Ferramentas

Cada definição de ferramenta é carregada no contexto do modelo, então --install grava AIBTC_TOOLS=core: um núcleo enxuto de 24 ferramentas: carteira (incluindo wallet_rotate_password; wallet_export está no grupo wallet para que a mnemônica não fique a uma chamada de distância), saldos, transferências STX/BTC/sBTC, x402 (list_x402_endpoints, probe_x402_endpoint, execute_x402_endpoint) e ganhos (earning_opportunities, bounty_list/get/submit, identity_register).

Adicione grupos com AIBTC_TOOLS=core,defi,ordinals no env do servidor (o núcleo é sempre incluído), ou carregue tudo com AIBTC_TOOLS=all / --profile full. Se AIBTC_TOOLS não estiver definido, todas as ferramentas são carregadas, então configurações gravadas por versões anteriores mantêm todas as suas ferramentas:

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

Grupo	Ferramentas
`wallet`	Extras de gerenciamento de carteira, armazenamento de credenciais criptografadas
`stacks`	Transações Stacks, contratos, tokens, NFTs, consultas de cadeia, ferramentas de nonce
`sbtc`	Depósito/retirada sBTC, Styx BTC→sBTC
`bitcoin`	UTXOs Bitcoin L1, monitoramento de mempool
`lightning`	Carteira Lightning (Spark) e pagamentos L402
`stacking`	Stacking PoX, stacking duplo, StackSpot
`defi`	ALEX, Zest, Bitflow, Jingswap, yield hunter/dashboard, análises Tenero
`pillar`	Carteira inteligente Pillar
`ordinals`	Inscrições, runas, PSBT, marketplace de ordinais/P2P, multisig taproot
`bns`	Nomes BNS
`identity`	Identidade e reputação ERC-8004, assinatura de mensagens
`social`	Nostr, caixa de entrada AIBTC
`earn`	Quadro de recompensas (criar, aceitar, pagar, minhas visualizações)
`legion`	AIBTC News Legion
`markets`	Mercado de previsão Stacks, At Stake
`dev`	Scaffolding, OpenRouter, configurações, marketplace de inferência, arXiv

As instruções do servidor listam os grupos que estão desativados, para que o agente possa informar qual habilitar. O bridge do OpenRouter começa com o conjunto completo e o restringe com suas próprias flags --read-only/--allow/--block.

Configuração Manual

Se você preferir configurar manualmente, adicione o seguinte ao arquivo de configuração do seu cliente. A flag -y impede que o npx solicite confirmação.

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 uma chave servers e uma entrada tipada:

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

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

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

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

Zed (settings.json) — usa uma chave context_servers:

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

Cline / Roo Code (extensão VS Code) — adicione o mesmo bloco JSON mcpServers acima via o painel de configurações MCP da extensão (o caminho exato do cline_mcp_settings.json varia por SO e build do VS Code).

Qualquer outro cliente MCP também funciona — aponte-o para npx -y @aibtc/mcp-server@latest via stdio com NETWORK no ambiente.

Dando uma Carteira ao Claude

--install cria uma carteira para você (veja Início Rápido). Se você instalou com --no-wallet, configurou o cliente manualmente ou quer outra carteira, o agente pode criar ou importar uma:

Exemplo de Conversa

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 da Carteira

Estado	O Que o Claude Diz	O Que Fazer
Sem carteira	"Ainda não tenho uma carteira"	Use `wallet_create` ou `wallet_import`
Bloqueada	"Minha carteira está bloqueada"	Use `wallet_unlock` com a senha
Pronta	"Meu endereço é ST..."	Claude pode realizar transações

Gerenciamento de Sessão

Por padrão, a carteira bloqueia automaticamente após 15 minutos
Você pode alterar isso com wallet_set_timeout (defina 0 para desativar)
Use wallet_lock para bloquear a carteira manualmente
Use wallet_unlock quando precisar que o Claude transacione novamente

Armazenamento da Carteira

As carteiras do Claude são armazenadas localmente na sua 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)

Segurança:

Criptografia AES-256-GCM com derivação de chave Scrypt
Senha necessária para desbloquear
Mnemônicas nunca armazenadas em texto simples
Permissões de arquivo definidas apenas para o proprietário (0600)

Suporte a Bitcoin L1

Cada carteira deriva automaticamente tanto um endereço Stacks quanto um endereço Bitcoin da mesma mnemônica usando os padrões BIP39/BIP32.

Caminhos de Derivação (BIP84):

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

Formato de Endereço:

Mainnet: bc1q... (Native SegWit P2WPKH)
Testnet: tb1q... (Native SegWit P2WPKH)

Capacidades:

Suporte completo a transações Bitcoin L1 (enviar BTC)
Consultas de saldo e UTXO via API mempool.space
Estimativa de taxas (rápida/média/lenta)
Transações P2WPKH (Native SegWit) para taxas ideais

Exemplo:

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...

Ambos os endereços são derivados da mesma frase de recuperação, facilitando o gerenciamento de ativos tanto na Camada 1 (Bitcoin) quanto na Camada 2 (Stacks).

Ferramentas Disponíveis (mais de 350 no total)

Gerenciamento de Carteira

Ferramenta	Descrição
`wallet_create`	Criar uma nova carteira para o Claude
`wallet_import`	Importar uma carteira existente para o Claude
`wallet_unlock`	Desbloquear a carteira do Claude
`wallet_lock`	Bloquear a carteira do Claude
`wallet_list`	Listar as carteiras disponíveis do Claude
`wallet_switch`	Alternar o Claude para uma carteira diferente
`wallet_delete`	Excluir uma carteira
`wallet_export`	Exportar a mnemônica da carteira
`wallet_status`	Verificar se a carteira do Claude está pronta (inclui endereços Stacks e Bitcoin)
`wallet_set_timeout`	Definir por quanto tempo a carteira permanece desbloqueada

Bitcoin L1

Ferramenta	Descrição
`get_btc_balance`	Obter saldo BTC (total, confirmado, não confirmado)
`get_btc_fees`	Obter estimativas de taxas (rápida, média, lenta)
`get_btc_utxos`	Listar UTXOs para um endereço
`transfer_btc`	Enviar BTC para um destinatário
`get_cardinal_utxos`	UTXOs seguros para gastar (sem inscrições)
`get_ordinal_utxos`	UTXOs contendo inscrições

Monitoramento de Mempool (Bitcoin)

Ferramenta	Descrição
`get_btc_mempool_info`	Obter estatísticas atuais do mempool Bitcoin (contagem de transações, vsize, taxas, histograma de taxas)
`get_btc_transaction_status`	Obter status de confirmação e detalhes de uma transação Bitcoin por txid
`get_btc_address_txs`	Obter histórico recente de transações para um endereço Bitcoin (últimas 25 transações)

Inscrições Bitcoin

Ferramenta	Descrição
`get_taproot_address`	Obter o endereço Taproot (P2TR) da carteira
`estimate_inscription_fee`	Calcular o custo da inscrição
`inscribe`	Criar transação de commit de inscrição
`inscribe_reveal`	Completar transação de reveal de inscrição
`get_inscription`	Buscar conteúdo da inscrição a partir da transação de reveal
`get_inscriptions_by_address`	Listar inscrições pertencentes a um endereço

Negociação de PSBT e Ordinals

Ferramenta	Descrição
`psbt_create_ordinal_buy`	Construir um PSBT do lado do comprador para compra de ordinais
`psbt_sign`	Assinar entradas de PSBT selecionadas com chaves da carteira ativa
`psbt_decode`	Decodificar entradas/saídas/status de assinatura do PSBT
`psbt_broadcast`	Finalizar e transmitir um PSBT totalmente assinado

Assinatura de Mensagens

Ferramenta	Descrição
`sip018_sign`	Assinar dados Clarity estruturados (SIP-018)
`sip018_verify`	Verificar assinatura SIP-018
`sip018_hash`	Calcular hash SIP-018 sem assinar
`stacks_sign_message`	Assinar texto simples (compatível com SIWS)
`stacks_verify_message`	Verificar assinatura de mensagem Stacks
`btc_sign_message`	Assinar com chave Bitcoin (BIP-137)
`btc_verify_message`	Verificar assinatura BIP-137

Carteira e Saldo

Ferramenta	Descrição
`get_wallet_info`	Obter endereços da carteira do Claude (Stacks + Bitcoin) e status
`get_stx_balance`	Obter saldo de STX para qualquer endereço
`get_stx_fees`	Obter estimativas de taxa de STX (baixa, média, alta)

Transferências de STX

Ferramenta	Descrição
`transfer_stx`	Enviar STX para um destinatário
`broadcast_transaction`	Transmitir uma transação pré-assinada

Operações sBTC

Ferramenta	Descrição
`sbtc_get_balance`	Obter saldo de sBTC
`sbtc_transfer`	Enviar sBTC
`sbtc_initiate_withdrawal`	Iniciar peg-out de sBTC para BTC L1
`sbtc_withdraw`	Alias para iniciar retirada
`sbtc_withdrawal_status`	Verificar status da solicitação de retirada
`sbtc_get_deposit_info`	Obter instruções de depósito de BTC
`sbtc_deposit`	Construir, assinar e transmitir depósito BTC→sBTC
`sbtc_deposit_status`	Verificar status do depósito via API Emily
`sbtc_get_peg_info`	Obter proporção de peg e TVL

Operações de Tokens (SIP-010)

Ferramenta	Descrição
`get_token_balance`	Obter saldo de qualquer token SIP-010
`transfer_token`	Enviar qualquer token SIP-010
`get_token_info`	Obter metadados do token
`list_user_tokens`	Listar tokens pertencentes a um endereço
`get_token_holders`	Obter principais detentores de um token

Operações de NFT (SIP-009)

Ferramenta	Descrição
`get_nft_holdings`	Listar NFTs pertencentes a um endereço
`get_nft_metadata`	Obter metadados do NFT
`transfer_nft`	Enviar um NFT
`get_nft_owner`	Obter proprietário do NFT
`get_collection_info`	Obter detalhes da coleção de NFT
`get_nft_history`	Obter histórico de transferências do NFT

Stacking / PoX

Ferramenta	Descrição
`get_pox_info`	Ciclo PoX-5 atual, altura de queima, fase de preparação
`get_stacking_status`	Valor bloqueado, gerenciador de signatário, altura de desbloqueio
`list_stacking_signers`	Gerenciadores de signatário no conjunto de signatários do próximo ciclo
`stack_stx`	Bloquear STX com um gerenciador de signatário
`extend_stacking`	Estender, aumentar, trocar signatário ou pagamento (atualização de stake)
`unstake_stx`	Parar antecipadamente; desbloqueia no próximo ciclo
`get_stacking_rewards`	Recompensas sBTC não reclamadas para um ciclo
`claim_stacking_rewards`	Reivindicar recompensas de um ciclo através do gerenciador de signatário

Domínios BNS (V1 + V2)

Ferramenta	Descrição
`lookup_bns_name`	Resolver domínio .btc para endereço
`reverse_bns_lookup`	Obter domínio .btc para um endereço
`get_bns_info`	Obter detalhes do domínio
`check_bns_availability`	Verificar se o domínio está disponível
`get_bns_price`	Obter preço de registro
`list_user_domains`	Listar domínios pertencentes
`preorder_bns_name`	Pré-encomendar um domínio .btc (etapa 1 de 2)
`register_bns_name`	Registrar um domínio .btc (etapa 2 de 2)

Contratos Inteligentes

Ferramenta	Descrição
`call_contract`	Chamar uma função de contrato inteligente
`deploy_contract`	Implantar um contrato inteligente Clarity
`get_transaction_status`	Verificar status da transação
`call_read_only_function`	Chamar função somente leitura

DeFi - ALEX DEX (Mainnet)

Usa o alex-sdk oficial para operações de swap. Suporta símbolos de tokens simples como "STX", "ALEX".

Ferramenta	Descrição
`alex_list_pools`	Descobrir todos os pools de negociação disponíveis
`alex_get_swap_quote`	Obter saída esperada para um swap de token
`alex_swap`	Executar um swap de token (SDK lida com roteamento)
`alex_get_pool_info`	Obter reservas do pool de liquidez

DeFi - Protocolo Zest (Mainnet)

Suporta 10 ativos: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC

Ferramenta	Descrição
`zest_list_assets`	Listar todos os ativos de empréstimo suportados
`zest_get_position`	Obter posição de fornecimento/empréstimo do usuário
`zest_supply`	Fornecer ativos para ganhar juros
`zest_withdraw`	Retirar ativos fornecidos
`zest_borrow`	Tomar emprestado contra garantia
`zest_repay`	Pagar ativos emprestados

DeFi - Bitflow DEX (Mainnet)

Agregador de DEX que roteia negociações por múltiplas fontes de liquidez.

Unidades: As ferramentas Bitflow usam por padrão unidades humanas (amountUnit: "human"). Passe "2" para trocar 2 STX, não "2000000". Defina amountUnit: "base" apenas ao trabalhar com inteiros on-chain brutos. Veja o guia Unidades e Decimais para detalhes e armadilhas comuns.

Ferramenta	Descrição
`bitflow_get_ticker`	Obter dados de mercado (sem necessidade de chave de API)
`bitflow_get_quote`	Obter cotação de swap
`bitflow_swap`	Executar swap de token

Pillar Smart Wallet

Carteira inteligente sBTC com integração ao Protocolo Zest e autenticação por passkey.

Ferramenta	Descrição
`pillar_connect`	Conectar à carteira Pillar
`pillar_send`	Enviar sBTC para nomes BNS ou endereços
`pillar_boost`	Criar posição sBTC alavancada
`pillar_position`	Visualizar carteira e posição Zest

Para agentes autônomos, use ferramentas pillar_direct_* (sem necessidade de navegador).

Consultas de Blockchain

Ferramenta	Descrição
`get_account_info`	Obter nonce da conta, saldo
`get_account_transactions`	Listar histórico de transações
`get_block_info`	Obter detalhes do bloco
`get_mempool_info`	Obter transações pendentes
`get_contract_info`	Obter ABI e código-fonte do contrato
`get_contract_events`	Obter histórico de eventos do contrato
`get_network_status`	Obter status de saúde da rede

Yield Hunter (Autônomo)

Ferramenta	Descrição
`yield_hunter_start`	Iniciar depósitos autônomos sBTC→Zest
`yield_hunter_stop`	Parar caça a rendimentos
`yield_hunter_status`	Verificar status do caçador de rendimentos
`yield_hunter_configure`	Ajustar limite, reserva, intervalo

Endpoints de API x402

Ferramenta	Descrição
`list_x402_endpoints`	Descobrir endpoints x402
`execute_x402_endpoint`	Executar endpoint x402 com pagamento automático
`scaffold_x402_endpoint`	Gerar projeto Cloudflare Worker x402
`scaffold_x402_ai_endpoint`	Gerar API de IA x402 com OpenRouter

Exemplos de Uso

Gerenciamento de carteira:

"Qual é o endereço da sua carteira?" "Crie uma carteira para você" "Desbloqueie sua carteira" "Mantenha sua carteira desbloqueada por 1 hora"

Verificar saldos:

"Quanto STX você tem?" "Qual é o seu saldo de sBTC?"

Transferir tokens:

"Envie 2 STX para ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" "Transfira 0.001 sBTC para muneeb.btc"

NFTs:

"Quais NFTs você possui?" "Envie este NFT para alice.btc"

Domínios BNS:

"Qual endereço é satoshi.btc?" "myname.btc está disponível?"

Negociação DeFi (mainnet):

"Quais pools estão disponíveis na ALEX?" "Troque 0.1 STX por ALEX" "Obtenha uma cotação para 100 STX para ALEX" "Quais ativos posso emprestar na Zest?" "Forneça 100 stSTX para Zest" "Tome emprestado 50 aeUSDC da Zest" "Verifique minha posição na Zest"

Endpoints x402:

"Obtenha pools de liquidez em alta" "Conte-me uma piada de pai"

Tokens Suportados

Tokens conhecidos podem ser referenciados por símbolo:

sBTC - Bitcoin nativo em Stacks
USDCx - USD Coin em Stacks
ALEX - Token de governança ALEX
wSTX - STX embrulhado

Tokens ALEX DEX: STX, ALEX e qualquer token de alex_list_pools

Ativos do Protocolo Zest: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC

Ou use qualquer token SIP-010 por ID de contrato: SP2X...::token-name

Configuração

Variável de Ambiente	Descrição	Padrão
`NETWORK`	`mainnet` ou `testnet`	`mainnet`
`AIBTC_TOOLS`	`core`, `core,<group,...>` ou `all` (veja Perfis de Ferramentas). `--install` grava `core`	todas as ferramentas quando não definido
`CLIENT_MNEMONIC`	(Opcional) Mnemônico pré-configurado	-
`HIRO_API_KEY`	(Opcional) Chave de API Hiro para limites de taxa mais altos	-
`SPEND_LIMIT_ENABLED`	Defina `false` para desativar o limite de gastos da carteira	`true`
`SPEND_LIMIT_DAILY_USTX` / `SPEND_LIMIT_SESSION_USTX`	Limite de gastos de STX por dia / por desbloqueio (micro-STX)	`50000000` (50 STX)
`SPEND_LIMIT_DAILY_SATS` / `SPEND_LIMIT_SESSION_SATS`	Limite de gastos de BTC por dia / por desbloqueio (sats)	`50000`
`AIBTC_ALLOW_BLIND_SIGN`	Permitir que `schnorr_sign_digest` assine digests brutos (um sighash assinado gasta fora do limite de gastos)	desativado

Nota sobre NETWORK: O comando --install grava NETWORK=mainnet por padrão (passe --testnet para usar testnet). Se você omitir NETWORK da sua configuração completamente, o fallback em tempo de execução também é mainnet.

Nota sobre limites de gastos: Um trilho de segurança ativado por padrão mede cada gasto de STX, sBTC e BTC (transferências, chamadas de contrato, transações patrocinadas, pagamentos automáticos x402/L402, transmissões Bitcoin, psbt_sign) contra um limite cumulativo por sessão e por dia, para que uma única instrução ruim ou um endpoint malicioso não possa drenar a carteira. Um gasto acima do limite é bloqueado antes de ser assinado ou transmitido, e o agente é instruído a perguntar a você. Aumente os limites via as variáveis de ambiente acima, ou desative com SPEND_LIMIT_ENABLED=false. O limite roda dentro do servidor: ele não contém um agente com acesso shell à sua máquina, então mantenha as ferramentas de gasto fora da lista de aprovação automática do seu cliente. Veja SECURITY.md.

Nota: CLIENT_MNEMONIC é opcional. A abordagem recomendada é deixar o Claude criar sua própria carteira. HIRO_API_KEY é opcional, mas recomendado para uso em produção — sem ela, você pode atingir os limites de taxa públicos da Hiro (respostas 429). Obtenha uma chave em platform.hiro.so.

Arquitetura

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

Notas de Segurança

A carteira do Claude é armazenada criptografada na SUA máquina
A senha nunca é armazenada - apenas o keystore criptografado
Mnemônicos mostrados apenas uma vez na criação
Bloqueio automático após 15 minutos (configurável)
Transações assinadas localmente antes da transmissão
Limite de gastos (ativado por padrão): gastos de saída são limitados por sessão e por dia para que uma única instrução ruim não possa drenar a carteira — veja Configuração
Hook de pré-commit de varredura de segredos: contribuidores recebem um hook (instalado automaticamente via npm install) que bloqueia o commit de uma frase-semente ou chave privada
Para mainnet: Financie com pequenas quantidades primeiro

Veja SECURITY.md para o modelo completo de proteção de chaves da carteira e etapas de recuperação de vazamento de chaves.

Avançado: Mnemônico Pré-configurado

Para configurações automatizadas onde o Claude precisa de acesso imediato à carteira, adicione a variável de ambiente CLIENT_MNEMONIC à sua configuração do servidor MCP (em ~/.claude.json para Claude Code, ou 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"
      }
    }
  }
}

Isso ignora o fluxo de criação de carteira - o Claude tem acesso imediato para transacionar.

Habilidade do Agente

Este pacote inclui uma habilidade compatível com Agent Skills que ensina a qualquer LLM como usar os recursos da carteira Bitcoin de forma eficaz.

O que é?

A habilidade aibtc-bitcoin-wallet fornece:

Fluxos de trabalho estruturados para operações Bitcoin L1 (saldo, envio, taxas)
Guias de referência para carteiras inteligentes Pillar e DeFi Stacks L2
Instruções agnósticas de LLM que funcionam com Claude Code, Cursor, Codex e mais de 20 outras ferramentas

Usando a Habilidade

A habilidade é incluída automaticamente quando você instala o servidor MCP. Encontre-a em:

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

Estrutura da Habilidade

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

Desenvolvimento

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)

Lançamentos

Este repositório usa Release Please para lançamentos automatizados:

Mescle PRs com commits convencionais (feat:, fix:, etc.)
O Release Please cria um PR de Lançamento com changelog
Mescle o PR de Lançamento para publicar

Segredos do Repositório (Mantenedores)

Segredo	Descrição
`NPM_TOKEN`	Token de publicação npm para o escopo @aibtc
`CLAWHUB_API_TOKEN`	Token da API ClawHub para publicação de habilidades

Para obter um token da API ClawHub, visite clawhub.ai e crie uma conta.

Licença

MIT