PacSpace

Advanced API

Facts & Audit Trails

Record arbitrary data as verified facts and retrieve them for compliance or verification.

Facts let you record arbitrary data — documents, events, agreements — as immutable, verified entries. Once committed, a fact can be queried by its content hash and independently verified. Use facts to build audit trails, prove document integrity, and support compliance 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

Commit a Fact

Record a new fact in the verification layer.

bash
curl -X POST https://balance-api.pacspace.io/api/v1/facts \
  -H "X-Api-Key: pk_live_PUBLIC.SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Contract signed by Alice and Bob on 2025-06-01",
    "metadata": {
      "type": "contract_signature",
      "parties": ["alice@example.com", "bob@example.com"],
      "documentId": "doc-789"
    }
  }'

Response 202 Accepted

json
{
  "statusCode": 202,
  "data": {
    "contentHash": "sha256_a1b2c3d4e5f6...",
    "status": "queued",
    "message": "Fact accepted and queued for verification.",
    "createdAt": "2025-06-01T12:00:00.000Z"
  }
}

The contentHash is a deterministic hash of the content you submitted. Use it to query and verify the fact later.

Query a Fact

Retrieve a previously recorded fact by its content hash.

bash
curl https://balance-api.pacspace.io/api/v1/facts/sha256_a1b2c3d4e5f6 \
  -H "X-Api-Key: pk_live_PUBLIC.SECRET"

Response 200 OK

json
{
  "statusCode": 200,
  "data": {
    "contentHash": "sha256_a1b2c3d4e5f6...",
    "content": "Contract signed by Alice and Bob on 2025-06-01",
    "metadata": {
      "type": "contract_signature",
      "parties": ["alice@example.com", "bob@example.com"],
      "documentId": "doc-789"
    },
    "verified": true,
    "verifiedAt": "2025-06-01T12:00:15.000Z",
    "createdAt": "2025-06-01T12:00:00.000Z"
  }
}

Verify a Fact

Independently verify that a fact exists and has been confirmed in the verification layer.

bash
curl https://balance-api.pacspace.io/api/v1/facts/sha256_a1b2c3d4e5f6/verify \
  -H "X-Api-Key: pk_live_PUBLIC.SECRET"

Response 200 OK

json
{
  "statusCode": 200,
  "data": {
    "contentHash": "sha256_a1b2c3d4e5f6...",
    "verified": true,
    "verifiedAt": "2025-06-01T12:00:15.000Z",
    "verificationProof": {
      "timestamp": "2025-06-01T12:00:15.000Z",
      "batchId": "batch_xyz789"
    }
  }
}

If the fact has not yet been verified:

json
{
  "statusCode": 200,
  "data": {
    "contentHash": "sha256_a1b2c3d4e5f6...",
    "verified": false,
    "status": "pending"
  }
}

Request & Response Fields

Commit Request

FieldTypeRequiredDescription
contentstringYesThe data to record (text, serialized JSON, etc.)
metadataobjectNoAdditional context stored alongside the fact

Query / Verify Response

FieldTypeDescription
contentHashstringDeterministic hash of the recorded content
contentstringOriginal content (only in query response)
metadataobjectAssociated metadata
verifiedbooleanWhether verification has completed
verifiedAtstringISO 8601 timestamp of verification
verificationProofobjectProof details (only in verify response)

Use Cases

Document Audit Trail

Record every version of a document as a fact:

javascript
const crypto = require('crypto');

async function recordDocumentVersion(document, version) {
  const content = JSON.stringify({
    documentId: document.id,
    version: version,
    hash: crypto.createHash('sha256').update(document.body).digest('hex'),
    author: document.lastEditedBy,
    timestamp: new Date().toISOString()
  });

  const response = await fetch('https://balance-api.pacspace.io/api/v1/facts', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.PACSPACE_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content,
      metadata: {
        type: 'document_version',
        documentId: document.id,
        version
      }
    })
  });

  return response.json();
}

Compliance Verification

Later, verify that a recorded fact hasn't been altered:

javascript
async function verifyFact(contentHash) {
  const response = await fetch(
    `https://balance-api.pacspace.io/api/v1/facts/${contentHash}/verify`,
    {
      headers: { 'X-Api-Key': process.env.PACSPACE_API_KEY }
    }
  );

  const result = await response.json();
  return result.data.verified;
}

Error Responses

StatusMeaning
400Invalid request — check required fields
401Invalid or missing API key
402Insufficient credits
404Fact not found for the given content hash
429Rate limit exceeded
500Server error — retry with exponential backoff

See Error Handling for full details.

Endpoints Summary

EndpointMethodDescription
/api/v1/factsPOSTCommit a new fact
/api/v1/facts/:contentHashGETQuery a fact by hash
/api/v1/facts/:contentHash/verifyGETVerify a fact's status
Was this page helpful?

Last updated February 11, 2026

Previous

Read Operations

Next

Basic Settlement