README.md
BYON (Bring Your Own Node) Bitcoin payments for AI agents
AgentBTC MCP Server
BYON (Bring Your Own Node) Bitcoin payments for AI agents via Model Context Protocol
The world's first Bitcoin/Lightning MCP server. Your Lightning node credentials never leave your machine. Works with Claude Desktop, OpenClaw, and any MCP-compatible AI tool.
🌟 Features
- 🔒 True BYON: Your Lightning credentials never leave your machine — zero-trust architecture
- ⚡ Lightning Network: Fast, cheap Bitcoin micropayments (~200ms per payment)
- 🤖 13 MCP Tools: Complete wallet management, payments, invoices, channels, and L402
- 📊 L402 Protocol: HTTP 402 "Payment Required" for API monetization
- 🛡️ Non-Custodial: Zero counterparty risk — you control your Bitcoin
- 🏷️ Lightning Addresses: Send to
bot@yourname.agentbtc.io - 💳 Spending Policies: Per-transaction, daily, and monthly limits for agent wallets
🚀 Quick Start
Option 1: npx (no install)
npx agentbtc-mcp start
Option 2: Global install
npm install -g agentbtc-mcp
agentbtc-mcp start
Claude Desktop Config
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"agentbtc": {
"command": "npx",
"args": ["-y", "agentbtc-mcp", "start"],
"env": {
"AGENTBTC_LND_HOST": "your-node:8080",
"AGENTBTC_LND_MACAROON": "/path/to/readonly.macaroon",
"AGENTBTC_API_URL": "https://agentbtc.io",
"AGENTBTC_API_KEY": "your-api-key"
}
}
}
}
🔧 Available Tools (13)
| Tool | Description |
|---|---|
list_agent_wallets |
List all agent wallets |
get_agent_balance |
Check wallet balance |
create_agent_wallet |
Create a new agent wallet |
delete_agent_wallet |
Remove an agent wallet |
get_node_info |
Lightning node status |
create_lightning_invoice |
Generate payment requests |
pay_lightning_invoice |
Send Lightning payments |
send_to_lightning_address |
Pay Lightning addresses |
decode_invoice |
Decode BOLT11 invoices |
check_channel_balance |
Channel liquidity info |
list_channels |
List Lightning channels |
get_transaction_history |
Payment history |
access_l402_api |
Access L402-protected APIs |
⚙️ Configuration
Environment Variables
| Variable | Required | Description |
|---|---|---|
AGENTBTC_LND_HOST |
Yes | LND REST API endpoint (e.g., localhost:8080) |
AGENTBTC_LND_MACAROON |
Yes | Path to LND macaroon file |
AGENTBTC_API_URL |
No | AgentBTC server URL (default: http://localhost:8000) |
AGENTBTC_API_KEY |
No | Your owner API key for wallet management |
CLI Commands
agentbtc-mcp start # Start MCP server
agentbtc-mcp setup # Interactive Claude Desktop setup
agentbtc-mcp test # Test Lightning node connection
agentbtc-mcp config # Show current configuration
agentbtc-mcp version # Show version
📋 Requirements
- Node.js 18+
- Lightning Node — LND with REST API enabled
- MCP Client — Claude Desktop, OpenClaw, or compatible
🔒 Security Model
AgentBTC uses a BYON (Bring Your Own Node) architecture:
- Your Lightning node credentials stay on your machine
- The MCP server runs locally, connecting directly to your node
- No credentials are ever transmitted to AgentBTC servers
- Agent wallets have configurable spending limits
- All payments are logged with full audit trail
🧪 Testing
# Test with testnet
export AGENTBTC_LND_HOST=your-testnet-node:8080
export AGENTBTC_LND_MACAROON=/path/to/testnet/readonly.macaroon
agentbtc-mcp test
🆘 Troubleshooting
"Connection refused"
- Verify your Lightning node is running
- Check
AGENTBTC_LND_HOST— usuallylocalhost:8080for LND REST - For Voltage nodes: use
your-node.t.voltageapp.io:8080
"Permission denied"
- Check macaroon file exists and is readable
- Use
readonly.macaroonfor safety
"Invalid macaroon"
- Ensure you're using the correct network (mainnet vs testnet)
- Try copying the macaroon to a new path
🌐 Links
- Website: agentbtc.io
- GitHub: github.com/bkblock/agentbtc-mcp
📜 License
MIT — see LICENSE.
Built by BK Block Solutions ⚡
Tools (13)
list_agent_walletsList all agent walletsget_agent_balanceCheck wallet balancecreate_agent_walletCreate a new agent walletdelete_agent_walletRemove an agent walletget_node_infoLightning node statuscreate_lightning_invoiceGenerate payment requestspay_lightning_invoiceSend Lightning paymentssend_to_lightning_addressPay Lightning addressesdecode_invoiceDecode BOLT11 invoicescheck_channel_balanceChannel liquidity infolist_channelsList Lightning channelsget_transaction_historyPayment historyaccess_l402_apiAccess L402-protected APIsEnvironment Variables
AGENTBTC_LND_HOSTrequiredLND REST API endpointAGENTBTC_LND_MACAROONrequiredPath to LND macaroon fileAGENTBTC_API_URLAgentBTC server URLAGENTBTC_API_KEYYour owner API key for wallet managementConfiguration
claude_desktop_config.json
{"mcpServers": {"agentbtc": {"command": "npx", "args": ["-y", "agentbtc-mcp", "start"], "env": {"AGENTBTC_LND_HOST": "your-node:8080", "AGENTBTC_LND_MACAROON": "/path/to/readonly.macaroon", "AGENTBTC_API_URL": "https://agentbtc.io", "AGENTBTC_API_KEY": "your-api-key"}}}}Try it
→Check the current balance of my agent wallet.
→Create a new Lightning invoice for 5000 sats.
→Pay this Lightning invoice: [invoice_string].
→List my current Lightning channels and check their liquidity.
→Access the L402-protected API at [url] using my wallet.