Referencia de la API

La API de ARGUS devuelve el mismo veredicto que muestra el sitio: un resultado de cribado de sanciones en vivo, un desglose de exposición y las señales que respaldan la puntuación, como un objeto JSON por dirección. Está pensada para el momento previo al movimiento de los fondos — cribe una dirección en el momento del pago, actúe según la respuesta y conserve el objeto como registro de auditoría.

URL base y autenticación

Todos los endpoints se sirven por HTTPS desde una única URL base y se versionan en la ruta. Cada solicitud debe llevar una clave de API como token Bearer; no hay endpoints sin autenticar.

https://api.argus.example

Authorization: Bearer <your key>
Accept: application/json

Las claves son secretos. Envíelas desde un servidor, nunca desde un navegador — una clave entregada a un cliente es pública en cuanto se carga la página.

Cribar una dirección

Criba una dirección y devuelve un veredicto completo. El parámetro de ruta address es la única entrada: una dirección EVM (0x más 40 caracteres hexadecimales) o una dirección TRON (T más 33 caracteres base58). La red se infiere de la forma — una dirección EVM es la misma cadena de texto en todas las cadenas EVM, así que cribarla una vez las cubre todas.

curl https://api.argus.example/v1/screen/TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t \
  -H "Authorization: Bearer $ARGUS_API_KEY"

const address = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t";

const res = await fetch(`https://api.argus.example/v1/screen/${address}`, {
  headers: { Authorization: `Bearer ${process.env.ARGUS_API_KEY}` },
});

if (!res.ok) throw new Error(`Screening failed: ${res.status}`);

const verdict: ScreenResult = await res.json();

if (verdict.sanctions.hit !== null) {
  // Designated. Decisive on its own — decline before funds move.
}

type Band = "clear" | "caution" | "high" | "severe";

interface SanctionsHit {
  name: string;        // the designated person or entity
  uid: number | null;  // OFAC's SDN entry id
  type: string;        // "Individual" | "Entity"
  asset: string;       // ticker OFAC recorded the address under
  programs: string[];  // e.g. ["DPRK3", "CYBER2"]
}

interface ScreenResult {
  address: string;
  network: "evm" | "tron";

  score: number | null;  // 0–100; null when no score is justified
  band: Band | null;     // clear <30 · caution <55 · high <75 · severe

  sanctions: {
    hit: SanctionsHit | null;  // null = screened and not found,
                               // never "not screened"
    publishDate: string;       // OFAC's own date, MM/DD/YYYY
    addressCount: number;      // addresses in the screened snapshot
    sourceUrl: string;
  };

  exposure: {
    label: string;  // source category, e.g. "Mixer"
    share: number;  // percentage of inbound value
    band: Band | "unknown";
  }[];

  signals: {
    title: string;
    detail: string;
    band: Band | "unknown";
  }[];

  // true while exposure and signals carry sample figures pending the
  // graph indexer; the sanctions block is live regardless
  exposureIsIllustrative: boolean;
}

{
  "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "network": "tron",
  "score": null,
  "band": null,
  "sanctions": {
    "hit": null,
    "publishDate": "08/20/2026",
    "addressCount": 961,
    "sourceUrl": "https://ofac.treasury.gov/sanctions-list-service"
  },
  "exposure": [
    { "label": "Major exchange", "share": 61.4, "band": "clear" },
    { "label": "Unattributed", "share": 12.6, "band": "unknown" }
  ],
  "signals": [
    {
      "title": "Majority of inbound value from a regulated venue",
      "detail": "61.4% · withdrawal pattern consistent with retail",
      "band": "clear"
    }
  ],
  "exposureIsIllustrative": true
}

