Querying Ledgers
List all customer ledgers, get individual ledger details, and inspect recent activity.
Use these endpoints to list all customer ledgers for your account, get detail for a specific customer, and paginate through recent activity.
List Customer Ledgers
GET https://balance-api.pacspace.io/api/v1/balance/customers
Headers
| Header | Required | Description |
|---|---|---|
X-Api-Key | Yes | Your PacSpace API key |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
page | number | No | 1 | Page number (1-indexed) |
limit | number | No | 25 | Results per page (1-100) |
search | string | No | — | Filter by customer ID (case-insensitive) |
Response
json
{
"success": true,
"data": {
"customers": [
{
"customerId": "cust_001",
"ledgerIdentifier": "0xA1b2C3d4E5f6789012345678901234567890Ef34",
"totalDeltas": 42,
"firstDeltaAt": "2026-01-15T10:30:00.000Z",
"lastDeltaAt": "2026-02-14T14:22:00.000Z"
},
{
"customerId": "cust_002",
"ledgerIdentifier": "0xC3d4E5f67890123456789012345678901234Abcd",
"totalDeltas": 128,
"firstDeltaAt": "2026-01-20T08:15:00.000Z",
"lastDeltaAt": "2026-02-14T16:45:00.000Z"
}
],
"pagination": {
"total": 47,
"page": 1,
"limit": 25,
"totalPages": 2
}
}
}
Examples
List all customers:
bash
curl https://balance-api.pacspace.io/api/v1/balance/customers \
-H "X-Api-Key: YOUR_API_KEY"
Search by customer ID:
bash
curl "https://balance-api.pacspace.io/api/v1/balance/customers?search=partner_" \
-H "X-Api-Key: YOUR_API_KEY"
SDK:
typescript
const { customers, pagination } = await pac.balance.customers({
search: 'partner_',
limit: 10,
});
Get Customer Ledger Detail
GET https://balance-api.pacspace.io/api/v1/balance/customers/:customerId
Headers
| Header | Required | Description |
|---|---|---|
X-Api-Key | Yes | Your PacSpace API key |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customerId | string | Yes | The customer ID to look up |
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
deltaPage | number | No | 1 | Page of recent activity |
deltaLimit | number | No | 20 | Activity items per page |
Response
json
{
"success": true,
"data": {
"customerId": "cust_001",
"ledgerIdentifier": "0xA1b2C3d4E5f6789012345678901234567890Ef34",
"ledgerSlot": "1234567890",
"totalDeltas": 42,
"computedBalance": 4500.00,
"firstDeltaAt": "2026-01-15T10:30:00.000Z",
"lastDeltaAt": "2026-02-14T14:22:00.000Z",
"latestCheckpoint": "chk_abc123",
"privacyNote": "PacSpace stores only the derived ledger identifier for this customer. Store the mapping between this ID and your internal records in your own system.",
"recentActivity": {
"items": [
{
"amount": 100.00,
"reason": "deposit",
"referenceId": "txn_01",
"status": "verified",
"time": "2026-02-14T14:22:00.000Z"
},
{
"amount": -30.00,
"reason": "usage_charge",
"referenceId": "txn_02",
"status": "verified",
"time": "2026-02-13T11:00:00.000Z"
}
],
"pagination": {
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3
}
}
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
customerId | string | The customer ID you passed |
ledgerIdentifier | string | Deterministic derived identifier for this customer |
ledgerSlot | string | The derived slot used for verification |
totalDeltas | number | Total number of deltas recorded |
computedBalance | number | Sum of all delta amounts |
firstDeltaAt | string | null | When the first delta was recorded |
lastDeltaAt | string | null | When the most recent delta was recorded |
latestCheckpoint | string | null | Most recent checkpoint receipt ID |
privacyNote | string | Reminder about the privacy boundary |
recentActivity | object | Paginated list of recent deltas |
Activity Item Fields
| Field | Type | Description |
|---|---|---|
amount | number | The delta amount (positive or negative) |
reason | string | null | The reason provided when the delta was emitted |
referenceId | string | null | Your reference ID for the transaction |
status | string | "verified" or "pending" |
time | string | When the delta was recorded |
Examples
Get customer detail:
bash
curl https://balance-api.pacspace.io/api/v1/balance/customers/cust_001 \
-H "X-Api-Key: YOUR_API_KEY"
SDK:
typescript
const ledger = await pac.balance.customer('cust_001');
console.log(ledger.ledgerIdentifier); // 0xA1b2...Ef34
console.log(ledger.computedBalance); // 4500.00
console.log(ledger.totalDeltas); // 42
Error Responses
| Status | Code | Description |
|---|---|---|
| 404 | CUSTOMER_NOT_FOUND | No ledger exists for this customer ID |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests (limit: 200/minute) |
| 500 | LIST_CUSTOMERS_FAILED | Internal error listing customer ledgers |
| 500 | GET_CUSTOMER_FAILED | Internal error fetching customer detail |
Cross-Tenant Isolation
Customer ledgers are scoped to your tenant. You cannot see another tenant's customers, and they cannot see yours. This is enforced at the API key level -- your API key determines which tenant's data you can access.