> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Modelo de balances

> Cómo funcionan las wallets por moneda y cómo se mueven los fondos dentro de tu cuenta business.

Tu cuenta business en Vita Wallet opera sobre un modelo de **múltiples wallets por moneda**: una wallet separada para cada moneda activa (fiat o cripto). Entender este modelo es clave antes de diseñar flujos de payins, payouts o reconciliación.

## Qué es una wallet

Una wallet es el saldo que tu business mantiene en una moneda específica. Las operaciones de la API siempre acreditan o debitan la wallet correspondiente — nunca "cuenta global".

> [card] Wallets fiat
>
> Una por cada moneda local soportada (USD, CLP, COP, MXN, EUR, etc.). Se usan para payins locales y para liquidar payouts bancarios.

> [card] Wallets cripto
>
> USDT, USDC y otras activadas en tu cuenta. Se usan para payouts crypto on-chain y para exchanges.

> [!NOTE]
>
> Para listar wallets activas y sus saldos usa `GET /api/businesses/wallets/{uuid}` (ver [User Information](https://docs.vitawallet.io/api-reference/user-information/overview.md)).

## Cómo entra y sale el dinero

```mermaid theme={null}
flowchart LR
  CLI[Cliente final] -- paga --> PO[Payin / Payment Order]
  PO -- acredita --> WALLET_LOCAL[Wallet moneda local]
  WALLET_LOCAL -- Exchange --> WALLET_USD[Wallet USD / USDT]
  WALLET_USD -- Bank Payout --> BANK[Cuenta bancaria]
  WALLET_USD -- Crypto Payout --> CHAIN[Dirección blockchain]
  WALLET_USD -- Vita Sent --> OTRO[Otro usuario Vita]
```

**1. Entrada: Payins**

Cuando un cliente paga un `Payment Order`, el monto se acredita en la wallet de la **moneda de destino** que definiste (`currency_destiny`). Si el pago fue en pesos pero destino es USD, Vita hace la conversión al tipo de cambio del momento del pago.

**2. Movimiento interno: Exchange**

`POST /api/businesses/transactions` con `transactions_type: exchange` mueve fondos de una wallet a otra dentro de tu cuenta. Es la única forma de pasar entre monedas sin salir del sistema.

**3. Salida: Payouts**

Todo payout **debita la wallet de origen** antes de rutear al destino. Si no hay saldo suficiente, la operación se rechaza antes de llegar al rail bancario o blockchain.

## Principios operativos

> [accordion] Saldo disponible vs saldo total
>
> El endpoint de balance devuelve el saldo **disponible para operar**. Montos retenidos por operaciones en curso (payouts `started` o `pending`) ya están descontados — no vuelvas a reservarlos del lado tuyo.

> [accordion] No hay 'cuenta global'
>
> No existe un balance consolidado automático en una moneda base. Si necesitas una vista en USD de todas tus wallets, consulta `GET /api/businesses/prices` para obtener la tasa vigente y agrega del lado de tu backend.

> [accordion] Precios con expiración
>
> `GET /api/businesses/prices` y `GET /api/businesses/crypto_prices` devuelven un campo `valid_until`. Después de ese timestamp, la tasa no es válida para crear exchanges — vuelve a consultar.

> [accordion] Toda operación es una Transaction
>
> Payouts, exchanges y transferencias internas se crean contra el mismo endpoint `POST /api/businesses/transactions`. El campo `transactions_type` decide qué tipo es. Para el ledger, todas aparecen en `GET /api/businesses/transactions` y `/get_all_transactions`.

## Antes de operar

Siempre que vayas a crear un payout o un exchange:

**1. Consulta precios**

Usa el endpoint de prices adecuado y guarda el `valid_until`.

**2. Verifica saldo de la wallet de origen**

`GET /api/businesses/wallets/{uuid}` — asegura que el saldo cubra el monto + fee + spread.

**3. Genera un identificador propio (`order`)**

Único por operación en tu sistema. Habilita idempotencia — ver [Idempotencia y reintentos](https://docs.vitawallet.io/idempotency-retries.md).

**4. Crea la transacción**

`POST /api/businesses/transactions` con los campos específicos del tipo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.