Verificaciones de dirección
Una verificación de dirección criba una dirección en un activo y responde con un veredicto: una puntuación (score), un nivel de riesgo (band), los hallazgos que movieron la puntuación y todo lo necesario para leerlo correctamente y reproducirlo más tarde. Para verificar una transacción, vea Verificaciones de transacción.
Solicitud
POST /v1/checks con el scope checks:write (vea Autenticación).
| Campo | Obligatorio | Descripción |
|---|---|---|
subject | sí | "address". |
asset | sí | Un símbolo de activo tal como figura en Activos admitidos, de 20 caracteres como máximo. |
address | sí | La dirección que se va a verificar, de 160 caracteres como máximo. Su forma debe ser válida para el activo. |
Los campos desconocidos se rechazan. Envíe una cabecera Idempotency-Key con su propio identificador de operación para que una solicitud reintentada nunca verifique ni cobre dos veces; vea Idempotencia.
- curl
- Node.js
- Python
curl -s -X POST https://api.leeri.ai/v1/checks \
-H "Authorization: Bearer $LEERI_API_KEY" \
-H "Idempotency-Key: customer-8841-onboarding" \
-H "Content-Type: application/json" \
-d '{"subject":"address","asset":"TRX","address":"'"$ADDRESS"'"}'
const response = await fetch('https://api.leeri.ai/v1/checks', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
'Idempotency-Key': 'customer-8841-onboarding',
'Content-Type': 'application/json',
},
body: JSON.stringify({ subject: 'address', asset: 'TRX', address }),
});
const { data } = await response.json();
if (data.status === 'completed') console.log(data.band, data.score);
else console.log('pending, poll', data.check_id);
import os
import requests
response = requests.post(
"https://api.leeri.ai/v1/checks",
headers={
"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}",
"Idempotency-Key": "customer-8841-onboarding",
},
json={"subject": "address", "asset": "TRX", "address": address},
timeout=30,
)
data = response.json()["data"]
if data["status"] == "completed":
print(data["band"], data["score"])
else:
print("pending, poll", data["check_id"])
Respuesta
Las respuestas correctas usan un solo sobre: el status exterior es "ok", la verificación está en data y errors está vacío. Los errores usan en su lugar el sobre de error.
La verificación en sí tiene una única forma para todos los estados. Ramifique solo según data.status:
data.status | Significado |
|---|---|
completed | El veredicto terminó dentro de la solicitud y viene en la respuesta. |
pending | La verificación pasó a una cola. Sondee GET /v1/checks/{check_id} o espere un webhook; vea Pending y sondeo. |
failed | La verificación terminó sin veredicto. Nunca se cobra. POST responde 422 CHECK_FAILED; este estado lo verá al leer una verificación más tarde. |
Todos los campos están presentes en todos los estados. Cuando una verificación pending o failed aún no tiene nada que informar, el campo es null (o una lista vacía). A continuación se muestra un ejemplo abreviado de una verificación completada; los valores son ilustrativos.
{
"status": "ok",
"data": {
"check_id": "5b0c3f64-1a52-4c8e-9f3e-2f6c1d7a9e10",
"verdict_id": "0f4d7e1c-6b2a-4d39-8e55-3a9c2b8f7d41",
"status": "completed",
"subject": "address",
"asset": "TRX",
"chain": "tron",
"address": "TEXAMPLEexampleEXAMPLEexample00000",
"score": 74,
"band": "high",
"analysis_depth": "full",
"partial": false,
"partial_reasons": [],
"degraded_sources": [],
"ruleset_version": "v23",
"label_snapshot_id": "412345",
"chain_height": "68000000",
"findings": [
{
"rule_id": "heuristic:transit",
"category": "unknown",
"weight": "25",
"source": "chain-engine",
"source_url": "https://leeri.ai/rules/transit?v=v23",
"source_kind": "methodology",
"provider": null,
"observed": { "role": "subject", "score": 62 }
}
],
"report": {
"id": "r1_…",
"pdf_url": "…",
"json_url": "…",
"verification_url": "…"
},
"created_at": "2026-10-27T09:14:02.118Z",
"completed_at": "2026-10-27T09:14:04.907Z"
},
"errors": []
}
Cómo leer el veredicto
Identidad y tiempos
| Campo | Significado |
|---|---|
check_id | El id de la verificación. Úselo para sondear y para volver a leer la verificación. |
verdict_id | El id del veredicto que produjo la verificación, y el id que recibe POST /v1/verdicts/{verdict_id}/rederive. null hasta que la verificación termina. |
status | completed, pending o failed. |
subject | address o transaction. |
asset | El símbolo de activo que usted envió. |
chain | La cadena en la que vive el activo, por ejemplo tron. null si el activo no tiene ninguna. |
address | La dirección que se verificó. |
created_at, completed_at | Cuándo se aceptó la verificación y cuándo terminó. completed_at es null hasta entonces. |
Puntuación y nivel de riesgo
| Campo | Significado |
|---|---|
score | Un número de 0 a 100. null hasta que la verificación termina. |
band | El nivel de riesgo en el que cae la puntuación: low, medium, high o severe. null hasta que la verificación termina. |
analysis_depth | full para los activos que se verifican con recorrido del grafo y exposición por salto; label_only para los activos que se verifican con una búsqueda de etiqueta por dirección, sin recorrido. Ambas son respuestas reales y facturadas; este campo indica cuál recibió, de modo que un resultado label_only nunca se confunda con el más profundo. Vea Activos admitidos. |
En el ruleset actual los niveles son low para puntuaciones de 0 a 30, medium de 31 a 70, high de 71 a 90 y severe de 91 a 100. Los límites pertenecen a una versión del ruleset, así que lea el nivel del campo band en lugar de recalcularlo a partir de la puntuación.
Qué tan completo es el veredicto
La caída de una fuente de datos de terceros no se convierte en un error. La verificación responde con un veredicto que indica que está incompleto y por qué. Trate un veredicto parcial como un veredicto con menos evidencia, no como uno limpio.
| Campo | Significado |
|---|---|
partial | true cuando una fuente de la que depende el veredicto no estaba disponible o estaba desactualizada, el recorrido fue incompleto o la respuesta está acotada por un límite declarado del motor. |
partial_reasons | Los motivos, como códigos estables. Algunos indican un límite del análisis (un límite de profundidad o de tamaño del recorrido, solo contrapartes directas en Ethereum, BNB Smart Chain y Base); el veredicto es entonces el servicio completo para esa dirección y se factura. Otros indican que una fuente estaba caída; ese veredicto no se factura y puede volver a ejecutarse más tarde. La lista completa está en la referencia de la API. |
degraded_sources | Las fuentes que estaban caídas, indicadas como provider y nunca por nombre. Cualquier entrada aquí hace que el veredicto no sea facturable. |
provider_fallback | Qué respuestas almacenadas de una fuente de datos de terceros sustituyeron a la respuesta porque esa fuente no respondió, y qué antigüedad tiene la más antigua (addresses, reasons, oldest_answer_at, oldest_answer_age_days). null mientras la verificación está pending o failed. Un objeto con la lista addresses vacía cuando no se usó ninguna. |
coverage_limitations | Lo que la fuente de datos de la cadena no puede mostrar para este activo, indicado en el veredicto: evm_internal_transfers (la moneda nativa movida por una llamada a un contrato no es visible), untraced_inbound_majority (más de la mitad de los fondos entrantes no pudo rastrearse hasta una fuente, por lo que la puntuación puede subestimar la exposición) y unpriced_assets (se movió un activo que no pudo valorarse en USD). Son declaraciones, no resultados parciales: no activan partial ni cambian la facturación. |
exposureIndexLag | true cuando existe una ejecución de atribución de depósitos más reciente que los datos de exposición que usó este veredicto. Las etiquetas directas están disponibles; la atribución más profunda espera a la próxima regeneración. |
El pin
Un veredicto se deriva de tres coordenadas, registradas en él para poder reproducirlo exactamente como se emitió.
| Campo | Significado |
|---|---|
ruleset_version | La versión de las reglas de puntuación aplicadas. |
label_snapshot_id | La posición en el historial de etiquetas que leyó el veredicto. |
chain_height | La altura de la cadena a la que se derivó el veredicto. |
pin | Las mismas tres coordenadas en un objeto, más lo que el veredicto leyó del índice de exposición (index, y exposure con su method, execution_mode y otros campos). null mientras la verificación está pending o failed. |
Guarde check_id, verdict_id y el pin junto con su propio registro de decisión. Reproducir un veredicto (POST /v1/verdicts/{verdict_id}/rederive, scope checks:read) lo vuelve a ejecutar con su ruleset y su instantánea de etiquetas fijados, nunca con uno más reciente; vea Rederive.
Hallazgos
findings enumera las reglas que movieron la puntuación. Un hallazgo nunca es un número sin explicación: cada uno indica qué se activó y dónde está su evidencia.
| Campo | Significado |
|---|---|
rule_id | La regla que se activó. |
category | Nuestra categoría de etiqueta: exchange, mixer, sanctioned, scam, contract, bridge, merchant, unknown, ransomware, exploit, gambling, illicit, high_risk_exchange o unidentified_service. |
weight | Cuánto cuenta el hallazgo en la puntuación, como cadena decimal. |
source | De dónde procede el hallazgo: un código corto de una fuente pública, chain-engine para nuestras propias heurísticas, o provider cuando se apoya en una fuente de datos de terceros. Nunca se nombra ninguna fuente de datos. |
source_url | Un enlace que siempre se resuelve y nunca es null. |
source_kind | A qué apunta source_url. document es un documento de una fuente pública, como una lista de una autoridad o un evento de congelación publicado. methodology es una página versionada en https://leeri.ai/es/rules que describe qué detecta la regla y por qué se activó en esta versión del ruleset. |
provider | Siempre null para un hallazgo que se apoya en una fuente de datos de terceros. |
evidence_chain, evidence_tx_hash | La cadena y la transacción a las que apunta el hallazgo, cuando las hay. |
observed | Lo que observó la verificación detrás del hallazgo: el papel de la dirección, recuentos, importes en USD, saltos, las direcciones y transacciones implicadas. null solo para una verificación hecha antes de que se registraran las observaciones. Es evidencia, no puntuación. |
evidence_refs | Más evidencia estructurada. Trate las claves desconocidas como informativas. |
Exposición
exposure indica de dónde vino o adónde fue el dinero de la dirección, por categoría, salto y dirección, para que vea cuán indirecto es un vínculo de riesgo.
| Campo | Significado |
|---|---|
category | La categoría del grupo de contrapartes. |
hop, hop_to | La distancia desde la dirección verificada; 0 es una contraparte directa. Más allá del salto 8, un segmento cubre un rango de saltos, de hop a hop_to. |
direction | in para fondos recibidos, out para fondos enviados. |
amount_usd, share | El valor del segmento y su fracción del total, como cadenas decimales. |
address_count | Cuántas direcciones cubre el segmento. |
scoring | Si el segmento cuenta para la puntuación o se muestra solo como contexto. |
source | Presente como provider solo en un segmento informado por una fuente de datos de terceros. |
Los segmentos de nuestro propio recorrido no aparecen en un activo label_only, y la lista está vacía para una dirección que es en sí misma un contrato de token conocido; en ambos casos es intencionado, no porque el recorrido haya fallado.
Avisos de seguridad de la wallet
wallet_security_warnings contiene señales dirigidas al titular de la dirección verificada, como envenenamiento de direcciones, una imitación parecida o tokens falsificados. No dicen nada sobre que la dirección sea de riesgo y nunca cambian la puntuación, el nivel de riesgo ni ningún hallazgo. Cada una tiene rule_id, severity (critical, high, warning o info), source, source_url, source_kind (siempre methodology), observed y evidence_refs. La lista siempre está presente y vacía mientras la verificación está pending o failed.
Campos de transacción
tx_hash, direction, amount y risky_volume_usd describen una verificación de transacción y son null en una verificación de dirección. amount y risky_volume_usd son cadenas decimales, nunca números de coma flotante. Vea Verificaciones de transacción.
Campos de espera
pending_reason, deadline_at y next_attempt_at describen una verificación que sigue pending y son null cuando ya es terminal. Vea Pending y sondeo.
El informe de evidencias
report enlaza el informe de evidencias de una verificación completada; el informe está incluido en el precio de la verificación. Contiene id, pdf_url, json_url y verification_url, y es null mientras la verificación está pending o failed. El id es una capability: cualquiera que lo tenga puede abrir el informe, así que trátelo como el propio informe. El gemelo JSON lleva un hash de su contenido, y la página de verificación confirma que el informe es auténtico y no ha sido alterado; vea Informes de evidencias.
Facturación y errores
Volver a verificar la misma dirección en la misma cadena dentro de 7 días es gratis; vea Límites de solicitudes y cuotas. Errores que debe esperar de POST /v1/checks:
| Estado | Código | Cuándo |
|---|---|---|
400 | VALIDATION_ERROR | Un campo desconocido o ausente, o una dirección con una forma no válida para el activo. |
422 | UNSUPPORTED_ASSET | El activo no figura en Activos admitidos. |
402 | INSUFFICIENT_BALANCE | La cuota y el saldo prepagado están agotados. |
429 | PROVIDER_CAPACITY_EXCEEDED | La capacidad para consultas está llena. Reintente tras Retry-After; no se aceptó ni se cobró nada. |
503 | RULESET_UNAVAILABLE | No se pudo alcanzar ningún ruleset de puntuación. Nunca un veredicto de apariencia limpia y nunca se cobra. |
Los errores de autenticación y de límite de solicitudes se tratan en Autenticación y Límites de solicitudes y cuotas. Si hay un webhook registrado, una verificación completada también se entrega a él una vez; vea Webhooks.