Skip to content

api-pt.md

Latest commit

 

History

History
268 lines (206 loc) · 7.47 KB

api-pt.md

File metadata and controls

268 lines (206 loc) · 7.47 KB
Raw

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 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": "exchange",
      "source": "fonte",
      "observed_at": "2026-07-19 12:00:00",
      "note": ""
    }
  ],
  "riskAddresses": [],
  "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.

GET /check

Calcula o risco de um endereço em uma escala de 0 a 10. 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/check?address=0x1111111111111111111111111111111111111111"

Exemplo de resposta

{
  "ok": true,
  "address": "0x1111111111111111111111111111111111111111",
  "chain": "evm",
  "risk": 9,
  "label": "Endereço bloqueado",
  "reasons": [
    {
      "rule": "blocked",
      "source": "fonte",
      "label": "Endereço bloqueado",
      "risk_category": "fraud",
      "observed_at": "2026-07-19 12:00:00"
    }
  ]
}

Interpretação da pontuação:

  • 10 — sanções, OFAC ou lista de risco de stablecoin;
  • 9 — endereço diretamente bloqueado por outra categoria;
  • 5 — ocorrência apenas reportada;
  • 3 — contraparte de segundo grau de um endereço bloqueado, disponível para EVM;
  • 0 — nenhum sinal de risco encontrado.

O campo reasons só é incluído quando risk é maior que zero.

GET /transfer - Cliente Enterprise

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 - Cliente Enterprise

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 (banco de dados, log de nodes, rpc ou blockscan). Uma lista vazia é uma resposta válida quando o provedor consultado não encontra transferências.

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.