GET /apiv2/compliance/

Consulta de cumplimiento abierta y sin clave para una sola dirección TRON. Devuelve un veredicto — si la dirección está bloqueada y en qué categoría — servido completamente desde una caché de lista de denegación en memoria. Sin clave API, sin saldo, sin costo. El objetivo es permitir que cualquiera integre la capa de cumplimiento con un solo HTTP GET.

El endpoint lee únicamente de una caché, nunca de la base de datos o de un nodo de la cadena, por lo que una consulta toma una fracción de milisegundo. Su tasa está limitada por IP mediante la pasarela.

URL del endpoint

GET https://netts.io/apiv2/compliance/{address}

No se requieren encabezados de autenticación.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
address	string	Sí	Dirección base58 de TRON — T seguida de 33 caracteres

Solicitudes de ejemplo

cURL

curl https://netts.io/apiv2/compliance/TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL

Python

import requests

address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL"
r = requests.get(f"https://netts.io/apiv2/compliance/{address}")
data = r.json()

if r.status_code == 200:
    d = data["data"]
    print(f"blocked : {d['blocked']}")
    print(f"category: {d['category']}")
    if d["category"] == "aml_risk":
        print(f"reason  : {d.get('reason_code')} — {d.get('label')}")
else:
    print(f"Error: {data}")

JavaScript

const address = "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL";
const res = await fetch(`https://netts.io/apiv2/compliance/${address}`);
const { data } = await res.json();
console.log(data.blocked, data.category, data.label);

Respuesta

Bloqueada — en la lista de denegación central (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL",
        "blocked": true,
        "category": "aml_risk",
        "severity": "BLOCK",
        "reason_code": "SANCTIONS_SCREENING",
        "label": "DPRK Bitget Exploit - September 2026",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": ["aml_risk"],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Billetera GasFree — un smart contract que puede recibir USDT (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TZEMF5vmSABaWjeUPty8kFpUsquMAKhGFp",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "gasfree_wallet",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T12:00:00+00:00"
    }
}

