← Back to Dashboard

AgentBTC REST API Reference

Universal HTTP API for any AI agent, automation platform, or custom integration
Base URL: http://localhost:8000/api/v1
Auth: X-API-Key header

Authentication

Every request requires an X-API-Key header:

curl -H "X-API-Key: your-key-here" http://localhost:8000/api/v1/me

Owner key — full admin access to all endpoints and all wallets.
Agent key — scoped to the agent's own wallet, bound by spending policies.

See the Auth Guide for details on key types and setup.

Endpoints

Identity

`GET /api/v1/me`

Get info about the authenticated key.

Agent key response:

{
  "agent_id": "5300230a",
  "name": "Shopping Bot",
  "enabled": true,
  "spending_policy": {
    "max_per_tx": 1100,
    "max_daily": 3000,
    "max_monthly": 20000
  }
}

Owner key response:

{
  "is_owner": true,
  "message": "Authenticated as owner"
}

Wallet

`GET /api/v1/balance`

Get balance for the authenticated agent.

curl -H "X-API-Key: agent_5300230a_xxx" http://localhost:8000/api/v1/balance

{
  "agent_id": "5300230a",
  "name": "Shopping Bot",
  "balance_sats": 3990,
  "enabled": true
}

`GET /api/v1/agents/{id}/spending-check?amount_sats=500`

Check if a payment amount is within spending policy limits.

{
  "allowed": true,
  "remaining_daily": 2500,
  "remaining_monthly": 19500
}

Or if blocked:

{
  "allowed": false,
  "reason": "Exceeds per-transaction limit (2000 > 1100 sats)"
}

Invoices & Payments

`POST /api/v1/invoices`

Create a Lightning invoice to receive payment.

Body:

{
  "amount_sats": 1000,
  "description": "API access fee"
}

Response:

{
  "success": true,
  "invoice": "lnbc10u1p...",
  "payment_hash": "abc123...",
  "amount_sats": 1000,
  "description": "API access fee [Shopping Bot]",
  "expires_in": "1 hour"
}

`POST /api/v1/payments`

Pay a Lightning invoice. Spending policy enforced for agent keys.

Body:

{
  "invoice": "lnbc10u1p...",
  "fee_limit_sats": 100
}

Success:

{
  "success": true,
  "payment_hash": "def456...",
  "amount_sats": 1000,
  "fee_sats": 0,
  "status": "SUCCEEDED"
}

Blocked by policy:

HTTP 403: "Payment blocked: Exceeds daily limit (3500 > 3000 sats, already spent 2500 today)"

`POST /api/v1/decode`

Decode a BOLT11 invoice before paying.

Body:

{
  "invoice": "lnbc10u1p..."
}

Response:

{
  "success": true,
  "amount_sats": 1000,
  "destination": "03abaf...",
  "description": "AgentBTC payment",
  "payment_hash": "abc123...",
  "is_expired": false
}

Transaction History

`GET /api/v1/transactions?limit=20`

Get payment history. Agent key: own transactions only. Owner key: all transactions.

{
  "success": true,
  "transactions": [
    {
      "id": "fbd55e98",
      "agent_id": "5300230a",
      "type": "payment",
      "amount_sats": 500,
      "destination": "03abaf...",
      "memo": "API purchase",
      "status": "completed",
      "created_at": "2026-02-19T04:21:57"
    }
  ],
  "count": 1
}

`POST /api/v1/agents/{id}/transactions`

Record a transaction (used by MCP server, also available to agents logging their own).

Body:

{
  "type": "payment",
  "amount_sats": 500,
  "destination": "03abaf...",
  "memo": "API purchase",
  "status": "completed"
}

Lightning Node

`GET /api/v1/node`

Get Lightning node status.

{
  "alias": "agentbtc-testnet-2",
  "pubkey": "03abaf...",
  "num_active_channels": 1,
  "num_peers": 3,
  "synced_to_chain": true,
  "version": "0.20.0-beta"
}

`GET /api/v1/channels`

Get channel balances and liquidity.

{
  "success": true,
  "outbound_sats": 9056,
  "inbound_sats": 10000,
  "num_channels": 1,
  "channels": [
    {
      "channel_id": "532335...",
      "capacity_sats": 20000,
      "local_balance_sats": 9056,
      "remote_balance_sats": 10000,
      "active": true
    }
  ]
}

Admin (Owner Key Only)

`GET /api/v1/agents`

List all agent wallets.

`POST /api/v1/agents`

Create a new agent wallet.

Body:

{
  "name": "Shopping Bot",
  "description": "AI agent for API purchases"
}

Response:

{
  "id": "5300230a",
  "name": "Shopping Bot",
  "api_key": "agent_5300230a_xxx...",
  "message": "Created wallet 'Shopping Bot'"
}

⚠️ Save the api_key — it's shown once and stored as a hash.

`DELETE /api/v1/agents/{id}`

Delete an agent wallet.

Tool Discovery

`GET /api/v1/openai-tools`

Returns OpenAI-compatible function/tool definitions. Import these into any OpenAI-style agent (GPTs, Assistants, LangChain, CrewAI).

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "agentbtc_pay_invoice",
        "description": "Pay a Lightning Network invoice...",
        "parameters": { ... }
      }
    }
  ],
  "base_url": "http://localhost:8000/api/v1",
  "auth": "X-API-Key header with agent API key"
}

Error Responses

HTTP Code	Meaning
400	Bad request (missing required field)
401	Invalid or missing API key
403	Access denied (agent scope violation or spending policy block)
404	Resource not found
502	Lightning node error
503	Lightning node not configured

All errors return JSON:

{
  "detail": "Human-readable error message"
}

Integration Examples

Python (requests)

import requests

API_KEY = "agent_5300230a_xxx"
BASE = "http://localhost:8000/api/v1"
headers = {"X-API-Key": API_KEY}

# Check balance
r = requests.get(f"{BASE}/balance", headers=headers)
print(r.json())

# Create invoice
r = requests.post(f"{BASE}/invoices", headers=headers, 
    json={"amount_sats": 1000, "description": "test"})
print(r.json()["invoice"])

# Pay invoice
r = requests.post(f"{BASE}/payments", headers=headers,
    json={"invoice": "lnbc..."})
print(r.json())

JavaScript (fetch)

const API_KEY = "agent_5300230a_xxx";
const BASE = "http://localhost:8000/api/v1";

// Check balance
const res = await fetch(`${BASE}/balance`, {
  headers: { "X-API-Key": API_KEY }
});
console.log(await res.json());

// Pay invoice  
const pay = await fetch(`${BASE}/payments`, {
  method: "POST",
  headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ invoice: "lnbc..." })
});
console.log(await pay.json());

curl

# Check who I am
curl -H "X-API-Key: agent_5300230a_xxx" http://localhost:8000/api/v1/me

# Create invoice
curl -X POST -H "X-API-Key: agent_5300230a_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount_sats": 1000}' \
  http://localhost:8000/api/v1/invoices

# Pay invoice
curl -X POST -H "X-API-Key: agent_5300230a_xxx" \
  -H "Content-Type: application/json" \
  -d '{"invoice": "lnbc..."}' \
  http://localhost:8000/api/v1/payments