Advanced API
Read Operations
Read the current state of records from PacSpace's verification layer.
Read operations let you retrieve the current verified state of a record by its key. Use reads to check balances, confirm data, and build reconciliation workflows.
Requires an API key in the X-Api-Key header:
bash
-H "X-Api-Key: pk_live_PUBLIC.SECRET"
Base URL: https://balance-api.pacspace.io
Read a Record
Retrieve the current state of a record by its key.
bash
curl https://balance-api.pacspace.io/api/v1/reads/bucket/order-12345 \
-H "X-Api-Key: pk_live_PUBLIC.SECRET"
Response 200 OK
json
{
"statusCode": 200,
"data": {
"key": "order-12345",
"accountId": "customer-001",
"currentBits": 1,
"totalWrites": 1,
"lastWriteAt": "2025-06-10T14:30:00.000Z",
"verified": true,
"metadata": {
"amount": 250.00,
"currency": "USD",
"description": "Monthly subscription"
}
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
key | string | The record's unique identifier |
accountId | string | The account this record belongs to |
currentBits | number | Accumulated bits value for this record |
totalWrites | number | Total number of write operations applied |
lastWriteAt | string | ISO 8601 timestamp of the most recent write |
verified | boolean | Whether the record has been verified |
metadata | object | The metadata from the most recent write |
Record Not Found
If the key does not exist, you'll receive a 404 response:
json
{
"statusCode": 404,
"error": "Not Found",
"message": "No record found for key: order-99999"
}
Use Cases
Check a Running Balance
Write incremental deltas, then read the accumulated total:
bash
# Write a delta
curl -X POST https://balance-api.pacspace.io/api/v1/writes \
-H "X-Api-Key: pk_live_PUBLIC.SECRET" \
-H "Content-Type: application/json" \
-d '{
"items": [{ "key": "balance-acct-001", "accountId": "acct-001", "bits": 100 }]
}'
# Later: read the accumulated balance
curl https://balance-api.pacspace.io/api/v1/reads/bucket/balance-acct-001 \
-H "X-Api-Key: pk_live_PUBLIC.SECRET"
Verify Agreement Between Parties
Both parties read the same key and confirm the value matches their local records:
bash
# Party A reads
curl https://balance-api.pacspace.io/api/v1/reads/bucket/agreement-xyz \
-H "X-Api-Key: pk_live_PARTY_A_KEY"
# Party B reads
curl https://balance-api.pacspace.io/api/v1/reads/bucket/agreement-xyz \
-H "X-Api-Key: pk_live_PARTY_B_KEY"
Error Responses
| Status | Meaning |
|---|---|
401 | Invalid or missing API key |
404 | Record key not found |
429 | Rate limit exceeded |
500 | Server error — retry with exponential backoff |
See Error Handling for full details.
Was this page helpful?
Last updated February 11, 2026