Primeros pasos
Quickstart
En esta guía integrarás el flujo completo: registrar un usuario, darle una dirección de depósito, ver el dinero entrar y sacarlo on-chain. Cada paso incluye el request real y qué esperar de vuelta.
Antes de empezar
Necesitas una API key de testnet (te la entrega tu equipo de cuenta) y un cliente HTTP. No hace falta ninguna librería especial: todo es REST y JSON.
export TULKIT_API_KEY="sk_test_..."
export TULKIT_BASE_URL="https://vaultcore.dev.tulkitpay.com"Configura tu entorno TESTNET
Los tres primeros pasos se hacen una sola vez desde el Portal de Comercios: credenciales, notificaciones y wallets de prueba.
Tareas de configuración TESTNET
Guía de inicio rápidoRecibir dinero: depósitos
Con el entorno listo, este es el flujo para que un usuario reciba fondos.
4. Crea un End User
El external_id es tu identificador interno (el user id de tu base de datos). Guarda el id que devolvemos: lo usarás en todos los pasos siguientes.
curl -X POST "https://vaultcore.dev.tulkitpay.com/v1/end-users" \
-H "x-api-key: $TULKIT_API_KEY" \
-H "content-type: application/json" \
-d '{
"external_id": "user_9381",
"metadata": { "email": "ana@empresa.com", "tier": "pro" }
}'Si vuelves a registrar el mismo external_id recibirás el usuario existente en lugar de un duplicado, así que puedes llamarlo desde tu flujo de onboarding sin miedo.
5. Genera direcciones de depósito
Pide solo las redes que vas a mostrar en tu producto. Cada dirección es exclusiva del usuario y permanente: puedes cachearla en tu base de datos.
curl -X POST "https://vaultcore.dev.tulkitpay.com/v1/deposit-addresses" \
-H "x-api-key: $TULKIT_API_KEY" \
-H "content-type: application/json" \
-d '{
"end_user_id": "eu_01H...",
"networks": ["POLYGON", "BASE", "TRON"]
}'Nunca muestres una dirección de una red en otra red. Si el usuario envía USDT de TRON a una dirección de POLYGON, los fondos no serán acreditados. Etiqueta siempre la red en tu UI.
6. Recibe el depósito con webhooks
Cuando el usuario envía fondos, detectamos la transacción, esperamos confirmaciones y la barremos a la hot wallet. Te avisamos con dos eventos: deposit.detected (aún sin confirmar) y deposit.confirmed (el momento correcto para acreditar saldo).
{
"event": "deposit.confirmed",
"created_at": "2026-08-20T21:18:45.000Z",
"data": {
"id": "dep_01J9X1A2B3C4D5E6F7G8H9J0",
"end_user_id": "eu_01H...",
"network": "POLYGON",
"asset": "USDT",
"amount": "250.000000",
"status": "CONFIRMED",
"tx_hash": "0x4f8a9b1c...8f9a"
}
}Verifica siempre la firma HMAC del header X-Vaultcore-Signature antes de procesar el evento, y mantén un job de conciliación sobre /v1/deposits como red de seguridad.
Ver documentación de WebhooksEnviar dinero: transferencias
Los pasos anteriores cubren cómo recibir dinero. Retirar es un flujo distinto: primero cotizas el costo on-chain y luego ejecutas la transferencia con una clave de idempotencia.
Paso 1. Cotiza el gas fee
Antes de retirar, consulta el costo estimado on-chain para mostrárselo al usuario o para decidir la red más barata en ese momento.
curl -X POST "https://vaultcore.dev.tulkitpay.com/v1/transfers/estimate-fee" \
-H "x-api-key: $TULKIT_API_KEY" \
-H "content-type: application/json" \
-d '{ "network": "POLYGON", "asset": "USDC" }'Paso 2. Ejecuta la transferencia
Genera un idempotency_key único por intención de pago (por ejemplo el id del retiro en tu sistema). Si reintentas con la misma clave, no se duplicará el envío.
curl -X POST "https://vaultcore.dev.tulkitpay.com/v1/transfers" \
-H "x-api-key: $TULKIT_API_KEY" \
-H "content-type: application/json" \
-d '{
"idempotency_key": "wd_2026_08_18_0001",
"network": "POLYGON",
"asset": "USDC",
"amount": "250.00",
"to_address": "0xA1b2...",
"end_user_id": "eu_01H...",
"type": "EXTERNAL",
"note": "Retiro solicitado desde la app"
}'Cuando este flujo funcione en testnet, pide tus credenciales de mainnet. El código es idéntico: solo cambia la API key y el entorno de los tokens.