Conceptos
Cómo funciona
Antes de escribir código conviene entender cinco piezas: end users, direcciones HD, depósitos y barridos, balances contables y transferencias. Con eso puedes predecir exactamente qué hace la plataforma en cada momento.
El recorrido del dinero
Usuario final
│ envía USDC a su dirección de depósito
▼
Deposit address (HD, derivada por usuario y red)
│ Tulkit detecta la tx y espera confirmaciones
▼
Deposit (DETECTED → CONFIRMED → SWEPT)
│ barrido on-chain hacia la hot wallet
▼
Hot wallet + Ledger entry (balance acreditado)
│ POST /v1/transfers
▼
Transfer (INTERNAL o EXTERNAL) → destinoEnd Users
Un End User es el cliente de tu plataforma dentro de Tulkit. No es una cuenta con login: es una entidad contable a la que se le asocian direcciones, depósitos, balances y transferencias.
- external_id es tu llave: úsalo para conciliar Tulkit con tu base de datos sin guardar mapeos frágiles.
- metadata es libre: guarda email, país, tier o cualquier dato que te ayude a operar y soportar al usuario.
- hd_index se asigna automáticamente y de forma incremental; es lo que garantiza direcciones únicas y reproducibles.
Direcciones HD de depósito
HD (Hierarchical Deterministic) significa que todas las direcciones se derivan matemáticamente de una misma semilla maestra custodiada por Tulkit. La ventaja práctica: cada usuario tiene su dirección propia sin que existan miles de llaves privadas sueltas que administrar.
- Son permanentes: la misma dirección sirve para depósitos ilimitados, así que puedes guardarla y mostrarla siempre.
- Son por red: una dirección de POLYGON no recibe fondos enviados por TRON o SOLANA.
- Son atribuibles: cualquier depósito que llegue se asocia automáticamente al usuario dueño de la dirección, sin memos ni referencias.
Muestra siempre red, activo y monto mínimo junto al QR. La mayoría de los fondos perdidos en cripto vienen de elegir la red equivocada, no de fallas de la API.
Depósitos y barridos (sweeps)
Cuando llegan fondos a una dirección de depósito, Tulkit los detecta, espera confirmaciones de la red y luego los mueve (barre) hacia la hot wallet del merchant. Ese barrido es lo que consolida la liquidez y hace posible pagar retiros al instante.
- 1
DETECTED
Vimos la transacción en el mempool o en un bloque reciente. Todavía no es definitiva; úsala solo para mostrar "depósito en camino".
- 2
CONFIRMED
La red alcanzó el número de confirmaciones requerido. Aquí es seguro acreditar el saldo al usuario en tu producto.
- 3
SWEPT
Los fondos se movieron a la hot wallet y quedó registrado swept_tx_hash junto con los asientos contables del depósito.
Hot wallet, gas wallet y balances
Piezas de custodia
HOT_WALLETsource_walletConcentra la liquidez operativa del merchant. Es el origen por defecto de las transferencias externas.
GAS_WALLETsource_walletFinancia las comisiones de red necesarias para barrer depósitos y firmar transacciones. Mantenla siempre fondeada.
LedgercontableCada movimiento genera asientos (LedgerEntry) que puedes auditar desde el detalle de depósitos y transferencias.
Balanceasset + networkLos saldos se agrupan por activo y red: 500 USDC en BASE y 500 USDC en POLYGON son dos balances distintos.
Distingue siempre entre saldo contable (lo que la plataforma reconoce que le pertenece al usuario) y liquidez on-chain (lo que hay disponible en la hot wallet de esa red). Un retiro necesita ambas cosas.
Transferencias internas vs externas
Tipos
INTERNALtypeMovimiento contable entre cuentas de la plataforma. Es instantáneo, no toca la blockchain y no paga gas.
EXTERNALtypeEnvío on-chain a una dirección fuera de Tulkit. Consume gas, tiene tx_hash y depende de la confirmación de la red.
Según tus políticas, una transferencia puede quedar en PENDING_APPROVAL. Nada sale on-chain hasta que un segundo operador la apruebe; si la rechaza, el saldo se reembolsa automáticamente al balance contable.