#Ledger & Balance

This is the most important concept to understand before touching any financial operations. Almost every issue with balances and account connections comes from not understanding what a ledger is.

What is a Ledger?

Think of a ledger like a bank account number that multiple cards and wallets can all draw from. The money lives in the ledger; the accounts are just ways to access it.

How do I create a Ledger?

You don't create one directly. A ledger is created automatically when you create your first virtual account without specifying a ledgerId.

const virtualAccount = await client.accounts.virtual.create({
  holderUrn: client.urn,
  name: 'Main',
})

console.log(virtualAccount.ledgerId) // "ldg_..."

That ledgerId is now the ID of your ledger. Save it — you'll use it to attach other accounts.

What is the "base account"?

Every financial user or entity in your system should have one base account.

How do I attach other accounts to the same Ledger?

Pass the ledgerId from your virtual account when creating any other account type:

// Create the base account (creates the ledger)
const base = await client.accounts.virtual.create({ holderUrn: client.urn })

// Attach a card to the same ledger
const card = await client.accounts.card.create({
  holderUrn: client.urn,
  ledgerId: base.ledgerId,
})

// Attach a Polygon wallet to the same ledger
const wallet = await client.accounts.polygon.create({
  holderUrn: client.urn,
  ledgerId: base.ledgerId,
})

Now base, card, and wallet all share the same balance pool.

What does "shared balance" mean in practice?

All accounts on the same ledger draw from the same pool of funds. If you fund the virtual account with 100 DUSD, that 100 DUSD is accessible from the card and the wallet too — not copies of it, the same balance.

Ledger ldg_abc
  ├─ balance: { DUSD/6: 100.00 }
  │
  ├─ Virtual account  → can check & transfer balance
  ├─ Card             → can spend from balance
  └─ Polygon wallet   → can receive & send from balance

Transfers between accounts on the same ledger are internal — they're just bookkeeping moves, no external payment rails involved.

What assets can a Ledger hold?

The format is always SYMBOL/DECIMALS. Amounts are always strings in the SDK to preserve precision.

// "50000000" in DUSD/6 = 50.000000 DUSD = $50.00
// "1000000" in COPM/2 = 10000.00 COP

What is a Balance?

Each asset in a ledger has four balance fields:

const balance = await client.accounts.balance(virtualAccount.urn)
// {
//   'DUSD/6': { current: '50000000', pending: '0', in: '50000000', out: '0' }
// }

What is the difference between a Movement and a Transaction?

Use movements when you want the history of one account. Use transactions when you want the full picture of a transfer between accounts.

#What's next

→ Accounts — the six account types and how to use them