Balance API

Verify — Compare Balances

Compare your balance against a counterparty's. PacSpace derives the neutral truth and tells you who is wrong.

Use this endpoint when two parties disagree on a balance. PacSpace independently derives the correct balance from verified deltas and reports which side (if either) has a discrepancy.

Endpoint

POST https://balance-api.pacspace.io/api/v1/balance/compare

Headers

Header	Required	Description
`X-Api-Key`	Yes	Your PacSpace API key
`Content-Type`	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`customerId`	string	Yes	Unique identifier for the customer account
`yourBalance`	number	Yes	The balance your system currently shows
`theirBalance`	number	Yes	The balance the counterparty claims
`startingBalance`	number	Yes	Agreed-upon starting balance for the comparison window
`startingCheckpoint`	string	No	Checkpoint to begin the comparison from
`startingCheckpointType`	string	No	Type of checkpoint: `itemsRoot` or `anchorId`

Examples

cURL

bash

curl -X POST https://balance-api.pacspace.io/api/v1/balance/compare \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_12345",
    "yourBalance": 48500,
    "theirBalance": 49000,
    "startingBalance": 50000,
    "startingCheckpoint": "0xdef456...",
    "startingCheckpointType": "itemsRoot"
  }'

JavaScript (Node.js)

javascript

const response = await fetch(
  "https://balance-api.pacspace.io/api/v1/balance/compare",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customerId: "cust_12345",
      yourBalance: 48500,
      theirBalance: 49000,
      startingBalance: 50000,
      startingCheckpoint: "0xdef456...",
      startingCheckpointType: "itemsRoot",
    }),
  }
);

const result = await response.json();
console.log(result);

Python

python

import requests

response = requests.post(
    "https://balance-api.pacspace.io/api/v1/balance/compare",
    headers={
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "customerId": "cust_12345",
        "yourBalance": 48500,
        "theirBalance": 49000,
        "startingBalance": 50000,
        "startingCheckpoint": "0xdef456...",
        "startingCheckpointType": "itemsRoot",
    },
)

result = response.json()
print(result)

Response

json

{
  "success": true,
  "data": {
    "customerId": "cust_12345",
    "neutralBalance": 48500,
    "matchesYours": true,
    "matchesTheirs": false,
    "discrepancyReport": {
      "amount": 500,
      "resolution": "Your balance is correct. The counterparty is overstated by 500.",
      "divergentParty": "theirs",
      "windowsToReview": [
        {
          "period": "2026-02",
          "expectedNet": -1500,
          "theirNet": -1000,
          "difference": 500
        }
      ],
      "recommendation": "Share this report with the counterparty. The discrepancy originates in the February 2026 period where a 500-unit debit was not reflected in their records."
    }
  }
}

Response Fields

Field	Type	Description
`customerId`	string	The customer account that was compared
`neutralBalance`	number	The independently derived balance from verified deltas
`matchesYours`	boolean	Whether your submitted balance matches the neutral balance
`matchesTheirs`	boolean	Whether the counterparty's balance matches the neutral balance
`discrepancyReport`	object	Detailed breakdown when a mismatch is found (see below)

Discrepancy Report

Field	Type	Description
`amount`	number	The absolute difference between the two balances
`resolution`	string	Human-readable explanation of the finding
`divergentParty`	string	Which side is incorrect: `"yours"`, `"theirs"`, or `"both"`
`windowsToReview`	array	Time periods where the discrepancy originated
`recommendation`	string	Suggested next steps to resolve the discrepancy

Window to Review Object

Field	Type	Description
`period`	string	Time period where the mismatch occurred
`expectedNet`	number	The correct net change derived from verified deltas
`theirNet`	number	The net change implied by the counterparty's balance
`difference`	number	The gap between expected and claimed

How It Works

You submit both balances — your view and the counterparty's view, along with an agreed starting point.
PacSpace derives the truth — Using only verified deltas, PacSpace computes the neutral balance independently of either party's records.
You get a verdict — The response tells you exactly who matches, who diverges, when the discrepancy started, and what to do about it.

Tip: If both matchesYours and matchesTheirs are true, the balances agree and no discrepancyReport is returned. If both are false, both parties have drifted from the verified record.

Was this page helpful?

Last updated February 11, 2026

Query — Derive a Balance

Receipt — Generate a Receipt

Endpoint#

Headers#

Request Body#

Examples#

cURL#

JavaScript (Node.js)#

Python#

Response#

Response Fields#

Discrepancy Report#

Window to Review Object#

How It Works#