AgentLedger

The financial control layer between AI agents and payment methods.

AgentLedger is a standalone service that securely vaults a payment card and gates access to it behind per-agent budgets, dual-token authorization, and an optional human-in-the-loop approval flow.

It is distributed as a single, zero-dependency Go binary and uses an embedded SQLite database. Included is an MCP (Model Context Protocol) server to seamlessly drop into Claude Desktop, Cursor, and other agent platforms.

---

~11 MB	<50 ms	<1 ms	~10 MB	0
on disk	cold start	per request	RAM at runtime	runtime deps

Full ledger, vault, approval workflow, and API surface in under 2,500 lines of Go. Single static binary — no Python, no Node, no Docker.

---

Core Features

• No runtime dependencies: Static Go binary with embedded SQLite — no C compiler, no system libraries.
• Strict Budget Controls: Cumulative or monthly caps mapped to free-form agent_id strings.
• Two-Tier Authentication: Distinct tokens for spending agents (alu_) and supervisor agents (als_).
• Human-in-the-loop (Optional): Require manual approval before an agent sees card details.
• Secure Vaulting: In-memory AES-256-GCM encryption with memguard enclave protection.
• MCP Native: Official servers included to plug directly into LLM clients.

Installation

1. Download Binary

Get the latest binary for your platform from Releases.

# macOS/Linux
mv agentledger-linux-amd64 agentledger
chmod +x agentledger
./agentledger --help

# Windows (PowerShell)
Rename-Item agentledger-windows-amd64.exe agentledger.exe
.\agentledger.exe --help

2. Build from Source

Requires Go 1.25+. No C compiler needed.

git clone https://github.com/agentledgerhq/agentledger
cd agentledger/apps/local
go build -o agentledger ./cmd/agentledger

Quick Start

# 1. Initialize DB and generate tokens (sets up .env)
agentledger init

# 2. Vault your credit card
agentledger vault add
# (No real card? Use --test-card to load a Stripe test card instead)
# agentledger vault add --test-card

# 3. Provision an agent's budget (e.g., $50.00 limit — amounts are in cents)
agentledger budget set researcher-agent 5000

# 4. Start the REST API
agentledger serve

By default, the server listens on http://127.0.0.1:9119.

Setting up the MCP Server

AgentLedger includes an MCP (Model Context Protocol) integration exposing REST API endpoints as LLM tools.

Configure your MCP client (e.g., claude_desktop_config.json) with the two servers:

{
  "mcpServers": {
    "agentledger-user": {
      "command": "npx",
      "args": ["agentledger-mcp", "user"],
      "env": {
        "AGENTLEDGER_USER_TOKEN": "alu_your-token"
      }
    },
    "agentledger-supervisor": {
      "command": "npx",
      "args": ["agentledger-mcp", "supervisor"],
      "env": {
        "AGENTLEDGER_SUPERVISOR_TOKEN": "als_your-token"
      }
    }
  }
}

The supervisor server exposes different tools depending on the tier set at agentledger init: tier 1 (default) handles transaction approvals; tier 2 adds budget and credit management; tier 3 adds vault updates.

Building from source instead of npx

cd apps/mcp && npm install && npm run build

Then replace "command": "npx" / "args": ["agentledger-mcp", ...] with:

"command": "node",
"args": ["/absolute/path/to/apps/mcp/dist/index.js", "user"]

REST API & Webhooks

When not using MCP, you can manually interact with the API:

# Request payment (Agent)
curl -X POST http://127.0.0.1:9119/authorize \
  -H "Authorization: Bearer alu_..." \
  -H "Content-Type: application/json" \
  -d '{"amount": 2500, "merchant": "AWS", "purpose": "EC2", "requesting_agent_id": "researcher-agent"}'

To receive real-time updates on approvals and denials, set TRANSACTION_CALLBACK_URL in your .env. AgentLedger will emit HMAC-SHA256 signed webhooks for every transaction outcome.

Documentation

Full technical documentation, ledger semantics, and configuration guides are available at agentledger.tech.

For LLMs, point them directly to our single-file documentation dump:

https://agentledger.tech/llms-full.txt

License

AGPL-3.0 License. See LICENSE for details.