Referencia de API

Depósitos

Un depósito es todo ingreso on-chain que llega a una dirección de tu comercio. Tulkit lo detecta, espera confirmaciones, lo barre hacia la hot wallet y genera los asientos contables correspondientes. Estos endpoints te dejan seguir ese recorrido con precisión.

Ciclo de vida

Estados

DETECTEDstatus

La transacción fue vista en la red pero aún no es definitiva. Muéstrala como "en camino", no acredites saldo todavía.

CONFIRMEDstatus

Se alcanzaron las confirmaciones requeridas por la red. Es el momento correcto para acreditar al usuario en tu producto.

SWEPTstatus

Los fondos se consolidaron en la hot wallet. Queda registrado swept_tx_hash para auditoría.

FAILEDstatus

La transacción fue revertida o quedó huérfana en una reorganización de cadena. No genera saldo.

GET/v1/deposits

Listar depósitos del comercio

Devuelve todos los depósitos recibidos por tu comercio, sin importar a qué usuario final pertenezcan.

Cuándo usarlo

Perfecto para tu job de conciliación: recórrelo cada pocos minutos y sincroniza los estados con tu base de datos.

curl

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

Respuesta de ejemplo

200 OK

[
  {
    "id": "dep_01J9X1A2B3C4D5E6F7G8H9J0",
    "merchant_id": "mrc_01HZX89ABCDEF1234567890",
    "deposit_address_id": "addr_01HZX89A...",
    "deposit_address": {
      "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "derivation_path": "m/44'/60'/0'/0/42",
      "end_user_id": "eu_01HZX89ABCDEF1234567890",
      "end_user": { "id": "eu_01HZX89ABCDEF1234567890", "external_id": "usr_internal_9381" }
    },
    "network": "POLYGON",
    "asset": "USDT",
    "amount": "250.000000",
    "tx_hash": "0x4f8a9b1c...8f9a",
    "block_number": "60123456",
    "confirmations": 12,
    "status": "CONFIRMED",
    "detected_at": "2026-08-20T21:15:30.000Z",
    "confirmed_at": "2026-08-20T21:18:45.000Z",
    "swept_tx_hash": null,
    "swept_at": null,
    "ledger_entries": []
  }
]

GET/v1/deposits/{id}

Detalle extendido de depósito

Retorna toda la información del depósito: hashes on-chain, confirmaciones, swept_tx_hash y los asientos contables (LedgerEntry) que generó.

Cuándo usarlo

Cuando soporte o finanzas necesitan probar exactamente qué pasó con un ingreso específico.

Parámetros

idstringrequerido

Id del depósito.

curl

curl "https://vaultcore.dev.tulkitpay.com/v1/deposits/dep_01J2A..." \
  -H "x-api-key: $TULKIT_API_KEY"

Respuesta de ejemplo

200 OK

{
  "id": "dep_01J9X1A2B3C4D5E6F7G8H9J0",
  "merchant_id": "mrc_01HZX89ABCDEF1234567890",
  "deposit_address_id": "addr_01HZX89A...",
  "deposit_address": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "derivation_path": "m/44'/60'/0'/0/42",
    "end_user_id": "eu_01HZX89ABCDEF1234567890",
    "end_user": { "id": "eu_01HZX89ABCDEF1234567890", "external_id": "usr_internal_9381" }
  },
  "network": "POLYGON",
  "asset": "USDT",
  "amount": "250.000000",
  "tx_hash": "0x4f8a9b1c...8f9a",
  "block_number": "60123456",
  "confirmations": 12,
  "status": "SWEPT",
  "detected_at": "2026-08-20T21:15:30.000Z",
  "confirmed_at": "2026-08-20T21:18:45.000Z",
  "swept_tx_hash": "0x9a8b7c6d...9a8b",
  "swept_at": "2026-08-20T21:20:00.000Z",
  "ledger_entries": [
    {
      "id": "led_01J9X1...",
      "type": "CREDIT",
      "amount": "250.000000",
      "balance_after": "1250.000000",
      "created_at": "2026-08-20T21:18:45.000Z"
    }
  ]
}

Buenas prácticas

Los asientos contables siempre cuadran: cada crédito al usuario tiene su contraparte en las cuentas de la plataforma.

Conciliación sin sorpresas

Usa el tx_hash como llave natural para deduplicar en tu sistema y trata los estados como avance monótono: un depósito nunca retrocede de SWEPT a DETECTED.

Transferencias

Mueve el saldo acreditado: retiros on-chain o movimientos internos.

Tokens

Define qué activos acepta tu comercio en cada red.