AgentBTC Authentication & Access Control Guide

How to assign API keys, enforce spending limits, and connect AI agents to Bitcoin wallets

Overview

AgentBTC uses a two-tier authentication model:

This separation ensures AI agents can only spend what you allow, from the wallet you assign them.

Understanding the Keys

Owner API Key

This is your master key. It has full admin access to the entire AgentBTC platform.

• Where it's set: Environment variable OWNER_API_KEY (or defaults to agentbtc-owner-test-key-2026 in development)
• Who uses it: You (via the dashboard), Claude Desktop (for admin tasks), or a trusted management agent
• Security: Treat this like a root password. Don't give it to untrusted agents.

Agent API Key

Every wallet gets its own unique API key when created. It's scoped to that wallet only.

• Format: agent_{wallet_id}_{random_token} (e.g., agent_5300230a_EAZdGb6l_YsB-2PP6...)
• Generated: Automatically when you create a wallet (via dashboard or MCP tool)
• Storage: The key is shown ONCE at creation. The platform only stores a SHA-256 hash.
• Scope: Can only access the wallet it belongs to

⚠️ Save the agent API key when you create the wallet! It cannot be recovered later.

Setting Up an AI Agent

Step 1: Create a Wallet for the Agent

Using Claude Desktop (with owner key):

"Create an agent wallet called Shopping Bot"

Or via the dashboard UI → Create Agent button.

You'll receive:

{
  "agent_id": "5300230a",
  "api_key": "agent_5300230a_EAZdGb6l_YsB-2PP6Bc9xcyEhrqN9H3KdSZw_DCoFck",
  "message": "Created wallet 'Shopping Bot'"
}

Save that api_key — you'll need it for the agent's config.

Step 2: Set Spending Limits

Currently set via the database (dashboard UI coming soon):

INSERT INTO spending_policies (id, agent_id, max_per_tx, max_daily, max_monthly, allowed_destinations, enabled)
VALUES ('unique-id', '5300230a', 1100, 3000, 20000, '[]', 1);

Set any limit to 0 to disable that check (unlimited).

Step 3: Configure the Agent's MCP Connection

Create an MCP config using the agent's API key (not the owner key):

{
  "mcpServers": {
    "agentbtc": {
      "command": "node",
      "args": ["/path/to/agentbtc/mcp_server/index.js"],
      "env": {
        "AGENTBTC_API_URL": "http://localhost:8000",
        "AGENTBTC_API_KEY": "agent_5300230a_EAZdGb6l_YsB-2PP6Bc9xcyEhrqN9H3KdSZw_DCoFck",
        "AGENTBTC_LND_HOST": "https://your-node:8080",
        "AGENTBTC_LND_MACAROON": "hex-macaroon"
      }
    }
  }
}

With this config, the agent: - ✅ Can check its own balance - ✅ Can create invoices to receive payments - ✅ Can make payments (within spending limits) - ✅ Can view transaction history - ❌ Cannot see other wallets - ❌ Cannot create or delete wallets - ❌ Cannot exceed spending limits - ❌ Cannot operate if disabled by owner

Agent Roles

🛒 Spending Agent (Agent API Key)

An AI that needs to make payments — buying API access, paying for services, tipping.

Config: Agent API key + Lightning node credentials Limits: Set per-tx, daily, and monthly caps Example: Shopping Bot, API Consumer, Content Purchaser

AGENTBTC_API_KEY=agent_5300230a_xxx  ← scoped to Shopping Bot wallet

🔧 Management Agent (Owner API Key)

A trusted AI that manages the platform — creating wallets for other agents, monitoring balances, adjusting settings.

Config: Owner API key + Lightning node credentials Limits: None (full access) Example: Your primary Claude Desktop session, an admin bot

AGENTBTC_API_KEY=agentbtc-owner-test-key-2026  ← full admin access

📊 Read-Only Agent (Agent API Key, no LND)

An AI that monitors wallet balances and transactions but can't make payments.

Config: Agent API key only (no LND credentials) Limits: Payment tools return "LND not configured" errors Example: Dashboard monitor, reporting bot, analytics agent

