Agent Capabilities
The exact operations an agent uses against PacSpace — with endpoints, SDK equivalents, and deeper-reference links.
This page is the operations map for agentic systems. It groups every operation an agent is likely to call, points at the authoritative reference page for each, and flags the common failure modes that are easy to miss.
Use When
Use this page when an agent needs the right endpoint or SDK method quickly, or when reviewing an integration to confirm it is using the canonical entrypoint instead of stitching together private calls.
Inputs
- A valid API key and the intended environment.
- A customer record strategy — one record per counterparty, one per cost center, or one per service.
- A deterministic
referenceIdstrategy the agent can reproduce from its own state.
Core Writes
These four operations cover the full write surface most agents need.
| Operation | Endpoint | SDK | Reference |
|---|---|---|---|
| Emit one delta | POST /api/v1/balance/delta | pac.balance.emit(...) | Emit |
| Emit a group of deltas | POST /api/v1/balance/delta/batch | pac.balance.emitBatch(...) | Emit |
| Wait for verification | POST /api/v1/balance/delta + poll | pac.balance.emitAndWait(...) | SDK Reference |
| Lock a period or window | POST /api/v1/balance/checkpoint | pac.balance.checkpoint(...) | Checkpoint |
Emit with a deterministic referenceId and an Idempotency-Key header. Use emitBatch when grouping deltas reduces call volume — for example, when collecting interval usage. Use emitAndWait only when the agent's next step depends on the delta being verified before moving on.
Core Reads
These are the reads an agent uses to confirm state, answer user questions, or build a dashboard.
| Operation | Endpoint | SDK | Reference |
|---|---|---|---|
| Derive a running balance | GET /api/v1/balance/derive/:customerId | pac.balance.derive(...) | Query |
| Compare two balance views | POST /api/v1/balance/compare | pac.balance.compare(...) | Verify |
| Check delta status | GET /api/v1/balance/delta/:recordId | pac.balance.deltaStatus(...) | Emit |
| Detect sequence gaps | GET /api/v1/balance/gaps/:customerId | pac.balance.gaps(...) | Emit |
| List checkpoints | GET /api/v1/balance/checkpoints | pac.balance.listCheckpoints(...) | Checkpoint |
Derive is the default way to answer "what is this customer's balance right now." Compare is the default way to surface a mismatch between two ledgers before month-end.
Receipts and Proofs
These are the operations an agent uses when it needs something safe to share with a counterparty or auditor.
| Operation | Endpoint | SDK | Reference |
|---|---|---|---|
| Generate a receipt | GET /api/v1/balance/receipt/:customerId | pac.balance.receipt(...) | Receipt |
| Verify a proof root publicly | GET /api/v1/verify/:proofRoot | pac.verify(...) | Verifying Proofs |
| Verify a spot-check package | POST /api/v1/verify/package | — | Verifying Proofs |
Receipts are the agent's hand-off format. Public verification works without an API key, which is the whole point — a counterparty can audit the proof root without needing PacSpace credentials of their own.
Customer Records
Customer records are the agent's view of "who has balance with us." Use these reads when building an interface that lists customers or drills into one record.
| Operation | Endpoint | SDK | Reference |
|---|---|---|---|
| List customer records | GET /api/v1/balance/customers | pac.balance.customers(...) | How Customer Records Work |
| Read one customer record | GET /api/v1/balance/customers/:customerId | pac.balance.customer(...) | Querying Records |
Webhooks
Inbound events are how PacSpace tells the agent that a delta is verified or a checkpoint is committed.
| Event | When it fires | Reference |
|---|---|---|
delta.verified | A delta is verified end-to-end. | Event Types |
delta.stored | A delta has been permanently committed on the verification layer. | Event Types |
delta.failed | A delta has reached a terminal failed state. | Event Types |
checkpoint.verified | A period-end checkpoint has been committed. | Event Types |
The Autonomous Agent Pattern is the reference design for handling these events.
SDK Entry Points
The TypeScript SDK is the fastest path to a correct integration. The SDK:
- Routes automatically based on the API key prefix.
- Handles retries with bounded exponential backoff on transient errors.
- Forwards idempotency keys through the
Idempotency-Keyheader. - Exposes typed errors for common failure modes.
See SDK Reference for every method, return shape, and error.
Idempotency
Every write call in this section supports idempotency. Set an Idempotency-Key header (or the idempotencyKey option in the SDK) and reuse the same deterministic referenceId on retry. Full rules live on Safety and Idempotency.
Retry
Retry only transient failures — 408, 429, 5xx — with bounded exponential backoff. Do not retry 4xx validation errors without changing the inputs.
Failure Modes
- Using
emitfor high-frequency telemetry whereemitBatchwould be correct, inflating call volume. - Using
emitAndWaiton a critical user-request path and timing out before verification completes. - Treating
receiptIdandproofRootas interchangeable —receiptIdis per submission,proofRootcovers a group or checkpoint. - Calling
comparewithout a consistentstartingBalanceorstartingCheckpointbetween the two sides.
Related Pages
- Overview — section entry point.
- Integration Patterns — event-driven, periodic, and hybrid metering.
- Safety and Idempotency — idempotency keys, retries, and cadence.
- Proofs for Agents — consuming and persisting proofs.