Skip to main content

​
System Overview

What You’ll LearnThis page explains:
  • How LedgerOS architecture separates users, agents, and cards
  • The funding and spending flow
  • Key concepts: attestation, intents, and velocity limits
  • How MCP integration works for AI agents
Time to read: 10 minutes
LedgerOS provides virtual cards designed specifically for AI agents. It creates a secure layer between user funds and agent spending, with built-in controls, audit trails, and anomaly detection.

​
Architecture Overview

​
Hierarchy

LevelDescriptionExample
OrganizationYour company account. Holds API keys.Acme Corp
UserPerson/entity who funds spending. Must complete KYC.John Doe (customer)
AgentLogical identity that spends. Your AI bot or workflow.checkout-bot
CardVirtual card issued to an agent.Single-use Amazon card

​
Main Workflows

LedgerOS is built around three main workflows:

​
1. User Onboarding & Funding

Before any spending can happen, a user must be verified and funded:

​
2. Agent & Card Creation

Once a user is verified and funded, register agents and issue cards:

​
3. Spending Flow

When your AI agent needs to make a purchase:

​
Core Concepts

​
Users vs Agents

Important DistinctionA User is NOT you (the developer). A User is the funding source—the person or entity whose money backs the cards.An Agent is your AI code that spends the money.
ConceptWho/WhatResponsibilities
UserHuman or companyKYC verification, deposit funds, set spending limits
AgentYour AI botRequest cards, declare intents, make purchases

​
Card Types

TypeBehaviorUse Case
Single-useAuto-closes after one transactionOne-time purchases
Multi-useReusable with velocity limitsRecurring purchases

​
Velocity Limits

Multi-use cards support spending controls to limit agent behavior: 
Card created → Set limits: $50/transaction, $200/day, $1000/month
            → Transactions within limits → Approved
            → Limits exceeded → Declined
Combined with attestation and the risk engine’s merchant drift detection, these controls provide comprehensive safety guardrails.

​
Security Attestation

Before accessing card credentials, agents must attest what they intend to do:

​
Spending Intents

Agents must declare intent before accessing card credentials: 
1. Create card
2. ledger_card({ action: "details" }) → Error: "Declare intent first"
3. ledger_intent({ action: "declare", summary: "Buy headphones", amount: 9999 })
4. ledger_card({ action: "details" }) → Returns PAN/CVV
5. Transaction completes → Intent marked "matched" or "mismatched"
Intent states: pending → revealed → matched | expired | mismatched

​
Integration Points

​
REST API

Direct HTTP calls for full control: 
curl -X POST https://api.ledger.so/v1/agents/agent_xxx/cards \
  -H "Api-Key: lk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "Buy office supplies", "type": "single", "maxAmount": 10000}'

​
MCP Server

For AI agents using Claude, Cursor, or other MCP clients: 
{
  "mcpServers": {
    "ledgeros": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.ledger.so/api/mcp"],
      "env": {
        "LEDGER_API_KEY": "lk_live_xxx"
      }
    }
  }
}

​
Webhooks

Real-time notifications for all events:
  • transaction.created - New transaction
  • transaction.settled - Transaction finalized
  • card.frozen - Card frozen (manual or limit exceeded)
  • user.approved - KYC completed
  • deposit.completed - Funds available

​
Common Deployment Patterns

Your company is the User. You fund one account, create multiple agents for different workflows.
Organization: Acme Corp
  └── User: Acme Corp (your company, $10k deposited)
        ├── Agent: checkout-bot (e-commerce)
        ├── Agent: travel-bot (booking)
        └── Agent: procurement-bot (supplies)
Each of your customers is a User. They fund their own agents.
Organization: Your Platform
  ├── User: Customer A ($500 deposited)
  │     └── Agent: customer-a-assistant
  ├── User: Customer B ($1000 deposited)
  │     └── Agent: customer-b-assistant
  └── User: Customer C ($200 deposited)
        └── Agent: customer-c-assistant
Some spending is company-funded, some is customer-funded.
Organization: Your Platform
  ├── User: Your Company (internal ops)
  │     └── Agent: internal-procurement
  └── User: Customer A (customer-funded)
        └── Agent: customer-a-assistant

​
Next Steps

Quick Start

Create your first card in 5 minutes

Payment Flow

Detailed walkthrough of the complete payment flow

MCP Integration

Connect your AI agent via MCP

Best Practices

Security guidelines and recommendations