AGENTBTC_API_KEY=agent_xxx  ← can read balance
(no AGENTBTC_LND_HOST)      ← can't make payments

Connecting Different AI Platforms

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agentbtc": {
      "command": "node",
      "args": ["/path/to/agentbtc/mcp_server/index.js"],
      "env": {
        "AGENTBTC_API_URL": "http://localhost:8000",
        "AGENTBTC_API_KEY": "your-key-here",
        "AGENTBTC_LND_HOST": "https://your-node:8080",
        "AGENTBTC_LND_MACAROON": "hex-macaroon"
      }
    }
  }
}

Restart Claude Desktop after saving. The 13 AgentBTC tools appear automatically.

OpenClaw (via mcporter)

OpenClaw agents use the mcporter skill to access MCP servers. Add to config/mcporter.json in your workspace:

{
  "mcpServers": {
    "agentbtc": {
      "transport": "stdio",
      "command": "node",
      "args": ["/path/to/agentbtc/mcp_server/index.js"],
      "env": {
        "AGENTBTC_API_URL": "http://localhost:8000",
        "AGENTBTC_API_KEY": "your-key-here",
        "AGENTBTC_LND_HOST": "https://your-node:8080",
        "AGENTBTC_LND_MACAROON": "hex-macaroon"
      }
    }
  }
}

The OpenClaw agent calls tools via mcporter:

mcporter call agentbtc.check_channel_balance
mcporter call agentbtc.get_agent_balance agent_id="Shopping Bot"
mcporter call agentbtc.pay_lightning_invoice invoice="lnbc..." agent="Shopping Bot"

Note: For a management agent (owner-level access), the OpenClaw agent needs the owner API key in its mcporter config. For a spending agent, use the agent's own API key.

Other MCP-Compatible Platforms

Any platform that supports the Model Context Protocol (Cursor, Windsurf, Cline, etc.) can connect using the same config format. The MCP server is platform-agnostic — it speaks standard MCP over stdio.

How Spending Enforcement Works

When an agent makes a payment, this happens:

Agent requests payment (500 sats)
    ↓
MCP Server identifies agent (from API key or agent parameter)
    ↓
Decode invoice to get exact amount
    ↓
Check spending policy:
  ├── Is agent enabled? → No → BLOCKED
  ├── Amount > per-tx limit? → Yes → BLOCKED
  ├── Today's total + amount > daily limit? → Yes → BLOCKED
  ├── This month's total + amount > monthly limit? → Yes → BLOCKED
  └── All checks pass → ALLOWED
    ↓
Pay via Lightning Network (direct LND connection)
    ↓
Log transaction against agent's wallet
    ↓
Return result to agent

What Gets Blocked

Security Model

Zero-Trust Architecture (BYON)

• Lightning credentials never leave your machine. They're in the MCP server's environment variables, not stored on the AgentBTC platform.
• Agent API keys are hashed. The platform stores SHA-256 hashes, not plaintext keys.
• Scope isolation. Agent keys can only access their own wallet data.
• Fail-closed on auth. Invalid or missing keys get HTTP 401/403.
• Fail-open on policy check errors. If the policy check API is unreachable, payments are allowed (to avoid locking out agents during outages). This is configurable.

Best Practices

1. Use agent keys for agents, owner key for admin only. Don't give the owner key to spending agents.
2. Set conservative limits initially. You can always increase them. Start with small per-tx and daily limits.
3. Save agent keys at creation time. They're shown once and stored as hashes.
4. Disable agents you're not using. Flipping enabled to false blocks all operations immediately.
5. Review transaction logs regularly. The /api/v1/agents/{id}/transactions endpoint shows all recorded payments.
6. Use separate wallets for separate purposes. Don't reuse a wallet across unrelated agents.

Quick Reference

Coming Soon

• Dashboard UI for spending policies — set limits without SQL
• API key rotation — generate new key, revoke old one
• Webhook notifications — alert when spending limits are approaching
• Allowed destinations — restrict which Lightning nodes/addresses an agent can pay
• Multi-owner support — multiple admins with separate owner keys