Quick Start
Create your first transfer in 5 minutes.
Quick Start
This guide walks you through the complete flow: sign up, create a ledger, add accounts, and execute your first transfer.
Create an Account
curl -X POST http://localhost:8080/v1/auth/signup \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "your-secure-password",
"name": "Your Name"
}'The response includes your JWT token and a default workspace:
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"user": { "id": "01969...", "email": "[email protected]", "name": "Your Name" },
"workspace": { "id": "01969...", "name": "Your Name's Workspace" }
}Save the token and workspace.id — you'll need them for all subsequent requests.
Create a Ledger
A ledger is an isolated financial environment. Think of it as a separate chart of accounts.
curl -X POST http://localhost:8080/v1/ledgers \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Beetles-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{ "name": "USD Operations" }'{
"id": "01969abc-...",
"name": "USD Operations"
}Every ledger automatically gets a @world funding account with unlimited balance. This is used to inject money into the system.
Create Accounts
Create two accounts in your ledger:
curl -X POST http://localhost:8080/v1/ledgers/YOUR_LEDGER_ID/accounts \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Beetles-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{ "name": "Revenue", "code": 1001 }'curl -X POST http://localhost:8080/v1/ledgers/YOUR_LEDGER_ID/accounts \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Beetles-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{ "name": "Expenses", "code": 2001 }'Fund an Account
Transfer from @world to your Revenue account:
curl -X POST http://localhost:8080/v1/transfers \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Beetles-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"ledger_id": "YOUR_LEDGER_ID",
"debit_account_id": "WORLD_ACCOUNT_ID",
"credit_account_id": "REVENUE_ACCOUNT_ID",
"amount": 100000,
"code": 1
}'Amounts are in the smallest unit (cents). 100000 = $1,000.00
Execute a Transfer
Move money between your accounts:
curl -X POST http://localhost:8080/v1/transfers \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Beetles-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"ledger_id": "YOUR_LEDGER_ID",
"debit_account_id": "REVENUE_ACCOUNT_ID",
"credit_account_id": "EXPENSES_ACCOUNT_ID",
"amount": 25000,
"code": 1
}'{
"id": "01969def-...",
"status": "posted",
"amount": 25000
}That's it! You've created your first financial ledger with proper double-entry bookkeeping.
What's Next?
- Learn about Authentication for API key access
- Understand Core Concepts like two-phase transfers
- Explore Settlement for receivables management
- Try Multi-Currency Exchange for cross-ledger currency conversion