Skip to main content

​
Quick Start

This guide will walk you through creating your first virtual card with LedgerOS.

​
Prerequisites

  • A LedgerOS account (sign up here)
  • An API key from your dashboard

​
Step 1: Get Your API Key

1

Log into Dashboard

Go to app.ledger.so and sign in.
2

Create API Key

Navigate to Settings > API Keys and click Create Key.
3

Copy Your Key

Copy your API key. It starts with lk_test_ for sandbox or lk_live_ for production.
Keep your API key secure. Never expose it in client-side code or commit it to version control.

​
Step 2: Create a User

Users fund card spending. Start by onboarding a user: 
curl -X POST https://api.ledger.so/v1/applications/user/initiate \
  -H "Api-Key: lk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  }'

{
  "id": "user_abc123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "applicationStatus": "pending",
  "applicationCompletionLink": "https://kyc.ledger.so/verify/xyz789"
}
The user must complete KYC via the applicationCompletionLink before they can use cards.

​
Step 3: Create an Agent

Once the user is approved, create an agent: 
curl -X POST https://api.ledger.so/v1/agents \
  -H "Api-Key: lk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc123",
    "name": "checkout-bot",
    "description": "Handles online purchases",
    "spendingLimit": 50000,
    "spendingLimitFrequency": "perMonth"
  }'

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

​
Step 4: Issue a Card

Now create a virtual card for the agent: 
curl -X POST https://api.ledger.so/v1/agents/agent_xyz789/cards \
  -H "Api-Key: lk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Purchase office supplies from Amazon",
    "type": "single",
    "maxAmount": 10000
  }'

{
  "id": "card_def456",
  "agentId": "agent_xyz789",
  "userId": "user_abc123",
  "status": "active",
  "last4": "4242",
  "purpose": "Purchase office supplies from Amazon",
  "type": "single",
  "maxAmount": 10000
}

​
Step 5: Get Card Details

To make a purchase, retrieve the card credentials: 
curl -X POST https://api.ledger.so/v1/cards/card_def456/details \
  -H "Api-Key: lk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Purchase office supplies from Amazon",
    "expectedAmount": 5000,
    "merchantText": "Amazon"
  }'

{
  "accessEventId": "evt_123",
  "exposureMode": "extensionOnly",
  "detailsToken": "tok_xyz789...",
  "tokenExpiresAt": 1703520120000,
  "last4": "4242"
}
The response depends on the card’s credentialExposure setting. See Credential Access for details.

​
Next Steps

Authentication

Learn about API authentication

Card Types

Understand single vs multi cards

Webhooks

Set up real-time notifications

API Reference

Explore all endpoints