How to reconcile agent wallet balances after stablecoin payments

Why reconciliation matters

Payment products accumulate small mismatches when webhooks fail, jobs retry, operators manually adjust access, or users report deposits late. Reconciliation catches these mismatches before they become financial support incidents.

For agent wallets, reconciliation also helps you understand which bots, users, and workflows are consuming funds.

Sources to compare

• Your local payment command table.
• Webhook events you received and processed.
• Viaclave wallet balances from the REST API.
• Payment status and transaction records.
• External Solana signatures for withdrawals or deposits.

Local ledger row

type LocalLedgerRow = {
  walletId: string;
  paymentId: string;
  direction: "credit" | "debit";
  token: "USDC" | "USDT" | "PYUSD" | "EURC";
  amount: number;
  source: "api" | "webhook" | "manual";
  createdAt: string;
};

Fetch a wallet balance

async function fetchWalletBalances(walletId: string) {
  const response = await fetch(
    "https://api.viaclave.com/v1/wallets/" + walletId + "/balances",
    {
      headers: {
        "Authorization": "Bearer vc_live_YOUR_KEY",
      },
    },
  );

  return response.json();
}

Daily reconciliation job

• Pick a cutoff time and reconcile a closed window.
• Sum local credits and debits by wallet and token.
• Fetch external balances for the same wallets.
• Flag differences above a small threshold.
• Produce a report with wallet ID, token, expected balance, actual balance, and suspected source.

How to handle mismatches

Do not automatically patch balances in your product without understanding the cause. First check webhook delivery, duplicate events, pending withdrawals, and manual operator actions.

Once the cause is known, write an adjustment record with a human-readable reason. Future audits should be able to explain every reconciliation fix.