Lote

Un lote verifica hasta 100 direcciones o transacciones en una sola solicitud. Úselo para volver a verificar una base de clientes existente o para despachar un atraso sin enviar cien solicitudes sueltas; un lote cuenta como una sola solicitud frente al límite de solicitudes.

Enviar un lote

POST /v1/checks/batch con el scope checks:write.

{
  "items": [
    { "subject": "address", "asset": "TRX", "address": "…" },
    { "subject": "transaction", "asset": "ETH", "tx_hash": "…", "direction": "deposit", "address": "…" }
  ]
}

• items contiene de 1 a 100 elementos. Una lista vacía, más de 100 elementos o un campo desconocido responden 400 VALIDATION_ERROR.
• Cada elemento tiene el cuerpo de una verificación individual: vea Verificaciones de dirección y Verificaciones de transacción.
• Los elementos siempre envían address, también los de transacción. Un lote se acepta sin leer ninguna cadena, por lo que la dirección no puede derivarse de la transacción. Un elemento sin ella es un error de validación.
• Un elemento con un activo no admitido responde 422 UNSUPPORTED_ASSET y se rechaza todo el lote.

La API acepta el lote y responde 202 sin verificar nada dentro de la solicitud:

{
  "status": "ok",
  "data": {
    "batch_id": "c1e5a9d2-3f1b-4a67-b2c8-7d90e4f61a35",
    "item_count": 2,
    "status": "queued",
    "items": [
      { "item_index": 0, "check_id": "8a2f6c10-5d4e-4b73-9a1c-0e3b7d52f984" },
      { "item_index": 1, "check_id": "2d7b1e90-6a3c-4f58-8c14-b5a09f3e7d62" }
    ]
  },
  "errors": []
}

item_index es la posición del elemento, empezando en cero, en la matriz items y se mantiene durante toda la vida del lote. Cada elemento es una verificación completa con su propio check_id.

curl

curl -s -X POST https://api.leeri.ai/v1/checks/batch \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Idempotency-Key: rescreen-2026-10" \
  -H "Content-Type: application/json" \
  -d '{"items":[
    {"subject":"address","asset":"TRX","address":"'"$ADDRESS_1"'"},
    {"subject":"address","asset":"BTC","address":"'"$ADDRESS_2"'"}
  ]}'

Node.js

const response = await fetch('https://api.leeri.ai/v1/checks/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Idempotency-Key': 'rescreen-2026-10',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: addresses.map(({ asset, address }) => ({ subject: 'address', asset, address })),
  }),
});
const { data } = await response.json();
console.log(data.batch_id, data.item_count); // status is "queued"

Python

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/checks/batch",
    headers={
        "Authorization": f"Bearer {os.environ['LEERI_API_KEY']}",
        "Idempotency-Key": "rescreen-2026-10",
    },
    json={"items": [{"subject": "address", "asset": a["asset"], "address": a["address"]} for a in addresses]},
    timeout=30,
)
data = response.json()["data"]
print(data["batch_id"], data["item_count"])  # status is "queued"

La admisión es todo o nada

Cada elemento se reserva y se une al lote en un solo paso. Si algo no puede admitirse, no se acepta nada y no se cobra nada:

Estado	Código	Significado
402	INSUFFICIENT_BALANCE	La cuota y el saldo prepagado no cubren todos los elementos.
429	PROVIDER_CAPACITY_EXCEEDED	La capacidad para consultas está llena en este momento. Reintente tras Retry-After.
422	PROVIDER_CAPACITY_REQUEST_TOO_LARGE	Solo este lote necesita más capacidad de la que tiene su cuenta. Nunca podrá admitirse ni es reintentable: divídalo en lotes más pequeños.

Cada elemento live puede retener hasta 10 espacios de consulta hasta que sus consultas quedan fijadas, y la capacidad por defecto de la cuenta siempre admite un lote completo de 100 cuando no hay nada más en espera. Vea Límites de solicitudes y cuotas.

Leer los resultados

Los elementos se verifican en segundo plano, detrás de un límite de ritmo en las consultas a fuentes de datos de terceros, por lo que un lote grande tarda. Consulte el progreso con GET /v1/checks/batch/{batch_id} (scope checks:read):

Campo	Significado
batch_id, item_count	El lote y cuántos elementos contiene.
status	queued, running o completed.
completed_count, failed_count	Cuántos elementos terminaron con un veredicto y cuántos fallaron.
items	Cada elemento, con el mismo cuerpo que GET /v1/checks/{check_id} más item_index.

El lote pasa a completed cuando completed_count + failed_count alcanza item_count. Un lote nunca falla por completo porque falle un elemento: lea el status propio de cada elemento, que es completed, pending o failed como en cualquier verificación, y vea Pending y sondeo para saber qué significan.

Los elementos son verificaciones normales, así que también puede leer uno por su check_id con GET /v1/checks/{check_id}. Si hay un webhook registrado, cada elemento que se completa activa su propia entrega check.completed: una por elemento y no una por lote; vea Webhooks.

curl

curl -s https://api.leeri.ai/v1/checks/batch/$BATCH_ID \
  -H "Authorization: Bearer $LEERI_API_KEY"

Node.js

async function waitForBatch(batchId) {
  for (;;) {
    const response = await fetch(`https://api.leeri.ai/v1/checks/batch/${batchId}`, {
      headers: { Authorization: `Bearer ${process.env.LEERI_API_KEY}` },
    });
    if (!response.ok) throw new Error(`poll failed with ${response.status}`);

    const { data } = await response.json();
    if (data.status === 'completed') return data;
    await new Promise((resolve) => setTimeout(resolve, 10_000));
  }
}

const batch = await waitForBatch(batchId);
for (const item of batch.items) console.log(item.item_index, item.status, item.band);

Python

import os
import time

import requests


def wait_for_batch(batch_id):
    while True:
        response = requests.get(
            f"https://api.leeri.ai/v1/checks/batch/{batch_id}",
            headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()["data"]
        if data["status"] == "completed":
            return data
        time.sleep(10)


batch = wait_for_batch(batch_id)
for item in batch["items"]:
    print(item["item_index"], item["status"], item["band"])

Reintentar un lote

Envíe un Idempotency-Key con el lote. Repetir la misma clave con el mismo cuerpo devuelve el mismo lote en lugar de crear un segundo, y cada elemento recibe su clave derivada de la clave del lote y de su posición, de modo que ningún elemento puede verificarse dos veces. La misma clave con un cuerpo distinto responde 422 IDEMPOTENCY_KEY_CONFLICT. Vea Idempotencia.