PacSpace API Docs

Checkpoint — Period-End

Commit a period-end checkpoint that locks a proof root over all verified deltas for a period.

Use this endpoint to commit a period-end checkpoint. A checkpoint locks a proof root over all verified deltas within a period, creating a tamper-evident snapshot you can reference later.

Endpoint

POST https://balance-api.pacspace.io/api/v1/balance/checkpoint

Headers

HeaderRequiredDescription
X-Api-KeyYesYour PacSpace API key
Content-TypeYesMust be application/json

Request Body

ParameterTypeRequiredDefaultDescription
customerIdstringNoAll customersSpecific customer to checkpoint. Omit to checkpoint all. Max 128 characters; must exist.
periodstringNoCurrent periodPeriod in YYYY-MM format. Must be a valid date and cannot be in the future. Defaults to current month.

Examples

SDK (TypeScript)

typescript
import { PacSpace } from '@pacspace-io/sdk';

const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY });

// Checkpoint a specific customer
const checkpoint = await pac.balance.checkpoint('cust_12345', {
  period: '2026-01',
});
console.log(checkpoint.merkleRoot); // proof root — include in your invoice

// Checkpoint all customers for the current period
const all = await pac.balance.checkpoint();

Checkpoint a Specific Customer (cURL)

bash
curl -X POST https://balance-api.pacspace.io/api/v1/balance/checkpoint \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_12345",
    "period": "2026-01"
  }'

Checkpoint All Customers for Current Period

bash
curl -X POST https://balance-api.pacspace.io/api/v1/balance/checkpoint \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript (Node.js)

javascript
const response = await fetch(
  "https://balance-api.pacspace.io/api/v1/balance/checkpoint",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customerId: "cust_12345",
      period: "2026-01",
    }),
  }
);

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

Python

python
import requests

response = requests.post(
    "https://balance-api.pacspace.io/api/v1/balance/checkpoint",
    headers={
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "customerId": "cust_12345",
        "period": "2026-01",
    },
)

result = response.json()
print(result)

Response

json
{
  "success": true,
  "data": {
    "checkpointId": "chk_abc123def456",
    "period": "2026-01",
    "merkleRoot": "0x7f3a9b2c...",
    "deltaCount": 42,
    "fromIndex": 0,
    "toIndex": 41,
    "customerId": "cust_12345",
    "status": "QUEUED",
    "message": "Checkpoint queued for commitment. You will receive a checkpoint.verified webhook when the proof root is confirmed."
  }
}

Response Fields

FieldTypeDescription
checkpointIdstringUnique identifier for the checkpoint
periodstringThe period this checkpoint covers (YYYY-MM)
merkleRootstringProof root over all verified deltas in the period
deltaCountnumberNumber of verified deltas included in the checkpoint
fromIndexnumberStarting delta index covered by this checkpoint
toIndexnumberEnding delta index covered by this checkpoint
customerIdstringThe customer this checkpoint covers, or "all" if checkpointing all customers
statusstringCheckpoint status — starts as QUEUED, moves to COMMITTED after verification
messagestringHuman-readable status message

Listing Checkpoints

Retrieve your committed checkpoints with optional filtering:

GET https://balance-api.pacspace.io/api/v1/balance/checkpoints

Query Parameters

ParameterTypeRequiredDefaultDescription
customerIdstringNo—Filter by customer
periodstringNo—Filter by period (YYYY-MM)
limitnumberNo20Results per page (max 100)
offsetnumberNo0Skip N results

Examples

cURL

bash
curl -X GET "https://balance-api.pacspace.io/api/v1/balance/checkpoints?period=2026-02&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

SDK (TypeScript)

typescript
const { checkpoints } = await pac.balance.listCheckpoints({
  period: '2026-02',
  limit: 10,
});

Response

json
{
  "success": true,
  "data": {
    "checkpoints": [
      {
        "checkpointId": "chk_abc123def456",
        "period": "2026-02",
        "merkleRoot": "0x7f3a9b2c...",
        "deltaCount": 42,
        "customerId": "cust_12345",
        "status": "COMMITTED",
        "createdAt": "2026-02-28T23:59:00.000Z"
      }
    ],
    "pagination": {
      "total": 25,
      "limit": 10,
      "offset": 0
    }
  }
}

When to Checkpoint

Checkpoints are designed for specific moments in your verification and record-keeping workflow:

Lock a Period for Verification

Run a checkpoint at the close of each period. This locks the period's deltas so that any future queries or receipts referencing that period return a consistent, verifiable snapshot.

bash
# Lock January 2026 at the end of the month
curl -X POST https://balance-api.pacspace.io/api/v1/balance/checkpoint \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period": "2026-01"}'

Before Generating Receipts

Checkpoint before pulling receipts or computing totals. This ensures the data backing your receipts is immutable and can be independently verified later.

For Tamper-Evident Records

Each checkpoint produces a proof root (merkleRoot) — a single fingerprint covering every verified delta in the period. If anyone questions the accuracy of a historical record, you can point to the checkpoint as proof that the data hasn't changed since it was locked.

How Checkpoints Work with Other Endpoints

  • Query — Use a checkpoint's proof root (merkleRoot) as the startingCheckpoint parameter to derive balances efficiently from a known good point.
  • Receipt — Generate receipts that align with checkpointed periods for consistent, verifiable invoicing.
  • Verify — Reference a checkpoint when comparing balances to ensure both parties are working from the same locked dataset.

Tip: Automate checkpoints at the end of each period using a scheduled job or cron task. This ensures you never forget to lock a period before generating receipts.

Previous

Receipt — Generate a Receipt

Next

Receipts & Verification