Referência da API

A API do ARGUS retorna o mesmo veredito que o site renderiza: um resultado de triagem de sanções ao vivo, um detalhamento da exposição e os sinais por trás da pontuação, como um objeto JSON por endereço. Ela foi projetada para o momento antes de os fundos se moverem — faça a triagem de um endereço na hora do pagamento, aja conforme a resposta e guarde o objeto como seu registro de auditoria.

URL base e autenticação

Todos os endpoints são servidos por HTTPS a partir de uma única URL base e são versionados no caminho. Toda requisição deve levar uma chave de API como token Bearer; não há endpoints sem autenticação.

https://api.argus.example

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

Chaves são segredos. Envie-as a partir de um servidor, nunca de um navegador — uma chave entregue a um cliente é pública no instante em que a página carrega.

Triagem de um endereço

Faz a triagem de um endereço e retorna um veredito completo. O parâmetro de caminho address é a única entrada: um endereço EVM (0x mais 40 caracteres hexadecimais) ou um endereço TRON (T mais 33 caracteres base58). A rede é inferida a partir do formato — um endereço EVM é a mesma string em todas as redes EVM, então triá-lo uma vez cobre todas elas.

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 que score pode ser null. Uma pontuação composta precisa das camadas de exposição, comportamento e atribuição, e elas ainda não estão ativas. Fabricar um número mesmo assim produziria a única coisa que uma ferramenta de triagem nunca deve fazer: contradizer a si mesma — "hit": null no bloco de sanções ao lado de um "score": 94 inventado soa como um gerador de números aleatórios, e custa mais confiança do que um campo vazio jamais custaria. Por isso a pontuação só está presente quando uma camada ativa a justifica: uma designação direta da OFAC retorna 100 e "severe", e uma contraparte designada encontrada a um salto retorna uma pontuação alta com a constatação em signals. Caso contrário, tanto score quanto band são null, e sua integração deve tratar isso como “sem pontuação”, não como “risco baixo”.

A mesma honestidade se aplica a sanctions.hit: null — significa que o endereço foi triado contra o snapshot e não foi encontrado, e o publishDate ao lado indica qual snapshot. Uma designação feita após essa data não apareceria. Enquanto exposureIsIllustrative for true, os arrays de exposição e de sinais trazem números de exemplo e não devem orientar decisões.

Triagem em lote

Faz a triagem de até 100 endereços em uma requisição. As redes podem ser misturadas. Os resultados voltam na ordem de entrada, e uma entrada que falha na validação é retornada como um objeto de erro em sua posição, em vez de derrubar o lote inteiro — um erro de digitação não deve anular os 99 vereditos ao lado.

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 endereço em um lote é contabilizado como uma chamada. Lotes com mais de 100 entradas são rejeitados com 400 invalid_request em vez de truncados silenciosamente.

Erros

Os erros são JSON com um código estável legível por máquina; a mensagem é para humanos e pode mudar.

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

Limites de taxa e medição

O acesso à API faz parte do plano API na página de preços: US$ 0,04 por chamada, preço por volume a partir de 50.000 chamadas, triagem em lote ilimitada. Os limites abaixo fazem parte desta especificação — publicados para revisão como tudo o mais aqui, e confirmados no lançamento.

Exceder um limite retorna 429 rate_limited com um cabeçalho Retry-After. Os limites se aplicam por chave, não por IP.

Webhooks

Triar um endereço uma vez informa sobre aquele momento. A lista muda depois: a OFAC publica novas designações, e um endereço que passou limpo no mês passado pode ser designado hoje. Os webhooks fecham essa lacuna — quando um endereço que sua chave já triou aparece em uma publicação SDN mais recente, o ARGUS envia um evento sanctions.designation para o endpoint 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"
  }
}

As entregas são assinadas com um cabeçalho de assinatura HMAC-SHA256 para que se possa verificar que o payload veio de nós, e são reenviadas com backoff por 24 horas até o endpoint retornar um 2xx. O endereço e a entidade acima são provisórios — o endereço não passa no base58check e a entidade não existe.

Acesso antecipado

Ainda não estamos emitindo chaves. Se quiser desenvolver com esta API — ou se já enxerga um problema nela — diga isso pela página de contato, em “API e parcerias”. Integradores que revisarem a especificação agora recebem chaves primeiro, e mudanças feitas antes do lançamento não custam nada.