Informes de direcciones

A menudo sabe sobre una dirección más de lo que sabe cualquier conjunto de datos: un cliente fue estafado a través de ella, o una dirección de depósito de su plataforma le pertenece. POST /v1/address-reports le permite enviarnos ese conocimiento. Hay dos tipos de informe.

report_type	Qué afirma	Qué necesita
abuse (por defecto)	La dirección se usa para abusos.	Una category y al menos una prueba verificable: evidence_url o evidence_tx_hash.
own_deposit	La dirección es una de sus propias direcciones de depósito.	Ni categoría ni prueba.

Qué hace un informe

Un informe entra en una cola de recepción independiente. Nunca cambia por sí solo un veredicto, una puntuación ni una etiqueta: el resultado del cribado sigue siendo el que determinan el ruleset y las etiquetas publicadas. Solo una revisión posterior puede convertir un informe en una etiqueta publicada. La cuenta que está detrás de un informe se conserva únicamente para el control de abusos y nunca se asocia a una etiqueta que pueda publicarse más tarde a partir de él.

El estado received de la respuesta es un acuse de recibo, no una decisión. No cuente con que un informe cambie el resultado de una verificación; siga aplicando su propia política a los veredictos que recibe.

Solicitud

POST /v1/address-reports con el scope checks:write (vea Autenticación).

Campo	Obligatorio	Descripción
chain	sí	tron, ethereum, bsc, base o bitcoin.
address	sí	La dirección, de hasta 160 caracteres. Se comprueba para la cadena, incluido el checksum cuando el formato lo tiene.
report_type	no	abuse (por defecto) o own_deposit.
category	para abuse	scam, illicit o exploit. No se acepta con own_deposit.
evidence	sí	Una breve descripción de lo que sabe, de 1 a 2000 caracteres.
evidence_url	para abuse, salvo que se envíe evidence_tx_hash	Un enlace público https que respalde el informe, de hasta 2048 caracteres. Nunca lo descargamos.
evidence_tx_hash	para abuse, salvo que se envíe evidence_url	Un hash de transacción de la misma cadena que muestre el abuso, de hasta 160 caracteres. Debe estar bien formado para la cadena.

Los campos desconocidos se rechazan. Acusar de abuso es grave: envíe solo lo que pueda sustentar.

curl

curl -s -X POST https://api.leeri.ai/v1/address-reports \
  -H "Authorization: Bearer $LEERI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "tron",
    "address": "'"$ADDRESS"'",
    "report_type": "abuse",
    "category": "scam",
    "evidence": "Received customer funds under a fake investment offer.",
    "evidence_tx_hash": "'"$TX_HASH"'"
  }'

Node.js

const response = await fetch('https://api.leeri.ai/v1/address-reports', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LEERI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    chain: 'tron',
    address,
    report_type: 'abuse',
    category: 'scam',
    evidence: 'Received customer funds under a fake investment offer.',
    evidence_tx_hash: txHash,
  }),
});
const { data } = await response.json();

console.log(response.status, data.report_id, data.duplicate);

Python

import os
import requests

response = requests.post(
    "https://api.leeri.ai/v1/address-reports",
    headers={"Authorization": f"Bearer {os.environ['LEERI_API_KEY']}"},
    json={
        "chain": "tron",
        "address": address,
        "report_type": "abuse",
        "category": "scam",
        "evidence": "Received customer funds under a fake investment offer.",
        "evidence_tx_hash": tx_hash,
    },
    timeout=30,
)
data = response.json()["data"]

print(response.status_code, data["report_id"], data["duplicate"])

Para confirmar una dirección de depósito propia, envíe "report_type": "own_deposit" con chain, address y evidence, sin categoría ni prueba.

Respuesta

Un informe nuevo responde 202; uno repetido responde 200. Ambos incluyen el informe en data:

Campo	Descripción
report_id	El id del registro de recepción. Estable entre repeticiones del mismo informe.
status	received.
chain, address	Tal como se almacenan: las direcciones EVM y bech32 se pasan a minúsculas, cualquier otra forma se conserva como se envió.
report_type, category	Tal como se presentaron. category es null en own_deposit.
duplicate	true cuando su cuenta ya había presentado un informe de este tipo para esta dirección en este entorno.
created_at	Cuándo se recibió el informe por primera vez.

Hay un informe por cuenta, entorno de la clave, cadena, dirección y tipo de informe. Presentarlo de nuevo responde 200 con el informe almacenado y duplicate: true, y nunca sobrescribe las pruebas que envió la primera vez.

Límites y errores

Los informes de direcciones están limitados a 10 por minuto por cuenta, entre todas sus claves; vea Límites de solicitudes y cuotas.

Estado	Código	Cuándo
400	VALIDATION_ERROR	Un campo desconocido; una dirección no válida para la cadena (formato o checksum); falta la categoría en un informe abuse o hay una categoría en uno own_deposit; un informe abuse sin evidence_url ni evidence_tx_hash; un evidence_url que no es https; o un hash de transacción mal formado para la cadena.
403	SCOPE_ERROR	La clave no tiene el scope checks:write.
429	RATE_LIMIT_EXCEEDED	Más de 10 informes en un minuto. Reintente tras Retry-After.
503	RATE_LIMIT_STORE_UNAVAILABLE	El almacén de límites no está disponible; la solicitud se rechaza en lugar de atenderse sin límite. Reintente en breve.