GET /apiv2/screening/history

Seu histórico de triagem, do mais recente ao mais antigo, com paginação por cursor.

Este é o contrato da versão 2. Ele substitui o GET /apiv2/aml/history, que continua funcionando.

URL do endpoint

GET https://netts.io/apiv2/screening/history

Cabeçalhos da requisição

Header	Obrigatório	Descrição
X-API-KEY	Sim	Sua chave de API do painel da Netts

Parâmetros de consulta

Todos os filtros são opcionais. Sem nenhum deles, você obtém todo o seu histórico.

Parâmetro	Tipo	Padrão	Descrição
address	string	—	Endereço exato, de 10 a 128 caracteres
network	string	—	Ticker da rede
provider	string	—	elliptic ou bitok
status	string	—	pending, processing, completed, skipped, failed
from	string	—	Apenas verificações criadas neste momento ou após ele, RFC 3339
to	string	—	Apenas verificações criadas neste momento ou antes dele, RFC 3339
cursor	string	—	De onde continuar. Obtenha-o a partir de next_cursor
limit	integer	50	Itens por página, de 1 a 200

Na versão 1, address e network eram ambos obrigatórios, portanto não havia como perguntar "o que verifiquei recentemente".

Verificações com status skipped estão incluídas. A versão 1 as oculta. Uma verificação ignorada (skipped) é um pedido real — o endereço não tinha atividade na blockchain, portanto nunca foi enviado ao provedor e nunca foi cobrado — e pertence ao histórico.

Exemplos de Requisições

cURL

curl "https://netts.io/apiv2/screening/history?limit=50" \
  -H "X-API-KEY: your_api_key"

Python — percorrer todo o histórico

import requests

headers = {"X-API-KEY": "your_api_key"}
params = {"limit": 200, "provider": "elliptic"}

while True:
    page = requests.get("https://netts.io/apiv2/screening/history",
                        headers=headers, params=params).json()
    for item in page["items"]:
        print(item["order"]["client_order_id"],
              item["order"]["status"],
              item["risk"]["level"],
              item["sanctions"]["verdict"])

    if not page["next_cursor"]:
        break
    params = {"limit": 200, "provider": "elliptic", "cursor": page["next_cursor"]}

Mantenha os filtros idênticos durante a paginação. Alterar um deles mantendo o mesmo cursor gera um erro, e não uma mudança silenciosa para um conjunto diferente.

Resposta

{
  "schema_version": 2,
  "items": [
    {
      "order": {
        "client_order_id": "A6F3221BAAE093A",
        "status": "completed",
        "api_version": "v2",
        "cache_hit": false,
        "created_at": "2026-09-13T08:24:19.838584Z",
        "started_at": "2026-09-13T08:24:20.998619Z",
        "completed_at": "2026-09-13T08:24:25.179967Z"
      },
      "request": {
        "address": "YOUR_ADDRESS_HERE",
        "network": "trx",
        "provider": "elliptic"
      },
      "check": {
        "provider": "elliptic",
        "provider_check_id": "1cc2fd64-1483-4ce3-946f-23a614f41a12",
        "checked_at": "2026-09-13T08:24:22.372000Z",
        "status": "completed",
        "provider_status": "complete"
      },
      "risk": {
        "score": "0.12428176721891304",
        "scale": { "min": 0, "max": 10 },
        "level": "low",
        "level_source": "computed",
        "provider_level": null,
        "policy": "netts-risk-v1",
        "by_direction": { "source": "0.12428176721891304", "destination": null }
      },
      "sanctions": { "verdict": "linked" }
    }
  ],
  "next_cursor": "eyJmIjp7InN0YXR1cyI6ImNvbXBsZXRlZCJ9LCJpIjoxMzQyNywidCI6...",
  "limit": 1
}

Campo	Tipo	Descrição
items	array	A página, do mais recente ao mais antigo
next_cursor	string | null	Passe-o de volta para obter a próxima página. null significa que você chegou ao fim
limit	integer	O limite que foi aplicado

O formato resumido de um item

Os blocos order, request, check e risk são idênticos aos da resposta completa de GET /apiv2/screening/{client_order_id}, campo por campo, de modo que o mesmo analisador processa ambos.

O que é omitido: provider_data, exposure[], rules[], entities[], wallet, billing, precheck e o bloco completo sanctions. Um único resultado da Elliptic tem cerca de 150 KB, e uma página de cinquenta teria sete megabytes. Busque uma verificação individual quando precisar dos detalhes.

sanctions.verdict

A análise de sanções comprimida em uma única palavra.

Valor	Significado
listed	O próprio endereço está em uma lista de sanções
linked	Foi encontrado um vínculo de sanções, mas o endereço em si não está listado
none	A análise foi executada e nada encontrou
null	Ainda não há resultado para analisar

A diferença entre listed e linked é o objetivo do campo — consulte Sanções em um resultado AML.

Paginação

A versão 1 pagina por número: ?page=2, 100 por página. A ordenação é por data de criação, do mais recente ao mais antigo; assim, enquanto você navega da página 1 para a página 2, novas verificações chegam e empurram tudo para baixo. Registros que você já viu reaparecem, registros que você ainda não viu passam despercebidos. Em uma conta movimentada, isso não é um caso isolado.

Um cursor aponta para uma posição no conjunto em vez do seu número ordinal, portanto novas verificações que chegam durante o percurso não o perturbam.

• a ordenação é created_at DESC, id DESC. Ambos os campos estão no cursor, porque created_at não é único — caso contrário, duas verificações criadas no mesmo microssegundo entrariam em loop ou seriam ignoradas;
• o cursor é opaco. Seu conteúdo é um detalhe de implementação; passe-o de volta exatamente como você o recebeu;
• os filtros fazem parte do cursor. Alterar um deles ao reutilizar o cursor retorna 400, e não uma mudança silenciosa para um conjunto diferente — do contrário, você acreditaria ter lido um conjunto que nunca leu;
• next_cursor: null significa o fim. Não há contagem total: contar todo o conjunto a cada página custa mais do que a informação que isso oferece.

Erros

RFC 9457, application/problem+json. A lista completa de códigos está na página do POST.

Código	HTTP	Quando
4001	400	limit fora de 1…200, um network, provider ou status desconhecido, um from/to que não esteja no formato RFC 3339, um cursor malformado ou um cursor emitido para filtros diferentes
4010 / 4011	401	Nenhuma chave de API fornecida, ou uma chave ou IP que não é aceito

{
  "type": "https://doc.netts.io/api/v2/errors/validation-failed",
  "title": "Request validation failed",
  "status": 400,
  "detail": "Cursor was issued for a different set of filters",
  "instance": "/apiv2/screening/history",
  "code": 4001
}

Limites de taxa

Compartilhado com todas as outras rotas de AML: 5 requisições por segundo, 150 por minuto. Com limit=200, um histórico completo de dez mil verificações requer cinquenta requisições.