Skip to main content

​
Agents

An Agent is your AI agent that makes purchases. Agents belong to Users and can have multiple Cards.

​
Users vs Agents

Users are the funding source. They complete KYC and deposit funds. Agents are the spenders. They issue cards and make purchases against the user’s balance. Example setups:
ScenarioUsersAgents
Your company funds all AI spending1 user (your company)Multiple agents (one per workflow)
Your customers fund their own AI1 user per customerAgents act on each customer’s behalf
User (funding source)
    └── Agent (AI agent)
          └── Cards

​
Create an Agent

curl -X POST https://api.ledger.so/v1/agents \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc123",
    "name": "shopping-agent",
    "spendingLimit": 50000,
    "spendingLimitFrequency": "perMonth"
  }'

{
  "id": "agent_xyz789",
  "userId": "user_abc123",
  "name": "shopping-agent",
  "status": "active",
  "spendingLimit": 50000,
  "spendingLimitFrequency": "perMonth",
  "currentSpend": 0
}

​
Spending Limits

Limit total spending across all of an agent’s cards:
FieldDescription
spendingLimitMax spend in cents
spendingLimitFrequencyReset period
onLimitExceededWhat happens when limit is hit
Frequencies: perTransaction, per24HourPeriod, perWeek, perMonth, perYear, allTime When limit exceeded:
ValueBehavior
suspendFreeze agent and all its cards
notifySend webhook, allow transactions
noneJust track

​
Status

StatusDescription
activeCan create cards and transact
suspendedAll cards frozen
Suspending an agent freezes all its cards. Reactivating unfreezes them.

​
Check Spending

curl https://api.ledger.so/v1/agents/$AGENT_ID/policy \
  -H "Api-Key: $API_KEY"

{
  "agentId": "agent_xyz789",
  "spendingLimit": 50000,
  "spendingLimitFrequency": "perMonth",
  "currentSpend": 25000,
  "remaining": 25000
}

​
Webhooks

EventDescription
agent.createdAgent created
agent.suspendedAgent suspended
agent.limit_exceededLimit hit