Contrato eliminado — la dirección aún cuenta como smart contract (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TBtrogXC58EAvE7vod56ZnzRY4y5jrwtbN",
        "blocked": true,
        "category": "smart_contract",
        "subtype": "selfdestructed_contract",
        "subtype_status": "confirmed",
        "matches": ["smart_contract"],
        "checks_complete": true,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

Limpia — en ninguno de los conjuntos (200 OK)

{
    "code": 0,
    "status": "ok",
    "data": {
        "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC",
        "blocked": false,
        "category": "clean",
        "subtype": null,
        "subtype_status": "not_found",
        "matches": [],
        "checks_complete": true,
        "checked_at": "2026-09-27T12:00:00+00:00"
    }
}

Campos de respuesta

Campo	Tipo	Descripción
data.address	string	La dirección que fue verificada
data.blocked	boolean	true si la dirección está en algún conjunto de bloqueo
data.category	string	aml_risk, usdt_frozen, smart_contract, spam_sender o clean (ver abajo); el endpoint por lotes también puede devolver invalid o unavailable
data.severity	string	Solo para aml_risk. Ej. BLOCK, REVIEW
data.reason_code	string	Solo para aml_risk. Código de máquina, ej. SANCTIONS_OFAC_SDN
data.label	string	Solo para aml_risk. Etiqueta legible por humanos
data.subtype	string | null	Refina smart_contract. gasfree_wallet — una billetera GasFree activa (ver Billeteras GasFree); selfdestructed_contract — el contrato en esta dirección ha sido eliminado (ver Contratos eliminados); null en caso contrario
data.subtype_status	string	confirmed — el subtipo se conoce por el último estado confirmado; not_found — no aplica ningún subtipo; unavailable — no se pudo consultar una lista de subtipos en este momento, por lo que subtype es null y no indica nada
data.matches	string[]	Todos los conjuntos en los que está la dirección, en orden de prioridad (ej. ["usdt_frozen", "smart_contract", "spam_sender"]). category es solo el primero de ellos
data.checks_complete	boolean	true si los cuatro conjuntos estaban cargados y actualizados en el momento de la consulta. false significa que una respuesta clean se basa en una verificación incompleta
data.checked_at	string	Marca de tiempo UTC ISO-8601 de la consulta

Categorías

category es un veredicto, no una puntuación de riesgo. Cuando una dirección está en más de un conjunto, prevalece la categoría más grave, en este orden (todas ellas se enumeran en matches):

Categoría	blocked	Significado
aml_risk	true	En la lista de denegación central: sanciones, estafas, ransomware, activos robados, fraude, investigaciones policiales o de abuso interno. Se adjunta una razón seleccionada
usdt_frozen	true	La dirección está congelada por el emisor de USDT (Tether). No puede mover USDT, por lo que se rechaza la delegación de recursos hacia ella
smart_contract	true	Una dirección de smart contract conocida, incluidos contratos eliminados posteriormente. Consulte la nota a continuación
spam_sender	true	Remitente de spam masivo confirmado
clean	false	En ninguno de los conjuntos
unavailable	null	La lista de denegación central no se pudo consultar, por lo que la dirección no está ni confirmada como limpia ni bloqueada. Solo por lotes; el endpoint de dirección única devuelve 503 con code 5004 en su lugar. Ver Lista de denegación central no disponible

Los smart contracts están bloqueados por una razón técnica, no de AML

Un veredicto de smart_contract significa que la dirección pertenece a un contrato, no a una billetera de usuario, por lo que no se le delega energía y la dirección se rechaza antes de que se cree una orden. El conjunto contiene cada dirección donde se creó con éxito un contrato, incluidos los contratos que fueron eliminados más tarde — un contrato eliminado no convierte su dirección en una billetera de usuario. Esto no significa que el contrato esté comprometido, contaminado o sea de alto riesgo bajo AML. La mayoría de los contratos en este conjunto son perfectamente ordinarios. Trate smart_contract como "no es un objetivo de delegación", no como una señal de riesgo.

Billeteras GasFree

Una billetera GasFree es un contrato que permite a su propietario recibir y enviar tokens y pagar la tarifa de red en esos tokens. Cada una es creada por el controlador GasFree TFFAMQLZybALaLb4uxHA9RBE7pxhUAjF3U. Dicha dirección se reporta como category: "smart_contract" con subtype: "gasfree_wallet".

La diferencia es importante cuando enruta fondos:

	Smart contract ordinario	Billetera GasFree
Enviar USDT hacia ella	no es un destinatario normal	sí — es la billetera de un usuario
Delegarle energía	no	no — no delegamos energía a billeteras GasFree
category / subtype	smart_contract / null	smart_contract / gasfree_wallet

Cobertura y advertencias:

• Solo se conocen las billeteras desplegadas. Una dirección GasFree que ha recibido USDT pero nunca ha enviado nada aún no está desplegada, por lo que no está en ningún conjunto y se devuelve como clean.
• El subtipo describe dónde puede recibir fondos la dirección. No dice nada sobre transferencias desde una billetera GasFree; examine la dirección del remitente por separado.
• subtype_status: "unavailable" significa que la lista de GasFree no pudo ser consultada. El resto del veredicto (blocked, category, matches) sigue siendo válido.
• El controlador en sí y otros contratos no son billeteras GasFree: se devuelven con subtype: null.

Contratos eliminados

Un contrato puede eliminarse a sí mismo (autodestruirse). La dirección permanece en el conjunto smart_contract: era una dirección de contrato, no una billetera de usuario, y Netts no delega recursos ni envía pagos a ella. Dicha dirección se reporta como category: "smart_contract" con subtype: "selfdestructed_contract".

• confirmed significa eliminado según el último estado confirmado por un nodo TRON. No es una promesa sobre el futuro: se puede desplegar un contrato en la misma dirección nuevamente, y entonces el subtipo se elimina mientras la dirección permanece como smart_contract.
• Una llamada de autodestrucción por sí sola no significa la eliminación: en TRON, un contrato creado en una transacción anterior conserva su código después de ella. Solo cuenta el estado del nodo.
• Si una dirección es tanto un contrato eliminado como parte de una lista GasFree, prevalece selfdestructed_contract — la dirección no se reporta como una billetera GasFree funcional.
• subtype_status: "unavailable" significa que la lista de contratos eliminados no pudo ser consultada; el resto del veredicto sigue siendo válido, y ninguna dirección se confirma como billetera GasFree hasta que pueda consultarse nuevamente.

Códigos de razón y el proveedor de datos

Para aml_risk, el reason_code y la label describen por qué la dirección está listada. Las autoridades sancionadoras públicas se mantienen tal cual — SANCTIONS_OFAC_SDN, SANCTIONS_EU_FSF, SANCTIONS_UK_FCDO, etcétera. El nombre del proveedor comercial de evaluación detrás de un hallazgo nunca se expone: dichos códigos se normalizan a SANCTIONS_SCREENING, y cualquier nombre de proveedor se elimina de label.

Tamaño de la lista de denegación

GET https://netts.io/apiv2/compliance/stats

Tamaños agregados de los conjuntos detrás del veredicto, desde la misma caché. Abierto y sin clave.

{
    "code": 0,
    "status": "ok",
    "data": {
        "aml_risk": 1079,
        "usdt_frozen": 8022,
        "smart_contract": 7581686,
        "spam_sender": 27039018,
        "gasfree_wallets_subset": 512487,
        "selfdestructed_contracts_subset": 4065766,
        "total": 34629805,
        "revision": 1117,
        "checked_at": "2026-10-23T21:40:00+00:00"
    }
}

smart_contract es la parte neutral respecto a AML más grande del total — consulte la nota sobre contratos arriba. gasfree_wallets_subset (billeteras GasFree activas) y selfdestructed_contracts_subset (contratos eliminados) son partes de smart_contract; no se suman a total. Si uno de estos dos contadores no se puede leer en este momento, es null y los otros números aún se devuelven.

Consulta por lotes (clave API)

Para verificar muchas direcciones a la vez, utilice el endpoint por lotes autenticado. Existe para ahorrar viajes de ida y vuelta en la red: una solicitud y una canalización interna en lugar de N GETs separados. Una sola dirección es simplemente una matriz de un solo elemento.

POST https://netts.io/apiv2/compliance/batch
x-api-key: YOUR_KEY
Content-Type: application/json

{ "addresses": ["TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC"] }

Hasta 1000 direcciones por solicitud. Los veredictos se devuelven en el mismo orden, cada uno con los mismos campos que la respuesta de dirección única (incluidos subtype, subtype_status, matches y checks_complete), más category: "invalid" (con un campo error) para cualquier entrada malformada — una entrada incorrecta no hace fallar todo el lote. Si la lista de denegación central no está cargada, una dirección que de otro modo estaría limpia se devuelve como category: "unavailable" (blocked: null, con un campo error) en lugar de clean — consulte Lista de denegación central no disponible.

{
    "code": 0,
    "status": "ok",
    "data": {
        "count": 2,
        "checked_at": "2026-09-27T12:00:00+00:00",
        "results": [
            { "address": "TTVUvAWUZafeHqQP82sYnfk4jNFPEHCRpL", "blocked": true, "category": "aml_risk", "subtype": null, "subtype_status": "not_found", "matches": ["aml_risk"], "checks_complete": true, "severity": "BLOCK", "reason_code": "SANCTIONS_SCREENING", "label": "DPRK Bitget Exploit - September 2026" },
            { "address": "TWaGxHZ9pFCFwUyzKtDsGNb6hEJ7tSjxEC", "blocked": false, "category": "clean", "subtype": null, "subtype_status": "not_found", "matches": [], "checks_complete": true }
        ]
    }
}

El endpoint por lotes requiere una clave API (encabezado x-api-key) y la clave puede vincularse opcionalmente a una lista blanca de IP. Contáctenos para obtener una clave.

Su límite de tasa es por clave y superior al del endpoint público de dirección única:

Período	Límite
1 segundo	200 solicitudes
1 minuto	12,000 solicitudes

Cada solicitud puede contener hasta 1000 direcciones, por lo que una sola clave puede evaluar más de cien mil direcciones por segundo dentro de este límite.

Respuestas de error

Formato de dirección no válido (400)

{
    "code": 1001,
    "status": "error",
    "msg": "Invalid TRON address format (expected base58, 'T' + 33 chars)"
}

Servicio temporalmente no disponible (503)

{
    "code": 5003,
    "status": "error",
    "msg": "compliance service temporarily unavailable"
}

Lista de denegación central no disponible (503, código 5004)

El veredicto se sirve desde una caché en memoria. Si esa caché es accesible pero la lista de denegación AML central no está cargada actualmente, o su revisión actual falla una comprobación de integridad, el endpoint no recurre a clean — eso informaría una dirección no verificada como segura. En su lugar, le informa claramente que no pudo producir un veredicto:

{
    "code": 5004,
    "status": "error",
    "msg": "compliance deny-list temporarily unavailable, verdict cannot be produced"
}

Qué significa esto: la dirección no está ni confirmada como limpia ni bloqueada. El servicio no pudo evaluarla frente a la lista de sanciones/AML en este momento. No trate la dirección como limpia — vuelva a intentarlo en breve.

Un bloqueo definitivo aún se devuelve normalmente: si la dirección coincide con USDT congelado, smart contract o remitente de spam (conjuntos que no dependen de la lista central), obtendrá el veredicto habitual blocked: true incluso en este estado. Solo una respuesta que de otro modo sería clean se convierte en 5004.

En el endpoint por lotes se informa la misma situación por dirección como category: "unavailable" (blocked: null, con un campo error); el resto del lote no se ve afectado. Este es un estado transitorio y poco común.

Registro no disponible (503, código 5005)

Los conjuntos se actualizan in situ y permanecen legibles mientras se actualizan, por lo que una actualización rutinaria nunca afecta al veredicto. Solo si un conjunto no se pudo aplicar, una dirección que de otro modo estaría limpia no podrá confirmarse como limpia. El endpoint de dirección única devuelve entonces:

{
    "code": 5005,
    "status": "error",
    "msg": "address registry temporarily unavailable, verdict cannot be produced, retry shortly"
}

Al igual que con 5004, un bloqueo definitivo aún se devuelve normalmente, y el endpoint por lotes informa el caso por dirección como category: "unavailable". Vuelva a intentarlo más tarde.

Referencia de códigos de error

Código	Descripción	Estado HTTP
0	Éxito	200
1001	Formato de dirección TRON no válido	400
5003	Backend de caché temporalmente no disponible	503
5004	Lista de denegación central no cargada — no se puede producir el veredicto (reintentar)	503
5005	No se pudo aplicar un conjunto — no se puede producir el veredicto (reintentar)	503

Límites de tasa

Existen dos niveles, aplicados en la pasarela:

Endpoint	Autenticación	Limitado por	1 segundo	1 minuto
GET /apiv2/compliance/{address}	abierta, sin clave	IP	10	300
GET /apiv2/compliance/stats	abierta, sin clave	IP	10	300
POST /apiv2/compliance/batch	clave API	clave	200	12,000

El endpoint abierto de dirección única está pensado para un uso interactivo y programático ligero. Para la evaluación masiva, utilice el endpoint por lotes: con hasta 1000 direcciones por solicitud y 200 solicitudes/segundo por clave, una sola clave evalúa más de cien mil direcciones por segundo. ¿Necesita más? El límite por clave es un ajuste de política, no un techo técnico — contáctenos.

Límite de tasa excedido (429)

{
    "message": "API rate limit exceeded"
}

Notas

• Sin autenticación y sin costo. Cualquiera puede llamarlo; no hay nada que firmar.
• Solo caché. El veredicto nunca toca la base de datos ni un nodo, por lo que es rápido y seguro consultarlo periódicamente dentro del límite de tasa.
• No es un informe AML completo. Para obtener una puntuación de riesgo, desglose de exposición y un informe firmado, utilice la API de evaluación autenticada (POST /apiv2/screening). Este endpoint responde a una sola pregunta más específica: si la dirección está en nuestra lista de denegación y por qué.