# AgentLedger

> AgentLedger is the financial control layer between AI agents and payment methods. Set per-agent budgets, require human or AI approvals, keep a full audit trail, and release card details only when the rules are met. Open-source (AGPL-3.0), single Go binary, zero runtime dependencies.

## Docs

- [Full Documentation](https://agentledger.tech/llms-full.txt): Complete API reference, MCP tool definitions, installation, authentication, ledger semantics, and webhook setup in a single Markdown file
- [Documentation (HTML)](https://agentledger.tech/docs.html): Same content in the browser
- [GitHub Repository](https://github.com/agentledgerhq/agentledger): Source code, releases, and issue tracker

## Key Concepts

- [Installation](https://agentledger.tech/docs.html#installation): Download a single binary for macOS, Linux, or Windows — no runtime dependencies
- [Quick Start](https://agentledger.tech/docs.html#quick-start): init → vault add → budget set → serve
- [Authentication](https://agentledger.tech/docs.html#authentication): Two-token model — user token (alu_) for spending agents, supervisor token (als_) for approval agents
- [Supervisor Tiers](https://agentledger.tech/docs.html#authentication): Tier 1 approve/deny, Tier 2 adds budget management, Tier 3 adds vault replacement
- [Ledger Semantics](https://agentledger.tech/docs.html#ledger-semantics): Authorize-is-final model — budget deducted atomically, card released, spend is permanent
- [MCP Servers Setup](https://agentledger.tech/docs.html#mcp-setup): Two MCP servers (user + supervisor) for Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients
- [Running on a VPS](https://agentledger.tech/docs.html#vps): Reverse proxy with TLS required — Caddy/nginx setup, firewall, AGENTLEDGER_HOST for bind address

## REST API Endpoints

- [POST /authorize](https://agentledger.tech/docs.html#post-authorize): Request payment authorization — returns card details (auto) or enters pending state (manual)
- [GET /status/{tx_id}](https://agentledger.tech/docs.html#get-status): Poll transaction status and retrieve card details after approval
- [GET /budget/{agent}](https://agentledger.tech/docs.html#get-budget): Check remaining budget for an agent
- [GET /transactions/{agent}](https://agentledger.tech/docs.html#get-transactions): Full transaction history for an agent
- [GET /pending](https://agentledger.tech/docs.html#get-pending): List transactions awaiting approval (supervisor)
- [POST /approve](https://agentledger.tech/docs.html#post-approve): Approve a pending transaction (supervisor)
- [POST /deny](https://agentledger.tech/docs.html#post-deny): Deny a pending transaction, refund budget (supervisor)
- [POST /budget/{agent}](https://agentledger.tech/docs.html#post-budget): Create or update agent budget (supervisor, Tier 2+)
- [POST /credit](https://agentledger.tech/docs.html#post-credit): Restore consumed budget after refund (supervisor, Tier 2+)
- [POST /vault/update](https://agentledger.tech/docs.html#post-vault-update): Replace the vaulted card (supervisor, Tier 3)
- [GET /health](https://agentledger.tech/docs.html#get-health): Health check, no auth required

## MCP Tools

- [request_payment](https://agentledger.tech/docs.html#mcp-user): Request payment (user agent)
- [check_budget](https://agentledger.tech/docs.html#mcp-user): Check available budget (user agent)
- [get_status](https://agentledger.tech/docs.html#mcp-user): Poll transaction status (user agent)
- [get_transactions](https://agentledger.tech/docs.html#mcp-user): Transaction history (user or supervisor)
- [list_pending_transactions](https://agentledger.tech/docs.html#mcp-supervisor): List pending approvals (supervisor, Tier 1+)
- [approve_transaction](https://agentledger.tech/docs.html#mcp-supervisor): Approve transaction (supervisor, Tier 1+)
- [deny_transaction](https://agentledger.tech/docs.html#mcp-supervisor): Deny transaction (supervisor, Tier 1+)
- [set_budget](https://agentledger.tech/docs.html#mcp-supervisor): Set agent budget (supervisor, Tier 2+)
- [credit_budget](https://agentledger.tech/docs.html#mcp-supervisor): Restore budget (supervisor, Tier 2+)
- [update_vault](https://agentledger.tech/docs.html#mcp-supervisor): Replace vaulted card (supervisor, Tier 3)

## Webhook

- [Transaction Notifications](https://agentledger.tech/docs.html#webhook): HTTP POST on every authorize outcome — events: transaction.spent, transaction.pending, transaction.denied. HMAC-SHA256 signed.