Balance Reconciliation

Every provider tells Vezgo two separate things about a connection: the positions it currently holds, and the transaction history that produced them. Balance reconciliation checks that those two stories agree.

During each sync, Vezgo replays the connection's transaction history to compute what each holding should be, then compares that figure against the balance the provider actually reported. When the two match, the wallet is flagged as reconciled — a signal that the history you received is complete enough to derive figures from, such as cost basis, realized P&L or a point-in-time balance.

The result is exposed as is_reconciled on each wallet in the account object.

info

Balance reconciliation is an Enterprise-only, opt-in feature. Contact us to enable it for your team. Until it is enabled, the is_reconciled field is omitted from wallets entirely.

How it works

1. Positions are fetched. The connector returns the holdings the provider reports for each wallet — the same figures that become balance objects in the Vezgo API.
2. History is replayed. Vezgo walks the connection's transactions in date order and accumulates a running balance per wallet, per ticker: transaction parts are added or subtracted according to their direction, and fees are deducted. Connectors that need provider-specific handling supply their own replay logic; the rest use the shared default.
3. The two are compared. For every ticker that has a reported position, Vezgo takes the difference between the reported quantity and the replayed quantity.
4. The wallet is flagged. If every compared ticker matches — within a rounding epsilon of 0.000001 — the wallet gets is_reconciled: true. If any ticker differs, it gets false. If there was nothing comparable to check, the flag is left unset and the field is omitted from the wallet.

Reconciliation is incremental. The first sync after the feature is enabled replays the full history Vezgo holds; later syncs only replay transactions that arrived since the previous run, so the flag stays current without re-processing everything.

Reading the flag

{
  "id": "603522490d2b02001233a5d6",
  "resource_type": "account",
  "wallets": [
    {
      "id": "kraken:cash:usd",
      "name": "Kraken",
      "address": null,
      "fiat_ticker": "USD",
      "fiat_value": "12904.55",
      "is_reconciled": true
    }
  ]
}

The field has exactly two values, and is otherwise absent. It is never null.

Value	Meaning	What to do with it
true	Every compared holding in this wallet matches the replayed transaction history.	Treat history-derived figures — cost basis, realized P&L, historical balances — as trustworthy for this wallet.
false	At least one holding does not match. The provider's reported balance cannot be fully explained by the history Vezgo has.	Current balances are still accurate — they come straight from the provider. Flag or footnote anything you derive from history. See why a wallet may not reconcile.
(field absent)	Reconciliation was not evaluated for this wallet. Either the feature is not enabled for your team, the provider does not support reconciliation, or reconciliation ran but found nothing comparable to check.	Treat as unknown, not as a failure. Do not infer anything from the absence of the field.

Because "not evaluated" is expressed by omitting the key rather than by a null, read the field defensively — a falsy check would fold the absent case into false:

const account = await vezgo.accounts.getOne(accountId);

for (const wallet of account.wallets) {
  if (wallet.is_reconciled === undefined) continue; // not evaluated — not a failure
  if (wallet.is_reconciled === false) {
    // surface a "history may be incomplete" note next to derived figures
  }
}

How to use

1. Email hello@vezgo.com to enable balance reconciliation for your team.

2. Once enabled, trigger an account sync — or wait for the next daily sync — for the accounts you care about. The flag is written by syncs that complete after the feature is turned on.

3. Read is_reconciled from the wallets in the account object:

   curl 'VEZGO_API_URL/accounts/ACCOUNT_ID' \
     -H 'Authorization: Bearer VEZGO_USER_TOKEN'

   Or via the SDK:

   const account = await vezgo.accounts.getOne(ACCOUNT_ID);
   const unreconciled = account.wallets.filter((w) => w.is_reconciled === false);

4. Decide how it surfaces in your product. Two patterns work well:

   • Gate derived analytics. Show cost basis and P&L unconditionally for reconciled wallets; add a caveat for the rest.
   • Drive support triage. A wallet that flips from true to false is a useful signal that something changed at the provider — a new transaction type, an unsupported asset, or a history gap.

Why a wallet may not reconcile

is_reconciled: false is a statement about the history, not a claim that the balance is wrong. The reported balance always comes from the provider. Common causes:

• Truncated or date-limited history. Some providers only return a bounded window of transactions, so the earlier activity that built up a position is missing. Connections in this state are skipped rather than marked failed.
• Assets the history cannot express. Staked positions are excluded from comparison, and connectors can mark individual assets as not reconcilable when the provider's ledger cannot represent them faithfully — for example an exchange that reports one deposit as separate advance and settlement events.
• Unsupported transaction types. An asset movement that Vezgo does not yet model leaves the replayed balance short.
• A backfill still in progress. A connection whose history is still being imported will not reconcile until the import finishes.

On several blockchains only the native token is compared — SOL on Solana, XRP on Ripple, ALGO on Algorand, XLM on Stellar, and the native coin on EVM chains. Token balances on those chains cannot be fully replayed from the available event data, so they are left out of the comparison. On these connections, is_reconciled: true means the native token matched, not that every token did.

Vezgo does not expose the per-asset deviation figures through the public API — is_reconciled is the summary. If you need to understand a specific false, contact us with the account id.

Coverage

Reconciliation runs where the provider returns history complete enough to replay — currently a set of major exchanges and blockchains, extended over time as connectors gain support. There is no endpoint that lists which providers qualify, and the set changes, so read the presence and value of is_reconciled per wallet rather than maintaining your own list.

A connection can also be skipped for reasons specific to that connection, such as truncated history, even when its provider is generally supported.

Not to be confused with: trade reconciliation

"Reconciliation" also appears in the Vezgo API in an unrelated sense. Trade reconciliation is the process that merges two or more raw provider rows — a buy leg, a sell leg and a fee — into a single Vezgo transaction with transaction_type: "trade".

That merging is why GET /transactions may return fewer rows than the limit you requested, and why a Vezgo transaction does not map one-to-one onto a raw exchange row. It has nothing to do with is_reconciled, applies to every client, and needs no feature flag.