Skip to main content

​
API Reference

The LedgerOS API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

​
Base URL

https://sandbox.ledger.so

​
Authentication

All endpoints require authentication via the Api-Key header: 
curl https://api.ledger.so/v1/agents \
  -H "Api-Key: lk_test_your_api_key"
See Authentication for more details.

​
Request Format

  • All request bodies must be JSON-encoded
  • Include Content-Type: application/json header for POST/PATCH requests

​
Response Format

All responses are JSON-encoded with the following structure: Success: 
{
  "id": "agent_xyz789",
  "name": "checkout-bot",
  "status": "active"
}
Error: 
{
  "error": "Invalid API key"
}
Paginated: 
{
  "data": [...],
  "cursor": "abc123",
  "hasMore": true
}

​
HTTP Status Codes

CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Access denied
404Not Found - Resource doesn’t exist
429Too Many Requests - Rate limited
500Server Error

​
Pagination

List endpoints support cursor-based pagination:
ParameterTypeDefaultDescription
limitnumber20Items per page (max 100)
cursorstring-Cursor from previous response
Example: 
# First page
curl "https://api.ledger.so/v1/agents?limit=10" \
  -H "Api-Key: lk_test_your_api_key"

# Next page
curl "https://api.ledger.so/v1/agents?limit=10&cursor=abc123" \
  -H "Api-Key: lk_test_your_api_key"

​
Idempotency

For POST requests, you can include an Idempotency-Key header to safely retry requests: 
curl -X POST https://api.ledger.so/v1/agents \
  -H "Api-Key: lk_test_your_api_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user_abc", "name": "my-agent"}'

​
Resources

Users

Onboard users and manage balances

Agents

Create and manage autonomous agents

Cards

Issue and manage virtual cards

Webhooks

Real-time event notifications