Skip to main content

​
Cards

Cards are issued to agents and used to make purchases. There are two types:
TypeUse caseBehavior
singleOne-time purchaseAuto-closes after transaction
multiRecurring with same merchantReusable, locks to first merchant

​
Single Cards

Create a card, use it once, it closes automatically. 
curl -X POST https://api.ledger.so/v1/agents/$AGENT_ID/cards \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Book flight LAX to JFK",
    "type": "single",
    "maxAmount": 50000
  }'

{
  "id": "card_abc123",
  "status": "active",
  "type": "single",
  "maxAmount": 50000,
  "last4": "4242"
}

​
Multi Cards

Reusable cards for repeat purchases. Locks to the first merchant it’s used with. 
curl -X POST https://api.ledger.so/v1/agents/$AGENT_ID/cards \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "DoorDash orders",
    "type": "multi",
    "limitPerAuth": 5000,
    "limitPerDay": 20000,
    "limitPerMonth": 100000,
    "ttlDays": 30
  }'
Transactions at merchants other than the first one are declined.

​
Get Card Credentials

Before using a card, request the credentials: 
curl -X POST https://api.ledger.so/v1/cards/$CARD_ID/details \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Order dinner",
    "expectedAmount": 2500
  }'

{
  "pan": "4111111111114242",
  "cvv": "123",
  "expirationMonth": "12",
  "expirationYear": "2027",
  "last4": "4242"
}
Your AI agent uses these credentials to complete checkout (via browser automation, API, etc).

Credential Access Guide

Learn about attestation and security options

​
Spending Limits

Single cards:
FieldDescription
maxAmountMaximum transaction amount (cents)
Multi cards:
FieldDescription
limitPerAuthMax per transaction
limitPerDayMax per 24 hours
limitPerMonthMax per calendar month
maxAuthCountMax number of transactions
ttlDaysCard expires after N days

​
Card Status

StatusDescription
activeReady to use
frozenTemporarily disabled
closedPermanently closed

​
Freeze / Unfreeze

# Freeze
curl -X PATCH https://api.ledger.so/v1/cards/$CARD_ID \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "frozen" }'

# Unfreeze
curl -X PATCH https://api.ledger.so/v1/cards/$CARD_ID \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

​
Close a Card

curl -X DELETE https://api.ledger.so/v1/cards/$CARD_ID \
  -H "Api-Key: $API_KEY"
Closed cards cannot be reopened.

​
Webhooks

EventDescription
card.createdCard issued
card.frozenCard frozen
card.closedCard closed
card.expiredTTL reached