Por qué la puntuación puede ser null. Una puntuación compuesta necesita las capas de exposición, comportamiento y atribución, y todavía no están activas. Fabricar una cifra de todos modos produciría lo único que una herramienta de cribado nunca debe hacer: contradecirse — "hit": null en el bloque de sanciones junto a un "score": 94 inventado se lee como un generador de números aleatorios, y cuesta más confianza de la que jamás costaría un campo vacío. Por eso la puntuación solo está presente cuando una capa activa la justifica: una designación directa de OFAC devuelve 100 y "severe", y una contraparte designada hallada a un salto devuelve una puntuación alta con el hallazgo en signals. En caso contrario, tanto score como band son null, y su integración debe tratarlo como «sin puntuación», no como «riesgo bajo».

La misma honestidad se aplica a sanctions.hit: null — significa que la dirección se cribó contra la instantánea y no se encontró, y el publishDate que aparece al lado indica de qué instantánea se trata. Una designación posterior a esa fecha no aparecería. Mientras exposureIsIllustrative sea true, los arrays de exposición y de señales contienen cifras de ejemplo y no deben guiar ninguna decisión.

Cribado por lotes

Criba hasta 100 direcciones en una sola solicitud. Se pueden mezclar redes. Los resultados vuelven en el orden de entrada, y una entrada que no supera la validación se devuelve como objeto de error en su posición en lugar de hacer fallar todo el lote — una errata no debería anular los 99 veredictos que la acompañan.

curl -X POST https://api.argus.example/v1/screen/batch \
  -H "Authorization: Bearer $ARGUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "0xdAC17F958D2ee523a2206206994597C13D831ec7"
    ]
  }'

{
  "results": [
    { "address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "…": "…" },
    {
      "error": {
        "code": "invalid_address",
        "message": "TRON address failed base58check."
      }
    }
  ]
}

Cada dirección de un lote se contabiliza como una llamada. Los lotes de más de 100 entradas se rechazan con 400 invalid_request en lugar de truncarse en silencio.

Errores

Los errores son JSON con un código estable legible por máquina; el mensaje es para humanos y puede cambiar.

{
  "error": {
    "code": "invalid_address",
    "message": "TRON address failed base58check — likely a typo."
  }
}

Límites de solicitudes y medición

El acceso a la API forma parte del plan API de la página de precios: 0,04 $ por llamada, precio por volumen a partir de 50.000 llamadas, cribado por lotes sin límite. Los límites de abajo forman parte de esta especificación — publicados para su revisión como todo lo demás aquí, y confirmados en el lanzamiento.

Superar un límite devuelve 429 rate_limited con una cabecera Retry-After. Los límites se aplican por clave, no por IP.

Webhooks

Cribar una dirección una vez informa de ese momento. Después la lista se mueve: OFAC publica nuevas designaciones, y una dirección que el mes pasado salió limpia puede estar designada hoy. Los webhooks cierran esa brecha — cuando una dirección cribada previamente con su clave aparece en una publicación SDN más reciente, ARGUS envía un evento sanctions.designation al endpoint que haya configurado.

{
  "id": "evt_9f2c81d4",
  "type": "sanctions.designation",
  "createdAt": "2026-09-02T14:11:08Z",
  "data": {
    "address": "T111111111111111111111111111111111",
    "network": "tron",
    "firstScreenedAt": "2026-08-23T09:30:00Z",
    "hit": {
      "name": "EXAMPLE DESIGNATED ENTITY",
      "uid": 99999,
      "type": "Entity",
      "asset": "TRX",
      "programs": ["CYBER2"]
    },
    "listPublishDate": "09/01/2026"
  }
}

Las entregas se firman con una cabecera de firma HMAC-SHA256 para que pueda verificar que el payload procede de nosotros, y se reintentan con espera progresiva durante 24 horas hasta que su endpoint devuelva un 2xx. La dirección y la entidad de arriba son provisionales — la dirección no puede superar base58check y la entidad no existe.

Acceso anticipado

Todavía no se emiten claves. Si quiere desarrollar contra esta API — o ya le ve un problema — díganoslo desde la página de contacto, en «API y colaboraciones». Los integradores que revisen la especificación ahora recibirán las claves primero, y los cambios hechos antes del lanzamiento no cuestan nada.