Balance API Docs

Agents Overview

Guide for building agentic systems on PacSpace. Emit, derive, compare, and checkpoint — with verifiable proofs and safe retries.

This section is written for agentic systems and the humans wiring them up. It is the shortest path from "agent has a customer and an event" to "agent has a verified delta and a receipt it can trust."

PacSpace gives an agent one primitive — the verified delta — plus three derivations on top of it: derive a running balance, compare two views of that balance, and checkpoint a window into a single proof. Everything else in this section is guidance on how to use those four operations safely.

Use When

Use this page when an agent is starting a new PacSpace integration, reviewing an existing one, or orienting before calling into a deeper reference page. It is the entry point, not the whole story.

Inputs

  • An API key for the right environment. pk_test_* routes to Sandbox. pk_live_* routes to Production. Never mix them.
  • A stable customerId for each counterparty, record, or cost center the agent writes about.
  • A deterministic referenceId strategy the agent can regenerate from its own inputs.
  • A clear answer for whether this integration is event-driven, periodic, or hybrid.

The Four Operations

OperationWhat an agent doesAPI call
EmitRecord one credit or debit as a delta.POST /api/v1/balance/delta
DeriveCompute the running balance from verified deltas.GET /api/v1/balance/derive/:customerId
CompareFind where the agent's view and the counterparty's view diverge.POST /api/v1/balance/compare
CheckpointLock a period or window into a single proof.POST /api/v1/balance/checkpoint

These four calls cover the full surface most agents need.

The Data Boundary

This distinction matters to every agent, because it controls what is safe to share externally:

  • Deltas are private. The business data inside a delta — customerId, delta, reason, metadata — stays inside PacSpace. It is not exposed to anyone else.
  • Proofs are public. The fingerprint of a delta, the proof root over a window, and the verification record of each proof are safe to share. They confirm that an event happened and when, without revealing what happened.

An agent should treat proof fields — proofRoot, receiptId, proofHash, contentHash, itemHash, verificationReference — as safe to publish, cite, and hand to a counterparty. Everything else should stay inside the agent's own perimeter.

A Minimal Agent Loop

A robust agent loop looks like this:

  1. Detect an operation worth metering.
  2. Build a deterministic referenceId from inputs the agent controls.
  3. Emit a delta with an idempotency key derived from that same reference.
  4. On webhook or poll, record the receiptId and proofHash.
  5. Derive or compare on demand, not on every event.
  6. Checkpoint at period close and attach the proofRoot to whatever document the agent hands downstream.

If an agent can execute those six steps safely under retries, it has a correct PacSpace integration.

Where to Go Next

You want to...Go to
See exact vocabulary before writing codeGlossary
Wire up the four core operations and common readsCapabilities
Store and rotate API keys safelyAuthentication
Pick event-driven, periodic, or hybrid meteringIntegration Patterns
Make retries, idempotency, and cadence safeSafety and Idempotency
Consume and verify proofs and receiptsProofs for Agents
Preview the PacSpace MCP interfacePacSpace MCP

Failure Modes

  • Mixing pk_test_* and pk_live_* credentials across environments.
  • Non-deterministic referenceId values that change on retry.
  • Emitting before the underlying operation has actually succeeded.
  • Unbounded retries that flood the API and obscure real failures.
  • Treating proofs as optional and leaving agents unable to audit their own behavior.

Each deeper page in this section addresses one of these failure modes directly.

Previous

Autonomous Agent Pattern

Next

Glossary