PacSpace Docs

Quick Start Guide

Request access, create an API key, record usage, and check the proof.

This guide records usage before an invoice. You request access, create an API key, emit a delta, derive a balance, compare views, and checkpoint the period.

Prerequisites

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

Step 1: Request Access

Request access first. PacSpace reviews requests before creating accounts.

bash
curl -X POST https://app.pacspace.io/dashboard/auth/request-access \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "you@example.com",
    "organization": "Acme Inc",
    "buyerMode": "DIRECT_INFERENCE_VENDOR",
    "useCase": "Record usage before invoices go out."
  }'

After your account is approved, use the approved access link to create your account and verify your email address.

Your account must be approved before you can create API keys.

Step 2: Get Your API Key

First, log in to establish a dashboard session:

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

The login response sets httpOnly dashboard session cookies in pacspace-dashboard-cookies.txt. Then create an API key:

bash
curl -X POST https://app.pacspace.io/dashboard/api-keys \
  -b pacspace-dashboard-cookies.txt \
  -H "X-Pacspace-CSRF: 1" \
  -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

If you need to check your environment status:

bash
curl https://app.pacspace.io/dashboard/environments \
  -b pacspace-dashboard-cookies.txt

Note: Environment activation typically completes shortly after approval. If it shows as "deploying", wait a moment and check again.

Now use the Balance API with your API key. For pk_test_* keys, set the base URL to the Sandbox URL shown in your PacSpace dashboard. For pk_live_* keys, use https://app.pacspace.io.

bash
export PACSPACE_API_BASE_URL="<Sandbox URL from dashboard>"

Record a delta for a customer:

bash
curl -X POST "$PACSPACE_API_BASE_URL/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 you can use to check the proof later.

Step 4: Query the Balance

Derive the current running balance for your customer:

bash
curl "$PACSPACE_API_BASE_URL/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 "$PACSPACE_API_BASE_URL/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 "$PACSPACE_API_BASE_URL/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 - one fingerprint covering every delta in the period.

That's It

Four calls - emit, derive, compare, checkpoint. That's the core Recordation flow.

Free plan reminder: Your Free plan includes 100 verified deltas/month 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.proofRoot); // 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

Use Cases

Next

Authentication