PacSpace

Balance API

Query — Derive a Balance

Derive a running balance from all verified deltas for a customer. Supports checkpointing for efficient pagination.

Use this endpoint to compute a customer's current balance by replaying all verified deltas. For large histories, use checkpoints to resume from a known point instead of replaying from the beginning.

Endpoint

GET https://balance-api.pacspace.io/api/v1/balance/derive/:customerId

Headers

HeaderRequiredDescription
X-Api-KeyYesYour PacSpace API key

Path Parameters

ParameterTypeRequiredDescription
customerIdstringYesUnique identifier for the customer account

Query Parameters

ParameterTypeRequiredDefaultDescription
startingBalancenumberNo0Initial balance to start the derivation from
startingCheckpointstringNo—Resume derivation from a previous checkpoint
startingCheckpointTypestringNoitemsRootType of checkpoint: itemsRoot or anchorId

Examples

Simple Query

Derive a balance from zero, replaying all verified deltas.

cURL

bash
curl -X GET "https://balance-api.pacspace.io/api/v1/balance/derive/cust_12345" \
  -H "X-Api-Key: YOUR_API_KEY"

JavaScript (Node.js)

javascript
const response = await fetch(
  "https://balance-api.pacspace.io/api/v1/balance/derive/cust_12345",
  {
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
    },
  }
);

const result = await response.json();
console.log(result);

Python

python
import requests

response = requests.get(
    "https://balance-api.pacspace.io/api/v1/balance/derive/cust_12345",
    headers={"X-Api-Key": "YOUR_API_KEY"},
)

result = response.json()
print(result)

Query with Checkpoint

Resume from a previous checkpoint to avoid replaying the entire delta history. This is useful for accounts with many transactions.

cURL

bash
curl -X GET "https://balance-api.pacspace.io/api/v1/balance/derive/cust_12345?\
startingBalance=50000&\
startingCheckpoint=0xdef456...&\
startingCheckpointType=itemsRoot" \
  -H "X-Api-Key: YOUR_API_KEY"

JavaScript (Node.js)

javascript
const params = new URLSearchParams({
  startingBalance: "50000",
  startingCheckpoint: "0xdef456...",
  startingCheckpointType: "itemsRoot",
});

const response = await fetch(
  `https://balance-api.pacspace.io/api/v1/balance/derive/cust_12345?${params}`,
  {
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
    },
  }
);

const result = await response.json();
console.log(result);

Python

python
import requests

response = requests.get(
    "https://balance-api.pacspace.io/api/v1/balance/derive/cust_12345",
    headers={"X-Api-Key": "YOUR_API_KEY"},
    params={
        "startingBalance": 50000,
        "startingCheckpoint": "0xdef456...",
        "startingCheckpointType": "itemsRoot",
    },
)

result = response.json()
print(result)

Response

json
{
  "success": true,
  "data": {
    "customerId": "cust_12345",
    "computedBalance": 48500,
    "deltasCount": 127,
    "latestCheckpoint": "0xabc789...",
    "deltas": [
      {
        "anchorId": "a_1234567890",
        "delta": -1000,
        "reason": "Monthly subscription charge",
        "status": "VERIFIED",
        "createdAt": "2026-02-10T14:30:00Z"
      },
      {
        "anchorId": "a_1234567891",
        "delta": 500,
        "reason": "Referral bonus",
        "status": "VERIFIED",
        "createdAt": "2026-02-11T09:15:00Z"
      }
    ],
    "windowSummaries": [
      {
        "period": "2026-01",
        "totalCredits": 10000,
        "totalDebits": -8500,
        "netChange": 1500,
        "deltasCount": 42
      }
    ],
    "verificationProof": {
      "rootHash": "0xabc789...",
      "algorithm": "sha256",
      "timestamp": "2026-02-11T12:00:00Z"
    }
  }
}

Response Fields

FieldTypeDescription
customerIdstringThe customer account the balance was derived for
computedBalancenumberThe derived running balance after replaying all deltas
deltasCountnumberTotal number of verified deltas included in the derivation
latestCheckpointstringCheckpoint value you can use in subsequent queries to resume here
deltasarrayList of individual delta records included in the derivation
windowSummariesarrayAggregated summaries grouped by time period
verificationProofobjectCryptographic proof that the derivation is correct and untampered

Delta Object

FieldTypeDescription
anchorIdstringUnique identifier for this delta
deltanumberThe adjustment amount
reasonstringHuman-readable reason for the adjustment
statusstringVerification status (always VERIFIED here)
createdAtstringISO 8601 timestamp of when the delta was created

Window Summary Object

FieldTypeDescription
periodstringTime period label (e.g., 2026-01)
totalCreditsnumberSum of all positive deltas in the period
totalDebitsnumberSum of all negative deltas in the period
netChangenumberNet balance change for the period
deltasCountnumberNumber of deltas in the period

Using Checkpoints

Checkpoints let you avoid replaying the entire delta history on every query. Here's the recommended workflow:

  1. First query — Call without checkpoint parameters. The response includes a latestCheckpoint and the computedBalance.

  2. Store the checkpoint — Save the latestCheckpoint value and computedBalance on your side.

  3. Subsequent queries — Pass startingBalance (the previously computed balance) and startingCheckpoint (the stored checkpoint). PacSpace only replays deltas recorded after that checkpoint.

Tip: Combine checkpoints with the Checkpoint endpoint to lock period-end snapshots for billing reconciliation.

Was this page helpful?

Last updated February 11, 2026

Previous

Emit — Record a Delta

Next

Verify — Compare Balances