#Ledger y Balance

Este es el concepto más importante para entender antes de tocar cualquier operación financiera. Casi todos los problemas con balances y conexiones de cuentas vienen de no entender qué es un ledger.

¿Qué es un Ledger?

Piensa en un ledger como un número de cuenta bancaria del que pueden sacar múltiples tarjetas y wallets. El dinero vive en el ledger; las cuentas son solo formas de acceder a él.

¿Cómo creo un Ledger?

No lo creas directamente. Un ledger se crea automáticamente cuando creas tu primera cuenta virtual sin especificar un ledgerId.

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

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

Ese ledgerId es ahora el ID de tu ledger. Guárdalo — lo usarás para adjuntar otras cuentas.

¿Qué es la "cuenta base"?

Cada usuario o entidad financiera en tu sistema debería tener una cuenta base.

¿Cómo adjunto otras cuentas al mismo Ledger?

Pasa el ledgerId de tu cuenta virtual al crear cualquier otro tipo de cuenta:

// Crear la cuenta base (crea el ledger)
const base = await client.accounts.virtual.create({ holderUrn: client.urn })

// Adjuntar una tarjeta al mismo ledger
const tarjeta = await client.accounts.card.create({
  holderUrn: client.urn,
  ledgerId: base.ledgerId,
})

// Adjuntar un wallet Polygon al mismo ledger
const wallet = await client.accounts.polygon.create({
  holderUrn: client.urn,
  ledgerId: base.ledgerId,
})

Ahora base, tarjeta y wallet comparten el mismo pool de balance.

¿Qué significa "balance compartido" en la práctica?

Todas las cuentas en el mismo ledger acceden al mismo pool de fondos. Si fondeas la cuenta virtual con 100 DUSD, esos 100 DUSD son accesibles desde la tarjeta y el wallet también — no son copias, es el mismo balance.

Ledger ldg_abc
  ├─ balance: { DUSD/6: 100.00 }
  │
  ├─ Cuenta virtual  → puede verificar y transferir balance
  ├─ Tarjeta         → puede gastar del balance
  └─ Wallet Polygon  → puede recibir y enviar desde el balance

¿Qué activos puede tener un Ledger?

El formato siempre es SÍMBOLO/DECIMALES. Los montos siempre son strings en el SDK para preservar precisión.

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

¿Qué es un Balance?

Cada activo en un ledger tiene cuatro campos de balance:

¿Cuál es la diferencia entre un Movimiento y una Transacción?

#¿Qué sigue?

→ Cuentas — los seis tipos de cuenta y cómo usarlos