Documentação de uso da API AuditKey

Visão geral

A API expõe endpoints HTTP GET para consulta de rótulos, risco e transferências em redes blockchain.

Nos exemplos abaixo, substitua:

https://api.auditkey.co é a URL base da API;
SEU_TOKEN pelo token de acesso;
endereços e hashes pelos valores que deseja consultar.

Autenticação

Todos os endpoints, exceto GET /health, exigem o token no cabeçalho X-Auth:

curl -H "X-Auth: SEU_TOKEN" \
  "https://api.auditkey.co/label?address=0x1111111111111111111111111111111111111111"

Tokens ausentes ou inválidos retornam 401. Um token inativo retorna 403. Quando o limite de requisições é excedido, a API retorna 429 e informa no cabeçalho Retry-After quantos segundos devem ser aguardados.

Todas as respostas são JSON.

Redes suportadas

Os endpoints de transferência recebem o parâmetro chain. Os slugs canônicos e aliases aceitos são:

Ethereum: eth, ethereum, ethereum mainnet, mainnet
Polygon: polygon, matic
Base: base
Arbitrum: arb, arbitrum, arbitrum one
Optimism: op, optimism, op mainnet
BNB Smart Chain: bsc, bnb, bnb smart chain
Avalanche C-Chain: avax, avalanche, avalanche c-chain
Bitcoin: bitcoin, btc
Tron: tron, trx
Solana: solana, sol

A resposta sempre utiliza o slug canônico.

`GET /label`

Consulta rótulos, registros de risco e informações de contrato de um endereço. A rede é identificada automaticamente pelo formato do endereço.

Parâmetros

address — obrigatório; endereço EVM, Bitcoin, Tron ou Solana.

Exemplo

curl -H "X-Auth: SEU_TOKEN" \
  "https://api.auditkey.co/label?address=0x1111111111111111111111111111111111111111"

Exemplo de resposta

{
  "ok": true,
  "address": "0x1111111111111111111111111111111111111111",
  "chain": "evm",
  "label": "Exemplo",
  "labels": [
    {
      "label": "Exemplo",
      "category": "cex",
      "subcategory": "deposit",
      "source": "fonte",
      "observed_at": "2026-07-19 12:00:00",
      "note": "",
      "account_type": "contract",
      "contract_pattern": ["multisig"]
    }
  ],
  "riskLabels": [
    {
      "risk_tier": "illicit",
      "category": "sanctions",
      "subcategory": "ofac",
      "label": "OFAC SDN",
      "source": "ofac_sdn",
      "status": "blocked",
      "observed_at": "2026-07-19 12:00:00",
      "account_type": "unknown",
      "contract_pattern": []
    }
  ],
  "riskAddresses": [
    {
      "label": "OFAC SDN",
      "risk_category": "sanctions",
      "source": "ofac_sdn",
      "status": "blocked",
      "observed_at": "2026-07-19 12:00:00",
      "tx_hash": "",
      "note": ""
    }
  ],
  "exposure": [],
  "contract": {
    "protocol_name": "Protocolo",
    "contract_type": "token",
    "display_name": "Contrato de exemplo"
  }
}

label e contract podem ser null; as listas podem estar vazias. Para endereços não EVM, contract é null.

riskLabels é a forma canônica (taxonomia risk_tier / category / subcategory). riskAddresses permanece por compatibilidade com clientes antigos (risk_category plano, derivado das mesmas linhas). exposure lista hops derivados (*_address_exposure).

Campos opcionais em labels / riskLabels (quando preenchidos no ClickHouse): account_type (eoa | contract | precompile | system | unknown) e contract_pattern (array, ex.: multisig, proxy_minimal_1167, honeypot_pattern). São dimensões ortogonais à categoria e alimentam o context_modifier em /check — nunca criam risco sozinhas. Multisig nunca é category.

`GET /check`

Calcula o risco de um endereço em uma escala de 0 a 100 (consulta, não persistido), com band, decision e ruleset_version. O campo risk (0–10) permanece por compatibilidade (score / 10).

Parâmetros

address — obrigatório; endereço EVM, Bitcoin, Tron ou Solana.

Exemplo

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

Exemplo de resposta

{
  "ok": true,
  "address": "0x1111111111111111111111111111111111111111",
  "chain": "evm",
  "score": 100,
  "band": "severe",
  "decision": "reject",
  "ruleset_version": "2026.09.01",
  "evaluated_at": "2026-09-02T14:22:10Z",
  "triggered_rules": [
    "reject WHEN risk_tier = 'illicit' AND category = 'sanctions' AND status = 'blocked'"
  ],
  "label": "Endereço bloqueado",
  "risk": 10,
  "summary": {
    "illicit": {"count": 1, "amount_usd": 0.0}
  }
}

Interpretação da pontuação:

75–100 (severe) — atribuição ilícita direta (ex.: OFAC);
50–74 (high) — exposição material (mixer, hops);
25–49 (medium);
0–24 (low) — sem sinal relevante, vítimas/informativo não pontuam.

decision segue reject > hold > flag > approve. O campo risk 0–10 é compatibilidade (round(score / 10)); use score / band / decision como fonte de verdade.

`GET /transfer`

