Balances and Ledger

Reference

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

Use balance.credited when fulfillment or reconciliation depends on spendable merchant balance availability.

Usage

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

curl https://dashboard.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' } });

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.