Connect your AI agent to payment rails in 10 minutes. No Lightning node required. No prior Bitcoin knowledge required.
Updated: March 3, 2026 — New: NWC support (Alby/Zeus/Mutiny), USDC on Base, dashboard-guided onboarding, OpenClaw featured as primary AI platform path.
The dashboard guides you through everything. Open it first:
https://agenticbtc.app/dashboard
That's it. Detailed instructions for each step below.
AgenticBTC is a universal payment routing platform that gives AI agents the ability to send and receive money. It connects AI assistants like Claude, GPT-4, OpenClaw agents, and custom agents to real payment rails — Lightning Network (LND + NWC), Strike, Coinbase, USDC on Base, PayPal, Venmo, Stripe, and on-chain Bitcoin — through a single, unified interface.
Think of it as a payment gateway built specifically for AI: one API call, and the platform automatically finds the best path to move money to whoever your agent needs to pay.
You don't need a Lightning node. Connect your existing Alby, Zeus, or Mutiny wallet via NWC (Nostr Wallet Connect) in under 10 seconds. Or connect PayPal, Coinbase, or Stripe — whatever you already have.
In plain terms: if you want your AI assistant to buy things, pay for API access, tip content creators, or receive payments on your behalf, AgenticBTC is the bridge that makes that possible. You keep full control of your money at all times — BYON means your credentials never leave your machine.
Before you set up AgenticBTC, make sure you have the following ready. If you do not have some of these yet, do not worry -- this guide will walk you through getting each one.
An AgenticBTC account
You need an account on the AgenticBTC platform. This is free to create and takes about two minutes.
Once you are logged in, you will see the AgenticBTC dashboard. This is your home base for managing wallets, viewing transactions, and generating API keys.
An API key
Your API key is how your AI agent authenticates with the AgenticBTC platform. It proves to the system that this agent is authorized to act on your behalf.
To generate your API key:
Important: Your API key is shown only once when it is generated. The platform stores a hashed version for security, which means it cannot show you the key again later. If you lose it, you will need to generate a new one. Treat your API key like a password. Do not share it publicly, do not paste it into chat messages, and do not commit it to version control (like GitHub).
Node.js 18 or higher
AgenticBTC's MCP server runs on Node.js. You need version 18 or newer installed on your computer.
To check if you already have Node.js installed, open your terminal (on Mac, search for "Terminal" in Spotlight; on Windows, search for "Command Prompt" or "PowerShell") and type:
node --version
If you see something like v18.17.0 or v20.10.0 or any number starting with 18 or higher, you are good to go.
If you get an error like "command not found" or your version is below 18, you need to install or update Node.js:
brew install node.sudo apt update && sudo apt install nodejs npm. On other distributions, check the Node.js website for specific instructions.After installing, close and reopen your terminal, then run node --version again to confirm it worked.
A Lightning Network node
A Lightning node is required only if you want to make Lightning Network payments (fast, cheap Bitcoin transactions). If you only need wallet management, balance checking, and non-Lightning payment rails (Strike, Coinbase, PayPal, Venmo), you can skip the Lightning node entirely.
If you do want Lightning:
If you are brand new to Lightning and just want to get started quickly, Voltage Cloud is the easiest path. You can always switch to a home node later.
This is the primary and recommended way to use AgenticBTC. If you use Claude Desktop as your AI assistant, this method gives Claude direct access to all 13 AgenticBTC payment tools — wallet management, Lightning payments, invoice creation, channel monitoring, L402 API access, and more.
There are two ways to complete this setup:
This is the easiest path. One command does everything — it asks for your API key, optionally asks for your Lightning node credentials, tests the connection, and writes the Claude Desktop config file automatically.
Step 1: Open your terminal
Step 2: Run the setup wizard
npx agenticbtc-mcp start
The first time you run this, npm will download the AgenticBTC MCP package (10-30 seconds). After that it runs from cache instantly.
Step 3: Answer the prompts
Prompt 1 — API URL:
AgenticBTC API URL (https://agenticbtc.app):
Press Enter to accept the default. This is correct for all users using the hosted platform.
Self-hosting? If you are running AgenticBTC on your own machine, enter
http://localhost:8000instead.
Prompt 2 — API Key:
AgenticBTC API Key:
Paste your Owner API Key and press Enter. To find your key: 1. Log in at https://agenticbtc.app/dashboard 2. Go to Settings → API Keys 3. Copy your Owner API Key
Prompt 3 — Lightning Node (optional):
LND REST API Host (optional):
LND Macaroon (hex, optional):
If you have a Lightning node, enter its host and macaroon. If not, press Enter twice to skip. You can add Lightning later.
Step 4: Confirm it worked
You should see:
✅ API connection successful
✅ Configuration saved to: ~/Library/Application Support/Claude/claude_desktop_config.json
🎉 Setup complete!
💡 Restart Claude Desktop to load the AgenticBTC MCP server.
If you see a warning that the API connection failed, double-check your API key — make sure there are no extra spaces when you copied it.
Step 5: Restart Claude Desktop
Fully quit Claude Desktop (do not just close the window) and reopen it. - Mac: Right-click the Claude icon in the Dock → Quit - Windows: Right-click the Claude icon in the system tray → Exit
Step 6: Verify it worked
In a new Claude conversation, type:
List my agent wallets
Claude should respond with your wallet list. If it says it cannot access AgenticBTC tools, make sure you fully quit and restarted Claude Desktop (not just closed the window).
You can also check from your terminal:
npx agenticbtc-mcp status
Use this if you prefer editing config files directly, or if Option A did not work for you.
Find your Claude Desktop config file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/claude/claude_desktop_config.jsonIf the file does not exist, create it:
# Mac/Linux
mkdir -p ~/Library/Application\ Support/Claude
echo '{"mcpServers":{}}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json
Add the AgenticBTC server config:
Without Lightning (wallet management only):
{
"mcpServers": {
"agenticbtc": {
"command": "npx",
"args": ["agenticbtc-mcp", "server"],
"env": {
"AGENTICBTC_API_URL": "https://agenticbtc.app",
"AGENTICBTC_API_KEY": "your-owner-api-key-here"
}
}
}
}
With Lightning (lndconnect URL — easiest):
{
"mcpServers": {
"agenticbtc": {
"command": "npx",
"args": ["agenticbtc-mcp", "server"],
"env": {
"AGENTICBTC_API_URL": "https://agenticbtc.app",
"AGENTICBTC_API_KEY": "your-owner-api-key-here",
"AGENTICBTC_LNDCONNECT": "lndconnect://your-node:8080?cert=...&macaroon=..."
}
}
}
}
With Lightning (host + macaroon separately):
{
"mcpServers": {
"agenticbtc": {
"command": "npx",
"args": ["agenticbtc-mcp", "server"],
"env": {
"AGENTICBTC_API_URL": "https://agenticbtc.app",
"AGENTICBTC_API_KEY": "your-owner-api-key-here",
"AGENTICBTC_LND_HOST": "https://your-node-address:8080",
"AGENTICBTC_LND_MACAROON": "your-hex-macaroon-here"
}
}
}
}
Fully quit and restart Claude Desktop after saving.
The REST API is the most flexible way to integrate with AgenticBTC. It works from any programming language, any platform, and any HTTP client. If you are building a custom agent, integrating with an automation platform, or working in a language other than JavaScript, this is your method.
All API requests go to:
https://agenticbtc.io/api/v1
This is the production AgenticBTC server. All endpoints described below are relative to this base URL. For example, the "create agent wallet" endpoint is POST https://agenticbtc.io/api/v1/agents.
Every API request must include your API key in the X-API-Key HTTP header. Without it, you will get a 401 Unauthorized error.
X-API-Key: your-api-key-here
There are two types of API keys:
Endpoint: POST /api/v1/agents
Creates a new wallet for an AI agent. Returns the wallet ID and a one-time API key.
curl example:
curl -X POST https://agenticbtc.io/api/v1/agents \
-H "X-API-Key: your-owner-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Research Agent",
"description": "AI agent for purchasing API access and research data"
}'
Response:
{
"id": "7f42cc91",
"name": "Research Agent",
"api_key": "agent_7f42cc91_xK9mPq2r_ABC123...",
"message": "Created wallet 'Research Agent'"
}
Save the api_key value immediately. It is displayed only once and cannot be recovered later.
Endpoint: GET /api/v1/agents/{id}
Retrieves the current balance and status of an agent wallet.
curl example:
curl https://agenticbtc.io/api/v1/agents/7f42cc91 \
-H "X-API-Key: your-owner-api-key"
Response:
{
"agent_id": "7f42cc91",
"name": "Research Agent",
"balance_sats": 12500,
"enabled": true,
"spending_policy": {
"max_per_tx": 5000,
"max_daily": 25000,
"max_monthly": 100000
}
}
Endpoint: POST /api/v1/invoices/pay
Pays a BOLT11 Lightning invoice. The payment is routed through your Lightning node.
curl example:
curl -X POST https://agenticbtc.io/api/v1/invoices/pay \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"invoice": "lnbc10u1pj9x4z7pp5qkv7m8...",
"fee_limit_sats": 50
}'
Response:
{
"success": true,
"payment_hash": "def456abc789...",
"amount_sats": 1000,
"fee_sats": 2,
"status": "SUCCEEDED"
}
The fee_limit_sats parameter is optional (defaults to 100 sats). It sets the maximum routing fee you are willing to pay. If the cheapest route costs more than your fee limit, the payment will fail rather than overpaying.
Endpoint: POST /api/v1/payments/send
This is the most powerful endpoint. It accepts any recipient type -- a Lightning invoice, a Lightning address, an email address, a phone number, a Bitcoin address -- and automatically routes the payment through the cheapest available rail.
curl example:
curl -X POST https://agenticbtc.io/api/v1/payments/send \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "research-agent",
"amount": 1000,
"currency": "SATS",
"recipient": "[email protected]",
"description": "API access payment"
}'
Response:
{
"success": true,
"rail_used": "lightning",
"payment_hash": "abc123...",
"amount_sats": 1000,
"fee_sats": 1,
"description": "API access payment",
"recipient": "[email protected]",
"status": "completed"
}
The currency field accepts "SATS", "BTC", or "USD". If you specify "USD", the platform converts to the appropriate amount based on current exchange rates.
Endpoint: POST /api/v1/payments/estimate
Before sending a payment, you can get fee estimates across all available payment rails. This helps you (or your agent) choose the cheapest option.
curl example:
curl -X POST https://agenticbtc.io/api/v1/payments/estimate \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"amount": 5000,
"currency": "SATS",
"recipient": "[email protected]"
}'
Response:
{
"estimates": [
{
"rail": "lightning",
"fee_sats": 2,
"estimated_time": "< 1 second",
"available": true
},
{
"rail": "strike",
"fee_sats": 0,
"estimated_time": "< 5 seconds",
"available": true
}
],
"recommended": "lightning"
}
Endpoint: GET /api/v1/payments/rails
Returns a list of all payment rails that are currently configured and available on your platform.
curl example:
curl https://agenticbtc.io/api/v1/payments/rails \
-H "X-API-Key: your-api-key"
Response:
{
"rails": [
{
"name": "lightning",
"status": "active",
"supports": ["bolt11_invoice", "lightning_address", "lnurl"],
"description": "Lightning Network - instant, low-fee Bitcoin payments"
},
{
"name": "strike",
"status": "active",
"supports": ["email", "phone", "lightning_address"],
"description": "Strike - fiat on/off ramp with Lightning"
},
{
"name": "onchain",
"status": "active",
"supports": ["bitcoin_address"],
"description": "On-chain Bitcoin - standard Bitcoin transactions"
}
]
}
Here is a complete Python example using the requests library:
import requests
# Configuration
API_KEY = "your-api-key-here"
BASE_URL = "https://agenticbtc.io/api/v1"
HEADERS = {
"X-API-Key": API_KEY,
"Content-Type": "application/json"
}
# 1. Create an agent wallet
response = requests.post(
f"{BASE_URL}/agents",
headers=HEADERS,
json={
"name": "My Python Agent",
"description": "Agent created from Python script"
}
)
wallet = response.json()
print(f"Created wallet: {wallet['name']} (ID: {wallet['id']})")
print(f"Agent API Key: {wallet['api_key']}") # Save this!
# 2. Check agent balance
response = requests.get(
f"{BASE_URL}/agents/{wallet['id']}",
headers=HEADERS
)
balance = response.json()
print(f"Balance: {balance['balance_sats']} sats")
# 3. Create a Lightning invoice
response = requests.post(
f"{BASE_URL}/invoices",
headers=HEADERS,
json={
"amount_sats": 1000,
"description": "Payment for data analysis"
}
)
invoice_data = response.json()
print(f"Invoice: {invoice_data['invoice']}")
# 4. Pay a Lightning invoice
response = requests.post(
f"{BASE_URL}/invoices/pay",
headers=HEADERS,
json={
"invoice": "lnbc10u1pj9x4z7pp5...", # Replace with real invoice
"fee_limit_sats": 50
}
)
payment = response.json()
print(f"Payment status: {payment['status']}")
# 5. Send a universal payment (auto-routes)
response = requests.post(
f"{BASE_URL}/payments/send",
headers=HEADERS,
json={
"agent_id": wallet['id'],
"amount": 500,
"currency": "SATS",
"recipient": "[email protected]",
"description": "Tip for great content"
}
)
result = response.json()
print(f"Sent via {result['rail_used']}, fee: {result['fee_sats']} sats")
# 6. Get fee estimates before sending
response = requests.post(
f"{BASE_URL}/payments/estimate",
headers=HEADERS,
json={
"amount": 5000,
"currency": "SATS",
"recipient": "[email protected]"
}
)
estimates = response.json()
for est in estimates['estimates']:
print(f" {est['rail']}: {est['fee_sats']} sats fee, {est['estimated_time']}")
# 7. Get transaction history
response = requests.get(
f"{BASE_URL}/transactions?limit=10",
headers=HEADERS
)
history = response.json()
for tx in history['transactions']:
print(f" {tx['type']}: {tx['amount_sats']} sats - {tx['memo']}")
Here is the equivalent in JavaScript using the built-in fetch API:
const API_KEY = "your-api-key-here";
const BASE_URL = "https://agenticbtc.io/api/v1";
const headers = {
"X-API-Key": API_KEY,
"Content-Type": "application/json",
};
// 1. Create an agent wallet
async function createWallet() {
const response = await fetch(`${BASE_URL}/agents`, {
method: "POST",
headers,
body: JSON.stringify({
name: "My JS Agent",
description: "Agent created from JavaScript",
}),
});
const wallet = await response.json();
console.log(`Created wallet: ${wallet.name} (ID: ${wallet.id})`);
console.log(`Agent API Key: ${wallet.api_key}`); // Save this!
return wallet;
}
// 2. Check agent balance
async function getBalance(agentId) {
const response = await fetch(`${BASE_URL}/agents/${agentId}`, { headers });
const data = await response.json();
console.log(`Balance: ${data.balance_sats} sats`);
return data;
}
// 3. Create a Lightning invoice
async function createInvoice(amountSats, description) {
const response = await fetch(`${BASE_URL}/invoices`, {
method: "POST",
headers,
body: JSON.stringify({
amount_sats: amountSats,
description: description,
}),
});
const data = await response.json();
console.log(`Invoice: ${data.invoice}`);
return data;
}
// 4. Pay a Lightning invoice
async function payInvoice(invoice, feeLimitSats = 50) {
const response = await fetch(`${BASE_URL}/invoices/pay`, {
method: "POST",
headers,
body: JSON.stringify({
invoice: invoice,
fee_limit_sats: feeLimitSats,
}),
});
const data = await response.json();
console.log(`Payment status: ${data.status}`);
return data;
}
// 5. Send a universal payment
async function sendPayment(agentId, amount, recipient, description) {
const response = await fetch(`${BASE_URL}/payments/send`, {
method: "POST",
headers,
body: JSON.stringify({
agent_id: agentId,
amount: amount,
currency: "SATS",
recipient: recipient,
description: description,
}),
});
const data = await response.json();
console.log(`Sent via ${data.rail_used}, fee: ${data.fee_sats} sats`);
return data;
}
// 6. Get fee estimates
async function getEstimates(amount, recipient) {
const response = await fetch(`${BASE_URL}/payments/estimate`, {
method: "POST",
headers,
body: JSON.stringify({
amount: amount,
currency: "SATS",
recipient: recipient,
}),
});
const data = await response.json();
data.estimates.forEach((est) => {
console.log(` ${est.rail}: ${est.fee_sats} sats fee, ${est.estimated_time}`);
});
return data;
}
// Run all examples
async function main() {
const wallet = await createWallet();
await getBalance(wallet.id);
await createInvoice(1000, "Test payment from JS");
await getEstimates(5000, "[email protected]");
}
main().catch(console.error);
If you are building AI agents using OpenAI's GPT-4 or GPT-4o, LangChain, CrewAI, AutoGPT, or any other framework that supports OpenAI-style function calling, this method is for you. Instead of using MCP (which is specific to Claude Desktop), you can get AgenticBTC's capabilities as OpenAI-compatible tool definitions and plug them directly into your agent framework.
OpenAI function calling (also called "tool use") is a standard format for describing tools that an AI model can invoke. When you give GPT-4 a list of tool definitions, it can decide when to call them and what arguments to pass. AgenticBTC provides its entire tool set in this format, so any framework that speaks this protocol can use it.
AgenticBTC exposes all of its tools in OpenAI-compatible format at a single endpoint:
curl https://agenticbtc.io/api/v1/openai-tools \
-H "X-API-Key: your-api-key"
This returns a JSON object containing all available tool definitions. You can import these directly into your agent framework.
Response structure:
{
"tools": [
{
"type": "function",
"function": {
"name": "agenticbtc_create_agent_wallet",
"description": "Create a new agent wallet on the AgenticBTC platform. Returns the wallet ID and a one-time API key.",
"parameters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "A descriptive name for the wallet (e.g., 'Shopping Bot', 'Research Agent')"
},
"description": {
"type": "string",
"description": "Optional description of what this agent wallet is used for"
}
},
"required": ["name"]
}
}
},
{
"type": "function",
"function": {
"name": "agenticbtc_pay_invoice",
"description": "Pay a Lightning Network BOLT11 invoice. The payment is routed through your Lightning node. Spending policy limits are enforced.",
"parameters": {
"type": "object",
"properties": {
"invoice": {
"type": "string",
"description": "The BOLT11 Lightning invoice string (starts with 'lnbc' for mainnet or 'lntb' for testnet)"
},
"fee_limit_sats": {
"type": "number",
"description": "Maximum routing fee in satoshis (default: 100)"
}
},
"required": ["invoice"]
}
}
},
{
"type": "function",
"function": {
"name": "agenticbtc_send_payment",
"description": "Send a payment to any recipient using the universal payment router. Automatically selects the best payment rail based on recipient type, fees, and speed.",
"parameters": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Agent wallet name or ID to send from"
},
"amount": {
"type": "number",
"description": "Amount to send"
},
"currency": {
"type": "string",
"enum": ["SATS", "BTC", "USD"],
"description": "Currency of the amount (SATS, BTC, or USD)"
},
"recipient": {
"type": "string",
"description": "Recipient identifier (Lightning invoice, Lightning address, email, phone, or Bitcoin address)"
},
"description": {
"type": "string",
"description": "Description or memo for the payment"
}
},
"required": ["amount", "currency", "recipient"]
}
}
},
{
"type": "function",
"function": {
"name": "agenticbtc_get_balance",
"description": "Get the current balance of an agent wallet in satoshis.",
"parameters": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Agent wallet name or ID"
}
},
"required": ["agent_id"]
}
}
},
{
"type": "function",
"function": {
"name": "agenticbtc_create_invoice",
"description": "Create a Lightning invoice to receive a payment. Returns a BOLT11 invoice string.",
"parameters": {
"type": "object",
"properties": {
"amount_sats": {
"type": "number",
"description": "Amount in satoshis"
},
"description": {
"type": "string",
"description": "Description or memo for the invoice"
}
},
"required": ["amount_sats"]
}
}
},
{
"type": "function",
"function": {
"name": "agenticbtc_get_fee_estimate",
"description": "Get fee estimates across all available payment rails for a given payment.",
"parameters": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount to send"
},
"currency": {
"type": "string",
"enum": ["SATS", "BTC", "USD"],
"description": "Currency of the amount"
},
"recipient": {
"type": "string",
"description": "Recipient identifier"
}
},
"required": ["amount", "currency", "recipient"]
}
}
}
],
"base_url": "https://agenticbtc.io/api/v1",
"auth": "X-API-Key header with your API key"
}
Here is a complete example of using AgenticBTC tools with GPT-4 via the OpenAI Python SDK:
import openai
import requests
import json
# Configuration
OPENAI_API_KEY = "sk-your-openai-key"
AGENTICBTC_API_KEY = "your-agenticbtc-api-key"
AGENTICBTC_BASE = "https://agenticbtc.io/api/v1"
client = openai.OpenAI(api_key=OPENAI_API_KEY)
# Step 1: Fetch tool definitions from AgenticBTC
tools_response = requests.get(
f"{AGENTICBTC_BASE}/openai-tools",
headers={"X-API-Key": AGENTICBTC_API_KEY}
)
tools = tools_response.json()["tools"]
# Step 2: Define how to execute each tool
def execute_tool(tool_name, arguments):
"""Execute an AgenticBTC tool by calling the REST API."""
headers = {
"X-API-Key": AGENTICBTC_API_KEY,
"Content-Type": "application/json"
}
if tool_name == "agenticbtc_create_agent_wallet":
resp = requests.post(f"{AGENTICBTC_BASE}/agents", headers=headers, json=arguments)
elif tool_name == "agenticbtc_get_balance":
resp = requests.get(f"{AGENTICBTC_BASE}/agents/{arguments['agent_id']}", headers=headers)
elif tool_name == "agenticbtc_pay_invoice":
resp = requests.post(f"{AGENTICBTC_BASE}/invoices/pay", headers=headers, json=arguments)
elif tool_name == "agenticbtc_send_payment":
resp = requests.post(f"{AGENTICBTC_BASE}/payments/send", headers=headers, json=arguments)
elif tool_name == "agenticbtc_create_invoice":
resp = requests.post(f"{AGENTICBTC_BASE}/invoices", headers=headers, json=arguments)
elif tool_name == "agenticbtc_get_fee_estimate":
resp = requests.post(f"{AGENTICBTC_BASE}/payments/estimate", headers=headers, json=arguments)
else:
return {"error": f"Unknown tool: {tool_name}"}
return resp.json()
# Step 3: Run a conversation with tool use
messages = [
{"role": "system", "content": "You are a helpful assistant with access to Bitcoin payment tools via AgenticBTC."},
{"role": "user", "content": "Check the balance of my Research Agent wallet and then create a 500 sat invoice."}
]
# First API call - model decides which tools to use
response = client.chat.completions.create(
model="gpt-4",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Process tool calls
message = response.choices[0].message
if message.tool_calls:
messages.append(message)
for tool_call in message.tool_calls:
tool_name = tool_call.function.name
arguments = json.loads(tool_call.function.arguments)
# Execute the tool
result = execute_tool(tool_name, arguments)
# Add tool result to conversation
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": json.dumps(result)
})
# Second API call - model processes tool results
final_response = client.chat.completions.create(
model="gpt-4",
messages=messages,
tools=tools,
tool_choice="auto"
)
print(final_response.choices[0].message.content)
import requests
from langchain.tools import StructuredTool
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_openai import ChatOpenAI
AGENTICBTC_API_KEY = "your-agenticbtc-api-key"
AGENTICBTC_BASE = "https://agenticbtc.io/api/v1"
HEADERS = {"X-API-Key": AGENTICBTC_API_KEY, "Content-Type": "application/json"}
# Define LangChain tools that wrap AgenticBTC endpoints
def check_balance(agent_id: str) -> str:
"""Check the balance of an agent wallet."""
resp = requests.get(f"{AGENTICBTC_BASE}/agents/{agent_id}", headers=HEADERS)
return str(resp.json())
def send_payment(agent_id: str, amount: int, recipient: str, description: str = "") -> str:
"""Send a payment to any recipient using AgenticBTC's universal router."""
resp = requests.post(f"{AGENTICBTC_BASE}/payments/send", headers=HEADERS, json={
"agent_id": agent_id,
"amount": amount,
"currency": "SATS",
"recipient": recipient,
"description": description
})
return str(resp.json())
def create_invoice(amount_sats: int, description: str = "AgenticBTC payment") -> str:
"""Create a Lightning invoice to receive payment."""
resp = requests.post(f"{AGENTICBTC_BASE}/invoices", headers=HEADERS, json={
"amount_sats": amount_sats,
"description": description
})
return str(resp.json())
# Create LangChain tools
tools = [
StructuredTool.from_function(check_balance, name="check_balance", description="Check an agent wallet balance"),
StructuredTool.from_function(send_payment, name="send_payment", description="Send a payment via AgenticBTC"),
StructuredTool.from_function(create_invoice, name="create_invoice", description="Create a Lightning invoice"),
]
# Create the agent
llm = ChatOpenAI(model="gpt-4", temperature=0)
agent = create_openai_tools_agent(llm, tools, prompt=your_prompt_template)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
# Run it
result = agent_executor.invoke({"input": "Check my Research Agent balance and send 500 sats to [email protected]"})
print(result["output"])
from crewai import Agent, Task, Crew
from crewai_tools import tool
import requests
AGENTICBTC_API_KEY = "your-agenticbtc-api-key"
AGENTICBTC_BASE = "https://agenticbtc.io/api/v1"
HEADERS = {"X-API-Key": AGENTICBTC_API_KEY, "Content-Type": "application/json"}
@tool("AgenticBTC Payment Tool")
def agenticbtc_pay(recipient: str, amount: int, description: str) -> str:
"""Send a Bitcoin payment to any recipient using AgenticBTC. Accepts Lightning invoices, Lightning addresses, emails, or Bitcoin addresses."""
resp = requests.post(f"{AGENTICBTC_BASE}/payments/send", headers=HEADERS, json={
"amount": amount,
"currency": "SATS",
"recipient": recipient,
"description": description
})
return str(resp.json())
@tool("AgenticBTC Balance Checker")
def agenticbtc_balance(agent_id: str) -> str:
"""Check the balance of an AgenticBTC agent wallet."""
resp = requests.get(f"{AGENTICBTC_BASE}/agents/{agent_id}", headers=HEADERS)
return str(resp.json())
# Create a CrewAI agent with payment capabilities
payment_agent = Agent(
role="Payment Specialist",
goal="Handle Bitcoin payments efficiently using AgenticBTC",
backstory="An AI agent specialized in managing cryptocurrency payments.",
tools=[agenticbtc_pay, agenticbtc_balance],
verbose=True
)
# Define a task
payment_task = Task(
description="Check the Research Agent balance and send 500 sats to [email protected] for API access.",
expected_output="Confirmation of payment with transaction details.",
agent=payment_agent
)
# Create and run the crew
crew = Crew(agents=[payment_agent], tasks=[payment_task], verbose=True)
result = crew.kickoff()
print(result)
OpenClaw and other MCP-capable agent platforms can connect to AgenticBTC directly via the MCP protocol — independent of Claude Desktop. This is the recommended path for:
OpenClaw uses a tool called mcporter to connect to MCP servers. You configure AgenticBTC as an MCP server in the mcporter config file, and any OpenClaw agent can then call AgenticBTC payment tools directly.
Important: Use an Agent Key, Not Your Owner Key
Your Owner API Key has full admin access — it can create/delete agents, change spending policies, and configure rails. Never put it in an agent's MCP config.
Instead:
1. Create an agent wallet in the AgenticBTC dashboard (Settings → Agent Wallets)
2. Set a spending limit and allowed rails for that wallet
3. Copy the agent_ prefixed API key it generates
4. Put that agent key in the mcporter config
This way, the OpenClaw agent operates within the limits you set and cannot modify its own policy.
~/.openclaw/workspace/config/mcporter.json
If this file doesn't exist yet, create it.
Edit mcporter.json to include the following. Replace placeholder values with your real credentials:
{
"mcpServers": {
"agenticbtc": {
"transport": "stdio",
"command": "npx",
"args": ["agenticbtc-mcp", "server"],
"env": {
"AGENTICBTC_API_URL": "https://agenticbtc.app",
"AGENTICBTC_API_KEY": "agent_YOUR_AGENT_KEY_HERE",
"AGENTBTC_LND_HOST": "https://your-node.t.voltageapp.io:8080",
"AGENTBTC_LND_MACAROON": "YOUR_HEX_MACAROON",
"NODE_TLS_REJECT_UNAUTHORIZED": "0"
}
}
}
}
Self-hosting? Set
AGENTICBTC_API_URLtohttp://localhost:8000No Lightning node? Omit theAGENTBTC_LND_HOSTandAGENTBTC_LND_MACAROONlines — the agent will use Strike, Coinbase, or other configured rails instead.
Getting the hex macaroon from Voltage:
xxd -p -c 1000 ~/Downloads/admin.macaroon
After saving the config, ask OpenClaw to check the connection:
"Check my AgenticBTC wallet balance"
Or via the mcporter CLI:
openclaw mcporter list
You should see agenticbtc listed as an available server.
Ask your OpenClaw agent to make a test payment within the spending limit you configured:
"Send 100 sats to [Lightning invoice or address]"
The agent should route the payment through AgenticBTC. If the amount exceeds the wallet's spending limit, it will receive a 402 response and report back that the limit was hit — it cannot override or raise its own limit.
agent_ key in mcporter config, never the owner_ key.A Lightning node is your gateway to instant, low-fee Bitcoin payments. This section covers two popular options: Voltage Cloud (easiest, no hardware required) and Umbrel (self-hosted, maximum control).
Voltage is a cloud hosting service that runs a Lightning node for you. You do not need to buy any hardware, sync the Bitcoin blockchain, or manage server infrastructure. Your node is running in the cloud, but you still control the keys -- Voltage cannot access your funds.
agenticbtc-main or my-lightning-nodeTestnet if you are just testing (free to use, no real money). Select Mainnet when you are ready for production (uses real Bitcoin).A note about testnet vs mainnet: Testnet uses fake Bitcoin that has no real value. It is perfect for learning and testing. When you are confident everything works, you can create a separate mainnet node with real Bitcoin. Many people run both -- a testnet node for development and a mainnet node for production.
The API endpoint is how the AgenticBTC MCP server communicates with your Lightning node.
https://your-node-name.t.voltageapp.io:8080This is the value you will use for AGENTBTC_LND_HOST in your configuration.
The :8080 at the end is the port number. This is the default REST API port for LND. Do not change it unless Voltage tells you otherwise.
The macaroon is your authentication credential for the Lightning node. It is what proves to the node that you are authorized to make requests.
admin.macaroon), you will need to convert it to hex format.Converting a downloaded macaroon file to hex:
If you downloaded the admin.macaroon file, open your terminal and run:
On Mac or Linux:
xxd -p admin.macaroon | tr -d '\n'
On Windows (PowerShell):
[System.BitConverter]::ToString([System.IO.File]::ReadAllBytes("admin.macaroon")) -replace '-',''
This will output a long string of hexadecimal characters. Copy the entire output. This is the value you will use for AGENTBTC_LND_MACAROON in your configuration.
What the output looks like: It will be a string like 0201036c6e6402f801030a10b3bf817e... (hundreds of characters long). Make sure you copy the entire string with no spaces or line breaks.
Some Voltage configurations provide an lndconnect:// URL that bundles the host, certificate, and macaroon into a single string. If this is available:
lndconnect://)AGENTBTC_LNDCONNECT configuration variableThis is the easiest method since everything is in one string, but not all Voltage configurations expose it.
Before your node can send Lightning payments, it needs Bitcoin and at least one open channel.
Funding your node:
bc1q for mainnet or tb1q for testnet)For testnet, use a Bitcoin testnet faucet like https://coinfaucet.eu/en/btc-testnet/ to get free test Bitcoin.
Opening your first channel:
Once your funds are confirmed:
Once the channel is confirmed and active, your node can send Lightning payments. The channel's capacity determines the maximum amount you can send in a single payment.
Umbrel is a self-hosted node that runs on hardware in your home. It gives you maximum privacy and control since all data stays on your own device. The tradeoff is that you need hardware and it takes more time to set up.
http://umbrel.local (if you are on the same local network)umbrel.local does not work, try your Umbrel's IP address directly (you can find this in your router's admin page). It will look like http://192.168.1.100.https://umbrel.local:8080The admin macaroon file is stored on your Umbrel device at:
~/umbrel/app-data/lightning/data/chain/bitcoin/mainnet/admin.macaroon
If your node is running testnet, replace mainnet with testnet in that path.
To convert it to hex, SSH into your Umbrel and run:
ssh [email protected]
xxd -p ~/umbrel/app-data/lightning/data/chain/bitcoin/mainnet/admin.macaroon | tr -d '\n'
Copy the output. This is your hex-encoded macaroon.
If you cannot SSH in, you can also copy the macaroon file to your computer first using scp:
scp [email protected]:~/umbrel/app-data/lightning/data/chain/bitcoin/mainnet/admin.macaroon ./admin.macaroon
xxd -p admin.macaroon | tr -d '\n'
By default, Umbrel's LND may only listen for REST connections on localhost. If you are running the AgenticBTC MCP server on the same machine as your Umbrel, https://umbrel.local:8080 should work. If you are accessing from a different machine on your local network, you may need to ensure the REST API is accessible.
Some Umbrel versions require you to add --restlisten=0.0.0.0:8080 to the LND configuration. Check your Umbrel's Lightning Node settings for REST API configuration options.
If you want to connect to your Umbrel node from outside your home network (for example, when traveling), you can set up an SSH tunnel. This creates a secure, encrypted connection from your computer to your home Umbrel.
Open a terminal and run:
ssh -L 8080:localhost:8080 umbrel@your-home-ip
This forwards port 8080 on your local machine to port 8080 on your Umbrel. You can then use https://localhost:8080 as your LND host in the AgenticBTC configuration.
You will need to know your home's public IP address (or use a dynamic DNS service) and have SSH port forwarding enabled on your home router.
Agent wallets are how you control what your AI agents can spend. Each wallet is an isolated container with its own balance, API key, and spending limits. Think of it like giving an employee a corporate credit card with a preset limit -- the agent can spend up to that limit but no more.
curl -X POST https://agenticbtc.io/api/v1/agents \
-H "X-API-Key: your-owner-api-key" \
-H "Content-Type: application/json" \
-d '{
"name": "Research Agent",
"description": "Agent for buying API access and research data"
}'
Simply tell Claude: "Create an agent wallet called Research Agent"
Claude will use the create_agent_wallet tool and return the wallet ID and API key.
Spending limits are the guardrails that prevent your AI agent from spending more than you want. There are three types of limits:
Per-transaction limit (max_per_tx): The maximum amount in satoshis that the agent can spend in a single payment. If the agent tries to pay an invoice that exceeds this limit, the payment is blocked. For example, if you set this to 5,000 sats and the agent tries to pay a 10,000 sat invoice, it will be rejected.
Daily budget (max_daily): The maximum total amount in satoshis that the agent can spend across all payments in a single day. The counter resets at midnight. For example, if you set this to 25,000 sats and the agent has already spent 20,000 sats today, it can only spend 5,000 more sats until midnight.
Monthly budget (max_monthly): The maximum total amount in satoshis that the agent can spend across all payments in a calendar month. The counter resets on the first of each month. For example, if you set this to 100,000 sats and the agent has already spent 95,000 sats this month, it can only spend 5,000 more sats until the next month.
Spending limits are currently configured via the dashboard or through the database. A future update will add API endpoints for managing limits programmatically.
When an agent initiates a payment, the system performs the following checks in order:
If a payment is blocked, the agent receives a clear error message explaining why. For example: "Exceeds daily limit (30,000 > 25,000 sats, already spent 22,000 today)."
Let us walk through a complete example. Suppose you want an AI agent that researches topics for you by purchasing access to paid APIs. You want to limit it to about $5 per day in spending.
At current Bitcoin prices (approximately 1 USD = 1,500 sats, though this fluctuates), $5 is roughly 7,500 sats. Let us round up to 10,000 sats per day to give some buffer for price fluctuations.
Step 1: Create the wallet
Tell Claude: "Create an agent wallet called Research Agent"
Or via API:
curl -X POST https://agenticbtc.io/api/v1/agents \
-H "X-API-Key: your-owner-api-key" \
-H "Content-Type: application/json" \
-d '{"name": "Research Agent"}'
Step 2: Configure spending limits
Set the following limits for the wallet: - Per-transaction: 5,000 sats (about $3.30 -- prevents any single expensive purchase) - Daily: 10,000 sats (about $6.60 -- your target $5/day with buffer) - Monthly: 200,000 sats (about $133 -- a reasonable monthly cap)
Configure these in the dashboard or database:
INSERT INTO spending_policies (id, agent_id, max_per_tx, max_daily, max_monthly, allowed_destinations, enabled)
VALUES ('policy-001', 'your-agent-id', 5000, 10000, 200000, '[]', 1);
Step 3: Fund the wallet
Transfer some sats into the Research Agent's wallet to give it a starting balance.
Step 4: Use the agent
Now your Research Agent can make payments up to 5,000 sats each, up to 10,000 sats per day, and 200,000 sats per month. If it tries to exceed any of these limits, the payment is blocked and the agent is told why. You can monitor its spending in the dashboard or by checking its transaction history.
This section covers every common error you might encounter, with the exact steps to fix each one.
What it means: The MCP server cannot reach your Lightning node or the AgenticBTC platform server.
How to fix:
Check that your Lightning node is running. If using Voltage, go to your Voltage dashboard and verify the node status shows "Running." If using Umbrel, make sure your device is powered on and connected to the network.
Verify the host and port. Open your terminal and test the connection manually:
bash
curl -k https://your-node.t.voltageapp.io:8080/v1/getinfo
If this returns a JSON response or an "auth" error, the node is reachable. If it hangs or says "connection refused," the address is wrong or the node is down.
Check for firewall issues. If you are running a home node, your router's firewall might be blocking external connections. You may need to set up port forwarding or use an SSH tunnel.
Verify the AgenticBTC platform is reachable:
bash
curl https://agenticbtc.io/health
If this returns a response, the platform is online.
What it means: Your macaroon does not have the required permissions, or the file cannot be read.
How to fix:
Make sure you are using the admin macaroon, not a read-only or invoice-only macaroon. The admin macaroon has full permissions for all operations.
If you are pointing to a macaroon file path (on a self-hosted node), check the file permissions:
bash
ls -la /path/to/admin.macaroon
The file should be readable by your user account. If it is not, fix the permissions:
bash
chmod 600 /path/to/admin.macaroon
If you are using a hex-encoded macaroon in your config, make sure the entire hex string is correct and has not been truncated.
What it means: The macaroon you provided does not match what the Lightning node expects.
How to fix:
Check the network. This is the most common cause. If your node is on testnet, you need a testnet macaroon. If your node is on mainnet, you need a mainnet macaroon. Using a testnet macaroon with a mainnet node (or vice versa) will result in "invalid macaroon."
Re-download the macaroon. The hex encoding may have been corrupted during copy-paste. Go back to your node management interface, download a fresh copy of the admin macaroon, and re-encode it:
bash
xxd -p admin.macaroon | tr -d '\n'
Check for extra whitespace or line breaks. When you paste the hex string into your config file, make sure there are no spaces, tabs, or newline characters in the middle of the string. It should be one continuous string.
What it means: Claude Desktop is not loading the AgenticBTC MCP server.
How to fix:
Use a JSON validator to check your file. Paste the contents into https://jsonlint.com and it will tell you if there are any syntax errors.
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonLinux: ~/.config/claude/claude_desktop_config.json
Make sure you fully restarted Claude Desktop. On Mac, press Command + Q to quit completely. On Windows, right-click the system tray icon and click "Quit." Simply closing the window is not enough -- Claude Desktop may still be running in the background.
Check that Node.js is installed and accessible. Claude Desktop needs to be able to find npx on your system. Open a terminal and run:
bash
which npx
If this returns a path, npx is installed. If it says "not found," you need to install Node.js (see Section 2).
Check Claude Desktop logs. On Mac, you can find logs at:
bash
~/Library/Logs/Claude/
Look for recent error messages related to MCP server startup.
What it means: The API key you are using is not recognized by the AgenticBTC platform.
How to fix:
What it means: Your Lightning node cannot find a path to the recipient through the Lightning Network.
How to fix:
Check your channel balance. You need outbound liquidity (local balance) to send payments. Ask Claude: "check my channel balance." If outbound is 0 or very low, you need to open new channels or wait for incoming payments to rebalance.
Open more channels. Having channels with well-connected nodes improves routing success. Open 2-3 channels with different large nodes for better connectivity.
Check the payment amount. If you are trying to send more sats than your largest channel's outbound capacity, the payment will fail. Split the payment into smaller amounts, or open a larger channel.
Try again later. Routing failures can be temporary. The Lightning Network's pathfinding improves as the network state updates.
What it means: The Lightning invoice you are trying to pay has passed its expiration time. Most invoices expire after 1 hour.
How to fix:
Ask the recipient (person, service, or API) to generate a new invoice. There is no way to pay an expired invoice -- a new one must be created. If you are generating your own invoices for testing, simply create a new one.
What it means: The agent wallet has hit one of its spending limits (per-transaction, daily, or monthly).
How to fix:
GET /api/v1/agents/{id}/spending-check?amount_sats=500What it means: The TLS/SSL certificate of your Lightning node is not being accepted.
How to fix:
For Voltage nodes: Always use https:// in the host URL. Voltage nodes have valid SSL certificates, so this error usually means you are using http:// instead of https://.
For Umbrel home nodes: Self-signed certificates are common. You may need to add --tlsextradomain=your-local-ip to your LND configuration so the certificate covers the IP address you are connecting from. Alternatively, the MCP server may need the NODE_TLS_REJECT_UNAUTHORIZED=0 environment variable set in your config (this disables strict certificate checking -- only use this for local/home nodes, never in production).
What it means: Your Lightning node is still syncing with the Bitcoin blockchain. Until it catches up, it cannot verify payments.
How to fix:
Wait. Blockchain synchronization can take anywhere from a few minutes to several hours depending on how far behind your node is. For a brand new node on Voltage, this usually takes less than 10 minutes since Voltage pre-syncs nodes. For a home node (Umbrel on Raspberry Pi), the initial sync can take 24-72 hours.
You can check sync status by asking Claude "what's my node status" and looking at the "synced_to_chain" field. When it shows true, your node is ready.
What it means: You have opened a Lightning channel, but it has not yet been confirmed on the Bitcoin blockchain.
How to fix:
Wait for the channel to be confirmed. Lightning channels require 3 blockchain confirmations before they become active, which typically takes about 30 minutes (3 Bitcoin blocks at approximately 10 minutes each). You can monitor the confirmation progress on mempool.space by searching for the channel funding transaction ID.
Once confirmed, the channel will automatically become active and you can start sending and receiving payments through it.
No. AgenticBTC uses a BYON (Bring Your Own Node) architecture with a precise security principle: wallet spend credentials never leave your machine. Service API keys (PayPal, Coinbase, Strike, etc.) are managed securely in the dashboard — the same way every major payment platform handles them.
There are two types of credentials and they get different treatment:
Wallet custody credentials — stays on your machine only: Your LND macaroon + endpoint, Bitcoin private keys, and NWC connection strings never leave your local environment. These credentials are the keys to your actual funds — compromising them means losing money. The MCP server connects directly to your node from your computer. AgenticBTC's servers never see these credentials and cannot move your Bitcoin.
Service delegation credentials — managed in the dashboard: PayPal, Coinbase, Strike, Stripe, and similar API keys are delegated access to third-party custodians. The money lives at those services, not in the credential itself. A compromised API key still faces platform-level fraud detection, transaction limits, and account verification — the same protections any fintech relies on. We store these the same way Stripe, PayPal, or any other payment platform stores credentials: encrypted, server-side.
The agent wallet system manages balances and spending limits at the application layer. Think of AgenticBTC as a remote control: it sends payment commands, but your wallet holds the keys and the funds.
If your node goes offline, Lightning-related tools will return errors, but your wallet management tools (creating wallets, checking balances, viewing transaction history) will continue to work normally since they interact with the AgenticBTC platform, not your node directly.
Your funds are safe even if your node goes down. When you bring it back online, everything resumes. However, if your node stays offline for an extended period (weeks), your channel partners may force-close your channels to recover their funds. This is a Lightning Network mechanism, not specific to AgenticBTC. The funds from force-closed channels return to your on-chain Bitcoin wallet after a timeout period.
Yes, and it is strongly recommended for initial setup and testing. Create a testnet node on Voltage (it is the same process -- just select "Testnet" when creating the node). Testnet Bitcoin is free (available from faucets) and behaves identically to mainnet Bitcoin, so you can test the entire workflow without risking real money.
To use testnet, just point your configuration at your testnet node's credentials. The AgenticBTC MCP server does not care whether you are on testnet or mainnet -- it works the same way with both.
The AgenticBTC platform itself is free to use. There are no subscription fees for the API or MCP server. You do pay for:
/api/v1/payments/estimate endpoint.The router fee is a small percentage that AgenticBTC charges when you use the universal payment router to send payments. This fee covers the cost of maintaining the routing infrastructure, supporting multiple payment rails, and providing the fee optimization logic. The exact fee varies by payment rail:
You can always check exact fees before sending by using the fee estimate endpoint (POST /api/v1/payments/estimate). The estimate shows you exactly what each rail will cost, including the router fee, so there are no surprises.
Yes. Your Lightning node is a shared infrastructure resource. You can create multiple agent wallets, each with their own API key and spending limits, and they all route payments through the same node. This is the recommended setup -- one node, many agents.
The spending limit system ensures that each agent stays within its budget, even though they all share the same underlying Lightning capacity. If Agent A has a 10,000 sat daily limit and Agent B has a 50,000 sat daily limit, they both use the same node but are independently constrained.
When an agent makes a payment, the system looks up the agent's spending policy and checks three things: (1) Is this single payment under the per-transaction limit? (2) Has the agent spent less than its daily budget today? (3) Has the agent spent less than its monthly budget this month?
All three checks must pass for the payment to proceed. The system tracks cumulative spending by logging every transaction and summing amounts for the current day and month. If any check fails, the payment is blocked and the agent receives a detailed error message explaining which limit was hit and how much headroom remains.
Setting any limit to 0 disables that particular check (meaning unlimited). For example, if you set max_monthly to 0, there is no monthly cap (but per-transaction and daily limits still apply if set).
L402 (formerly called LSAT) is a protocol that uses HTTP status code 402 ("Payment Required") to gate access to APIs and web content behind Lightning micropayments. When an API endpoint returns a 402 status, it includes a Lightning invoice in the response header. The client pays the invoice and resubmits the request with proof of payment to get the actual data.
AgenticBTC's access_l402_api tool handles this entire flow automatically. You tell Claude "access this L402 API endpoint" and it: (1) makes the initial request, (2) receives the 402 response with the invoice, (3) pays the invoice through your Lightning node, (4) resubmits the request with proof of payment, and (5) returns the API response to you. The entire process takes about 1-2 seconds.
L402 is important because it enables pay-per-use AI services. Instead of monthly subscriptions, AI agents can pay tiny amounts (a few sats) for each individual API call. This is much more efficient for agents that only need occasional access to expensive data sources.
Yes. See Section 5 (METHOD 3: OpenAI Tool Schema) for detailed instructions. AgenticBTC provides its tools in OpenAI-compatible function calling format, which works with GPT-4, GPT-4o, and any framework that supports OpenAI tool definitions (LangChain, CrewAI, AutoGPT, etc.).
The main difference is that GPT-4 does not support MCP natively, so instead of the seamless Claude Desktop integration, you connect via the REST API and use the OpenAI tool schema to let GPT-4 decide when to call AgenticBTC endpoints. The functionality is identical -- the integration method is just different.
Your API key is stored in plain text in the Claude Desktop configuration file on your local machine. This is the standard approach for MCP server configurations. The key is as safe as any other file on your computer.
To improve security:
bash
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json.gitignore).Your Lightning macaroon (if configured) follows the same security model. It is stored locally and never transmitted to AgenticBTC servers.
If a Lightning payment fails (no route found, invoice expired, insufficient balance, etc.), no money is deducted from your balance. Lightning payments are atomic -- they either succeed completely or fail completely. There is no state where money is "stuck" in transit.
The agent will receive a clear error message explaining why the payment failed. Common failure reasons include: no route to the recipient, expired invoice, insufficient outbound liquidity, or fee limit exceeded. You or the agent can then take corrective action (open more channels, request a new invoice, increase the fee limit, etc.).
Failed payments do not count against spending limits. Only successful payments are deducted from daily and monthly budgets.
Yes. AgenticBTC is designed for production use. The platform supports real mainnet Lightning payments, real Bitcoin transactions, and real fiat payment rails. The spending limit system, audit logging, and agent isolation features are specifically designed for production deployments where reliability and security matter.
For production, you should: - Use mainnet (not testnet) - Set conservative spending limits initially and increase as needed - Monitor your agent's transaction logs regularly - Keep your Lightning node well-funded with adequate channel capacity - Have at least 2-3 Lightning channels for routing redundancy - Back up your node's channel.backup file regularly
There are several ways to monitor agent activity:
Dashboard: Log in to https://agenticbtc.app/dashboard to see all wallets, balances, and recent transactions in a visual interface.
Transaction history API: Call GET /api/v1/transactions with your owner API key to get all transactions across all agents.
MCP tools via Claude: Ask Claude "show me the transaction history for Research Agent" or "list all my agent wallets with their balances."
Spending check: Call GET /api/v1/agents/{id}/spending-check?amount_sats=0 to see how much budget an agent has remaining for the day and month.
Yes. Agent A can create a Lightning invoice, and Agent B can pay it. The flow is:
create_lightning_invoice to generate an invoicepay_lightning_invoice with that invoice stringBoth agents' spending limits are respected independently. Agent B's payment is checked against Agent B's policy, regardless of who the recipient is.
AgenticBTC currently supports LND (Lightning Network Daemon), which is the most widely used Lightning implementation. LND is what Voltage, Umbrel, BTCPay Server, Start9, and most Lightning node packages run.
Support for other implementations may be added in the future:
If you are starting fresh, LND is the recommended choice and is fully supported by AgenticBTC.
Because the configuration uses npx with the -y flag, npm will automatically check for and download the latest version of agenticbtc-mcp each time Claude Desktop starts a new session. You do not need to manually update anything.
If you want to force an update immediately, you can clear the npx cache:
npx clear-npx-cache
Then restart Claude Desktop. The next time the MCP server starts, it will download the freshest version.
Yes. Claude Desktop supports multiple MCP servers simultaneously. Your claude_desktop_config.json can contain many entries in the mcpServers object. Each one is independent and loaded separately. For example, you might have AgenticBTC for payments, a filesystem MCP server for file access, and a database MCP server for queries -- all available to Claude at the same time.
Just make sure each server has a unique key name in the config (e.g., "agenticbtc", "filesystem", "database"), and that there are no JSON syntax errors like missing commas between entries.
The owner key is your master admin key. It has unrestricted access to everything on the platform: creating and deleting wallets, viewing all agents, making payments from any wallet, and changing settings. Think of it as the root or admin account.
An agent key is scoped to a single wallet. It can only check that wallet's balance, make payments from that wallet (within spending limits), create invoices, and view that wallet's transaction history. It cannot see other wallets, create or delete wallets, or change spending limits.
Use the owner key for your primary Claude Desktop setup (so you have full control). Use agent keys when you are giving access to an individual AI agent that should only have limited permissions.
AgenticBTC primarily operates in Bitcoin, denominated in satoshis (sats). One Bitcoin equals 100,000,000 satoshis.
Through the universal payment router, you can also: - Specify amounts in USD (which are converted to sats at the current exchange rate) - Send to fiat recipients via Strike, PayPal, and Venmo (the conversion to fiat happens on the payment rail's side) - Specify amounts in BTC (decimal Bitcoin)
The currency parameter in the universal payment endpoint accepts "SATS", "BTC", or "USD".
If you have followed this guide and something is still not working:
node --version)Config file locations:
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/claude/claude_desktop_config.json
Minimal config (no Lightning):
{
"mcpServers": {
"agenticbtc": {
"command": "npx",
"args": ["-y", "agenticbtc-mcp", "start"],
"env": {
"AGENTBTC_API_URL": "https://agenticbtc.io",
"AGENTBTC_API_KEY": "your-api-key-here"
}
}
}
}
Full config (with Lightning):
{
"mcpServers": {
"agenticbtc": {
"command": "npx",
"args": ["-y", "agenticbtc-mcp", "start"],
"env": {
"AGENTBTC_API_URL": "https://agenticbtc.io",
"AGENTBTC_API_KEY": "your-api-key-here",
"AGENTBTC_LND_HOST": "https://your-node.t.voltageapp.io:8080",
"AGENTBTC_LND_MACAROON": "0201036c6e6402..."
}
}
}
}
API base URL: https://agenticbtc.io/api/v1
Dashboard: https://agenticbtc.app/dashboard
Key test commands for Claude: - "list my wallets" - "what's my node status" - "check my channel balance" - "create an invoice for 1000 sats" - "show me my transaction history"
Convert macaroon to hex:
xxd -p admin.macaroon | tr -d '\n'
This guide was last updated on February 27, 2026. For the latest information, visit https://agenticbtc.io.