Skip to content

api-pt.md

Latest commit

 

History

History
210 lines (166 loc) · 6.9 KB

api-pt.md

File metadata and controls

210 lines (166 loc) · 6.9 KB
Raw

AuditKey Public API — documentação

Base: https://api.auditkey.co.

Todas as respostas são JSON {"ok": true|false, ...}.

Autenticação

Envie a chave secreta em cada pedido no header X-Auth. A chave é criada no painel (Configurações → Integrações) e tem de estar com TokStatus = Active.

curl -H "X-Auth: $TOKEN" "https://api.auditkey.co/v1/check?address=0x…"

Regras:

  • Chave em ASCII imprimível, sem espaços, entre 8 e 512 caracteres.
  • Limite: 60 pedidos por minuto por chave (janela fixa de 60 s). TokLimit na chave substitui esse valor quando estiver definido.
  • Ao exceder, a API responde 429 com Retry-After (segundos).
  • O uso mensal aparece na aba Integrações.
HTTP Body Significado
401 {"ok": false, "error": "unauthorized"} Header ausente, malformado ou chave desconhecida
403 {"ok": false, "error": "token inactive"} Chave existe, mas não está Active
429 {"ok": false, "error": "rate limit"} Limite por minuto excedido
500 {"ok": false, "error": "internal error"} Falha ao resolver a chave ou erro interno

GET /health não exige autenticação.

GET /v1/check?address={address}

Label e risco de um endereço. A chain não vai na URL: é inferida pelo formato (EVM, Bitcoin, Tron, Solana). Um endereço EVM é o mesmo em todas as chains EVM.

curl -H "X-Auth: $TOKEN" \
  "https://api.auditkey.co/v1/check?address=0x1111111111111111111111111111111111111111"

Resposta:

{
  "ok": true,
  "chain": "ethereum",
  "address": "0x1111111111111111111111111111111111111111",
  "label": "Lazarus Group",
  "category": "sanctions",
  "tier": "illicit",
  "score": 100,
  "band": "severe",
  "decision": "reject",
  "resolver_version": "2026.09.09",
  "ruleset_version": "2026.09.09",
  "evaluated_at": "2026-09-09T00:00:00Z",
  "raw_label": "LAZARUS GROUP",
  "findings": [
    {
      "tier": "illicit",
      "category": "sanctions",
      "label": "Lazarus Group",
      "raw_label": "LAZARUS GROUP",
      "source": "ofac_sdn",
      "confidence": 1.0,
      "event_type": "sanction_listed",
      "attrs": { "entity": "lazarus_group" }
    }
  ]
}

Faixas de score: 0–24 low, 25–49 medium, 50–74 high, 75–100 severe. A pontuação é calculada na consulta. Labels informativos (vítima, apreensão, burn) não somam.

tier é o eixo de risco. category pode manter contexto (ex. cex) mesmo com tier=illicit.

Cada item de findings traz tier, category, label, source e confidence. Campos opcionais: event_type, raw_label, observed_at, first_seen_at, attrs, amount_usd, counterparty, weight. A API pública não devolve id, active, status nem occurrences.

Se a conta da chave tiver um label customizado para o endereço, label e raw_label passam a ser esse texto. score, decision e findings não mudam.

400 com invalid address quando o endereço não é EVM, Bitcoin, Tron nem Solana.

GET /v1/transfer?chain={chain}&hash={hash}

Consulta uma transação pelo hash e devolve as transferências dentro dela (movimento nativo e logs de token). Não devolve a transação bruta: sem gas, nonce, input nem receipt.

Alias de compatibilidade: GET /transfer com os mesmos parâmetros.

curl -H "X-Auth: $TOKEN" \
  "https://api.auditkey.co/v1/transfer?chain=eth&hash=0xabc…64hex"

chain aceita o slug ou um alias:

Slug Aliases
eth ethereum, mainnet
polygon matic
base
arb arbitrum
op optimism
bsc bnb
avax avalanche
bitcoin btc
tron trx
solana sol

Hash: EVM 0x + 64 hex (o 0x é opcional na entrada); Bitcoin e Tron 64 hex; Solana assinatura base58.

Resposta:

{
  "ok": true,
  "transactionHash": "0xabc…",
  "blockTimestamp": "2024-01-01 00:00:00",
  "chain": "eth",
  "source": "etherscan",
  "transfers": [
    {
      "fromAddress": "0x…",
      "fromLabel": null,
      "fromIsContract": false,
      "toAddress": "0x…",
      "toLabel": "Uniswap V3 Pool",
      "toIsContract": true,
      "tokenName": "USD Coin",
      "tokenSymbol": "USDC",
      "tokenAddress": "0x…",
      "type": "token",
      "unitValue": "198.44",
      "historicalUSD": 198.44,
      "index": 12
    }
  ]
}

type é native (moeda da chain; tokenAddress fica null) ou token. index é o log index; a perna nativa usa -1. Se a transação não move valor, a resposta traz uma perna nativa com valor zero para preservar remetente e destinatário. fromLabel / toLabel usam o label da conta quando existir.

HTTP error Significado
400 invalid chain or transaction hash Chain ou hash inválidos
404 transaction not found Hash não encontrado na fonte
502 upstream provider error Explorador ou RPC falhou
503 data source unavailable Nenhuma fonte configurada

GET /v1/transferbyaddress?chain={chain}&address={address}&limit={n}

Histórico de transferências de um endereço na chain pedida. Cada item inclui o hash e o horário da transação de origem.

Alias de compatibilidade: GET /transferbyaddress com os mesmos parâmetros.

curl -H "X-Auth: $TOKEN" \
  "https://api.auditkey.co/v1/transferbyaddress?chain=polygon&address=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&limit=50"

chain usa a mesma tabela de slugs e aliases de /v1/transfer. O endereço tem de pertencer à família dessa chain (EVM com eth/polygon/…, Bitcoin, Tron ou Solana).

limit é opcional. Predefinição 50. Mínimo 1, máximo 1000. Valor inválido responde 400 com invalid limit.

Resposta:

{
  "ok": true,
  "chain": "polygon",
  "address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
  "limit": 50,
  "source": "etherscan",
  "transfers": [
    {
      "transactionHash": "0xabc…",
      "blockTimestamp": "2024-01-01 00:00:00",
      "chain": "polygon",
      "fromAddress": "0x…",
      "fromLabel": null,
      "fromIsContract": false,
      "toAddress": "0x…",
      "toLabel": null,
      "toIsContract": false,
      "tokenName": "BRZ",
      "tokenSymbol": "BRZ",
      "tokenAddress": "0x…",
      "type": "token",
      "unitValue": "198.44",
      "historicalUSD": 198.44,
      "index": 3
    }
  ]
}

Os campos de cada transferência são os mesmos de /v1/transfer, mais transactionHash, blockTimestamp e chain em cada linha.

HTTP error Significado
400 invalid chain or address Chain desconhecida ou endereço incompatível com a chain
400 invalid limit limit fora de 1–1000
502 upstream provider error Explorador ou RPC falhou
503 data source unavailable Nenhuma fonte configurada

POST /v1/classify / POST /v1/classify/batch

Classificação on-demand de contratos EVM.

Spec

Fonte de verdade do label/risk: specs/api/v1.md.