PacSpace API Docs

Quick Start Guide

Go from zero to your first verified delta in under 5 minutes.

This guide takes you from zero to a verified settlement delta in under 5 minutes. You'll create an account, get an API key, and make the four core API calls: emit, derive, compare, and checkpoint.

Prerequisites

  • A terminal with curl installed (macOS, Linux, or WSL)
  • An email address for registration
  • Optional: Node.js 18+ if you want to use the TypeScript SDK

Step 1: Create Your Account

Register for a PacSpace account. Your account starts on the Free plan with 100 verified deltas and an automatically provisioned Sandbox environment.

bash
curl -X POST https://balance-api.pacspace.io/dashboard/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password",
    "firstName": "Jane",
    "lastName": "Doe",
    "companyName": "Acme Inc"
  }'

Check your inbox and verify your email address before continuing.

Your Sandbox environment is activated automatically when you register. No additional setup needed.

Step 2: Get Your API Key

First, log in to get a JWT token:

bash
curl -X POST https://balance-api.pacspace.io/dashboard/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password"
  }'

Copy the token from the response. Then create an API key:

bash
curl -X POST https://balance-api.pacspace.io/dashboard/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-key"
  }'

The response includes your full API key in the format pk_test_PUBLIC.SECRET. Save it — the secret portion is only shown once.

Step 3: Emit Your First Delta

Your Sandbox environment was activated automatically when you registered. If you need to check its status:

bash
curl https://balance-api.pacspace.io/dashboard/contracts \
  -H "Authorization: Bearer YOUR_TOKEN"

Note: Environment activation typically completes within a few seconds of registration. If it shows as "deploying", wait a moment and check again.

Now use the Balance API with your API key. Record a delta for a customer:

Note: When using pk_test_* keys, requests are automatically routed to the Sandbox API endpoint on dedicated sandbox infrastructure. Production keys (pk_live_*) route to the Production API endpoint (api.pacspace.io).

bash
curl -X POST https://balance-api.pacspace.io/api/v1/balance/delta \
  -H "X-Api-Key: pk_test_PUBLIC.SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer_001",
    "delta": 100.00,
    "reason": "initial-deposit",
    "referenceId": "txn-quickstart-001",
    "metadata": {
      "source": "quickstart-guide",
      "note": "First delta!"
    }
  }'

You'll receive a response confirming the delta was recorded, including a unique receipt ID that serves as your immutable proof of submission.

Step 4: Query the Balance

Derive the current running balance for your customer:

bash
curl https://balance-api.pacspace.io/api/v1/balance/derive/customer_001 \
  -H "X-Api-Key: pk_test_PUBLIC.SECRET"

The response returns the derived balance computed from all recorded deltas — in this case, 100.00.

Step 5: Verify Agreement

Compare your view of the balance against a counterparty's. In a real integration, each side submits their computed balance. For this test, both sides agree:

bash
curl -X POST https://balance-api.pacspace.io/api/v1/balance/compare \
  -H "X-Api-Key: pk_test_PUBLIC.SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "yourBalance": 100.00,
    "theirBalance": 100.00,
    "startingBalance": 0
  }'

The response confirms whether the balances match. If they don't, PacSpace tells you the exact discrepancy.

Step 6: Checkpoint the Period

Lock a proof root over all the verified deltas in this window. Include this proof in your invoice so your counterparty can independently audit the period.

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

The response includes a proofRoot — a cryptographically anchored fingerprint covering every delta in the period.

That's It

Four calls — emit, derive, compare, checkpoint. That's the entire settlement flow.

Free plan reminder: Your Free plan includes 100 verified deltas in the Sandbox. When you're ready for higher volumes or production access, upgrade to a paid plan from the dashboard.

Using the SDK

Prefer TypeScript? Install the official SDK and do the same flow in a few lines:

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

const pac = new PacSpace({ apiKey: 'pk_test_PUBLIC.SECRET' });

// Step 3: Emit a delta
const delta = await pac.balance.emit('customer_001', 100.00, 'initial-deposit', {
  referenceId: 'txn-quickstart-001',
  metadata: { source: 'quickstart-guide' },
});

// Step 4: Query the balance
const { computedBalance } = await pac.balance.derive('customer_001');
console.log(computedBalance); // 100.00

// Step 5: Verify agreement
const report = await pac.balance.compare('customer_001', {
  yours: 100.00,
  theirs: 100.00,
}, { startingBalance: 0 });

console.log(report.matchesYours); // true

// Step 6: Checkpoint
const checkpoint = await pac.balance.checkpoint('customer_001');
console.log(checkpoint.merkleRoot); // proof root for this period

The SDK auto-detects your environment from the API key prefix (pk_test_ = sandbox, pk_live_ = production), handles retries, and throws typed errors you can catch:

typescript
import { PlanLimitExceededError, RateLimitError } from '@pacspace-io/sdk';

try {
  await pac.balance.emit('cust_123', -1000, 'charge');
} catch (err) {
  if (err instanceof PlanLimitExceededError) {
    console.log('Plan limit reached — upgrade or wait for next period');
  } else if (err instanceof RateLimitError) {
    console.log(`Wait ${err.retryAfter}s`);
  }
}

From here you can:

Previous

What You Can Build

Next

Authentication