Consulta uma transação por hash e retorna suas transferências. A descoberta tenta primeiro o BigQuery e, quando não há resultado ou ele está indisponível, utiliza APIs de scanner ou RPC. O ClickHouse é usado apenas para enriquecer rótulos, contratos e preços históricos.

Parâmetros

chain — obrigatório; slug ou alias de uma rede suportada;
hash — obrigatório; hash da transação.

Hashes EVM podem ser enviados com ou sem o prefixo 0x. Hashes de Bitcoin e Tron também aceitam o prefixo 0x. Assinaturas Solana devem estar em Base58.

Exemplo

curl -H "X-Auth: SEU_TOKEN" \
  "https://api.auditkey.co/transfer?chain=eth&hash=0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

Exemplo de resposta

{
  "ok": true,
  "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "blockTimestamp": "2026-07-19 12:00:00",
  "chain": "eth",
  "transfers": [
    {
      "fromAddress": "0x1111111111111111111111111111111111111111",
      "fromLabel": "Carteira A",
      "fromIsContract": false,
      "toAddress": "0x2222222222222222222222222222222222222222",
      "toLabel": "Carteira B",
      "toIsContract": false,
      "tokenName": "USD Coin",
      "tokenSymbol": "USDC",
      "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "type": "token",
      "unitValue": "10",
      "historicalUSD": 10.0,
      "index": 0
    }
  ],
  "source": "bigquery"
}

Uma transação pode conter várias entradas em transfers. Para transferência da moeda nativa, type é native e tokenAddress é null. Campos de enriquecimento podem ser null quando não houver dados.

`GET /transferbyaddress`

Lista transferências em que um endereço aparece como origem ou destino. O BigQuery é consultado primeiro com uma janela de busca limitada; quando não há resultado ou ele está indisponível, a API usa o scanner da rede.

Parâmetros

chain — obrigatório; slug ou alias de uma rede suportada;
address — obrigatório; deve ser válido para a rede informada;
limit — opcional; número máximo de transferências, de 1 a 1000. O padrão é 50.

Exemplo

curl -H "X-Auth: SEU_TOKEN" \
  "https://api.auditkey.co/transferbyaddress?chain=eth&address=0x1111111111111111111111111111111111111111&limit=50"

Exemplo de resposta

{
  "ok": true,
  "chain": "eth",
  "address": "0x1111111111111111111111111111111111111111",
  "limit": 50,
  "transfers": [
    {
      "transactionHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "blockTimestamp": "2026-07-19 12:00:00",
      "chain": "eth",
      "fromAddress": "0x1111111111111111111111111111111111111111",
      "fromLabel": "Carteira A",
      "fromIsContract": false,
      "toAddress": "0x2222222222222222222222222222222222222222",
      "toLabel": null,
      "toIsContract": false,
      "tokenName": "Ether",
      "tokenSymbol": "ETH",
      "tokenAddress": null,
      "type": "native",
      "unitValue": "0.5",
      "historicalUSD": 1750.0,
      "index": -1
    }
  ],
  "source": "bigquery"
}

As fontes não são combinadas: o primeiro provedor que retorna dados é utilizado. Uma lista vazia é uma resposta válida quando o provedor consultado não encontra transferências.

`GET /health`

Verifica a conectividade da API com MySQL e ClickHouse. Este é o único endpoint que não exige autenticação.

Exemplo

curl "https://api.auditkey.co/health"

Resposta saudável

{
  "ok": true,
  "mysql": true,
  "clickhouse": true
}

Retorna 503 se uma das dependências não estiver disponível.

Erros

Os erros seguem o formato:

{
  "ok": false,
  "error": "mensagem do erro"
}

Principais códigos HTTP:

400 — parâmetros inválidos;
401 — token ausente ou inválido;
403 — token inativo;
404 — rota ou transação não encontrada;
405 — método HTTP não permitido;
414 — URL longa demais;
429 — limite de requisições excedido;
500 — erro interno;
502 — erro em um provedor externo;
503 — fonte de dados ou dependência indisponível.

Navigation Menu

Uh oh!

Documentação de uso da API AuditKey

Visão geral

Autenticação

Redes suportadas

`GET /label`

Parâmetros

Exemplo

Exemplo de resposta

`GET /check`

Parâmetros

Exemplo

Exemplo de resposta

`GET /transfer`

Parâmetros

Exemplo

Exemplo de resposta

`GET /transferbyaddress`

Parâmetros

Exemplo

Exemplo de resposta

`GET /health`

Exemplo

Resposta saudável

Erros

Uh oh!

FilesExpand file tree

api-pt.md

Latest commit

History

api-pt.md

File metadata and controls

Documentação de uso da API AuditKey

Visão geral

Autenticação

Redes suportadas

GET /label

Parâmetros

Exemplo

Exemplo de resposta

GET /check

Parâmetros

Exemplo

Exemplo de resposta

GET /transfer

Parâmetros

Exemplo

Exemplo de resposta

GET /transferbyaddress

Parâmetros

Exemplo

Exemplo de resposta

GET /health

Exemplo

Resposta saudável

Erros

`GET /label`

`GET /check`

`GET /transfer`

`GET /transferbyaddress`

`GET /health`