Balances and Ledger

Reference

Balances show current funds per currency. The ledger explains how funds moved through deposits, fees, payouts, late deposits, and reversals.

For converted invoice payments, balance credit happens after settlement. A payment can be confirmed before the merchant balance is available; balance.credited marks the actual credited amount and asset.

Usage

Read balances for an overview, then inspect a currency ledger when reconciling.

curl https://api.halfin.xyz/api/v1/balances \
  -H "X-API-Key: $HALFIN_API_KEY"

import { createHalfin, getLedger, listBalances } from '@halfin/sdk-merchant';

const client = createHalfin({ apiKey: process.env.HALFIN_API_KEY });
const balances = await listBalances({ client });
const btcLedger = await getLedger({ client, path: { currency: 'BTC' } });

# Python SDK coming soon. Use the cURL example for now.

Pitfalls

• Do not calculate spendable funds from webhook totals alone.
• Treat invoice.paid as payment confirmation; use balance.credited for spendable balance credit.
• Treat reversals and late deposits as reconciliation events, not normal paid invoices.

Troubleshooting

Balance differs from invoice totals usually means fees, payouts, reversals, or late deposits are included in the ledger.