Tulkit Enterprise
Agendar citaConsola

Referencia de API

End Users

Los End Users representan a los clientes de tu plataforma. Todo lo demás —direcciones, depósitos, balances y transferencias— cuelga de ellos, así que este suele ser el primer recurso que integras.

POST/v1/end-users

Registrar End User

Crea el usuario final dentro del merchant y le asigna automáticamente un hd_index seguro, que es la base para derivar sus direcciones de depósito.

Cuándo usarlo

Llámalo al terminar el onboarding en tu producto, o justo antes de mostrar por primera vez una pantalla de depósito.

Cuerpo (JSON)

external_idstringrequerido

Tu identificador interno del usuario. Debe ser único y estable en el tiempo; es la llave de conciliación.

metadataobject | null

Datos libres para tu operación (email, país, segmento). No los usamos para lógica de negocio.

curl
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": "usr_internal_9381",
    "metadata": { "email": "ana@empresa.com", "country": "PE", "tier": "vip" }
  }'

Respuesta de ejemplo

200 OK
{
  "id": "eu_01HZX89ABCDEF1234567890",
  "merchant_id": "mrc_01HZX89ABCDEF1234567890",
  "external_id": "usr_internal_9381",
  "hd_index": 42,
  "metadata": { "email": "ana@empresa.com", "country": "PE", "tier": "vip" },
  "created_at": "2026-08-20T20:00:00.000Z"
}

Buenas prácticas

  • No envíes merchant_id: se inyecta automáticamente desde tu x-api-key.
  • Guarda el id devuelto junto a tu usuario: lo necesitarás para generar direcciones y transferir.
  • Errores posibles: 400 BAD_REQUEST, 401 UNAUTHORIZED, 409 CONFLICT, 500 INTERNAL_ERROR.
GET/v1/end-users

Listar y buscar End Users

Devuelve el listado paginado de tus usuarios finales, con búsqueda libre, filtro por external_id y por rango de fechas de creación.

Cuándo usarlo

Ideal para tu back office: buscar al usuario que escribió a soporte o exportar altas de un periodo.

Parámetros

pagenumber

Página a consultar, empezando en 1.

limitnumber

Cantidad de resultados por página. Mantenlo bajo (25-100) para respuestas rápidas.

searchstring

Búsqueda libre sobre los campos identificables del usuario.

external_idstring

Filtra por tu identificador exacto. Es la forma más rápida de resolver un usuario concreto.

from_datestring (ISO)

Fecha inicial del rango de creación.

to_datestring (ISO)

Fecha final del rango de creación.

curl
curl "https://vaultcore.dev.tulkitpay.com/v1/end-users?external_id=user_9381" \
  -H "x-api-key: $TULKIT_API_KEY"

Respuesta de ejemplo

200 OK
{
  "data": [
    {
      "id": "eu_01HZX89ABCDEF1234567890",
      "merchant_id": "mrc_01HZX89ABCDEF1234567890",
      "external_id": "usr_internal_9381",
      "hd_index": 42,
      "metadata": { "email": "ana@empresa.com" },
      "deposit_addresses": [
        {
          "id": "da_01HZX89...",
          "network": "POLYGON",
          "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
          "created_at": "2026-08-20T20:05:00.000Z"
        }
      ],
      "balances": [
        { "network": "POLYGON", "asset": "USDT", "balance": "250.000000" }
      ],
      "created_at": "2026-08-20T20:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}
GET/v1/end-users/:id

Obtener End User

Recupera el detalle completo de un usuario final por su id de Tulkit.

Parámetros

idstringrequerido

Id del End User devuelto al registrarlo (no tu external_id).

curl
curl "https://vaultcore.dev.tulkitpay.com/v1/end-users/eu_01HZX89ABCDEF1234567890" \
  -H "x-api-key: $TULKIT_API_KEY"

Respuesta de ejemplo

200 OK
{
  "id": "eu_01HZX89ABCDEF1234567890",
  "merchant_id": "mrc_01HZX89ABCDEF1234567890",
  "external_id": "usr_internal_9381",
  "hd_index": 42,
  "metadata": { "email": "ana@empresa.com" },
  "created_at": "2026-08-20T20:00:00.000Z"
}

Buenas prácticas

  • Errores posibles: 401 UNAUTHORIZED y 404 NOT_FOUND.
GET/v1/end-users/:id/transactions

Historial del End User

Devuelve depósitos y transacciones asociadas a las direcciones del usuario, en orden cronológico y paginado. Es la fuente perfecta para la pantalla de "movimientos" de tu app.

Parámetros

idstringrequerido

Id del End User.

pagenumber

Página a consultar.

limitnumber

Resultados por página.

networkstring

Filtra por red (ETHEREUM, POLYGON, BASE, TRON, SOLANA…).

assetstring

Filtra por símbolo del activo, por ejemplo USDC.

statusstring

Filtra por estado del movimiento (DETECTED, CONFIRMED, SWEPT, COMPLETED…).

from_datestring (ISO)

Inicio del rango.

to_datestring (ISO)

Fin del rango.

curl
curl "https://vaultcore.dev.tulkitpay.com/v1/end-users/eu_01HZX.../transactions?network=POLYGON&limit=20" \
  -H "x-api-key: $TULKIT_API_KEY"

Respuesta de ejemplo

200 OK
{
  "data": [
    {
      "id": "dep_01J9X1A2B3C4D5E6F7G8H9J0",
      "type": "DEPOSIT",
      "network": "POLYGON",
      "asset": "USDT",
      "amount": "250.000000",
      "status": "CONFIRMED",
      "tx_hash": "0x4f8a9b1c...8f9a",
      "created_at": "2026-08-20T21:15:30.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "total_pages": 1 }
}

Buenas prácticas

  • Para una pantalla de "esperando depósito", filtra por status y haz polling cada 15-30 segundos. Mejor aún: usa webhooks y evita el polling.

Direcciones de depósito

Deriva las direcciones por red que verá tu usuario.

Depósitos

Sigue el dinero desde que entra hasta que se barre a la hot wallet.