How Customer Ledgers Work

When you record a delta using the Balance API, each customerId you pass automatically receives its own isolated ledger. There is no setup or configuration required -- it happens on the first emit.

Automatic Isolation#

Every time you call the emit endpoint with a customerId, PacSpace:

1. Derives a unique ledger identifier for that customer (deterministic -- the same ID always produces the same identifier)
2. Assigns an isolated verification space so that customer's deltas, balances, and checkpoints are independently verifiable
3. Tracks aggregate statistics including total deltas, first and last activity timestamps

# First emit for "cust_001" -- creates the ledger automatically
curl -X POST https://balance-api.pacspace.io/api/v1/balance/delta \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_001",
    "delta": 500,
    "reason": "initial_deposit"
  }'

After this call, cust_001 has a ledger with:

• A unique ledger identifier (e.g., 0xA1b2...Ef34)
• A total delta count of 1
• A computed balance of 500

One Customer, One Ledger#

Each customer's data is completely isolated:

• Deltas emitted for cust_001 only affect cust_001's balance
• Verifications for cust_002 only return cust_002's proof data
• There is no cross-contamination between customers

Deterministic Identifiers#

Ledger identifiers are deterministic -- the same customerId always produces the same identifier. This means:

• You can independently verify which identifier belongs to which customer
• Identifiers are stable across API calls and SDK versions
• You do not need to store the ledger identifier separately (though you can)

The Privacy Boundary#

PacSpace stores only the derived ledger identifier for each customer. It does not know or store any information about who that customer is in your system.

Your responsibility:

• Store the mapping between your internal customer records and the customerId you pass to PacSpace
• Maintain your own customer database with names, emails, account details, etc.

PacSpace stores:

• The derived ledger identifier (a deterministic address)
• Aggregate counts (total deltas, first/last activity)
• Individual delta amounts, verification fingerprints, and timestamps

This separation means PacSpace operates as neutral infrastructure -- it verifies data integrity without knowing the business context.

Viewing Customer Ledgers#

Dashboard#

Navigate to Customer Ledgers in the sidebar to see all your customers, search by ID, and drill into individual ledger details.

API#

Use the customer ledger endpoints to programmatically list and inspect ledgers:

# List all customer ledgers
curl https://balance-api.pacspace.io/api/v1/balance/customers \
  -H "X-Api-Key: YOUR_API_KEY"

# Get a specific customer's ledger detail
curl https://balance-api.pacspace.io/api/v1/balance/customers/cust_001 \
  -H "X-Api-Key: YOUR_API_KEY"

SDK#

const { customers } = await pac.balance.customers();
const ledger = await pac.balance.customer('cust_001');
console.log(ledger.computedBalance); // 4500.00

See Querying Ledgers for full endpoint documentation.